View Javadoc

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