BaseObject


1   package org.apache.torque.om;
2   
3   /*
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *   http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
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 476550 2006-11-18 16:08:37Z tfischer $
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 occures 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 occures 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 occures 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 }
365
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags