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