1 package org.apache.ojb.broker;
2
3 /* Copyright 2002-2005 The Apache Software Foundation
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 import org.apache.ojb.broker.metadata.ClassDescriptor;
19
20 /**
21 * Builds {@link org.apache.ojb.broker.Identity} objects to identify persistence capable objects within OJB.
22 * In many cases the primary key (based on metadata declaration) of an object is known
23 * and the whole object should be materialized (e.g. findByPrimaryKey(...) calls).
24 * This class make available a bunch of methods help to create {@link org.apache.ojb.broker.Identity}
25 * objects based on
26 * <ul>
27 * <li>the persistence capable object itself</li>
28 * <li>the primary key values of a persistence capable object</li>
29 * </ul>
30 * NOTE:
31 * <br/>
32 * It is possible to create transient {@link Identity} objects for transient,
33 * "new created" persistence capable objects. But keep in mind that this transient
34 * {@link Identity} object is only valid till the persistence capable object was written
35 * to datastore. After this the {@link Identity} have to be renewed by calling
36 * <code>IdentityFactory.buildIdentity(...)</code> again (then the transient Identity
37 * will be replaced by the persistent Identity).
38 *
39 * @version $Id: IdentityFactory.java,v 1.1 2007-08-24 22:17:36 ewestfal Exp $
40 */
41 public interface IdentityFactory
42 {
43 /**
44 * Build a unique {@link org.apache.ojb.broker.Identity} for the given
45 * persistence capable object.
46 *
47 * @param obj The object to build the {@link Identity} for
48 * @return The new <em>Identity</em> object
49 */
50 Identity buildIdentity(Object obj);
51
52 /**
53 * Build a unique {@link org.apache.ojb.broker.Identity} for the given
54 * persistence capable object.
55 *
56 * @param cld The {@link org.apache.ojb.broker.metadata.ClassDescriptor} of the object
57 * @param obj The object to build the {@link Identity} for
58 * @return The new <em>Identity</em> object.
59 */
60 Identity buildIdentity(ClassDescriptor cld, Object obj);
61
62 /**
63 * Build a unique {@link org.apache.ojb.broker.Identity}
64 * for the given primary key values (composite PK's) of a
65 * persistence capable object.
66 *
67 * @param realClass The class of the associated object
68 * @param topLevelClass The top-level class of the associated object
69 * @param pkFieldName The field names of the PK fields
70 * @param pkValues The PK values
71 * @return The new <em>Identity</em> object
72 */
73 Identity buildIdentity(Class realClass, Class topLevelClass, String[] pkFieldName, Object[] pkValues);
74
75 /**
76 * Convenience shortcut method for
77 * {@link #buildIdentity(java.lang.Class, java.lang.Class, java.lang.String[], java.lang.Object[])}.
78 *
79 * @param realClass The class of the associated object
80 * @param pkFieldName The field names of the PK fields
81 * @param pkValues The PK values
82 * @return The new <em>Identity</em> object
83 */
84 Identity buildIdentity(Class realClass, String[] pkFieldName, Object[] pkValues);
85
86 /**
87 * Convenience method for persistent objects with single primary key.
88 * NOTE: Do not use for objects with composed PK!
89 *
90 * @param realClass The class of the associated object
91 * @param pkValue The PK value
92 * @return The new <em>Identity</em> object
93 * @see #buildIdentity(java.lang.Class, java.lang.String[], java.lang.Object[])
94 */
95 Identity buildIdentity(Class realClass, Object pkValue);
96
97 /**
98 * Create a new {@link Identity} object based on given arguments - NOTE: There
99 * 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 }