View Javadoc

1   package org.apache.torque.om;
2   
3   /*
4    * Copyright 2001-2005 The Apache Software Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License")
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
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 }