net.as_development.asdk.api.db

Interface IDB

All Known Implementing Classes:

DB

public interface IDB

provides all functionality of an 'object oriented' data base abstraction layer. Those layer wont support relation ships .. it tries to support a more 'non sql' related approach where entities (objects) can be stored and retrieved. Concepts: -------- Handling of multiple entity types at the same time -------- Sometimes you have to handle more then one entity at the same time. And most time those entities are from different type. Normal you have to issue several different requests to different DB objects (one for every entity type) to store, update or remove it. Thats different here - at least for store and remove .-) E.g. for storing new or updating existing entities ... You can create and prepare all entity objects outside and call IDB.storeEntities() with an array of those objects. An example: You wish to create a new user and further he should get a new created home directory. UserEntity aUser = new UserEntity (); aUser.Name = ...; HomeDirEntity aHomeDir = new HomeDirEntity (); aHomeDir.Path = ...; iDB.storeEntities (aUser, aHomeDir); -------- Queries -------- Any query to be used here has to be created first by calling IDB.prepareQuery (). The parameter you have to provide with that call is an unique ID for that new query. Internal it's used to e.g. compile queries at the first time they are used and cache them for later using. -------- Paging -------- Sometimes your queries match to so many result entities that providing all of them at the same time can make trouble (e.g. high memory consumption). On the other side the 'distributed character' of the underlying DB implementation may result in to long request times ... because many sub layer has to be asked (hopefully in parallel) ... but they return her own result sets at different times. So paging will be the answer. Every time you expect to get a bunch of entities back ... you wont get all at the same time (if the size of the result set does not fit into a minimum range). You get 'pages of entities' instead. Additional to the result page an iterator/cursor is provided to you - called 'NextToken'. On calling e.g. the query method the first time you can call it with NextToken=NULL (or even with an empty string). You will get the results filled into the result list (means first page of data available at that time) ... and the return value of the method itself will be a valid next-token (if more data exists or can be expected). If no further results exists the given result list will be cleared and not filled. Furthermore the method return NULL as next token so you know - it's over ... no more data available.

  	IQuery iQuery     = iDB.prepareQuery ("my_query");
  	// ... set query values on iQuery
  	String sNextToken = null;
  	do
  	{
  		List< MyEntity > lResults   = new ArrayList< MyEntity >(10);
  						 sNextToken = iDB.query (MyEntity.class,
  												 sNextToken    ,
  												 lResults      ,
  												 iQuery        );
  
  		// process result list ...
  		// There is no need to check next token here again ...
  		// result list will be empty if no results exists ...
  		// so the following loop will work even if next token will be null .-)
  
  		Iterator< MyEntity > pIt = lResults.iterator ();
  		while (pIt.hasMoreElements ())
  			...  
  	}
  	while (sNextToken != null);
  

It's not required to use such NextToken inside a loop. You can cache such token or even provide it to any other piece of code ... so if the token comes back to to DB-layer you can retrieve the next page of results. Problem doing so: ... those token might time out .-) TODO can it be solved ?

Method Summary

Modifier and Type	Method and Description
<TEntity extends IEntity> String	getAllEntitiesOfType(Class<TEntity> aType, String sNextToken, List<TEntity> lResults) return all entities matching to the given type.
<TEntity extends IEntity> String	getEntitiesById(Class<TEntity> aType, String sNextToken, List<TEntity> lResults, String... lIds) return a list of entities matching to the given list of primary keys.
<TEntity extends IEntity> TEntity	getEntityById(Class<TEntity> aType, String sId) direct access to ONE entity which specified ID.
<TEntity extends IEntity> IDBQuery<TEntity>	prepareQuery(Class<TEntity> aType, String sQueryId) provide a query object which we can use later at the interface method IDB.query ().
<TEntity extends IEntity> String	query(Class<TEntity> aType, String sNextToken, List<TEntity> lResults, IDBQuery<TEntity> iQuery) query for entities where it's attributes match the given set of query parameters/values.
<TEntity extends IEntity> TEntity	queryOne(Class<TEntity> aType, IDBQuery<TEntity> iQuery) Does the same then query () ... but instead of be usable for big sets of results these method can be used if one result will be expected.
<TEntity extends IEntity> void	removeAllEntitiesOfType(Class<TEntity> aType) remove all entities of given type from these DB.
<TEntity extends IEntity> void	removeEntities(TEntity... lEntities) remove the given set of entities from the DB.
<TEntity extends IEntity> void	removeEntitiesById(Class<TEntity> aType, String... lIds) remove all entities of specified type from the DB where it's Id's match to given Id set.
void	setPersistenceUnit(IPersistenceUnit aUnit) same as setPersistenceUnit(java.lang.String) ...
void	setPersistenceUnit(String sUnit) bind these DB instance to a persistence unit configuration.
<TEntity extends IEntity> void	storeEntities(TEntity... lEntities) make all given entities persistent inside DB.

Method Detail

setPersistenceUnit

void setPersistenceUnit(String sUnit)
                 throws Exception

bind these DB instance to a persistence unit configuration. Note Must be called as first method after creating a new instance of type IDB to initialize those instance right and prepare it for it's further work.

Parameters:

sUnit - [IN] name of the persistence unit.

Throws:

IllegalArgumentException - in case given persistence unit does not exists.

Exception - in case an internal (runtime) error occur.

setPersistenceUnit

void setPersistenceUnit(IPersistenceUnit aUnit)
                 throws Exception

same as setPersistenceUnit(java.lang.String) ...

Parameters:

aUnit - [IN] the persistence unit to be used here.

Throws:

IllegalArgumentException - in case given persistence unit does not exists.

Exception - in case an internal (runtime) error occur.

storeEntities

<TEntity extends IEntity> void storeEntities(TEntity... lEntities)
                                      throws Exception

make all given entities persistent inside DB. You can store different kind of entities here at the same time. E.g. you can create a collection of different entities which 'works' together (e.g. user...file...storage) and put them to the DB together also.

Parameters:

lEntities - [IN] the list of entities to be made persistent. If list will be empty or null - nothing will happen.

Throws:

Exception - in case an internal (runtime) error occured.

removeEntities

<TEntity extends IEntity> void removeEntities(TEntity... lEntities)
                                       throws Exception

remove the given set of entities from the DB. You can remove different kind of entities here at the same time. E.g. you can create a collection of different entities which 'works' together (e.g. user...file...storage) and remove them from the DB together also. Because there is no relation ship between those entities order of remove request can be ignored.

Parameters:

lEntities - [IN] the list of entities to be removed. If list will be empty or null - nothing will happen.

Throws:

Exception

removeEntitiesById

<TEntity extends IEntity> void removeEntitiesById(Class<TEntity> aType,
                                                  String... lIds)
                                           throws Exception

remove all entities of specified type from the DB where it's Id's match to given Id set.

Parameters:

aType - [IN] the type of those entities to be removed here.

lIds - [IN] the list of Id's where the matching entities must be removed. If list will be empty or null - nothing will happen.

Throws:

Exception

removeAllEntitiesOfType

<TEntity extends IEntity> void removeAllEntitiesOfType(Class<TEntity> aType)
                                                throws Exception

remove all entities of given type from these DB.

Parameters:

aType - [IN] describe the type where all corresponding entities has to be removed.

Throws:

Exception - in case an internal (runtime) error occur.

getEntityById

<TEntity extends IEntity> TEntity getEntityById(Class<TEntity> aType,
                                                String sId)
                                         throws Exception

direct access to ONE entity which specified ID.

Parameters:

aType - [IN] the type of entity asked here.

sId - [IN] the unique ID (primary key) of those entity.

Returns:

the queried entity if it exists; null otherwise.

Throws:

Exception - in case an internal (runtime) error occur.

getEntitiesById

<TEntity extends IEntity> String getEntitiesById(Class<TEntity> aType,
                                                 String sNextToken,
                                                 List<TEntity> lResults,
                                                 String... lIds)
                                          throws Exception

return a list of entities matching to the given list of primary keys.

Parameters:

aType - [IN] the type of entities where we must search for.

sNextToken - [IN] the next token where further results might be available for. Can be null or an empty string if this the 'first query'.

lResults - [OUT] the list of matching entities for this request. Will be empty if no (further) results exists.

lIds - [IN] the list of Id's. If list will be empty (or even null) - nothing will happen.

Returns:

the new next token (if there is one). Return null if no further results exists.

Throws:

Exception - in case an internal (runtime) error occur.

getAllEntitiesOfType

<TEntity extends IEntity> String getAllEntitiesOfType(Class<TEntity> aType,
                                                      String sNextToken,
                                                      List<TEntity> lResults)
                                               throws Exception

return all entities matching to the given type. Please use it carefully because it can return more data as you need real .-)

Parameters:

aType - [IN] the type of entities where we must search for.

sNextToken - [IN] the next token where further results might be available for. Can be null or an empty string if this the 'first query'.

lResults - [OUT] the list of matching entities for this request. Will be empty if no (further) results exists.

Returns:

the new next token (if there is one). Return null if no further results exists.

Throws:

Exception - in case an internal (runtime) error occur.

prepareQuery

<TEntity extends IEntity> IDBQuery<TEntity> prepareQuery(Class<TEntity> aType,
                                                         String sQueryId)
                                                  throws Exception

provide a query object which we can use later at the interface method IDB.query ().

Parameters:

aType - [IN] the type of entities where the query must be suitable for.

sQueryId - [ID] an unique ID for this query. Will be might used for internal caching of pre-compiled queries.

Returns:

the query object to be used now.

Throws:

Exception

query

<TEntity extends IEntity> String query(Class<TEntity> aType,
                                       String sNextToken,
                                       List<TEntity> lResults,
                                       IDBQuery<TEntity> iQuery)
                                throws Exception

query for entities where it's attributes match the given set of query parameters/values. An instance of IDBQuery can be obtained by calling IDB.prepareQuery (). see IDBQuery see prepareQuery(java.lang.String)

Parameters:

aType - [IN] the entity type where this query is for.

sNextToken - [IN] the next token where further results might be available for. Can be null or an empty string if this the 'first query'.

lResults - [OUT] the list of matching entities for this query. Will be empty if no (further) results exists.

iQuery - [IN] the query itself.

Returns:

the new next token (if there is one). Return null if no further results exists.

Throws:

Exception

queryOne

<TEntity extends IEntity> TEntity queryOne(Class<TEntity> aType,
                                           IDBQuery<TEntity> iQuery)
                                    throws Exception

Does the same then query () ... but instead of be usable for big sets of results these method can be used if one result will be expected. Of course YOU have to make sure exact one result will be possible for that query. E.g. you should issue those query on columns where the UNIQUE property was set .-)

Parameters:

aType - [IN] the entity type where this query is for.

iQuery - [IN] the query itself.

Returns:

the (hopefully) one and only result. Can be null.

Throws:

Exception