001: /*
002: * Copyright (c) 2001 - 2005 ivata limited.
003: * All rights reserved.
004: * -----------------------------------------------------------------------------
005: * ivata groupware may be redistributed under the GNU General Public
006: * License as published by the Free Software Foundation;
007: * version 2 of the License.
008: *
009: * These programs are free software; you can redistribute them and/or
010: * modify them under the terms of the GNU General Public License
011: * as published by the Free Software Foundation; version 2 of the License.
012: *
013: * These programs are distributed in the hope that they will be useful,
014: * but WITHOUT ANY WARRANTY; without even the implied warranty of
015: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
016: *
017: * See the GNU General Public License in the file LICENSE.txt for more
018: * details.
019: *
020: * If you would like a copy of the GNU General Public License write to
021: *
022: * Free Software Foundation, Inc.
023: * 59 Temple Place - Suite 330
024: * Boston, MA 02111-1307, USA.
025: *
026: *
027: * To arrange commercial support and licensing, contact ivata at
028: * http://www.ivata.com/contact.jsp
029: * -----------------------------------------------------------------------------
030: * $Log: QueryPersistenceManager.java,v $
031: * Revision 1.2 2005/10/11 18:55:29 colinmacleod
032: * Fixed some checkstyle and javadoc issues.
033: *
034: * Revision 1.1 2005/09/29 12:10:24 colinmacleod
035: * Moved from ivata groupware to ivata cms.
036: *
037: * Revision 1.2 2005/04/09 17:19:37 colinmacleod
038: * Changed copyright text to GPL v2 explicitly.
039: *
040: * Revision 1.1 2005/03/10 19:23:04 colinmacleod
041: * Moved to ivata groupware.
042: *
043: * Revision 1.1 2004/11/12 16:08:12 colinmacleod
044: * Removed dependencies on SSLEXT.
045: * Moved Persistence classes to ivata masks.
046: *
047: * Revision 1.2 2004/08/01 11:55:03 colinmacleod
048: * Added removeAll.
049: *
050: * Revision 1.1 2004/07/13 19:42:44 colinmacleod
051: * Moved project to POJOs from EJBs.
052: * Applied PicoContainer to services layer (replacing session EJBs).
053: * Applied Hibernate to persistence layer (replacing entity EJBs).
054: * -----------------------------------------------------------------------------
055: */
056: package com.ivata.mask.persistence;
057:
058: import java.util.List;
059:
060: import com.ivata.mask.persistence.listener.AddPersistenceListener;
061: import com.ivata.mask.persistence.listener.AmendPersistenceListener;
062: import com.ivata.mask.persistence.listener.RemovePersistenceListener;
063: import com.ivata.mask.valueobject.ValueObject;
064:
065: /**
066: * Extends the <strong>ivata masks</strong> persistence manager to include
067: * facilities to execute queries against the persistence store, and adds
068: * listeners.
069: *
070: * @author Colin MacLeod
071: * <a href='mailto:colin.macleod@ivata.com'>colin.macleod@ivata.com</a>
072: * @since ivata masks 1.0 (2004-03-27)
073: * @version $Revision: 1.2 $
074: */
075: public interface QueryPersistenceManager extends PersistenceManager {
076: /**
077: * Add an add listener to this persistence manager. This listener will be
078: * invoked whenever a value object of the given type is added to the system.
079: *
080: * @param dOClass Class to listen for. Whenever a value object of this class
081: * (or a subclass of this class) is added, then the listener will be
082: * invoked.
083: * @param listener The listener to add.
084: */
085: void addAddListener(Class dOClass, AddPersistenceListener listener);
086:
087: /**
088: * Add an amend listener to this persistence manager. This listener will be
089: * invoked whenever a value object of the given type is amended in the
090: * system.
091: *
092: * @param dOClass Class to listen for. Whenever a value object of this class
093: * (or a subclass of this class) is amended, then the listener will be
094: * invoked.
095: * @param listener The listener to add.
096: */
097: void addAmendListener(Class dOClass,
098: AmendPersistenceListener listener);
099:
100: /**
101: * Add a persitence to the system. This filter will be called every time
102: * a value object is read from the persistence store for viewing by a
103: * client.
104: *
105: * @param filter The filter to be added.
106: */
107: void addFilter(PersistenceFilter filter);
108:
109: /**
110: * Add an remove listener to this persistence manager. This listener will be
111: * invoked whenever a value object of the given type is removed from the
112: * system.
113: *
114: * @param dOClass Class to listen for. Whenever a value object of this class
115: * (or a subclass of this class) is removed, then the listener will be
116: * invoked.
117: * @param listener The listener to add.
118: */
119: void addRemoveListener(Class dOClass,
120: RemovePersistenceListener listener);
121:
122: /**
123: * <p>
124: * Find a list of value objects, with the given query name and arguments.
125: * The meaning of the query name is implementation specific - in the
126: * initialization of your concrete persistence manager, you define
127: * which queries are available.
128: * </p>
129: *
130: * @param session A valid persistence session. See
131: * {@link PersistenceManager#openSession openSession}.
132: * @param queryName The name of the query to execute. The actual definition
133: * of the query with this name depends on the implementation of the
134: * persistence manager.
135: * @param queryArguments All query arguments in the order in which they
136: * appear in the query text.
137: * @return <code>List</code> of <code>ValueObject</code> instances, matching
138: * the results of this query.
139: * @throws PersistenceException Thrown if the query cannot be performed for
140: * any reason.
141: */
142: List find(final PersistenceSession session, final String queryName,
143: final Object[] queryArguments) throws PersistenceException;
144:
145: /**
146: * <p>
147: * Find a list of value objects, with the given query name and arguments.
148: * The meaning of the query name is implementation specific - in the
149: * initialization of your concrete persistence manager, you define
150: * which queries are available.
151: * </p>
152: *
153: * @param session A valid persistence session. See
154: * {@link PersistenceManager#openSession openSession}.
155: * @param queryName The name of the query to execute. The actual definition
156: * of the query with this name depends on the implementation of the
157: * persistence manager.
158: * @param queryArguments All query arguments in the order in which they
159: * appear in the query text.
160: * @param pageSize Maximum number of items to return.
161: * @param pageNumber Defines where to start returning. This number
162: * multiplied by <code>pageSize</code> gives the total number of rows
163: * <em>before</em> the first row returned.
164: * @return <code>List</code> of <code>ValueObject</code> instances, matching
165: * the results of this query.
166: * @throws PersistenceException Thrown if the query cannot be performed for
167: * any reason.
168: */
169: List find(final PersistenceSession session, final String queryName,
170: final Object[] queryArguments, final Integer pageSize,
171: final Integer pageNumber) throws PersistenceException;
172:
173: /**
174: * <p>
175: * Find a single value object, using the given query name and arguments.
176: * The meaning of the query name is implementation specific - in the
177: * initialization of your concrete persistence manager, you define
178: * which queries are available.
179: * </p>
180: *
181: * @param session A valid persistence session. See
182: * {@link PersistenceManager#openSession openSession}.
183: * @param queryName The name of the query to execute. The actual definition
184: * of the query with this name depends on the implementation of the
185: * persistence manager.
186: * @param queryArguments All query arguments in the order in which they
187: * appear in the query text.
188: * @return a single <code>ValueObject</code> matching
189: * the result of this query.
190: * @throws PersistenceException Thrown if the query cannot be performed for
191: * any reason.
192: */
193: ValueObject findInstance(final PersistenceSession session,
194: final String queryName, final Object[] queryArguments)
195: throws PersistenceException;
196:
197: /**
198: * <p>
199: * Find a integer property value, using the given query name and arguments.
200: * The meaning of the query name is implementation specific - in the
201: * initialization of your concrete persistence manager, you define
202: * which queries are available.
203: * </p>
204: *
205: * @param session A valid persistence session. See
206: * {@link PersistenceManager#openSession openSession}.
207: * @param queryName The name of the query to execute. The actual definition
208: * of the query with this name depends on the implementation of the
209: * persistence manager.
210: * @param queryArguments All query arguments in the order in which they
211: * appear in the query text.
212: * @return a single <code>Integer</code> matching
213: * the result of this query.
214: * @throws PersistenceException Thrown if the query cannot be performed for
215: * any reason.
216: */
217: Integer findInteger(final PersistenceSession session,
218: final String queryName, final Object[] queryArguments)
219: throws PersistenceException;
220:
221: /**
222: * <p>
223: * Find a string property value, using the given query name and arguments.
224: * The meaning of the query name is implementation specific - in the
225: * initialization of your concrete persistence manager, you define
226: * which queries are available.
227: * </p>
228: *
229: * @param session A valid persistence session. See
230: * {@link PersistenceManager#openSession openSession}.
231: * @param queryName The name of the query to execute. The actual definition
232: * of the query with this name depends on the implementation of the
233: * persistence manager.
234: * @param queryArguments All query arguments in the order in which they
235: * appear in the query text.
236: * @return a single <code>String</code> matching
237: * the result of this query.
238: * @throws PersistenceException Thrown if the query cannot be performed for
239: * any reason.
240: */
241: String findString(final PersistenceSession session,
242: final String queryName, final Object[] queryArguments)
243: throws PersistenceException;
244:
245: /**
246: * <p>
247: * Remove a single value object from the system.
248: * </p>
249: *
250: * @param session A valid persistence session. See
251: * {@link PersistenceManager#openSession openSession}.
252: * @param valueObject The value object to be removed.
253: * @throws PersistenceException Thrown if the object cannot be removed for
254: * any reason.
255: */
256: void remove(final PersistenceSession session,
257: final ValueObject valueObject) throws PersistenceException;
258:
259: /**
260: * <p>
261: * Remove all value objects matching the given query name and arguments.
262: * The meaning of the query name is implementation specific - in the
263: * initialization of your concrete persistence manager, you define
264: * which queries are available.
265: * </p>
266: *
267: * @param session A valid persistence session. See
268: * {@link PersistenceManager#openSession openSession}.
269: * @param queryName The name of the query to execute. The actual definition
270: * of the query with this name depends on the implementation of the
271: * persistence manager.
272: * @param queryArguments All query arguments in the order in which they
273: * appear in the query text.
274: * @throws PersistenceException Thrown if the query cannot be performed for
275: * any reason.
276: */
277: void removeAll(final PersistenceSession session,
278: final String queryName, final Object[] queryArguments)
279: throws PersistenceException;
280: }
|