net.as_development.asdk.db_service.impl

Class DB

java.lang.Object

net.as_development.asdk.db_service.impl.DB

All Implemented Interfaces:

IDB, IDBSchema

public class DB
extends Object
implements IDB, IDBSchema

Base for all implementations of the interface IDB. It provides the basic functionality which is used by all those derived classes ... as e.g. handling of the persistence unit.

Constructor Summary

Constructors

Constructor and Description
DB() create new instance.

Method Summary

Modifier and Type	Method and Description
<TEntity extends IEntity> void	createEntitySchema(Class<TEntity> aType) create necessary structures inside DB for specified entity type.
<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.
<TEntity extends IEntity> void	removeEntitySchema(Class<TEntity> aType) remove all data within DB back end related to the specified entity.
void	setPersistenceUnit(IPersistenceUnit iUnit) 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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DB

public DB()

create new instance.

Method Detail

setPersistenceUnit

public void setPersistenceUnit(String sUnit)
                        throws Exception

Description copied from interface: IDB

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.

Specified by:

setPersistenceUnit in interface IDB

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

public void setPersistenceUnit(IPersistenceUnit iUnit)
                        throws Exception

Description copied from interface: IDB

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

Specified by:

setPersistenceUnit in interface IDB

Parameters:

iUnit - [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

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

Description copied from interface: IDB

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.

Specified by:

storeEntities in interface IDB

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

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

Description copied from interface: IDB

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.

Specified by:

removeEntities in interface IDB

Parameters:

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

Throws:

Exception

removeEntitiesById

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

Description copied from interface: IDB

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

Specified by:

removeEntitiesById in interface IDB

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

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

Description copied from interface: IDB

remove all entities of given type from these DB.

Specified by:

removeAllEntitiesOfType in interface IDB

Parameters:

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

Throws:

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

getEntityById

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

Description copied from interface: IDB

direct access to ONE entity which specified ID.

Specified by:

getEntityById in interface IDB

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

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

Description copied from interface: IDB

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

Specified by:

getEntitiesById in interface IDB

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

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

Description copied from interface: IDB

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

Specified by:

getAllEntitiesOfType in interface IDB

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.

query

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

Description copied from interface: IDB

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)

Specified by:

query in interface IDB

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

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

Description copied from interface: IDB

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 .-)

Specified by:

queryOne in interface IDB

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

prepareQuery

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

Description copied from interface: IDB

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

Specified by:

prepareQuery in interface IDB

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

createEntitySchema

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

Description copied from interface: IDBSchema

create necessary structures inside DB for specified entity type. Means: it will create the table inside data base backend. It's separated because we do not wish to create such structures on demand if an entity should be made persistent. YOU should decide when it's time to do so ..

Specified by:

createEntitySchema in interface IDBSchema

Parameters:

aType - [IN] describe the entity type.

Throws:

Exception - is creating the schema was not successfully.

removeEntitySchema

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

Description copied from interface: IDBSchema

remove all data within DB back end related to the specified entity.

Specified by:

removeEntitySchema in interface IDBSchema

Parameters:

aType - [IN] describe the entity type.

Throws:

Exception - if operation failed and entity data couldn't be removed. Note It throws NO exception in case entity is unknown within these DB.