IdentityFactory


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.2.2.4 2005/12/21 22:22:08 tomdz 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 }
110
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags