001: package org.apache.torque.om;
002:
003: /*
004: * Licensed to the Apache Software Foundation (ASF) under one
005: * or more contributor license agreements. See the NOTICE file
006: * distributed with this work for additional information
007: * regarding copyright ownership. The ASF licenses this file
008: * to you under the Apache License, Version 2.0 (the
009: * "License"); you may not use this file except in compliance
010: * with the License. You may obtain a copy of the License at
011: *
012: * http://www.apache.org/licenses/LICENSE-2.0
013: *
014: * Unless required by applicable law or agreed to in writing,
015: * software distributed under the License is distributed on an
016: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017: * KIND, either express or implied. See the License for the
018: * specific language governing permissions and limitations
019: * under the License.
020: */
021:
022: import java.io.Serializable;
023: import java.sql.Connection;
024:
025: import org.apache.commons.logging.Log;
026: import org.apache.commons.logging.LogFactory;
027:
028: import org.apache.torque.TorqueException;
029: import org.apache.torque.map.TableMap;
030:
031: /**
032: * This class contains attributes and methods that are used by all
033: * business objects within the system.
034: *
035: * @author <a href="mailto:frank.kim@clearink.com">Frank Y. Kim</a>
036: * @author <a href="mailto:jmcnally@collab.net">John D. McNally</a>
037: * @version $Id: BaseObject.java 516325 2007-03-09 08:03:53Z seade $
038: */
039: public abstract class BaseObject implements Persistent, Serializable {
040: /** The constant denoting an unset numeric database identifier. */
041: public static final int NEW_ID = -1;
042:
043: /**
044: * Shared portion of the error message thrown for methods which
045: * are not implemented.
046: */
047: private static final String NOT_IMPLEMENTED = "Not implemented: Method must be overridden if called";
048:
049: /** attribute to determine if this object has previously been saved. */
050: private boolean isNew = true;
051:
052: /** The unique id for the object which can be used for persistence. */
053: private ObjectKey primaryKey = null;
054:
055: /**
056: * A flag that indicates an object has been modified since it was
057: * last retrieved from the persistence mechanism. This flag is
058: * used to determine if this object should be saved to the
059: * database. We initialize it to true to force new objects to be
060: * saved.
061: */
062: private boolean modified = true;
063:
064: /** Cache the log to avoid looking it up every time its needed. */
065: private transient Log log = null;
066:
067: /**
068: * getter for the object primaryKey.
069: *
070: * @return the object primaryKey as an Object
071: */
072: public ObjectKey getPrimaryKey() {
073: return primaryKey;
074: }
075:
076: /**
077: * Returns whether the object has been modified.
078: *
079: * @return True if the object has been modified.
080: */
081: public boolean isModified() {
082: return modified;
083: }
084:
085: /**
086: * Returns whether the object has ever been saved. This will
087: * be false, if the object was retrieved from storage or was created
088: * and then saved.
089: *
090: * @return true, if the object has never been persisted.
091: */
092: public boolean isNew() {
093: return isNew;
094: }
095:
096: /**
097: * Setter for the isNew attribute. This method will be called
098: * by Torque-generated children and Peers.
099: *
100: * @param b the state of the object.
101: */
102: public void setNew(boolean b) {
103: this .isNew = b;
104: }
105:
106: /**
107: * Sets the PrimaryKey for the object.
108: *
109: * @param primaryKey The new PrimaryKey for the object.
110: * @exception TorqueException This method will not throw any exceptions
111: * but this allows for children to override the method more easily
112: */
113: public void setPrimaryKey(String primaryKey) throws TorqueException {
114: this .primaryKey = new StringKey(primaryKey);
115: }
116:
117: /**
118: * Sets the PrimaryKey for the object as an Object.
119: *
120: * @param primaryKey The new PrimaryKey for the object.
121: * @exception TorqueException This method will not throw any exceptions
122: * but this allows for children to override the method more easily
123: */
124: public void setPrimaryKey(SimpleKey[] primaryKey)
125: throws TorqueException {
126: this .primaryKey = new ComboKey(primaryKey);
127: }
128:
129: /**
130: * Sets the PrimaryKey for the object as an Object.
131: *
132: * @param primaryKey The new PrimaryKey for the object.
133: * @exception TorqueException This method will not throw any exceptions
134: * but this allows for children to override the method more easily
135: */
136: public void setPrimaryKey(ObjectKey primaryKey)
137: throws TorqueException {
138: this .primaryKey = primaryKey;
139: }
140:
141: /**
142: * Sets the modified state for the object.
143: *
144: * @param m The new modified state for the object.
145: */
146: public void setModified(boolean m) {
147: modified = m;
148: }
149:
150: /**
151: * Sets the modified state for the object to be false.
152: */
153: public void resetModified() {
154: modified = false;
155: }
156:
157: /**
158: * Retrieves a field from the object by name. Must be overridden if called.
159: * BaseObject's implementation will throw an Error.
160: *
161: * @param field The name of the field to retrieve.
162: * @return The retrieved field value
163: *
164: */
165: public Object getByName(String field) {
166: throw new Error("BaseObject.getByName: " + NOT_IMPLEMENTED);
167: }
168:
169: /**
170: * Set a field in the object by field (Java) name.
171: *
172: * @param name field name
173: * @param value field value
174: * @return True if value was set, false if not (invalid name / protected
175: * field).
176: * @throws IllegalArgumentException if object type of value does not match
177: * field object type.
178: * @throws TorqueException If a problem occurs with the set[Field] method.
179: */
180: public boolean setByName(String name, Object value)
181: throws TorqueException {
182: throw new Error("BaseObject.setByName: " + NOT_IMPLEMENTED);
183: }
184:
185: /**
186: * Retrieves a field from the object by name passed in as a String. Must be
187: * overridden if called. BaseObject's implementation will throw an Error.
188: *
189: * @param name field name
190: * @return value of the field
191: */
192: public Object getByPeerName(String name) {
193: throw new Error("BaseObject.getByPeerName: " + NOT_IMPLEMENTED);
194: }
195:
196: /**
197: * Set field values by Peer Field Name
198: *
199: * @param name field name
200: * @param value field value
201: * @return True if value was set, false if not (invalid name / protected
202: * field).
203: * @throws IllegalArgumentException if object type of value does not match
204: * field object type.
205: * @throws TorqueException If a problem occurs with the set[Field] method.
206: */
207: public boolean setByPeerName(String name, Object value)
208: throws TorqueException {
209: throw new Error("BaseObject.setByPeerName: " + NOT_IMPLEMENTED);
210: }
211:
212: /**
213: * Retrieves a field from the object by position as specified in a database
214: * schema for example. Must be overridden if called. BaseObject's
215: * implementation will throw an Error.
216: *
217: * @param pos field position
218: * @return value of the field
219: */
220: public Object getByPosition(int pos) {
221: throw new Error("BaseObject.getByPosition: " + NOT_IMPLEMENTED);
222: }
223:
224: /**
225: * Set field values by it's position (zero based) in the XML schema.
226: *
227: * @param position The field position
228: * @param value field value
229: * @return True if value was set, false if not (invalid position / protected
230: * field).
231: * @throws IllegalArgumentException if object type of value does not match
232: * field object type.
233: * @throws TorqueException If a problem occurs with the set[Field] method.
234: */
235: public boolean setByPosition(int position, Object value)
236: throws TorqueException {
237: throw new Error("BaseObject.setByPosition: " + NOT_IMPLEMENTED);
238: }
239:
240: /**
241: * Compares this with another <code>BaseObject</code> instance. If
242: * <code>obj</code> is an instance of <code>BaseObject</code>,
243: * delegates to <code>equals(BaseObject)</code>. Otherwise, returns
244: * <code>false</code>.
245: *
246: * @param obj The object to compare to.
247: * @return Whether equal to the object specified.
248: */
249: public boolean equals(Object obj) {
250: if (obj != null && obj instanceof BaseObject) {
251: return equals((BaseObject) obj);
252: } else {
253: return false;
254: }
255: }
256:
257: /**
258: * Compares the primary key of this instance with the key of another.
259: *
260: * @param bo The object to compare to.
261: * @return Whether the primary keys are equal and the object have the
262: * same class.
263: */
264: public boolean equals(BaseObject bo) {
265: if (bo == null) {
266: return false;
267: }
268: if (this == bo) {
269: return true;
270: } else if (getPrimaryKey() == null
271: || bo.getPrimaryKey() == null) {
272: return false;
273: } else if (!getClass().equals(bo.getClass())) {
274: return false;
275: } else {
276: return getPrimaryKey().equals(bo.getPrimaryKey());
277: }
278: }
279:
280: /**
281: * If the primary key is not <code>null</code>, return the hashcode of the
282: * primary key. Otherwise calls <code>Object.hashCode()</code>.
283: *
284: * @return an <code>int</code> value
285: */
286: public int hashCode() {
287: ObjectKey ok = getPrimaryKey();
288: if (ok == null) {
289: return super .hashCode();
290: }
291:
292: return ok.hashCode();
293: }
294:
295: /**
296: * gets a commons-logging Log based on class name.
297: *
298: * @return a <code>Log</code> to write log to.
299: */
300: protected Log getLog() {
301: if (log == null) {
302: log = LogFactory.getLog(getClass().getName());
303: }
304: return log;
305: }
306:
307: /**
308: * @see org.apache.torque.om.Persistent#save()
309: */
310: public abstract void save() throws Exception;
311:
312: /**
313: * @see org.apache.torque.om.Persistent#save(String)
314: */
315: public abstract void save(String dbName) throws Exception;
316:
317: /**
318: * @see org.apache.torque.om.Persistent#save(Connection)
319: */
320: public abstract void save(Connection con) throws Exception;
321:
322: /**
323: * Retrieves the TableMap object related to this Table data.
324: * Must be overridden in generated classes. If BaseObject's
325: * implementation is called it will throw an Error.
326: *
327: * @return The associated TableMap object.
328: */
329: public TableMap getTableMap() throws TorqueException {
330: throw new Error("BaseObject.getTableMap: " + NOT_IMPLEMENTED);
331: }
332: }
|