Package rife.database.querymanagers.generic

Interface GenericQueryManager<BeanType>

All Superinterfaces:
ValidationContext
All Known Implementing Classes:
AbstractGenericQueryManager, 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 be 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
See Also:

  • Method Details

    • 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:

    • 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:

    • 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:

    • 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 identifier assigned to the new bean
      Throws:
      DatabaseException
      Since:
      1.0
      See Also:

    • 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 identifier assigned to the new bean
      Throws:
      DatabaseException
      Since:
      1.0
      See Also:

    • 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

      boolean restore(BeanFetcher<BeanType> beanFetcher) throws DatabaseException
      Restore all beans using the bean fetcher provided.

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

      Parameters:
      beanFetcher - the RowProcessor each row should be passed to
      Returns:
      true if beans were restored, false if not
      Throws:
      DatabaseException
      Since:
      1.0
      See Also:

    • 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

      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

      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

    • restore

      boolean restore(RestoreQuery query, BeanFetcher<BeanType> beanFetcher) throws DatabaseException
      Restore a list of beans that match the provided RestoreQuery and process with the BeanFetcher.

      This method will return a list of beans that match the provided RestoreQuery and process these matches with the provided BeanFetcher. 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
      beanFetcher - the bean fetch 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 identified 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<BeanType> 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.0

    • removeListeners

      void removeListeners()
      Remove all the listeners that are registered to the manager.
      Since:
      1.0

    • 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.0