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