Interface Persistence

  • All Known Implementing Classes:
    SQLEngine

    public interface Persistence
    The persistence engine implements this interface in order to allow objects to be created, removed, loaded, stored, locked and checked for dirtyness.

    The caller takes full responsibility to assure integrity of transactions and object caching and only relies on the engine to assist in assuring that through the mechanisms available to it.

    All method calls provide an open connection into the persistence storage. The connection is opened by and maintained in the context of a transaction. The type of the connection depends on the persistence engine (JDBC, JNDI, etc).

    All method calls provide the object fields and the object identity. The engine must always use the identity passed in the method call and never the identity contained in the object itself.

    The stamp is an arbitrary object that is returned on object creation and loading and passed when performing a dirty check. The stamp can be used to detect object dirtyness in a more efficient manner in database that support a stamping mechanism (e.g. Oracle RAWID, Sybase TIMESTAMP).

    An implementation of this object must be re-entrant and thread safe. It must depend on the connection passed in each method call and never hold a reference to a connection.

    Version:
    $Revision: 8752 $ $Date: 2006-04-26 16:24:34 -0600 (Wed, 26 Apr 2006) $
    Author:
    Assaf Arkin
    See Also:
    TransactionContext, PersistenceQuery
    • Method Detail

      • create

        Identity create​(Database database,
                        java.lang.Object conn,
                        ProposedEntity entity,
                        Identity identity)
                 throws PersistenceException
        Creates a new object in persistence storage. Called for an object that was created during the transaction when the identity of that object is known. Creates a new record in persistence storage. Must detect an attempt to create an object with the same identity and must retain a lock on the object after creation. If the identity is null, an identity might be created and returned by this method.
        Parameters:
        conn - An open connection
        entity - The fields to store
        identity - The object's identity
        Returns:
        The object's identity
        Throws:
        PersistenceException - An object with the same identity already exists in persistent storage or any other persistence error occured.
      • createQuery

        PersistenceQuery createQuery​(QueryExpression query,
                                     java.lang.Class<?>[] types,
                                     AccessMode accessMode)
                              throws QueryException
        Creates and returns a new query object. The query object is used to execute a query against persistent storage and fetch the results of the query. The query parameter types are specified prehand. If a particular parameter type is unknown, null may be used and type checking will defer to query execution.
        Parameters:
        query - The query expression
        types - List of all parameter types, or null
        Returns:
        A new query object that can be executed
        Throws:
        QueryException - The query is invalid