001: package org.apache.torque.oid;
002:
003: /*
004: * Licensed to the Apache Software Foundation (ASF) under one
005: * or more contributor license agreements. See the NOTICE file
006: * distributed with this work for additional information
007: * regarding copyright ownership. The ASF licenses this file
008: * to you under the Apache License, Version 2.0 (the
009: * "License"); you may not use this file except in compliance
010: * with the License. You may obtain a copy of the License at
011: *
012: * http://www.apache.org/licenses/LICENSE-2.0
013: *
014: * Unless required by applicable law or agreed to in writing,
015: * software distributed under the License is distributed on an
016: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017: * KIND, either express or implied. See the License for the
018: * specific language governing permissions and limitations
019: * under the License.
020: */
021:
022: import java.sql.Connection;
023: import java.math.BigDecimal;
024:
025: /**
026: * Interface to be implemented by id generators. It is possible
027: * that some implementations might not require all the arguments,
028: * for example MySQL will not require a keyInfo Object, while the
029: * IDBroker implementation does not require a Connection as
030: * it only rarely needs one and retrieves a connection from the
031: * Connection pool service only when needed.
032: *
033: * @author <a href="mailto:jmcnally@collab.net">John D. McNally</a>
034: * @version $Id: IdGenerator.java 473821 2006-11-11 22:37:25Z tv $
035: */
036: public interface IdGenerator {
037: /**
038: * Returns an id as a primitive int. If you use numeric
039: * identifiers, it's suggested that {@link
040: * #getIdAsLong(Connection, Object)} be used instead (due to the
041: * limitted range of this method).
042: *
043: * @param connection A Connection.
044: * @param keyInfo an Object that contains additional info.
045: * @return An int with the value for the id.
046: * @exception Exception Database error.
047: */
048: int getIdAsInt(Connection connection, Object keyInfo)
049: throws Exception;
050:
051: /**
052: * Returns an id as a primitive long.
053: *
054: * @param connection A Connection.
055: * @param keyInfo an Object that contains additional info.
056: * @return A long with the value for the id.
057: * @exception Exception Database error.
058: */
059: long getIdAsLong(Connection connection, Object keyInfo)
060: throws Exception;
061:
062: /**
063: * Returns an id as a BigDecimal.
064: *
065: * @param connection A Connection.
066: * @param keyInfo an Object that contains additional info.
067: * @return A BigDecimal id.
068: * @exception Exception Database error.
069: */
070: BigDecimal getIdAsBigDecimal(Connection connection, Object keyInfo)
071: throws Exception;
072:
073: /**
074: * Returns an id as a String.
075: *
076: * @param connection A Connection.
077: * @param keyInfo an Object that contains additional info.
078: * @return A String id
079: * @exception Exception Database error.
080: */
081: String getIdAsString(Connection connection, Object keyInfo)
082: throws Exception;
083:
084: /**
085: * A flag to determine the timing of the id generation
086: *
087: * @return a <code>boolean</code> value
088: */
089: boolean isPriorToInsert();
090:
091: /**
092: * A flag to determine the timing of the id generation
093: *
094: * @return Whether id is availble post-<code>insert</code>.
095: */
096: boolean isPostInsert();
097:
098: /**
099: * A flag to determine whether a Connection is required to
100: * generate an id.
101: *
102: * @return a <code>boolean</code> value
103: */
104: boolean isConnectionRequired();
105: }
|