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: PersistenceSession.java,v $
031: * Revision 1.5 2005/04/09 18:04:15 colinmacleod
032: * Changed copyright text to GPL v2 explicitly.
033: *
034: * Revision 1.4 2005/03/10 10:32:21 colinmacleod
035: * Added cancel method.
036: *
037: * Revision 1.3 2005/01/19 12:38:34 colinmacleod
038: * Renamed CausedByException to SystemException.
039: *
040: * Revision 1.2 2005/01/06 22:13:22 colinmacleod
041: * Moved up a version number.
042: * Changed copyright notices to 2005.
043: * Updated the documentation:
044: * - started working on multiproject:site docu.
045: * - changed the logo.
046: * Added checkstyle and fixed LOADS of style issues.
047: * Added separate thirdparty subproject.
048: * Added struts (in web), util and webgui (in webtheme) from ivata op.
049: *
050: * Revision 1.1 2004/12/29 20:07:08 colinmacleod
051: * Renamed subproject masks to mask.
052: *
053: * Revision 1.1 2004/11/12 15:10:41 colinmacleod
054: * Moved persistence classes from ivata op as a replacement for
055: * ValueObjectLocator.
056: *
057: * Revision 1.1 2004/07/13 19:42:44 colinmacleod
058: * Moved project to POJOs from EJBs.
059: * Applied PicoContainer to services layer (replacing session EJBs).
060: * Applied Hibernate to persistence layer (replacing entity EJBs).
061: * -----------------------------------------------------------------------------
062: */
063: package com.ivata.mask.persistence;
064:
065: import java.io.Serializable;
066: import java.sql.Connection;
067:
068: /**
069: * A persistence session must be opened (by calling {@link
070: * PersistenceManager#openSession PersistenceManager.openSession} before
071: * performing any other persistence operation. It can be considered analagous to
072: * a transaction in a database environment.
073: *
074: * @author Colin MacLeod
075: * <a href='mailto:colin.macleod@ivata.com'>colin.macleod@ivata.com</a>
076: * @since ivata masks 0.3 (2004-03-27)
077: * @version $Revision: 1.5 $
078: * @see PersistenceManager
079: */
080: public interface PersistenceSession extends Serializable {
081: /**
082: * <p>
083: * Cancel all operations performed in this session. These operations should
084: * then be rolled back in <code>close</code>
085: * </p>
086: * @throws PersistenceException
087: * if the session cannot be cancelled for any reason.
088: */
089: void cancel() throws PersistenceException;
090:
091: /**
092: * <p>
093: * Commit any changes made in this transaction to the data store. You must
094: * call this method after performing persistence methods - use it within a
095: * <code>finally</code> block as shown in the example code.
096: * </p>
097: * <p>
098: * TODO: link to demo code reference here.
099: * </p>
100: *
101: * @throws PersistenceException
102: * if the session cannot be closed/committed for any reason.
103: */
104: void close() throws PersistenceException;
105:
106: /**
107: * <p>
108: * Access the data connection wrapped by this persistence session. You
109: * should think twice before using this method - not all implementations of
110: * a persistence layer may use a database, and therefore this may not always
111: * be appropriate.
112: * </p>
113: *
114: * @return valid database connection for the underlying data store.
115: * @throws PersistenceException
116: * if the database connection cannot be retrieved for any reason
117: * (including lack of support by the underlying persistence
118: * layer).
119: */
120: Connection getConnection() throws PersistenceException;
121:
122: /**
123: * Return a system-specific (i.e. <strong>ivata masks</strong> knows nothing
124: * about it's specific implementation) session object - this is stored when
125: * <code>PersistenceManager.openSession</code> is called with an object
126: * parameter.
127: *
128: * @return system-specific session object, or <code>null</code> if none was
129: * set.
130: */
131: Object getSystemSession();
132: }
|