com.uwyn.rife.database.querymanagers.generic
Interface GenericQueryManager<BeanType>

All Superinterfaces:

ValidationContext

All Known Implementing Classes:

AbstractGenericQueryManager, ContentQueryManager, GenericQueryManagerDelegate

public interface GenericQueryManager<BeanType>
extends ValidationContext

A GenericQueryManager provides features that make it easy to persist and retrieve beans in a database with single method calls. An instance of the manager can by obtained by using the GenericQueryManagerFactory class.

Callbacks are also supported to make it possible to interact with the persistence actions in a bean-centric way. More information can be found in the Callbacks interface.

Since:

1.0

Version:

$Revision: 3634 $

Author:

Geert Bevin (gbevin[remove] at uwyn dot com)

See Also:

GenericQueryManagerFactory, Callbacks

Method Summary

void	addListener(GenericQueryManagerListener listener) Add the listener to the manager to get notifications when actions were successful.
int	count() Count the number of beans persisted.
int	count(CountQuery query) Count the number of beans persisted with a custom CountQuery.
<OtherBeanType> GenericQueryManager<OtherBeanType>	createNewManager(Class<OtherBeanType> beanClass) Create a new generic query manager of the same kind but for another bean class.
boolean	delete(DeleteQuery query) Delete beans selected by the passed in DeleteQuery
boolean	delete(int objectId) Delete a single identified bean
Class	getBaseClass() Get the handled class
CountQuery	getCountQuery() Get the base CountQuery used to count the number of beans persisted under this manager
DeleteQuery	getDeleteQuery() Return the base DeleteQuery that would be used to delete beans
DeleteQuery	getDeleteQuery(int objectId) Return the base DeleteQuery that would be used to delete a single bean
String	getIdentifierName() Get the name of the property defined as the identifier.
int	getIdentifierValue(BeanType bean) Get the value of the property defined as the identifier.
CreateTable	getInstallTableQuery() Get the query that would be used to install the table.
RestoreQuery	getRestoreQuery() Get the base query used to restore beans.
RestoreQuery	getRestoreQuery(int objectId) Get the base query used to restore a single identifed bean.
String	getTable() Get the managed database table name
int	insert(BeanType bean) Insert a bean in the database.
void	install() Install the database structure into the database.
void	install(CreateTable query) Install the database structure into the database using a custom query.
void	remove() Remove the database structure
void	removeListeners() Remove all the listeners that are registered to the manager.
List<BeanType>	restore() Restore all the beans persisted under this manager.
boolean	restore(DbRowProcessor rowProcessor) Restore all beans using the row processor provided.
BeanType	restore(int objectId) Restore a single bean using the identifier.
List<BeanType>	restore(RestoreQuery query) Restore a list of beans that match the provided RestoreQuery.
boolean	restore(RestoreQuery query, DbRowProcessor rowProcessor) Restore a list of beans that match the provided RestoreQuery and process with the DbRowProcessor.
BeanType	restoreFirst(RestoreQuery query) Restore the first bean that matches the RestoreQuery.
int	save(BeanType bean) Persist a bean.
int	update(BeanType bean) Update an existing bean in the database.

Methods inherited from interface com.uwyn.rife.site.ValidationContext

validate

Method Detail

getBaseClass

Class getBaseClass()

Get the handled class

Returns:

the handled class

Since:

1.0

getTable

String getTable()

Get the managed database table name

Returns:

the table name

Since:

1.0

getIdentifierName

String getIdentifierName()

Get the name of the property defined as the identifier.

Defaults to "id".

Returns:

the name of the property defined as the identifier

Since:

1.0

getIdentifierValue

int getIdentifierValue(BeanType bean)
                       throws DatabaseException

Get the value of the property defined as the identifier.

The property defaults to "id".

Parameters:

bean - the bean to retrieve the identifier value for

Returns:

the value of the property defined as the identifier

Throws:

DatabaseException

Since:

1.0

install

void install()
             throws DatabaseException

Install the database structure into the database.

This method will cause the structure needed to persist the bean to be installed into the database. This includes any validatity checks that the database supports and that have already been defined. Including (but not limited to): length, notNull, notEmpty, etc. etc. This method will fail semi-gracefully if the installation fails. Generally it's best to catch the DatabaseException and assume that the database is already installed.

Throws:

DatabaseException

Since:

1.0

See Also:

remove()

install

void install(CreateTable query)
             throws DatabaseException

Install the database structure into the database using a custom query.

This method will cause the structure needed to persist the bean to be installed into the database using the provided custom query. The custom query is usually obtained by using getInstallTableQuery(). This includes any validatity checks that the database supports and that have already been defined. Including (but not limited to): length, notNull, notEmpty, etc. etc. This method will fail semi-gracefully if the installation fails. Generally it's best to catch the DatabaseException and assume that the database is already installed.

Parameters:

query - the CreateTable query to use to create the table

Throws:

DatabaseException

Since:

1.0

See Also:

install(), remove()

remove

void remove()
            throws DatabaseException

Remove the database structure

This method will cause the database structure to be removed from the database deleting all saved beans in the process. No new beans of this type can be persisted until the database structure is reinstalled.

Throws:

DatabaseException

Since:

1.0

See Also:

install()

save

int save(BeanType bean)
         throws DatabaseException

Persist a bean.

This method allows a person to persist a bean to a DB to be later restored. A bean to be persisted must have at least one integer identifier and one bean property both with accessors. If the identifier value is greater than or equal to 0, the bean is attempted to be updated first, if this fails (or the identifier is -1) the bean is assumed to be a new bean and a new sequential identifier is generated by the database.

Parameters:

bean - the bean to be saved

Returns:

the identifier assigned to the new/updated bean

Throws:

DatabaseException

Since:

1.0

insert

int insert(BeanType bean)
           throws DatabaseException

Insert a bean in the database.

This method specifically forces insertion of the bean into the database. This method is only recommended for use when you know what you are doing. The save(Object bean) method is safer because it can detect whether to insert or update the bean in that database, leading to safer, simpler code. Bean restrictions mirror save(Object bean).

Parameters:

bean - the bean to be inserted

Returns:

the indentier assigned to the new bean

Throws:

DatabaseException

Since:

1.0

See Also:

save(Object bean)

update

int update(BeanType bean)
           throws DatabaseException

Update an existing bean in the database.

This method specifically forces the updating of the bean into the database. This method is only recommended for use when you know what you are doing. The save(Object bean) method is safer because it can detect whether to insert or update the bean in that database, leading to safer, simpler code. Bean restrictions mirror save(Object bean).

Parameters:

bean - the bean to be updated

Returns:

the indentier assigned to the new bean

Throws:

DatabaseException

Since:

1.0

See Also:

save(Object bean)

restore

List<BeanType> restore()
                       throws DatabaseException

Restore all the beans persisted under this manager.

This method will return a List of all the beans persisted under this manager.

Returns:

a List of all the persisted beans

Throws:

DatabaseException

Since:

1.0

restore

BeanType restore(int objectId)
                 throws DatabaseException

Restore a single bean using the identifier.

This method will return a single bean having the provided identifier. Since the identifier is unique, you can be assured of a single bean with a persistent id. This id is never changed under normal circumstances.

Parameters:

objectId - the identifier to identify the bean to restore

Returns:

the bean that matches the identifier provided

Throws:

DatabaseException

Since:

1.0

restore

boolean restore(DbRowProcessor rowProcessor)
                throws DatabaseException

Restore all beans using the row processor provided.

This method will return all beans using a DbRowProcessor for reduced memory requirements as opposed to the full List version of restore().

Parameters:

rowProcessor - the DbRowProcessor each row should be passed to

Returns:

true if beans were restored, false if not

Throws:

DatabaseException

Since:

1.0

See Also:

restore()

restoreFirst

BeanType restoreFirst(RestoreQuery query)
                      throws DatabaseException

Restore the first bean that matches the RestoreQuery.

This method will return the first bean that matches the RestoreQuery. Especially useful for selecting the first returned bean from a complex query.

Parameters:

query - the query the bean should be restored from

Returns:

the first bean that matches the RestoreQuery

Throws:

DatabaseException

Since:

1.0

See Also:

restore(RestoreQuery)

restore

List<BeanType> restore(RestoreQuery query)
                       throws DatabaseException

Restore a list of beans that match the provided RestoreQuery.

This method will return a list of beans that match the provided RestoreQuery. This can be used for more complex queries, or for exclusion of certain beans from the results.

Parameters:

query - the query the beans should be restored from

Returns:

a list containing all the restored beans

Throws:

DatabaseException

Since:

1.0

See Also:

restore()

restore

boolean restore(RestoreQuery query,
                DbRowProcessor rowProcessor)
                throws DatabaseException

Restore a list of beans that match the provided RestoreQuery and process with the DbRowProcessor.

This method will return a list of beans that match the provided RestoreQuery and process these matches with the provided DbRowProcessor. This can be used for more memory-intensive (or larger result sets) complex queries or for the exclusion of certain beans from the results.

Parameters:

query - the query the beans should be restored from

rowProcessor - the row processor that should be used to process each matched bean row

Returns:

true if beans were processed, false if not

Throws:

DatabaseException

Since:

1.0

getInstallTableQuery

CreateTable getInstallTableQuery()
                                 throws DatabaseException

Get the query that would be used to install the table.

This method will return the query that would be used to install the database structure. Can be used to modify the structure if i custom structure is needed. Mostly likely to be passed into install(CreateTable)

Returns:

the query that would be used to install the database structure

Throws:

DatabaseException

Since:

1.0

getRestoreQuery

RestoreQuery getRestoreQuery()

Get the base query used to restore beans.

This method will return the base query that would be used to restore beans with restore(). This can be used to restrict the query so that less beans are returned or certain beans are returned.

Returns:

the query that would be used to restore a number of beans

Since:

1.0

getRestoreQuery

RestoreQuery getRestoreQuery(int objectId)

Get the base query used to restore a single identifed bean.

This method will return the base query that would be used to restore a single bean with restore(int). This can be used to restrict the query so that a bean not matching the query will not be returned.

Returns:

the query that would be used to restore a single identified bean

Since:

1.0

count

int count()
          throws DatabaseException

Count the number of beans persisted.

This method will count the total number of beans persisted under this manager.

Returns:

the number of beans persisted under this manager

Throws:

DatabaseException

Since:

1.0, 1.0

count

int count(CountQuery query)
          throws DatabaseException

Count the number of beans persisted with a custom CountQuery.

This method will count the total number of beans persisted under this manager that match the provided CountQuery.

Parameters:

query - the query that will be used to determine which beans to count

Returns:

the number of beans persisted under this manager that match the provided query

Throws:

DatabaseException

Since:

1.0

getCountQuery

CountQuery getCountQuery()

Get the base CountQuery used to count the number of beans persisted under this manager

Returns:

the query that would be used to count the total number of beans persisted under this managerù

Since:

1.0

delete

boolean delete(int objectId)
               throws DatabaseException

Delete a single identified bean

This method will delete the bean identifed by the passed in identifier.

Parameters:

objectId - the identifier of the bean

Returns:

true if the deletion suceeded, false if it did not

Throws:

DatabaseException

Since:

1.0

delete

boolean delete(DeleteQuery query)
               throws DatabaseException

Delete beans selected by the passed in DeleteQuery

This method will delete all beans identified by the passed in DeleteQuery.

Parameters:

query - the query to select the beans

Returns:

true if the deletion suceeded, false if it did not

Throws:

DatabaseException

Since:

1.0

getDeleteQuery

DeleteQuery getDeleteQuery()

Return the base DeleteQuery that would be used to delete beans

Returns:

the base DeleteQuery

Since:

1.0

getDeleteQuery

DeleteQuery getDeleteQuery(int objectId)

Return the base DeleteQuery that would be used to delete a single bean

Parameters:

objectId - the identifier to fill into the base DeleteQuery

Returns:

the base DeleteQuery

Since:

1.0

addListener

void addListener(GenericQueryManagerListener listener)

Add the listener to the manager to get notifications when actions were successful.

Parameters:

listener - the listener that has to be added

Since:

1.5

removeListeners

void removeListeners()

Remove all the listeners that are registered to the manager.

Since:

1.5

createNewManager

<OtherBeanType> GenericQueryManager<OtherBeanType> createNewManager(Class<OtherBeanType> beanClass)

Create a new generic query manager of the same kind but for another bean class.

Parameters:

beanClass - the class of the bean for which the new generic query manager has to be created

Returns:

a new generic query manager instance

Since:

1.6