public class EntityManager extends Object
The root control class for the entire ActiveObjects API. EntityManager
is the source of all RawEntity
objects, as well as the dispatch layer between the entities, the pluggable table name converters, and the
database abstraction layers. This is the entry point for any use of the API.
EntityManager
is designed to be used in an instance fashion with each instance corresponding to a
single database. Thus, rather than a singleton instance or a static factory method, EntityManager
does
have a proper constructor. Any static instance management is left up to the developer using the API.
Constructor and Description |
---|
EntityManager(DatabaseProvider provider,
EntityManagerConfiguration configuration)
Creates a new instance of
EntityManager using the specified DatabaseProvider . |
Modifier and Type | Method and Description |
---|---|
<K> int |
count(Class<? extends RawEntity<K>> type)
Counts all entities of the specified type.
|
<K> int |
count(Class<? extends RawEntity<K>> type,
Query query)
Counts all entities of the specified type matching the given
Query instance. |
<K> int |
count(Class<? extends RawEntity<K>> type,
String criteria,
Object... parameters)
Counts all entities of the specified type matching the given criteria and parameters.
|
<T extends RawEntity<K>,K> |
create(Class<T> type,
DBParam... params)
Creates a new entity of the specified type with the optionally specified
initial parameters.
|
<T extends RawEntity<K>,K> |
create(Class<T> type,
List<Map<String,Object>> rows)
Creates and INSERTs a batch of new entities represented by
rows of the given type. |
<T extends RawEntity<K>,K> |
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(RawEntity<?>... entities)
Deletes the specified entities from the database.
|
<K> int |
deleteWithSQL(Class<? extends RawEntity<K>> type,
String criteria,
Object... parameters)
Deletes rows from the table corresponding to
type . |
<T extends RawEntity<K>,K> |
find(Class<T> type)
Returns all entities of the given type.
|
<T extends RawEntity<K>,K> |
find(Class<T> type,
Query query)
Selects all entities matching the given type and
Query . |
<T extends RawEntity<K>,K> |
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 RawEntity<K>,K> |
find(Class<T> type,
String field,
Query query)
Selects all entities of the specified type which match the given
Query . |
<T extends RawEntity<K>,K> |
findSingleEntity(Class<T> type,
String criteria,
Object... parameters)
Convenience method to select a single entity of the given type with the specified, parameterized criteria.
|
<T extends RawEntity<K>,K> |
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(RawEntity<?>... entities)
Deprecated.
since 0.25. Entities and values now no longer cached.
|
void |
flushAll()
Deprecated.
since 0.23. EntityManager now no longer caches entities.
use
flush(RawEntity[]) to flush values for individual entities |
void |
flushEntityCache()
Deprecated.
since 0.23. EntityManager now no longer caches entities.
use
flush(RawEntity[]) to flush values for individual entities |
<T extends RawEntity<K>,K> |
get(Class<T> type,
K... keys)
Returns an array of entities of the specified type corresponding to the
varargs primary keys.
|
<T extends RawEntity<K>,K> |
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.
|
protected <T extends RawEntity<K>,K> |
getAndInstantiate(EntityInfo<T,K> entityInfo,
K key)
Creates a new instance of the entity of the specified type corresponding to the given primary key.
|
FieldNameConverter |
getFieldNameConverter()
Retrieves the
FieldNameConverter instance used for name conversion of all entity methods. |
NameConverters |
getNameConverters() |
PolymorphicTypeMapper |
getPolymorphicTypeMapper()
Retrieves the
PolymorphicTypeMapper instance used for flag value conversion of polymorphic types. |
DatabaseProvider |
getProvider()
Retrieves the database provider used by this
EntityManager for all database operations. |
SchemaConfiguration |
getSchemaConfiguration()
Retrieves
SchemaConfiguration used by this entity manager. |
TableNameConverter |
getTableNameConverter()
Retrieves the
TableNameConverter instance used for name conversion of all entity types. |
void |
migrate(Class<? extends RawEntity<?>>... entities)
Convenience method to create the schema for the specified entities using the current settings (table/field name
converter and database provider).
|
void |
migrateDestructively(Class<? extends RawEntity<?>>... entities)
Convenience method to create the schema for the specified entities using the current settings (table/field name
converter and database provider).
|
protected <T extends RawEntity<K>,K> |
peer(EntityInfo<T,K> entityInfo,
K... keys) |
protected <T extends RawEntity<K>,K> |
peer(EntityInfo<T,K> entityInfo,
K key) |
protected <T extends RawEntity<K>,K> |
resolveEntityInfo(Class<T> type) |
void |
setPolymorphicTypeMapper(PolymorphicTypeMapper typeMapper)
Specifies the
PolymorphicTypeMapper instance to use for all flag value conversion of polymorphic types. |
<T extends RawEntity<K>,K> |
stream(Class<T> type,
EntityStreamCallback<T,K> streamCallback)
Optimised read for large datasets.
|
<T extends RawEntity<K>,K> |
stream(Class<T> type,
Query query,
EntityStreamCallback<T,K> streamCallback)
Selects all entities of the given type and feeds them to the callback, one by one.
|
public EntityManager(DatabaseProvider provider, EntityManagerConfiguration configuration)
EntityManager
using the specified DatabaseProvider
.provider
- the DatabaseProvider
to use in all database operations.configuration
- the configuration for this entity managerpublic void migrate(Class<? extends RawEntity<?>>... entities) throws SQLException
entities
- the "list" of entity classes to consider for migration.SQLException
SchemaGenerator.migrate(DatabaseProvider, SchemaConfiguration, NameConverters, boolean, Class[])
public void migrateDestructively(Class<? extends RawEntity<?>>... entities) throws SQLException
entities
- the "list" of entity classes to consider for migration.SQLException
SchemaGenerator.migrate(DatabaseProvider, SchemaConfiguration, NameConverters, boolean, Class[])
@Deprecated public void flushAll()
flush(RawEntity[])
to flush values for individual entities@Deprecated public void flushEntityCache()
flush(RawEntity[])
to flush values for individual entities@Deprecated public void flush(RawEntity<?>... entities)
public <T extends RawEntity<K>,K> T[] get(Class<T> type, K... keys) throws SQLException
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.
If the entity is known to exist in the database, then no checks are performed
and the method returns extremely quickly. However, for any key which has not
already been verified, a query to the database is performed to determine whether
or not the entity exists. If the entity does not exist, then null
is returned.
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
inheritence (if inheriting from Entity
, this is Integer
or int
). Thus, the keys
array is type-checked at compile
time.null
value in the resulting array.SQLException
protected <T extends RawEntity<K>,K> T[] peer(EntityInfo<T,K> entityInfo, K... keys) throws SQLException
SQLException
protected <T extends RawEntity<K>,K> T getAndInstantiate(EntityInfo<T,K> entityInfo, K key)
get(Class, Object[])
} to create the entity.entityInfo
- The type of the entity to create.key
- The primary key corresponding to the entity instance required.public <T extends RawEntity<K>,K> T get(Class<T> type, K key) throws SQLException
get
method and
functions as syntactical sugar.type
- The type of the entity instance to retrieve.key
- The primary key corresponding to the entity to be retrieved.null
if
the entity does not exist in the database.SQLException
get(Class, Object[])
protected <T extends RawEntity<K>,K> T peer(EntityInfo<T,K> entityInfo, K key) throws SQLException
SQLException
public <T extends RawEntity<K>,K> T create(Class<T> type, DBParam... params) throws SQLException
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
DatabaseProvider.insertReturningKey(net.java.ao.EntityManager, java.sql.Connection, java.lang.Class<T>, java.lang.Class<K>, java.lang.String, boolean, java.lang.String, net.java.ao.DBParam...)
.
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.
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.SQLException
DBParam
public <T extends RawEntity<K>,K> T create(Class<T> type, Map<String,Object> params) throws SQLException
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.type
- The type of the entity to INSERT.params
- A map of parameters to pass to the INSERT.SQLException
create(Class, DBParam...)
public <T extends RawEntity<K>,K> void create(Class<T> type, List<Map<String,Object>> rows) throws SQLException
rows
of the given type. Each entity
corresponds to a single row.type
- The type of the entity to INSERT.rows
- A list of rows to be INSERTed. A row is represented as a map from column name to its value.
All rows must have the same columns.SQLException
public void delete(RawEntity<?>... entities) throws SQLException
Deletes the specified entities from the database. DELETE statements are called on the rows in the corresponding tables. 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.
entities
- A varargs array of entities to delete. Method returns immediately if length == 0.SQLException
public <K> int deleteWithSQL(Class<? extends RawEntity<K>> type, String criteria, Object... parameters) throws SQLException
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.
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
.SQLException
delete(RawEntity...)
,
find(Class, String, Object...)
,
findWithSQL(Class, String, String, Object...)
public <T extends RawEntity<K>,K> T[] find(Class<T> type) throws SQLException
find(Class, Query)
method.type
- The type of entity to retrieve.SQLException
public <T extends RawEntity<K>,K> T[] find(Class<T> type, String criteria, Object... parameters) throws SQLException
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, Query)
method, properly parameterizing the Query
object.
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
.SQLException
public <T extends RawEntity<K>,K> T findSingleEntity(Class<T> type, String criteria, Object... parameters) throws SQLException
Convenience method to select a single entity 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.findSingleEntity(Person.class, "name LIKE ? OR age > ?", "Joe", 9);
This actually delegates the call to the find(Class, String, Object...)
method, properly
parameterizing the Object
object.
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
.SQLException
public <T extends RawEntity<K>,K> T[] find(Class<T> type, Query query) throws SQLException
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, Query)
, passing the primary key field for the
given type as the String
parameter.
Note that in the case of calling this function with a Query
with select fields, the
first field will be passed to find(Class, String, Query)
. If this is not the intention, a direct
call to find(Class, String, Query)
should be made instead, with the primary key field specified
and present in the select fields.
type
- The type of the entities to retrieve.query
- The Query
instance to be used to determine the results.SQLException
public <T extends RawEntity<K>,K> T[] find(Class<T> type, String field, Query query) throws SQLException
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.
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.SQLException
public <T extends RawEntity<K>,K> T[] findWithSQL(Class<T> type, String keyField, String sql, Object... parameters) throws SQLException
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.
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
.SQLException
public <T extends RawEntity<K>,K> void stream(Class<T> type, EntityStreamCallback<T,K> streamCallback) throws SQLException
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.
type
- The type of the entities to retrieve.streamCallback
- The receiver of the data, will be passed one entity per returned rowSQLException
public <T extends RawEntity<K>,K> void stream(Class<T> type, Query query, EntityStreamCallback<T,K> streamCallback) throws SQLException
Selects all entities of the given type and feeds them to the callback, one by one. The entities are slim,
read-only representations of the data. They only supports getters or designated Accessor
methods. Calling setters
or
savewill result in an exception. Other method calls will be ignored. The proxies do not support lazy-loading of related entities.
Only the fields specified in the Query are loaded. Since lazy loading is not supported, calls to unspecified getters will return null (or AO's defaults in case of primitives)
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.
type
- The type of the entities to retrieve.query
- streamCallback
- The receiver of the data, will be passed one entity per returned rowSQLException
public <K> int count(Class<? extends RawEntity<K>> type) throws SQLException
count(Class<?
extends Entity>, Query)
type
- The type of the entities which should be counted.SQLException
public <K> int count(Class<? extends RawEntity<K>> type, String criteria, Object... parameters) throws SQLException
count(type, Query.select().where(criteria, 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
.SQLException
public <K> int count(Class<? extends RawEntity<K>> type, Query query) throws SQLException
Query
instance. The SQL runs as a
SELECT COUNT(*)
to ensure maximum performance.type
- The type of the entities which should be counted.query
- The Query
instance used to determine the result set which will be counted.SQLException
public NameConverters getNameConverters()
protected <T extends RawEntity<K>,K> EntityInfo<T,K> resolveEntityInfo(Class<T> type)
public TableNameConverter getTableNameConverter()
TableNameConverter
instance used for name conversion of all entity types.public FieldNameConverter getFieldNameConverter()
FieldNameConverter
instance used for name conversion of all entity methods.public void setPolymorphicTypeMapper(PolymorphicTypeMapper typeMapper)
PolymorphicTypeMapper
instance to use for all flag value conversion of polymorphic types.
The default type mapper is an empty DefaultPolymorphicTypeMapper
instance (thus using the fully qualified
classname for all values).getPolymorphicTypeMapper()
public PolymorphicTypeMapper getPolymorphicTypeMapper()
PolymorphicTypeMapper
instance used for flag value conversion of polymorphic types.public DatabaseProvider getProvider()
Retrieves the database provider used by this EntityManager
for all database operations. This
method can be used reliably to obtain a database provider and hence a Connection
instance which can be
used for JDBC operations outside of ActiveObjects. Thus:
Connection conn = manager.getProvider().getConnection(); try { // ... } finally { conn.close(); }
public SchemaConfiguration getSchemaConfiguration()
SchemaConfiguration
used by this entity manager.SchemaConfiguration
Copyright © 2007–2022 Atlassian. All rights reserved.