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.2.2.4 2005/12/21 22:22:08 tomdz Exp $
040: */
041: public interface IdentityFactory {
042: /**
043: * Build a unique {@link org.apache.ojb.broker.Identity} for the given
044: * persistence capable object.
045: *
046: * @param obj The object to build the {@link Identity} for
047: * @return The new <em>Identity</em> object
048: */
049: Identity buildIdentity(Object obj);
050:
051: /**
052: * Build a unique {@link org.apache.ojb.broker.Identity} for the given
053: * persistence capable object.
054: *
055: * @param cld The {@link org.apache.ojb.broker.metadata.ClassDescriptor} of the object
056: * @param obj The object to build the {@link Identity} for
057: * @return The new <em>Identity</em> object.
058: */
059: Identity buildIdentity(ClassDescriptor cld, Object obj);
060:
061: /**
062: * Build a unique {@link org.apache.ojb.broker.Identity}
063: * for the given primary key values (composite PK's) of a
064: * persistence capable object.
065: *
066: * @param realClass The class of the associated object
067: * @param topLevelClass The top-level class of the associated object
068: * @param pkFieldName The field names of the PK fields
069: * @param pkValues The PK values
070: * @return The new <em>Identity</em> object
071: */
072: Identity buildIdentity(Class realClass, Class topLevelClass,
073: 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,
085: Object[] pkValues);
086:
087: /**
088: * Convenience method for persistent objects with single primary key.
089: * NOTE: Do not use for objects with composed PK!
090: *
091: * @param realClass The class of the associated object
092: * @param pkValue The PK value
093: * @return The new <em>Identity</em> object
094: * @see #buildIdentity(java.lang.Class, java.lang.String[], java.lang.Object[])
095: */
096: Identity buildIdentity(Class realClass, Object pkValue);
097:
098: /**
099: * Create a new {@link Identity} object based on given arguments - NOTE: There
100: * will be no check to resolve the order of the PK values. This method expect
101: * the correct order based on the declaration of the {@link org.apache.ojb.broker.metadata.FieldDescriptor}
102: * in the mapping file.
103: *
104: * @param realClass The class of the associated object
105: * @param topLevelClass The top-level class of the associated object
106: * @param pkValues The PK values
107: * @return The new <em>Identity</em> object
108: */
109: Identity buildIdentity(Class realClass, Class topLevelClass,
110: Object[] pkValues);
111: }
|