KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > versant > core > common > OID


1
2 /*
3  * Copyright (c) 1998 - 2005 Versant Corporation
4  * All rights reserved. This program and the accompanying materials
5  * are made available under the terms of the Eclipse Public License v1.0
6  * which accompanies this distribution, and is available at
7  * http://www.eclipse.org/legal/epl-v10.html
8  *
9  * Contributors:
10  * Versant Corporation - initial API and implementation
11  */
12 package com.versant.core.common;
13
14 import com.versant.core.metadata.ClassMetaData;
15 import com.versant.core.util.FastExternalizable;
16
17 /**
18  * This is an abstract base class for OID classes. Each PC class has its own
19  * implementation generated for it at runtime. These implementations have fast
20  * implementations of various methods in the base class designed for different
21  * data stores.
22  * </p>
23  * Implementations must define equals and hashcode so that OIDs for the same
24  * class heirachy with the same datastore or application identity are equal and
25  * have the same hashcode.
26  * </p>
27  * Some of the methods in this interface can be implemented by calling other
28  * methods. This is deliberate as a generated hyperdrive OID class can
29  * hardcode the return value and avoid having to dereference a field every
30  * time. Example: OID.getClassIndex() == OID.getClassMetaData().index.
31  * </p>
32  * This interface must not extend Externalizable. Subclasses except for
33  * NewObjectOID must implement Externalizable so they can be serialized
34  * using writeObject. NewObjectOID must be serialized using the
35  * FastExternalizable methods instead and this restriction enforces this
36  * (NotSerializable exception if it happens).
37  */
38 public interface OID extends Comparable JavaDoc, FastExternalizable {
39
40     /**
41      * Is this an OID for a new object?
42      */
43     public boolean isNew();
44
45     /**
46      * If this is a real OID (i.e. it has been assigned in the database)
47      * then return itself. Otherwise return the corresponding real OID or
48      * null if none has been allocated yet.
49      */
50     public OID getRealOID();
51
52     /**
53      * If this is a real OID (i.e. it has been assigned in the database)
54      * then return itself. Otherwise return the corresponding real OID or
55      * this if none has been allocated yet. This differs from
56      * {@link #getRealOID()} in that it always returns an OID reference
57      * even if this is a new OID and no real OID has been allocated.
58      */
59     public OID getAvailableOID();
60
61     /**
62      * Do we know the actual class of the object we are referencing? An
63      * OID may be created from a reference to a base class. The actual
64      * class of the object referenced might only be detirmined when its
65      * State is fetched from the store.
66      *
67      * @see #resolve
68      */
69     public boolean isResolved();
70
71     /**
72      * Resolve this OID from the state. This will update our class index
73      * to reflect the state. It is a NOP to call this on an already
74      * resolved OID.
75      *
76      * @see #isResolved
77      */
78     public void resolve(State state);
79
80     /**
81      * Get the meta data for our class. This will throw a RuntimeException
82      * if called on an unresolved or untyped OID.
83      *
84      * @see #isResolved
85      * @see #resolve
86      */
87     public ClassMetaData getClassMetaData();
88
89     /**
90      * Get whatever meta data is currently available for our class. The
91      * actual class may be a subclass of this. This will return null for
92      * an untyped OID.
93      */
94     public ClassMetaData getAvailableClassMetaData();
95
96     /**
97      * Get the meta data for the least derived class in our heirachy.
98      * This is getAvailableClassMetaData().top but this method can be
99      * hardcoded in a generated class. This will return null for
100      * an untyped OID.
101      */
102     public ClassMetaData getBaseClassMetaData();
103
104     /**
105      * Return the index of our PC class in the meta data. This can be
106      * called on an unresolved OID and the actual class may
107      * be a subclass of the class for the returned index.
108      * This is getAvailableClassMetaData().index but this method can be
109      * hardcoded in a generated class.
110      */
111     public int getClassIndex();
112
113     /**
114      * Get the identity type of the class we are referencing. It is ok to
115      * call this for an unresolved OID as the identity type is the same for
116      * all classes in a heirachy.
117      */
118     public int getIdentityType();
119
120     /**
121      * Populate this OID from the array of Objects supplied. These will
122      * come from some sort of key generator (e.g. a JdbcKeyGenerator).
123      * This is used to construct OIDs for newly created objects. Note that
124      * data may contain extra garbage objects from previously usages.
125      */
126     public void copyKeyFields(Object JavaDoc[] data);
127
128     /**
129      * Return a copy of the oid.
130      */
131     public OID copy();
132
133     /**
134      * Fill in this OID from an instance of the objectid-class for the
135      * heirachy.
136      */
137     public void fillFromPK(Object JavaDoc pk);
138
139     /**
140      * Fill this OID from its toString. The classid will have already been
141      * parsed out with index indicating the first character after the
142      * separator.
143      */
144     public void fillFromIDString(String JavaDoc idString, int index);
145
146     /**
147      * Fill this OID from the given id. If objectIdClass is mapped then 'id' will
148      * be assumed to be a instance of the objectIdClass, else 'id' is assumed to
149      * be a 'pk' for a class with a single pk field.
150      * @param id
151      */
152     public OID fillFromIDObject(Object JavaDoc id);
153
154     /**
155      * Encode the 'primary key' of this OID as a String. This is used for
156      * pretty printing OIDs in the workbench.
157      */
158     public String JavaDoc toPkString();
159
160     /**
161      * Encode the 'primary key' of this OID as a String. This is used for
162      * debugging.
163      */
164     public String JavaDoc toSString();
165
166     /**
167      * Get the toString of this OID even if it has not been resolved.
168      */
169     public String JavaDoc toStringImp();
170
171     /**
172      * The IBM VMs have a problem with unimplemented interface methods in
173      * classes so we need this.
174      */
175     public int compareTo(Object JavaDoc o);
176
177     /**
178      * Return the primary key stored in this OID as an int. This will only
179      * be called for datastore identity classes.
180      */
181     public long getLongPrimaryKey();
182
183     /**
184      * Set the primary key stored in this OID as an int. This will only be
185      * called for datastore identity classes.
186      */
187     public void setLongPrimaryKey(long pk);
188
189     /**
190      * Populate an instance of the objectid-class for our class from this
191      * OID. This must throw a JDOFatalInternalException if invoked on an
192      * OID for a datastore identity class.
193      */
194     public void populateObjectIdClassInstance(Object JavaDoc o);
195     
196     /**
197      * Get the classId from the available class meta data or -1 if this is
198      * an untyped OID.
199      */
200     public int getAvailableClassId();
201
202 }
203
Popular Tags