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 */