View Javadoc

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