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.sql.Connection;
20  
21  /***
22   * This interface defines methods related to saving an object
23   *
24   * @author <a href="mailto:jmcnally@collab.net">John D. McNally</a>
25   * @author <a href="mailto:fedor@apache.org">Fedor K.</a>
26   * @version $Id: Persistent.java 239630 2005-08-24 12:25:32Z henning $
27   */
28  public interface Persistent
29  {
30      /***
31       * getter for the object primaryKey.
32       *
33       * @return the object primaryKey as an Object
34       */
35      ObjectKey getPrimaryKey();
36  
37      /***
38       * Sets the PrimaryKey for the object.
39       *
40       * @param primaryKey The new PrimaryKey for the object.
41       * @throws Exception This method might throw an exception
42       */
43      void setPrimaryKey(ObjectKey primaryKey) throws Exception;
44  
45      /***
46       * Sets the PrimaryKey for the object.
47       *
48       * @param primaryKey the String should be of the form produced by
49       *        ObjectKey.toString().
50       * @throws Exception This method might throw an exception
51       */
52      void setPrimaryKey(String primaryKey) throws Exception;
53  
54      /***
55       * Returns whether the object has been modified, since it was
56       * last retrieved from storage.
57       *
58       * @return True if the object has been modified.
59       */
60      boolean isModified();
61  
62      /***
63       * Returns whether the object has ever been saved.  This will
64       * be false, if the object was retrieved from storage or was created
65       * and then saved.
66       *
67       * @return true, if the object has never been persisted.
68       */
69      boolean isNew();
70  
71      /***
72       * Setter for the isNew attribute.  This method will be called
73       * by Torque-generated children and Peers.
74       *
75       * @param b the state of the object.
76       */
77      void setNew(boolean b);
78  
79      /***
80       * Sets the modified state for the object.
81       *
82       * @param m The new modified state for the object.
83       */
84      void setModified(boolean m);
85  
86      /***
87       * Saves the object.
88       *
89       * @throws Exception This method might throw an exception
90       */
91      void save() throws Exception;
92  
93      /***
94       * Stores the object in the database.  If the object is new,
95       * it inserts it; otherwise an update is performed.
96       *
97       * @param dbName the name of the database
98       * @throws Exception This method might throw an exception
99       */
100     void save(String dbName) throws Exception;
101 
102     /***
103      * Stores the object in the database.  If the object is new,
104      * it inserts it; otherwise an update is performed.  This method
105      * is meant to be used as part of a transaction, otherwise use
106      * the save() method and the connection details will be handled
107      * internally
108      *
109      * @param con the Connection used to store the object
110      * @throws Exception This method might throw an exception
111      */
112     void save(Connection con) throws Exception;
113 }