/*
* Copyright (c) 2001 - 2005 ivata limited.
* All rights reserved.
* -----------------------------------------------------------------------------
* ivata groupware may be redistributed under the GNU General Public
* License as published by the Free Software Foundation;
* version 2 of the License.
*
* These programs are free software; you can redistribute them and/or
* modify them under the terms of the GNU General Public License
* as published by the Free Software Foundation; version 2 of the License.
*
* These programs are distributed in the hope that they will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
*
* See the GNU General Public License in the file LICENSE.txt for more
* details.
*
* If you would like a copy of the GNU General Public License write to
*
* Free Software Foundation, Inc.
* 59 Temple Place - Suite 330
* Boston, MA 02111-1307, USA.
*
*
* To arrange commercial support and licensing, contact ivata at
* http://www.ivata.com/contact.jsp
* -----------------------------------------------------------------------------
* $Log: QueryPersistenceManager.java,v $
* Revision 1.2 2005/10/11 18:55:29 colinmacleod
* Fixed some checkstyle and javadoc issues.
*
* Revision 1.1 2005/09/29 12:10:24 colinmacleod
* Moved from ivata groupware to ivata cms.
*
* Revision 1.2 2005/04/09 17:19:37 colinmacleod
* Changed copyright text to GPL v2 explicitly.
*
* Revision 1.1 2005/03/10 19:23:04 colinmacleod
* Moved to ivata groupware.
*
* Revision 1.1 2004/11/12 16:08:12 colinmacleod
* Removed dependencies on SSLEXT.
* Moved Persistence classes to ivata masks.
*
* Revision 1.2 2004/08/01 11:55:03 colinmacleod
* Added removeAll.
*
* Revision 1.1 2004/07/13 19:42:44 colinmacleod
* Moved project to POJOs from EJBs.
* Applied PicoContainer to services layer (replacing session EJBs).
* Applied Hibernate to persistence layer (replacing entity EJBs).
* -----------------------------------------------------------------------------
*/
package com.ivata.mask.persistence;
import java.util.List;
import com.ivata.mask.persistence.listener.AddPersistenceListener;
import com.ivata.mask.persistence.listener.AmendPersistenceListener;
import com.ivata.mask.persistence.listener.RemovePersistenceListener;
import com.ivata.mask.valueobject.ValueObject;
/**
* Extends the <strong>ivata masks</strong> persistence manager to include
* facilities to execute queries against the persistence store, and adds
* listeners.
*
* @author Colin MacLeod
* <a href='mailto:colin.macleod@ivata.com'>colin.macleod@ivata.com</a>
* @since ivata masks 1.0 (2004-03-27)
* @version $Revision: 1.2 $
*/
public interface QueryPersistenceManager extends PersistenceManager {
/**
* Add an add listener to this persistence manager. This listener will be
* invoked whenever a value object of the given type is added to the system.
*
* @param dOClass Class to listen for. Whenever a value object of this class
* (or a subclass of this class) is added, then the listener will be
* invoked.
* @param listener The listener to add.
*/
void addAddListener(Class dOClass, AddPersistenceListener listener);
/**
* Add an amend listener to this persistence manager. This listener will be
* invoked whenever a value object of the given type is amended in the
* system.
*
* @param dOClass Class to listen for. Whenever a value object of this class
* (or a subclass of this class) is amended, then the listener will be
* invoked.
* @param listener The listener to add.
*/
void addAmendListener(Class dOClass, AmendPersistenceListener listener);
/**
* Add a persitence to the system. This filter will be called every time
* a value object is read from the persistence store for viewing by a
* client.
*
* @param filter The filter to be added.
*/
void addFilter(PersistenceFilter filter);
/**
* Add an remove listener to this persistence manager. This listener will be
* invoked whenever a value object of the given type is removed from the
* system.
*
* @param dOClass Class to listen for. Whenever a value object of this class
* (or a subclass of this class) is removed, then the listener will be
* invoked.
* @param listener The listener to add.
*/
void addRemoveListener(Class dOClass, RemovePersistenceListener listener);
/**
* <p>
* Find a list of value objects, with the given query name and arguments.
* The meaning of the query name is implementation specific - in the
* initialization of your concrete persistence manager, you define
* which queries are available.
* </p>
*
* @param session A valid persistence session. See
* {@link PersistenceManager#openSession openSession}.
* @param queryName The name of the query to execute. The actual definition
* of the query with this name depends on the implementation of the
* persistence manager.
* @param queryArguments All query arguments in the order in which they
* appear in the query text.
* @return <code>List</code> of <code>ValueObject</code> instances, matching
* the results of this query.
* @throws PersistenceException Thrown if the query cannot be performed for
* any reason.
*/
List find(final PersistenceSession session,
final String queryName,
final Object [] queryArguments) throws PersistenceException;
/**
* <p>
* Find a list of value objects, with the given query name and arguments.
* The meaning of the query name is implementation specific - in the
* initialization of your concrete persistence manager, you define
* which queries are available.
* </p>
*
* @param session A valid persistence session. See
* {@link PersistenceManager#openSession openSession}.
* @param queryName The name of the query to execute. The actual definition
* of the query with this name depends on the implementation of the
* persistence manager.
* @param queryArguments All query arguments in the order in which they
* appear in the query text.
* @param pageSize Maximum number of items to return.
* @param pageNumber Defines where to start returning. This number
* multiplied by <code>pageSize</code> gives the total number of rows
* <em>before</em> the first row returned.
* @return <code>List</code> of <code>ValueObject</code> instances, matching
* the results of this query.
* @throws PersistenceException Thrown if the query cannot be performed for
* any reason.
*/
List find(final PersistenceSession session,
final String queryName,
final Object [] queryArguments,
final Integer pageSize,
final Integer pageNumber) throws PersistenceException;
/**
* <p>
* Find a single value object, using the given query name and arguments.
* The meaning of the query name is implementation specific - in the
* initialization of your concrete persistence manager, you define
* which queries are available.
* </p>
*
* @param session A valid persistence session. See
* {@link PersistenceManager#openSession openSession}.
* @param queryName The name of the query to execute. The actual definition
* of the query with this name depends on the implementation of the
* persistence manager.
* @param queryArguments All query arguments in the order in which they
* appear in the query text.
* @return a single <code>ValueObject</code> matching
* the result of this query.
* @throws PersistenceException Thrown if the query cannot be performed for
* any reason.
*/
ValueObject findInstance(final PersistenceSession session,
final String queryName,
final Object [] queryArguments) throws PersistenceException;
/**
* <p>
* Find a integer property value, using the given query name and arguments.
* The meaning of the query name is implementation specific - in the
* initialization of your concrete persistence manager, you define
* which queries are available.
* </p>
*
* @param session A valid persistence session. See
* {@link PersistenceManager#openSession openSession}.
* @param queryName The name of the query to execute. The actual definition
* of the query with this name depends on the implementation of the
* persistence manager.
* @param queryArguments All query arguments in the order in which they
* appear in the query text.
* @return a single <code>Integer</code> matching
* the result of this query.
* @throws PersistenceException Thrown if the query cannot be performed for
* any reason.
*/
Integer findInteger(final PersistenceSession session,
final String queryName,
final Object [] queryArguments) throws PersistenceException;
/**
* <p>
* Find a string property value, using the given query name and arguments.
* The meaning of the query name is implementation specific - in the
* initialization of your concrete persistence manager, you define
* which queries are available.
* </p>
*
* @param session A valid persistence session. See
* {@link PersistenceManager#openSession openSession}.
* @param queryName The name of the query to execute. The actual definition
* of the query with this name depends on the implementation of the
* persistence manager.
* @param queryArguments All query arguments in the order in which they
* appear in the query text.
* @return a single <code>String</code> matching
* the result of this query.
* @throws PersistenceException Thrown if the query cannot be performed for
* any reason.
*/
String findString(final PersistenceSession session,
final String queryName,
final Object [] queryArguments) throws PersistenceException;
/**
* <p>
* Remove a single value object from the system.
* </p>
*
* @param session A valid persistence session. See
* {@link PersistenceManager#openSession openSession}.
* @param valueObject The value object to be removed.
* @throws PersistenceException Thrown if the object cannot be removed for
* any reason.
*/
void remove(final PersistenceSession session,
final ValueObject valueObject) throws PersistenceException;
/**
* <p>
* Remove all value objects matching the given query name and arguments.
* The meaning of the query name is implementation specific - in the
* initialization of your concrete persistence manager, you define
* which queries are available.
* </p>
*
* @param session A valid persistence session. See
* {@link PersistenceManager#openSession openSession}.
* @param queryName The name of the query to execute. The actual definition
* of the query with this name depends on the implementation of the
* persistence manager.
* @param queryArguments All query arguments in the order in which they
* appear in the query text.
* @throws PersistenceException Thrown if the query cannot be performed for
* any reason.
*/
void removeAll(final PersistenceSession session,
final String queryName,
final Object [] queryArguments) throws PersistenceException;
}
|