View Javadoc

1   package org.apache.torque.oid;
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  import java.math.BigDecimal;
21  
22  /***
23   * Interface to be implemented by id generators.  It is possible
24   * that some implementations might not require all the arguments,
25   * for example MySQL will not require a keyInfo Object, while the
26   * IDBroker implementation does not require a Connection as
27   * it only rarely needs one and retrieves a connection from the
28   * Connection pool service only when needed.
29   *
30   * @author <a href="mailto:jmcnally@collab.net">John D. McNally</a>
31   * @version $Id: IdGenerator.java 239630 2005-08-24 12:25:32Z henning $
32   */
33  public interface IdGenerator
34  {
35      /***
36       * Returns an id as a primitive int.  If you use numeric
37       * identifiers, it's suggested that {@link
38       * #getIdAsLong(Connection, Object)} be used instead (due to the
39       * limitted range of this method).
40       *
41       * @param connection A Connection.
42       * @param keyInfo an Object that contains additional info.
43       * @return An int with the value for the id.
44       * @exception Exception Database error.
45       */
46      int getIdAsInt(Connection connection, Object keyInfo)
47          throws Exception;
48  
49      /***
50       * Returns an id as a primitive long.
51       *
52       * @param connection A Connection.
53       * @param keyInfo an Object that contains additional info.
54       * @return A long with the value for the id.
55       * @exception Exception Database error.
56       */
57      long getIdAsLong(Connection connection, Object keyInfo)
58          throws Exception;
59  
60      /***
61       * Returns an id as a BigDecimal.
62       *
63       * @param connection A Connection.
64       * @param keyInfo an Object that contains additional info.
65       * @return A BigDecimal id.
66       * @exception Exception Database error.
67       */
68      BigDecimal getIdAsBigDecimal(Connection connection, Object keyInfo)
69          throws Exception;
70  
71      /***
72       * Returns an id as a String.
73       *
74       * @param connection A Connection.
75       * @param keyInfo an Object that contains additional info.
76       * @return A String id
77       * @exception Exception Database error.
78       */
79      String getIdAsString(Connection connection, Object keyInfo)
80          throws Exception;
81  
82      /***
83       * A flag to determine the timing of the id generation
84       *
85       * @return a <code>boolean</code> value
86       */
87      boolean isPriorToInsert();
88  
89      /***
90       * A flag to determine the timing of the id generation
91       *
92       * @return Whether id is availble post-<code>insert</code>.
93       */
94      boolean isPostInsert();
95  
96      /***
97       * A flag to determine whether a Connection is required to
98       * generate an id.
99       *
100      * @return a <code>boolean</code> value
101      */
102     boolean isConnectionRequired();
103 }