001: /*
002: * ====================================================================
003: * JAFFA - Java Application Framework For All
004: *
005: * Copyright (C) 2002 JAFFA Development Group
006: *
007: * This library is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU Lesser General Public
009: * License as published by the Free Software Foundation; either
010: * version 2.1 of the License, or (at your option) any later version.
011: *
012: * This library is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this library; if not, write to the Free Software
019: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
020: *
021: * Redistribution and use of this software and associated documentation ("Software"),
022: * with or without modification, are permitted provided that the following conditions are met:
023: * 1. Redistributions of source code must retain copyright statements and notices.
024: * Redistributions must also contain a copy of this document.
025: * 2. Redistributions in binary form must reproduce the above copyright notice,
026: * this list of conditions and the following disclaimer in the documentation
027: * and/or other materials provided with the distribution.
028: * 3. The name "JAFFA" must not be used to endorse or promote products derived from
029: * this Software without prior written permission. For written permission,
030: * please contact mail to: jaffagroup@yahoo.com.
031: * 4. Products derived from this Software may not be called "JAFFA" nor may "JAFFA"
032: * appear in their names without prior written permission.
033: * 5. Due credit should be given to the JAFFA Project (http://jaffa.sourceforge.net).
034: *
035: * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED
036: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
037: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
038: * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
039: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
040: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
041: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
042: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
043: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
044: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
045: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
046: * SUCH DAMAGE.
047: * ====================================================================
048: */
049:
050: package org.jaffa.persistence;
051:
052: import java.io.Serializable;
053: import org.jaffa.persistence.exceptions.*;
054: import org.jaffa.datatypes.ValidationException;
055: import org.jaffa.exceptions.FrameworkException;
056:
057: /** Interface for all persistent objects.
058: */
059: public interface IPersistent extends Cloneable, Serializable {
060:
061: /** Returns the UOW to which this object is associated.
062: * @return The UOW
063: */
064: public UOW getUOW();
065:
066: /** Associates this object to a UOW.
067: * Note: This method is for internal use by the Persistence Engine only.
068: * @param uow The UOW.
069: */
070: public void setUOW(UOW uow);
071:
072: /** Returns a true value if the object had any of its fields updated.
073: * @return a true value if the object had any of its fields updated.
074: */
075: public boolean isModified();
076:
077: /** Set the modified status of this object.
078: * Note: This method is for internal use by the Persistence Engine only.
079: * @param modified the modified status.
080: */
081: public void setModified(boolean modified);
082:
083: /** Returns a true value if the object was loaded from the database.
084: * @return a true value if the object was loaded from the database.
085: */
086: public boolean isDatabaseOccurence();
087:
088: /** Set the database status of this object.
089: * Note: This method is for internal use by the Persistence Engine only.
090: * @param databaseOccurence the database status.
091: */
092: public void setDatabaseOccurence(boolean databaseOccurence);
093:
094: /** Returns the locking strategy for this persistent object.
095: * @return the locking strategy for this persistent object.
096: */
097: public int getLocking();
098:
099: /** Set the locking strategy for this persistent object.
100: * Note: This method is for internal use by the Persistence Engine only.
101: * @param locking the locking strategy.
102: */
103: public void setLocking(int locking);
104:
105: /** Returns a true value if the underlying database row is locked.
106: * @return a true value if the underlying database row is locked.
107: */
108: public boolean isLocked();
109:
110: /** Set the locked status of this object.
111: * Note: This method is for internal use by the Persistence Engine only.
112: * @param locked the locked status.
113: */
114: public void setLocked(boolean locked);
115:
116: /** Returns a true value if this object has been added/updated/deleted and not yet been committed.
117: * @return a true value if this object has been added/updated/deleted and not yet been committed.
118: */
119: public boolean isQueued();
120:
121: /** Set the queued status of this object.
122: * The Persistence Engine will set the queued status to true on an Add/Update/Delete. Thereafter, any updates on this object will throw a RuntimeException.
123: * This flag will be reset after the object actaully gets added/updated/deleted to the database.
124: * Note: This method is for internal use by the Persistence Engine only.
125: * @param queued the queued status.
126: */
127: public void setQueued(boolean queued);
128:
129: /** Returns a true value if the field has been updated.
130: * @param fieldName the field to check.
131: * @return a true value if the field has been updated.
132: */
133: public boolean isModified(String fieldName);
134:
135: /** Returns the initial value for a field; i.e. before it was modified.
136: * A null will be returned if the field was never modified. Use the isModified() method to determine if the field was modified.
137: * A null can also be returned if the field had a null value to begin with.
138: * @param fieldName the field.
139: * @return the initial value for a field; i.e. before it was modified.
140: */
141: public Object returnInitialValue(String fieldName);
142:
143: /** This method is triggered by the UOW, before adding this object to the Add-Store, but after a UOW has been associated to the object.
144: * A concrete persistent object should provide the implementation, if its necessary.
145: * @throws PreAddFailedException if any error occurs during the process.
146: */
147: public void preAdd() throws PreAddFailedException;
148:
149: /** This method is triggered by the UOW, after adding this object to the Add-Store.
150: * A concrete persistent object should provide the implementation, if its necessary.
151: * @throws PostAddFailedException if any error occurs during the process.
152: */
153: public void postAdd() throws PostAddFailedException;
154:
155: /** This method is triggered by the UOW, before adding this object to the Update-Store.
156: * A concrete persistent object should provide the implementation, if its necessary.
157: * @throws PreUpdateFailedException if any error occurs during the process.
158: */
159: public void preUpdate() throws PreUpdateFailedException;
160:
161: /** This method is triggered by the UOW, after adding this object to the Update-Store.
162: * A concrete persistent object should provide the implementation, if its necessary.
163: * @throws PostUpdateFailedException if any error occurs during the process.
164: */
165: public void postUpdate() throws PostUpdateFailedException;
166:
167: /** This method is triggered by the UOW, before adding this object to the Delete-Store.
168: * A concrete persistent object should provide the implementation, if its necessary.
169: * @throws PreDeleteFailedException if any error occurs during the process.
170: */
171: public void preDelete() throws PreDeleteFailedException;
172:
173: /** This method is triggered by the UOW, after adding this object to the Delete-Store.
174: * A concrete persistent object should provide the implementation, if its necessary.
175: * @throws PostDeleteFailedException if any error occurs during the process.
176: */
177: public void postDelete() throws PostDeleteFailedException;
178:
179: /** This method is triggered by the UOW after a query loads this object.
180: * A concrete persistent object should provide the implementation, if its necessary.
181: * @throws PostLoadFailedException if any error occurs during the process.
182: */
183: public void postLoad() throws PostLoadFailedException;
184:
185: }
|