1 package org.apache.torque.om;
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19 import java.io.Serializable;
20 import java.sql.Connection;
21
22 import org.apache.commons.logging.Log;
23 import org.apache.commons.logging.LogFactory;
24
25 import org.apache.torque.TorqueException;
26
27 /***
28 * This class contains attributes and methods that are used by all
29 * business objects within the system.
30 *
31 * @author <a href="mailto:frank.kim@clearink.com">Frank Y. Kim</a>
32 * @author <a href="mailto:jmcnally@collab.net">John D. McNally</a>
33 * @version $Id: BaseObject.java 239630 2005-08-24 12:25:32Z henning $
34 */
35 public abstract class BaseObject implements Persistent, Serializable
36 {
37 /*** The constant denoting an unset numeric database identifier. */
38 public static final int NEW_ID = -1;
39
40 /***
41 * Shared portion of the error message thrown for methods which
42 * are not implemented.
43 */
44 private static final String NOT_IMPLEMENTED
45 = "Not implemented: Method must be overridden if called";
46
47 /*** attribute to determine if this object has previously been saved. */
48 private boolean isNew = true;
49
50 /*** The unique id for the object which can be used for persistence. */
51 private ObjectKey primaryKey = null;
52
53 /***
54 * A flag that indicates an object has been modified since it was
55 * last retrieved from the persistence mechanism. This flag is
56 * used to determine if this object should be saved to the
57 * database. We initialize it to true to force new objects to be
58 * saved.
59 */
60 private boolean modified = true;
61
62 /*** Cache the log to avoid looking it up every time its needed. */
63 private transient Log log = null;
64
65 /***
66 * getter for the object primaryKey.
67 *
68 * @return the object primaryKey as an Object
69 */
70 public ObjectKey getPrimaryKey()
71 {
72 return primaryKey;
73 }
74
75 /***
76 * Returns whether the object has been modified.
77 *
78 * @return True if the object has been modified.
79 */
80 public boolean isModified()
81 {
82 return modified;
83 }
84
85 /***
86 * Returns whether the object has ever been saved. This will
87 * be false, if the object was retrieved from storage or was created
88 * and then saved.
89 *
90 * @return true, if the object has never been persisted.
91 */
92 public boolean isNew()
93 {
94 return isNew;
95 }
96
97 /***
98 * Setter for the isNew attribute. This method will be called
99 * by Torque-generated children and Peers.
100 *
101 * @param b the state of the object.
102 */
103 public void setNew(boolean b)
104 {
105 this.isNew = b;
106 }
107
108 /***
109 * Sets the PrimaryKey for the object.
110 *
111 * @param primaryKey The new PrimaryKey for the object.
112 * @exception TorqueException This method will not throw any exceptions
113 * but this allows for children to override the method more easily
114 */
115 public void setPrimaryKey(String primaryKey) throws TorqueException
116 {
117 this.primaryKey = new StringKey(primaryKey);
118 }
119
120 /***
121 * Sets the PrimaryKey for the object as an Object.
122 *
123 * @param primaryKey The new PrimaryKey for the object.
124 * @exception TorqueException This method will not throw any exceptions
125 * but this allows for children to override the method more easily
126 */
127 public void setPrimaryKey(SimpleKey[] primaryKey) throws TorqueException
128 {
129 this.primaryKey = new ComboKey(primaryKey);
130 }
131
132 /***
133 * Sets the PrimaryKey for the object as an Object.
134 *
135 * @param primaryKey The new PrimaryKey for the object.
136 * @exception TorqueException This method will not throw any exceptions
137 * but this allows for children to override the method more easily
138 */
139 public void setPrimaryKey(ObjectKey primaryKey) throws TorqueException
140 {
141 this.primaryKey = primaryKey;
142 }
143
144 /***
145 * Sets the modified state for the object.
146 *
147 * @param m The new modified state for the object.
148 */
149 public void setModified(boolean m)
150 {
151 modified = m;
152 }
153
154 /***
155 * Sets the modified state for the object to be false.
156 */
157 public void resetModified()
158 {
159 modified = false;
160 }
161
162 /***
163 * Retrieves a field from the object by name. Must be overridden if called.
164 * BaseObject's implementation will throw an Error.
165 *
166 * @param field The name of the field to retrieve.
167 * @return The retrieved field value
168 *
169 */
170 public Object getByName(String field)
171 {
172 throw new Error("BaseObject.getByName: " + NOT_IMPLEMENTED);
173 }
174
175 /***
176 * Retrieves a field from the object by name passed in
177 * as a String. Must be overridden if called.
178 * BaseObject's implementation will throw an Error.
179 *
180 * @param name field name
181 * @return value of the field
182 */
183 public Object getByPeerName(String name)
184 {
185 throw new Error("BaseObject.getByPeerName: " + NOT_IMPLEMENTED);
186 }
187
188 /***
189 * Retrieves a field from the object by position as specified
190 * in a database schema for example. Must be overridden if called.
191 * BaseObject's implementation will throw an Error.
192 *
193 * @param pos field position
194 * @return value of the field
195 */
196 public Object getByPosition(int pos)
197 {
198 throw new Error("BaseObject.getByPosition: " + NOT_IMPLEMENTED);
199 }
200
201 /***
202 * Compares this with another <code>BaseObject</code> instance. If
203 * <code>obj</code> is an instance of <code>BaseObject</code>, delegates to
204 * <code>equals(BaseObject)</code>. Otherwise, returns <code>false</code>.
205 *
206 * @param obj The object to compare to.
207 * @return Whether equal to the object specified.
208 */
209 public boolean equals(Object obj)
210 {
211 if (obj != null && obj instanceof BaseObject)
212 {
213 return equals((BaseObject) obj);
214 }
215 else
216 {
217 return false;
218 }
219 }
220
221 /***
222 * Compares the primary key of this instance with the key of another.
223 *
224 * @param bo The object to compare to.
225 * @return Whether the primary keys are equal.
226 */
227 public boolean equals(BaseObject bo)
228 {
229 if (bo == null)
230 {
231 return false;
232 }
233 if (this == bo)
234 {
235 return true;
236 }
237 else if (getPrimaryKey() == null || bo.getPrimaryKey() == null)
238 {
239 return false;
240 }
241 else
242 {
243 return getPrimaryKey().equals(bo.getPrimaryKey());
244 }
245 }
246
247 /***
248 * If the primary key is not <code>null</code>, return the hashcode of the
249 * primary key. Otherwise calls <code>Object.hashCode()</code>.
250 *
251 * @return an <code>int</code> value
252 */
253 public int hashCode()
254 {
255 ObjectKey ok = getPrimaryKey();
256 if (ok == null)
257 {
258 return super.hashCode();
259 }
260
261 return ok.hashCode();
262 }
263
264 /***
265 * gets a commons-logging Log based on class name.
266 *
267 * @return a <code>Log</code> to write log to.
268 */
269 protected Log getLog()
270 {
271 if (log == null)
272 {
273 log = LogFactory.getLog(getClass().getName());
274 }
275 return log;
276 }
277
278 /***
279 * @see org.apache.torque.om.Persistent#save()
280 */
281 public abstract void save() throws Exception;
282
283 /***
284 * @see org.apache.torque.om.Persistent#save(String)
285 */
286 public abstract void save(String dbName) throws Exception;
287
288 /***
289 * @see org.apache.torque.om.Persistent#save(Connection)
290 */
291 public abstract void save(Connection con) throws Exception;
292 }