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


Copyright © 2001-2007 Uwyn sprl/bvba. All Rights Reserved.