com.atlassian.activeobjects.external

Interface ActiveObjects

All Known Implementing Classes:

EntityManagedActiveObjects, TestActiveObjects

public interface ActiveObjects

Interface to the active objects framework. Instance is threadsafe.

Method Summary

Modifier and Type	Method and Description
<K> int	count(Class<? extends net.java.ao.RawEntity<K>> type) Counts all entities of the specified type.
<K> int	count(Class<? extends net.java.ao.RawEntity<K>> type, net.java.ao.Query query) Counts all entities of the specified type matching the given Query instance.
<K> int	count(Class<? extends net.java.ao.RawEntity<K>> type, String criteria, Object... parameters) Counts all entities of the specified type matching the given criteria and parameters.
<T extends net.java.ao.RawEntity<K>,K> T	create(Class<T> type, net.java.ao.DBParam... params) Creates a new entity of the specified type with the optionally specified initial parameters.
<T extends net.java.ao.RawEntity<K>,K> T	create(Class<T> type, Map<String,Object> params) Creates and INSERTs a new entity of the specified type with the given map of parameters.
void	delete(net.java.ao.RawEntity<?>... entities) Deletes the specified entities from the database.
<K> int	deleteWithSQL(Class<? extends net.java.ao.RawEntity<K>> type, String criteria, Object... parameters) Deletes rows from the table corresponding to type.
<T> T	executeInTransaction(com.atlassian.sal.api.transaction.TransactionCallback<T> callback) Execute the given callback within a transaction if the host supports transactions, otherwise executes the callback immediately.
<T extends net.java.ao.RawEntity<K>,K> T[]	find(Class<T> type) Returns all entities of the given type.
<T extends net.java.ao.RawEntity<K>,K> T[]	find(Class<T> type, net.java.ao.Query query) Selects all entities matching the given type and Query.
<T extends net.java.ao.RawEntity<K>,K> T[]	find(Class<T> type, String criteria, Object... parameters) Convenience method to select all entities of the given type with the specified, parameterized criteria.
<T extends net.java.ao.RawEntity<K>,K> T[]	find(Class<T> type, String field, net.java.ao.Query query) Selects all entities of the specified type which match the given Query.
<T extends net.java.ao.RawEntity<K>,K> T[]	findWithSQL(Class<T> type, String keyField, String sql, Object... parameters) Executes the specified SQL and extracts the given key field, wrapping each row into a instance of the specified type.
void	flush(net.java.ao.RawEntity<?>... entities) Flushes the value caches of the specified entities along with all of the relevant relations cache entries.
void	flushAll() Flushes all value caches contained within entities controlled by this EntityManager instance.
<T extends net.java.ao.RawEntity<K>,K> T[]	get(Class<T> type, K... keys) Returns an array of entities of the specified type corresponding to the varargs primary keys.
<T extends net.java.ao.RawEntity<K>,K> T	get(Class<T> type, K key) Cleverly overloaded method to return a single entity of the specified type rather than an array in the case where only one ID is passed.
void	migrate(Class<? extends net.java.ao.RawEntity<?>>... entities) Creates the schema for the specified entities
void	migrateDestructively(Class<? extends net.java.ao.RawEntity<?>>... entities) Create the schema for the specified entities, dropping columns and tables which are no longer required
ActiveObjectsModuleMetaData	moduleMetaData() Provides information about the state of the ActiveObjects module
<T extends net.java.ao.RawEntity<K>,K> void	stream(Class<T> type, net.java.ao.EntityStreamCallback<T,K> streamCallback) Optimised read for large datasets.
<T extends net.java.ao.RawEntity<K>,K> void	stream(Class<T> type, net.java.ao.Query query, net.java.ao.EntityStreamCallback<T,K> streamCallback) Selects all entities of the given type and feeds them to the callback, one by one.

Method Detail

migrate

void migrate(Class<? extends net.java.ao.RawEntity<?>>... entities)

Creates the schema for the specified entities

migrateDestructively

void migrateDestructively(Class<? extends net.java.ao.RawEntity<?>>... entities)

Create the schema for the specified entities, dropping columns and tables which are no longer required

flushAll

void flushAll()

Flushes all value caches contained within entities controlled by this EntityManager instance. This does not actually remove the entities from the instance cache maintained within this class. Rather, it simply dumps all of the field values cached within the entities themselves (with the exception of the primary key value). This should be used in the case of a complex process outside AO control which may have changed values in the database. If it is at all possible to determine precisely which rows have been changed, the flush(net.java.ao.RawEntity...) method should be used instead.

flush

void flush(net.java.ao.RawEntity<?>... entities)

Flushes the value caches of the specified entities along with all of the relevant relations cache entries. This should be called after a process outside of AO control may have modified the values in the specified rows. This does not actually remove the entity instances themselves from the instance cache. Rather, it just flushes all of their internally cached values (with the exception of the primary key).

get

<T extends net.java.ao.RawEntity<K>,K> T[] get(Class<T> type,
                                               K... keys)

Returns an array of entities of the specified type corresponding to the varargs primary keys. If an in-memory reference already exists to a corresponding entity (of the specified type and key), it is returned rather than creating a new instance.

No checks are performed to ensure that the key actually exists in the database for the specified object. Thus, this method is solely a Java memory state modifying method. There is no database access involved. The upshot of this is that the method is very very fast. The flip side of course is that one could conceivably maintain entities which reference non-existent database rows.

Parameters:

type - The type of the entities to retrieve

keys - The primary keys corresponding to the entities to retrieve. All keys must be typed according to the generic type parameter of the entity's RawEntity inheritance (if inheriting from Entity, this is Integer or int). Thus, the keys array is type-checked at compile time.

Returns:

An array of entities of the given type corresponding with the specified primary keys

get

<T extends net.java.ao.RawEntity<K>,K> T get(Class<T> type,
                                             K key)

Cleverly overloaded method to return a single entity of the specified type rather than an array in the case where only one ID is passed. This method merely delegates the call to the overloaded get method and functions as syntactical sugar.

Parameters:

type - The type of the entity instance to retrieve

key - The primary key corresponding to the entity to be retrieved

Returns:

An entity instance of the given type corresponding to the specified primary key

See Also:

get(Class, Object...)

create

<T extends net.java.ao.RawEntity<K>,K> T create(Class<T> type,
                                                net.java.ao.DBParam... params)

Creates a new entity of the specified type with the optionally specified initial parameters. This method actually inserts a row into the table represented by the entity type and returns the entity instance which corresponds to that row.

The DBParam object parameters are designed to allow the creation of entities which have non-null fields which have no defalut or auto-generated value. Insertion of a row without such field values would of course fail, thus the need for db params. The db params can also be used to set the values for any field in the row, leading to more compact code under certain circumstances.

Unless within a transaction, this method will commit to the database immediately and exactly once per call. Thus, care should be taken in the creation of large numbers of entities. There doesn't seem to be a more efficient way to create large numbers of entities, however one should still be aware of the performance implications.

This method delegates the action INSERT action to This is necessary because not all databases support the JDBC RETURN_GENERATED_KEYS constant (e.g. PostgreSQL and HSQLDB). Thus, the database provider itself is responsible for handling INSERTion and retrieval of the correct primary key value.

Parameters:

type - The type of the entity to INSERT

params - An optional varargs array of initial values for the fields in the row. These values will be passed to the database within the INSERT statement.

Returns:

The new entity instance corresponding to the INSERTed row

See Also:

DBParam

create

<T extends net.java.ao.RawEntity<K>,K> T create(Class<T> type,
                                                Map<String,Object> params)

Creates and INSERTs a new entity of the specified type with the given map of parameters. This method merely delegates to the create(Class, DBParam...) method. The idea behind having a separate convenience method taking a map is in circumstances with large numbers of parameters or for people familiar with the anonymous inner class constructor syntax who might be more comfortable with creating a map than with passing a number of objects.

Parameters:

type - The type of the entity to INSERT

params - A map of parameters to pass to the INSERT

Returns:

The new entity instance corresponding to the INSERTed row

See Also:

create(Class, DBParam...)

delete

void delete(net.java.ao.RawEntity<?>... entities)

Deletes the specified entities from the database. DELETE statements are called on the rows in the corresponding tables and the entities are removed from the instance cache. The entity instances themselves are not invalidated, but it doesn't even make sense to continue using the instance without a row with which it is paired.

This method does attempt to group the DELETE statements on a per-type basis. Thus, if you pass 5 instances of EntityA and two instances of EntityB, the following SQL prepared statements will be invoked:

     DELETE FROM entityA WHERE id IN (?,?,?,?,?);
     DELETE FROM entityB WHERE id IN (?,?);
 

Thus, this method scales very well for large numbers of entities grouped into types. However, the execution time increases linearly for each entity of unique type.

Parameters:

entities - A varargs array of entities to delete. Method returns immediately if length == 0.

deleteWithSQL

<K> int deleteWithSQL(Class<? extends net.java.ao.RawEntity<K>> type,
                      String criteria,
                      Object... parameters)

Deletes rows from the table corresponding to type. In contrast to delete(RawEntity[]), this method allows you to delete rows without creating entities for them first.

Example:

     manager.deleteWithSQL(Person.class, "name = ?", "Charlie")
 

The SQL in criteria is not parsed or modified in any way by ActiveObjects, and is simply appended to the DELETE statement in a WHERE clause. The above example would cause an SQL statement similar to the following to be executed:

     DELETE FROM people WHERE name = 'Charlie';
 

If criteria is null, this method deletes all rows from the table corresponding to type.

This method does not attempt to determine the set of entities affected by the statement. As such, it is recommended that you call flushAll() after calling this method.

Parameters:

type - The entity type corresponding to the table to delete from

criteria - An optional SQL fragment specifying which rows to delete

parameters - A varargs array of parameters to be passed to the executed prepared statement. The length of this array must match the number of parameters (denoted by the '?' char) in criteria.

Returns:

The number of rows deleted from the table

See Also:

delete(RawEntity...), find(Class, String, Object...), findWithSQL(Class, String, String, Object...)

find

<T extends net.java.ao.RawEntity<K>,K> T[] find(Class<T> type)

Returns all entities of the given type. This actually peers the call to the find(Class, net.java.ao.Query) method.

Parameters:

type - The type of entity to retrieve

Returns:

An array of all entities which correspond to the given type

find

<T extends net.java.ao.RawEntity<K>,K> T[] find(Class<T> type,
                                                String criteria,
                                                Object... parameters)

Convenience method to select all entities of the given type with the specified, parameterized criteria. The criteria String specified is appended to the SQL prepared statement immediately following the WHERE.

Example:

     manager.find(Person.class, "name LIKE ? OR age > ?", "Joe", 9);
 

This actually delegates the call to the find(Class, net.java.ao.Query) method, properly parameterizing the Query object.

Parameters:

type - The type of the entities to retrieve

criteria - A parameterized WHERE statement used to determine the results

parameters - A varargs array of parameters to be passed to the executed prepared statement. The length of this array must match the number of parameters (denoted by the '?' char) in the criteria.

Returns:

An array of entities of the given type which match the specified criteria

find

<T extends net.java.ao.RawEntity<K>,K> T[] find(Class<T> type,
                                                net.java.ao.Query query)

Selects all entities matching the given type and Query. By default, the entities will be created based on the values within the primary key field for the specified type (this is usually the desired behavior).

Example:

     manager.find(Person.class, Query.select().where("name LIKE ? OR age > ?", "Joe", 9).limit(10));
 

This method delegates the call to find(Class, String, net.java.ao.Query), passing the primary key field for the given type as the String parameter.

Parameters:

type - The type of the entities to retrieve

query - The Query instance to be used to determine the results

Returns:

An array of entities of the given type which match the specified query

find

<T extends net.java.ao.RawEntity<K>,K> T[] find(Class<T> type,
                                                String field,
                                                net.java.ao.Query query)

Selects all entities of the specified type which match the given Query. This method creates a PreparedStatement using the Query instance specified against the table represented by the given type. This query is then executed (with the parameters specified in the query). The method then iterates through the result set and extracts the specified field, mapping an entity of the given type to each row. This array of entities is returned.

Parameters:

type - The type of the entities to retrieve

field - The field value to use in the creation of the entities. This is usually the primary key field of the corresponding table.

query - The Query instance to use in determining the results

Returns:

An array of entities of the given type which match the specified query

findWithSQL

<T extends net.java.ao.RawEntity<K>,K> T[] findWithSQL(Class<T> type,
                                                       String keyField,
                                                       String sql,
                                                       Object... parameters)

Executes the specified SQL and extracts the given key field, wrapping each row into a instance of the specified type. The SQL itself is executed as a PreparedStatement with the given parameters.

Example:

     manager.findWithSQL(Person.class, "personID", "SELECT personID FROM chairs WHERE position < ? LIMIT ?", 10, 5);
 

The SQL is not parsed or modified in any way by ActiveObjects. As such, it is possible to execute database-specific queries using this method without realizing it. For example, the above query will not run on MS SQL Server or Oracle, due to the lack of a LIMIT clause in their SQL implementation. As such, be extremely careful about what SQL is executed using this method, or else be conscious of the fact that you may be locking yourself to a specific DBMS.

Parameters:

type - The type of the entities to retrieve

keyField - The field value to use in the creation of the entities. This is usually the primary key field of the corresponding table.

sql - The SQL statement to execute.

parameters - A varargs array of parameters to be passed to the executed prepared statement. The length of this array must match the number of parameters (denoted by the '?' char) in the criteria.

Returns:

An array of entities of the given type which match the specified query

stream

<T extends net.java.ao.RawEntity<K>,K> void stream(Class<T> type,
                                                   net.java.ao.EntityStreamCallback<T,K> streamCallback)

Optimised read for large datasets. This method will stream all rows for the given type to the given callback.

Please see stream(Class, Query, EntityStreamCallback) for details / limitations.

Parameters:

type - The type of the entities to retrieve

streamCallback - The receiver of the data, will be passed one entity per returned row

stream

<T extends net.java.ao.RawEntity<K>,K> void stream(Class<T> type,
                                                   net.java.ao.Query query,
                                                   net.java.ao.EntityStreamCallback<T,K> streamCallback)

Selects all entities of the given type and feeds them to the callback, one by one. The entities are slim, uncached, read-only representations of the data. They only supports getters or designated Accessor methods. Calling setters or

save

will result in an exception. Other method calls will be ignored. The proxies do not support lazy-loading of related entities.

This call is optimised for efficient read operations on large datasets. For best memory usage, do not buffer the entities passed to the callback but process and discard them directly. Unlike regular Entities, the read only implementations do not support flushing/refreshing. The data is a snapshot view at the time of query.

Parameters:

type - The type of the entities to retrieve

query - The Query instance to use in determining the results

streamCallback - The receiver of the data, will be passed one entity per returned row

count

<K> int count(Class<? extends net.java.ao.RawEntity<K>> type)

Counts all entities of the specified type. This method is actually a delegate for: count(Class<? extends Entity>, Query)

Parameters:

type - The type of the entities which should be counted.

Returns:

The number of entities of the specified type.

count

<K> int count(Class<? extends net.java.ao.RawEntity<K>> type,
              String criteria,
              Object... parameters)

Counts all entities of the specified type matching the given criteria and parameters. This is a convenience method for: count(type, Query.select().where(criteria, parameters))

Parameters:

type - The type of the entities which should be counted

criteria - A parameterized WHERE statement used to determine the result set which will be counted

parameters - A varargs array of parameters to be passed to the executed prepared statement. The length of this array must match the number of parameters (denoted by the '?' char) in the criteria.

Returns:

The number of entities of the given type which match the specified criteria

count

<K> int count(Class<? extends net.java.ao.RawEntity<K>> type,
              net.java.ao.Query query)

Counts all entities of the specified type matching the given Query instance. The SQL runs as a SELECT COUNT(*) to ensure maximum performance.

Parameters:

type - The type of the entities which should be counted

query - The Query instance used to determine the result set which will be counted

Returns:

The number of entities of the given type which match the specified query

executeInTransaction

<T> T executeInTransaction(com.atlassian.sal.api.transaction.TransactionCallback<T> callback)

Execute the given callback within a transaction if the host supports transactions, otherwise executes the callback immediately.

Parameters:

callback - the callback to execute within a transaction

Returns:

the result of the transactionCallback

moduleMetaData

ActiveObjectsModuleMetaData moduleMetaData()

Provides information about the state of the ActiveObjects module

Returns:

activeObjectsModuleMetaData

Since:

0.24