org.apache.ojb.broker.PersistenceBroker Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of db-ojb Show documentation
ObJectRelationalBridge (OJB) is an Object/Relational mapping tool that allows transparent persistence for Java Objects against relational databases.
The newest version!
package org.apache.ojb.broker;

/* Copyright 2002-2005 The Apache Software Foundation
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import org.apache.ojb.broker.accesslayer.ConnectionManagerIF;
import org.apache.ojb.broker.accesslayer.JdbcAccess;
import org.apache.ojb.broker.accesslayer.StatementManagerIF;
import org.apache.ojb.broker.accesslayer.sql.SqlGenerator;
import org.apache.ojb.broker.cache.ObjectCache;
import org.apache.ojb.broker.metadata.ClassDescriptor;
import org.apache.ojb.broker.metadata.DescriptorRepository;
import org.apache.ojb.broker.query.Query;
import org.apache.ojb.broker.util.BrokerHelper;
import org.apache.ojb.broker.util.ObjectModification;
import org.apache.ojb.broker.util.configuration.Configurable;
import org.apache.ojb.broker.util.sequence.SequenceManager;
import org.odbms.ObjectContainer;

import java.util.Collection;
import java.util.Enumeration;
import java.util.Iterator;

/**
 *
 * PersistenceBroker declares a protocol for persisting arbitrary objects.
 * A typical implementation might wrap an RDBMS access layer.
 *
 * @see org.apache.ojb.broker.core.PersistenceBrokerImpl
 * @see org.apache.ojb.broker.core.PersistenceBrokerBean
 *
 * @author Thomas Mahler
 * @version $Id: PersistenceBroker.java,v 1.1 2007-08-24 22:17:35 ewestfal Exp $
 */
public interface PersistenceBroker extends Configurable, ObjectContainer
{
    // *************************************************************************
    // Services handled by the PersistenceBroker
    // *************************************************************************

    /**
     * Returns the {@link org.apache.ojb.broker.accesslayer.StatementManagerIF} instance associated with this broker.
     * 
     * @return The statement manager
     */
    public StatementManagerIF serviceStatementManager();

    /**
     * Returns the {@link org.apache.ojb.broker.accesslayer.ConnectionManagerIF} instance associated with this broker.
     * 
     * @return The connection manager
     */
    public ConnectionManagerIF serviceConnectionManager();

    /**
     * Returns the {@link org.apache.ojb.broker.accesslayer.sql.SqlGenerator} instance associated with this broker.
     * 
     * @return The SQL generator
     */
    public SqlGenerator serviceSqlGenerator();

    /**
     * Returns the {@link org.apache.ojb.broker.accesslayer.JdbcAccess} instance associated with this broker.
     * 
     * @return The JDBC access object
     */
    public JdbcAccess serviceJdbcAccess();

    /**
     * Returns the {@link org.apache.ojb.broker.util.sequence.SequenceManager} instance associated with this broker.
     * 
     * @return The sequence manager
     */
    public SequenceManager serviceSequenceManager();

    /**
     * Returns the {@link org.apache.ojb.broker.util.BrokerHelper} instance associated with this broker, which
     * makes some additional helper methods available.
     * 
     * @return The broker helper object
     */
    public BrokerHelper serviceBrokerHelper();

    /**
     * Returns the {@link org.apache.ojb.broker.cache.ObjectCache} instance associated
     * with this broker.
     * 
     * @return The object cache
     */
    public ObjectCache serviceObjectCache();

    /**
     * Return the {@link IdentityFactory} instance associated with this broker.
     * 
     * @return The identity factory
     */
    public IdentityFactory serviceIdentity();


    // *************************************************************************
    // PersistenceBroker listener methods
    // *************************************************************************

    /**
     * Fires a broker event to inform all registered {@link PBListener} instances.
     * 
     * @param event The event to fire
     */
    public void fireBrokerEvent(PersistenceBrokerEvent event);

    /**
     * Fires a life cycle event to inform all registered {@link PBListener} instances.
     * 
     * @param event The event to fire
     */
    public void fireBrokerEvent(PBLifeCycleEvent event);

    /**
     * Fires a state event to inform all registered {@link PBListener} instances.
     * 
     * @param event The event to fire
     */
    public void fireBrokerEvent(PBStateEvent event);

    /**
     * Removes all temporary listeners from this broker.
     * Use with care, because some internals rely on this mechanism.
     * 
     * @see #removeListener(PBListener)
     */
    public void removeAllListeners() throws PersistenceBrokerException;

    /**
     * Removes all temporary and, if desired, permanent listeners from this broker.
     * Use with care, because some internals rely on this mechanism.
     * 
     * @param permanent Whether the listener will stay registered after closing
     *                  the broker
     * @see #removeListener(PBListener)
     */
    public void removeAllListeners(boolean permanent) throws PersistenceBrokerException;


    /**
     * Adds a temporary {@link org.apache.ojb.broker.PBListener} to this broker.
     * Note that temporary listeners will be removed upon closing a broker (returning
     * it to the pool).
     *
     * @param listener The listener to add
     * @see #addListener(PBListener, boolean)
     */
    public void addListener(PBListener listener) throws PersistenceBrokerException;

    /**
     * Adds a temporary or permanent {@link org.apache.ojb.broker.PBListener} to this broker,
     * depending on the parameter value. Note that temporary listeners will be removed upon
     * closing a broker (returning it to the pool).
     * 

     * NOTE: Handle carefully when using this method, keep in mind you don't
     * know which broker instance will be returned next time from the pool! To guarantee that
     * a listener is connect to every broker, the best way is to define your own implementation of
     * {@link org.apache.ojb.broker.core.PersistenceBrokerFactoryIF} or extend the default
     * one, {@link org.apache.ojb.broker.core.PersistenceBrokerFactoryDefaultImpl}. There you
     * can add the listener at creation of the {@link org.apache.ojb.broker.PersistenceBroker}
     * instances.
     * 
     * @param listener  The listener to add
     * @param permanent Whether the listener will stay registered after closing
     *                  the broker
     */
    public void addListener(PBListener listener, boolean permanent) throws PersistenceBrokerException;

    /**
     * Removes the specified listener from this broker.
     * 
     * @param listener The listener to remove
     */
    public void removeListener(PBListener listener) throws PersistenceBrokerException;


    // *************************************************************************
    // Transaction and instance handling stuff
    // *************************************************************************

    /**
     * Aborts and closes the current transaction. This abandons all persistent object modifications
     * and releases the associated locks.
     * 
     * @throws TransactionNotInProgressException If no transaction is currently in progress
     */
    public void abortTransaction() throws TransactionNotInProgressException;

    /**
     * Begins a transaction against the underlying RDBMS.
     * 
     * @throws TransactionInProgressException If there is already a transaction in progress
     */
    public void beginTransaction() throws TransactionInProgressException, TransactionAbortedException;

    /**
     * Commits and closes the current transaction. This commits all database-changing statements (e.g.
     * UPDATE, INSERT and DELETE) issued within the transaction since the last commit to the database,
     * and releases any locks held by the transaction.
     * 
     * @throws TransactionNotInProgressException If there is no transaction currently in progress
     * @throws TransactionAbortedException       If the transaction cannot be committed
     */
    public void commitTransaction() throws TransactionNotInProgressException, TransactionAbortedException;

    /**
     * Determines whether there is currently a transaction in progress.
     * 
     * @return true if there is a transaction in progress
     */
    public boolean isInTransaction() throws PersistenceBrokerException;

    /**
     * Closes this broker so that no further requests may be made on it. Closing a broker might release
     * it to the pool of available brokers, or might be garbage collected, at the option of the implementation.
     *
     * @return true if the broker was successfully closed
     */
    public boolean close();

    /**
     * Determines whether this broker is closed.
     * 
     * @return true if this instance is closed
     */
    public boolean isClosed();



    // *************************************************************************
    // Metadata service methods
    // *************************************************************************

    /**
     * Returns the metadata descriptor repository associated with this broker.
     * 
     * @return The descriptor repository
     */
    public DescriptorRepository getDescriptorRepository();

    /**
     * Get the {@link PBKey} for this broker.
     * 
     * @return The broker key
     */
    public PBKey getPBKey();

    /**
     * Returns the class descriptor for the given persistence capable class.
     * 
     * @param clazz The target class
     * @return The class descriptor
     * @throws PersistenceBrokerException If the class is not persistence capable, i.e.
     *         if no metadata was defined for this class and hence its class descriptor
     *         was not found
     */
    public ClassDescriptor getClassDescriptor(Class clazz) throws PersistenceBrokerException;

    /**
     * Determines whether the given class is persistence capable and thus has an associated
     * class descriptor in the metadata.
     * 
     * @param clazz The target class
     * @return true if a class descriptor was found
     */
    public boolean hasClassDescriptor(Class clazz);

    /**
     * Returns the top level class (most abstract class in terms of extents) from which the
     * given class extends. This may be a (abstract) base-class, an interface or the given
     * class itself, if no extent is defined.
     *
     * @param clazz The class to get the top level class for
     * @return The top level class for it
     * @throws PersistenceBrokerException If the class is not persistence capable,
     *         if no metadata was defined for this class
     */
    public Class getTopLevelClass(Class clazz) throws PersistenceBrokerException;

    // *************************************************************************
    // Object lifecycle
    // *************************************************************************

    /**
     * Clears the broker's internal cache.
     */
    public void clearCache() throws PersistenceBrokerException;

    /**
     * Removes the given object or, if it is an instance of {@link org.apache.ojb.broker.Identity},
     * the object identified by it, from the broker's internal cache. Note that the removal is
     * not recursive. This means, objects referenced by the removed object will not be
     * automatically removed from the cache by this operation.
     * 
     * @param objectOrIdentity The object to be removed from the cache or its identity 
     */
    public void removeFromCache(Object objectOrIdentity) throws PersistenceBrokerException;

    /**
     * Makes the given object persistent in the underlying persistence system.
     * This is usually done by issuing an INSERT ... or UPDATE ...  in an RDBMS.
     *
     * @param obj The object to store
     * @param modification Specifies what operation to perform (for generating optimized SQL)
     */
    public void store(Object obj,
                      ObjectModification modification) throws PersistenceBrokerException;

    /**
     * Make the given object persistent in the underlying persistence system.
     * This is usually done by issuing an INSERT ... or UPDATE ...  in an RDBMS.
     * 
     * @param obj The object to store
     */
    public void store(Object obj) throws PersistenceBrokerException;

    /**
     * Deletes the given object's persistent representation in the underlying persistence system.
     * This is usually done by issuing a DELETE ... in an RDBMS
     * 
     * @param obj The object to delete
     */
    public void delete(Object obj) throws PersistenceBrokerException;

    /**
     * Deletes an m:n implementor which defines the relationship between two persistent objects.
     * This is usually a row in an indirection table.

     * Note that OJB currently doesn't handle collection inheritance, so collections descriptors
     * are written per class. We try to match one of these collection descriptors, iterating from the left side
     * and looking for possible for classes on the right side using isAssignableFrom(rightClass).
     *
     * TODO: handle cache problems
     * TODO: delete more than one row if possible
     * 
     * @param m2nImpl The m:n implementor to delete
     */
    public void deleteMtoNImplementor(MtoNImplementor m2nImpl) throws PersistenceBrokerException;

    /**
     * Stores the given m:n implementor int the underlying persistence system. 
     * This is usually done by inserting a row in an indirection table.

     * Note that OJB currently doesn't handle collection inheritance, so collections descriptors
     * are written per class. We try to match one of these collection descriptors, iterating from the left side
     * and looking for possible for classes on the right side using isAssignableFrom(rightClass).
     * 
     * @param m2nImpl The m:n implementor to delete
     */
    public void addMtoNImplementor(MtoNImplementor m2nImpl) throws PersistenceBrokerException;

    /**
     * Deletes all objects matching the given query, from the underlying persistence system.
     * This is usually done via DELETE ... in an RDBMS.

     * Note: This method directly perform the delete statement ignoring any object
     * references and does not synchronize the cache - take care!
     * 
     * @param query The query determining the objects to delete
     */
    public void deleteByQuery(Query query) throws PersistenceBrokerException;

    // *************************************************************************
    // Query methods
    // *************************************************************************

    /**
     * Retrieve all references and collections of the given object irrespective of the
     * metadata settings defined for them.
     *  
     * @param obj The persistent object
     */
    public void retrieveAllReferences(Object obj) throws PersistenceBrokerException;

    /**
     * Retrieve the specified reference or collection attribute for the given persistent object.
     * 
     * @param obj      The persistent object
     * @param attrName The name of the attribute to retrieve
     */
    public void retrieveReference(Object obj, String attrName) throws PersistenceBrokerException;

    /**
     * Returns the number of elements that the given query will return.
     * 
     * @param query The query
     * @return The number of elements returned by the query
     */
    public int getCount(Query query) throws PersistenceBrokerException;

    /**
     * Retrieves the persistent objects matching the given query. Note that if the Query has
     * no criteria ALL persistent objects of the class targeted by the query will be returned.
     * 
     * @param query The query
     * @return The persistent objects matching the query
     */
    public Collection getCollectionByQuery(Query query) throws PersistenceBrokerException;

    /**
     * Retrieves the persistent objects matching the given query. The resulting collection will
     * be of the supplied collection type. Note that if the Query has no criteria ALL persistent
     * objects of the class targeted by the query will be returned.
     * 
     * @param collectionClass The collection type which needs to implement
     *                        {@link ManageableCollection}
     * @param query           The query
     * @return The persistent objects matching the query
     */
    public ManageableCollection getCollectionByQuery(Class collectionClass, Query query)
            throws PersistenceBrokerException;

    /**
     * Retrieves the persistent objects matching the given query and returns them as an iterator
     * which may, depending on the configured collection type, be reloading the objects from
     * the database upon calling {@link Iterator#next()}. Note that if the Query has no criteria
     * ALL persistent objects of the class targeted by the query will be returned.
     * 
     * @param query The query
     * @return The persistent objects matching the query
     */
    public Iterator getIteratorByQuery(Query query) throws PersistenceBrokerException;

    /**
     * Retrieves the rows (as Object[] instances) matching the given query and
     * returns them as an iterator which may, depending on the configured collection type, be reloading
     * the objects from the database upon calling {@link Iterator#next()}.
     * 
     * @param query The report query
     * @return The rows matching the query
     */
    public Iterator getReportQueryIteratorByQuery(Query query) throws PersistenceBrokerException;

    /**
     * Retrieve a persistent object from the underlying datastore by its identity. However, users
     * are encouraged to use {@link #getObjectByQuery(Query)} instead, as this method is mainly
     * intended to be used for internal handling of materialization by OID (e.g. in Proxies).
     * 
     * @param id The persistent object's id
     * @return The persistent object
     */
    public Object getObjectByIdentity(Identity id) throws PersistenceBrokerException;

    /**
     * Retrieve the (first) persistent object from the underlying datastore that matches the given
     * query.
     * 
     * @param query The query
     * @return The persistent object
     */
    public Object getObjectByQuery(Query query) throws PersistenceBrokerException;

    /**
     * Returns an enumeration of objects representing the primary keys for the objects that match
     * the given query. Mainly useful for EJB Finder Methods.

     * Note: This method is not yet aware of extents!
     * 
     * @param pkClass The class to use for the primary keys
     * @param query   The query
     * @return The pk enumeration
     */
    public Enumeration getPKEnumerationByQuery(Class pkClass, Query query)
            throws PersistenceBrokerException;
}