001 package org.apache.ojb.broker;
002
003 /* Copyright 2002-2005 The Apache Software Foundation
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 import org.apache.ojb.broker.metadata.ClassDescriptor;
019
020 /**
021 * Builds {@link org.apache.ojb.broker.Identity} objects to identify persistence capable objects within OJB.
022 * In many cases the primary key (based on metadata declaration) of an object is known
023 * and the whole object should be materialized (e.g. findByPrimaryKey(...) calls).
024 * This class make available a bunch of methods help to create {@link org.apache.ojb.broker.Identity}
025 * objects based on
026 * <ul>
027 * <li>the persistence capable object itself</li>
028 * <li>the primary key values of a persistence capable object</li>
029 * </ul>
030 * NOTE:
031 * <br/>
032 * It is possible to create transient {@link Identity} objects for transient,
033 * "new created" persistence capable objects. But keep in mind that this transient
034 * {@link Identity} object is only valid till the persistence capable object was written
035 * to datastore. After this the {@link Identity} have to be renewed by calling
036 * <code>IdentityFactory.buildIdentity(...)</code> again (then the transient Identity
037 * will be replaced by the persistent Identity).
038 *
039 * @version $Id: IdentityFactory.java,v 1.1 2007-08-24 22:17:36 ewestfal Exp $
040 */
041 public interface IdentityFactory
042 {
043 /**
044 * Build a unique {@link org.apache.ojb.broker.Identity} for the given
045 * persistence capable object.
046 *
047 * @param obj The object to build the {@link Identity} for
048 * @return The new <em>Identity</em> object
049 */
050 Identity buildIdentity(Object obj);
051
052 /**
053 * Build a unique {@link org.apache.ojb.broker.Identity} for the given
054 * persistence capable object.
055 *
056 * @param cld The {@link org.apache.ojb.broker.metadata.ClassDescriptor} of the object
057 * @param obj The object to build the {@link Identity} for
058 * @return The new <em>Identity</em> object.
059 */
060 Identity buildIdentity(ClassDescriptor cld, Object obj);
061
062 /**
063 * Build a unique {@link org.apache.ojb.broker.Identity}
064 * for the given primary key values (composite PK's) of a
065 * persistence capable object.
066 *
067 * @param realClass The class of the associated object
068 * @param topLevelClass The top-level class of the associated object
069 * @param pkFieldName The field names of the PK fields
070 * @param pkValues The PK values
071 * @return The new <em>Identity</em> object
072 */
073 Identity buildIdentity(Class realClass, Class topLevelClass, String[] pkFieldName, Object[] pkValues);
074
075 /**
076 * Convenience shortcut method for
077 * {@link #buildIdentity(java.lang.Class, java.lang.Class, java.lang.String[], java.lang.Object[])}.
078 *
079 * @param realClass The class of the associated object
080 * @param pkFieldName The field names of the PK fields
081 * @param pkValues The PK values
082 * @return The new <em>Identity</em> object
083 */
084 Identity buildIdentity(Class realClass, String[] pkFieldName, Object[] pkValues);
085
086 /**
087 * Convenience method for persistent objects with single primary key.
088 * NOTE: Do not use for objects with composed PK!
089 *
090 * @param realClass The class of the associated object
091 * @param pkValue The PK value
092 * @return The new <em>Identity</em> object
093 * @see #buildIdentity(java.lang.Class, java.lang.String[], java.lang.Object[])
094 */
095 Identity buildIdentity(Class realClass, Object pkValue);
096
097 /**
098 * Create a new {@link Identity} object based on given arguments - NOTE: There
099 * will be no check to resolve the order of the PK values. This method expect
100 * the correct order based on the declaration of the {@link org.apache.ojb.broker.metadata.FieldDescriptor}
101 * in the mapping file.
102 *
103 * @param realClass The class of the associated object
104 * @param topLevelClass The top-level class of the associated object
105 * @param pkValues The PK values
106 * @return The new <em>Identity</em> object
107 */
108 Identity buildIdentity(Class realClass, Class topLevelClass, Object[] pkValues);
109 }