001/* ----------------------------------------------------------------------------
002   The Kiwi Toolkit - A Java Class Library
003   Copyright (C) 1998-2004 Mark A. Lindner
004
005   This library is free software; you can redistribute it and/or
006   modify it under the terms of the GNU General Public License as
007   published by the Free Software Foundation; either version 2 of the
008   License, or (at your option) any later version.
009
010   This library is distributed in the hope that it will be useful,
011   but WITHOUT ANY WARRANTY; without even the implied warranty of
012   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
013   General Public License for more details.
014
015   You should have received a copy of the GNU General Public License
016   along with this library; if not, write to the Free Software
017   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
018   02111-1307, USA.
019 
020   The author may be contacted at: mark_a_lindner@yahoo.com
021   ----------------------------------------------------------------------------
022   $Log: PersistentObject.java,v $
023   Revision 1.7  2004/05/05 21:37:04  markl
024   comment block updates
025
026   Revision 1.6  2003/01/19 09:35:41  markl
027   Javadoc & comment header updates.
028
029   Revision 1.5  2002/08/11 09:49:56  markl
030   Javadoc fixes.
031
032   Revision 1.4  2001/03/12 05:58:46  markl
033   Javadoc cleanup.
034
035   Revision 1.3  2001/03/12 01:17:30  markl
036   Source code cleanup.
037
038   Revision 1.2  1999/02/28 01:21:43  markl
039   Added expire() method.
040
041   Revision 1.1  1999/02/28 00:58:14  markl
042   Initial revision
043   ----------------------------------------------------------------------------
044*/
045
046package kiwi.db;
047
048import java.sql.*;
049
050/** This class represents a <i>persistent object</i>--a domain object that can
051  * be written to (and then read back from) a persistent store such as a file
052  * or, most commonly, a SQL database. Persistent objects have unique IDs
053  * that identify them. These IDs generally correspond to primary keys in a
054  * relational database.
055  * <p>
056  * The <code>store()</code>, <code>restore()</code>, and <code>delete()</code>
057  * methods should be overridden to provide the appropriate logic for
058  * interacting with the persistent store.
059  * <p>
060  * This class provides support for time-to-live, timestamping, and expiration.
061  * This support facilitates the implementation of a caching mechanism for
062  * persistent objects. See <code>PersistentObjectPool</code> for one such
063  * implementation. An object can be explicitly expired via a call to
064  * <code>expire()</code>; this will cause the object to be removed from
065  * any cache when the cache performs its next expiration sweep.
066  *
067  * @see kiwi.db.PersistentObjectPool
068  *
069  * @author Mark Lindner
070  */
071
072public class PersistentObject extends DomainObject
073  {
074  /** The ID of the object. */
075  protected int id = -1;
076  private long lastAccess;
077  /** The object's <i>ttl</i> (time to live) value, in milliseconds. */
078  protected int timeToLive = (60 * 1000);
079
080  /** Construct a new <code>PersistentObject</code>. The object will have an
081    * ID of -1.
082    */
083  
084  public PersistentObject()
085    {
086    setID(-1);
087    }
088
089  /** Construct a new <code>PersistentObject</code> with the given ID.
090    *
091    * @param id The ID for the object.
092    */
093  
094  public PersistentObject(int id)
095    {
096    setID(id);
097    }
098
099  /** Set the last access time for this object to the current time.
100   */
101  
102  protected void timestamp()
103    {
104    lastAccess = System.currentTimeMillis();
105    }
106
107  /** Expire this object.
108    */
109
110  public void expire()
111    {
112    lastAccess = 0;
113    }
114
115  /** Determine if this object has expired. An object <i>expires</i> if
116    * the length of time since its last access exceeds its <i>ttl</i>
117    * (time to live) value.
118    *
119    * @param now The current time.
120    * @return <code>true</code> if the object has expired, and
121    * <code>false</code> otherwise.
122    */
123  
124  protected final boolean isExpired(long now)
125    {
126    return((now - lastAccess) >= timeToLive);
127    }
128
129  /** Determine if this object is new. An object that is <i>new</i> is one
130    * that has never been persisted. Objects that have not been persisted
131    * do not have IDs assigned to them, so the ID of a new object is always
132    * -1.
133    *
134    * @return <code>true</code> if the object is new, and <code>false</code>
135    * otherwise.
136    */
137  
138  public boolean isNew()
139    {
140    return(getID() < 0);
141    }
142
143  /** Get the ID for this object.
144    *
145    * @return The ID.
146    */
147  
148  public int getID()
149    {
150    return(id);
151    }
152
153  /** Set the ID for this object.
154    *
155    * @param id The new ID.
156    */
157  
158  public void setID(int id)
159    {
160    this.id = id;
161    }
162
163  /** Dispose of this object. Sets the ID to -1, effectively marking this as
164    * a <i>new</i> object.
165    */
166  
167  public void dispose()
168    {
169    setID(-1);
170    }
171
172  /** Determine if this object is equal to another object.
173   *
174   * @param o The object to compare against.
175   * @return <code>true</code> if the other object is an instance of
176   * <code>PersistentObject</code> <i>and</i> neither object is new
177   * <i>and</i> the IDs of the two objects are equal.
178   */
179  
180  public boolean equals(Object o)
181    {
182    if(o instanceof PersistentObject)
183      {
184      PersistentObject p = (PersistentObject)o;
185      int oid = p.getID();
186      
187      return((oid >= 0) && (oid == getID()));
188      }
189    else
190      return(false);
191    }
192
193  /** Obtain the hashcode for this object. If the object is not new, the ID
194   * is returned as the hashcode; otherwise <code>Object.hashCode()</code> is
195   * called to generate the hashcode.
196   *
197   * @return The hashcode.
198   */
199  
200  public int hashCode()
201    {
202    return(isNew() ? super.hashCode() : id);
203    }
204
205  /** Generate a string representation of this object.
206    */
207  
208  public String toString()
209    {
210    return(getClass().getName() + "(" + getID() + ")");
211    }
212
213  /** Store this object in a persistent store, presumably a SQL database. The
214    * default implementation does nothing.
215    *
216    * @throws java.sql.SQLException If the operation failed.
217    */
218  
219  public void store() throws SQLException
220    {
221    }
222
223  /** Restore this object from a persistent store, presumably a SQL database.
224    * The default implementation does nothing.
225    *
226    * @throws java.sql.SQLException If the operation failed.
227    */
228
229  public void restore() throws SQLException
230    {
231    }
232
233  /** Delete this object from a persistent store, presumably a SQL database.
234    * The default implementation does nothing.
235    *
236    * @throws java.sql.SQLException If the operation failed.
237    */
238
239  public void delete() throws SQLException
240    {
241    }
242  
243  }
244
245/* end of source file */