001: /*
002: * Copyright (c) 2001 - 2005 ivata limited.
003: * All rights reserved.
004: * -----------------------------------------------------------------------------
005: * ivata masks 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: PersistenceManager.java,v $
031: * Revision 1.5 2005/09/29 12:08:02 colinmacleod
032: * Removed PersistenceRights (for now, moved to ivata groupware).
033: * Changed openSession method in PersistenceManager to accept HTTP
034: * session.
035: *
036: * Revision 1.4 2005/04/09 18:04:15 colinmacleod
037: * Changed copyright text to GPL v2 explicitly.
038: *
039: * Revision 1.3 2005/01/19 12:38:34 colinmacleod
040: * Renamed CausedByException to SystemException.
041: *
042: * Revision 1.2 2005/01/06 22:13:22 colinmacleod
043: * Moved up a version number.
044: * Changed copyright notices to 2005.
045: * Updated the documentation:
046: * - started working on multiproject:site docu.
047: * - changed the logo.
048: * Added checkstyle and fixed LOADS of style issues.
049: * Added separate thirdparty subproject.
050: * Added struts (in web), util and webgui (in webtheme) from ivata op.
051: *
052: * Revision 1.1 2004/12/29 20:07:08 colinmacleod
053: * Renamed subproject masks to mask.
054: *
055: * Revision 1.1 2004/11/12 15:10:41 colinmacleod
056: * Moved persistence classes from ivata op as a replacement for
057: * ValueObjectLocator.
058: *
059: * Revision 1.2 2004/08/01 11:55:03 colinmacleod
060: * Added removeAll.
061: *
062: * Revision 1.1 2004/07/13 19:42:44 colinmacleod
063: * Moved project to POJOs from EJBs.
064: * Applied PicoContainer to services layer (replacing session EJBs).
065: * Applied Hibernate to persistence layer (replacing entity EJBs).
066: * -----------------------------------------------------------------------------
067: */
068: package com.ivata.mask.persistence;
069:
070: import java.io.Serializable;
071: import java.util.List;
072:
073: import javax.servlet.http.HttpSession;
074:
075: import com.ivata.mask.valueobject.ValueObject;
076:
077: /**
078: * <p>
079: * Defines how data objects are stored and retrieved throughout the system.
080: * </p>
081: * <p>
082: * For each <strong>ivata masks </strong> implementation, you will need an
083: * implementation of this interface. Think of it as an <a
084: * href='http://c2.com/cgi/wiki?AdapterPattern'>Adapter </a> to your persistence
085: * layer.
086: * </p>
087: *
088: * @author Colin MacLeod
089: * <a href='mailto:colin.macleod@ivata.com'>colin.macleod@ivata.com</a>
090: * @since ivata masks 0.3 (2004-03-27)
091: * @version $Revision: 1.5 $
092: */
093: public interface PersistenceManager {
094: /**
095: * Store a new value object. This is analagous to a database
096: * <code>INSERT</code>.
097: *
098: * @param session
099: * current persistence session. Should have been previously
100: * opened with {@link #openSession() openSession()}.
101: * @param valueObject
102: * new value object which should be saved.
103: * @return the value object which is currently persisted.
104: * @throws PersistenceException
105: * if the object cannot be persisted.
106: */
107: ValueObject add(PersistenceSession session, ValueObject valueObject)
108: throws PersistenceException;
109:
110: /**
111: * Amend a previously stored value object, after changes have been made.
112: * This is analagous to a database <code>UPDATE</code>.
113: *
114: * @param session
115: * current persistence session. Should have been previously
116: * opened with {@link #openSession() openSession()}.
117: * @param valueObject
118: * value object for which changes should be saved.
119: * @throws PersistenceException
120: * if the object cannot be persisted.
121: */
122: void amend(PersistenceSession session, ValueObject valueObject)
123: throws PersistenceException;
124:
125: /**
126: * Find all value objects in the system with the given class. This is
127: * analagous to a database <code>SELECT * FROM ...</code>.
128: *
129: * @param session
130: * current persistence session. Should have been previously
131: * opened with {@link #openSession() openSession()}.
132: * @param dOClass
133: * class of value objects to return.
134: * @return a <code>List</code> of instances of the class specified.
135: * @throws PersistenceException
136: * if no object can be found, or there is an error looking for
137: * objects of this class.
138: */
139: List findAll(PersistenceSession session, Class dOClass)
140: throws PersistenceException;
141:
142: /**
143: * Find a single value object with the unique identifier given. This is
144: * analagous to a database <code>SELECT UNIQUE ... FROM WHERE ...</code>.
145: *
146: * @param session
147: * current persistence session. Should have been previously
148: * opened with {@link #openSession() openSession()}.
149: * @param dOClass
150: * class of value object to find.
151: * @param key
152: * unique identifier of the object to find. The exact meaning of
153: * this field depends on the persistence mechanism used.
154: * @return an instance of the class specified with the matching identifier.
155: * @throws PersistenceException
156: * if no object can be found, or there is an error looking for
157: * this object.
158: */
159: ValueObject findByPrimaryKey(PersistenceSession session,
160: Class dOClass, Serializable key)
161: throws PersistenceException;
162:
163: /**
164: * Before performing any other persistence operation, you need to open a
165: * valid persistence session. An <strong>ivata masks </strong> persistence
166: * session can be considered analagous to a database transaction.
167: *
168: * @param webSession Current HTTP session we are processing.
169: * @return a valid, open persistence session.
170: * @throws PersistenceException
171: * if the session cannot be opened for any reason.
172: */
173: PersistenceSession openSession(HttpSession webSession)
174: throws PersistenceException;
175:
176: /**
177: * Before performing any other persistence operation, you need to open a
178: * valid persistence session. An <strong>ivata masks </strong> persistence
179: * session can be considered analagous to a database transaction.
180: *
181: * @param systemSession system/implementation-specific session object which
182: * will be wrapped by the persistence session.
183: * @return a valid, open persistence session.
184: * @throws PersistenceException
185: * if the session cannot be opened for any reason.
186: */
187: PersistenceSession openSession(Object systemSession)
188: throws PersistenceException;
189:
190: /**
191: * Remove a value object from the persistence store. This is analagous to a
192: * database <code>DELETE</code>.
193: *
194: * @param session
195: * current persistence session. Should have been previously
196: * opened with {@link #openSession() openSession()}.
197: * @param dOClass
198: * class of value object to remove.
199: * @param key
200: * unique identifier of the object to remove. The exact meaning
201: * of this field depends on the persistence mechanism used.
202: * @throws PersistenceException
203: * if the object cannot be removed.
204: */
205: void remove(PersistenceSession session, Class dOClass,
206: Serializable key) throws PersistenceException;
207: }
|