001: /*
002: * Copyright (c) 1998 - 2005 Versant Corporation
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * Versant Corporation - initial API and implementation
010: */
011: package com.versant.core.common;
012:
013: import com.versant.core.metadata.ClassMetaData;
014: import com.versant.core.util.FastExternalizable;
015:
016: /**
017: * This is an abstract base class for OID classes. Each PC class has its own
018: * implementation generated for it at runtime. These implementations have fast
019: * implementations of various methods in the base class designed for different
020: * data stores.
021: * </p>
022: * Implementations must define equals and hashcode so that OIDs for the same
023: * class heirachy with the same datastore or application identity are equal and
024: * have the same hashcode.
025: * </p>
026: * Some of the methods in this interface can be implemented by calling other
027: * methods. This is deliberate as a generated hyperdrive OID class can
028: * hardcode the return value and avoid having to dereference a field every
029: * time. Example: OID.getClassIndex() == OID.getClassMetaData().index.
030: * </p>
031: * This interface must not extend Externalizable. Subclasses except for
032: * NewObjectOID must implement Externalizable so they can be serialized
033: * using writeObject. NewObjectOID must be serialized using the
034: * FastExternalizable methods instead and this restriction enforces this
035: * (NotSerializable exception if it happens).
036: */
037: public interface OID extends Comparable, FastExternalizable {
038:
039: /**
040: * Is this an OID for a new object?
041: */
042: public boolean isNew();
043:
044: /**
045: * If this is a real OID (i.e. it has been assigned in the database)
046: * then return itself. Otherwise return the corresponding real OID or
047: * null if none has been allocated yet.
048: */
049: public OID getRealOID();
050:
051: /**
052: * If this is a real OID (i.e. it has been assigned in the database)
053: * then return itself. Otherwise return the corresponding real OID or
054: * this if none has been allocated yet. This differs from
055: * {@link #getRealOID()} in that it always returns an OID reference
056: * even if this is a new OID and no real OID has been allocated.
057: */
058: public OID getAvailableOID();
059:
060: /**
061: * Do we know the actual class of the object we are referencing? An
062: * OID may be created from a reference to a base class. The actual
063: * class of the object referenced might only be detirmined when its
064: * State is fetched from the store.
065: *
066: * @see #resolve
067: */
068: public boolean isResolved();
069:
070: /**
071: * Resolve this OID from the state. This will update our class index
072: * to reflect the state. It is a NOP to call this on an already
073: * resolved OID.
074: *
075: * @see #isResolved
076: */
077: public void resolve(State state);
078:
079: /**
080: * Get the meta data for our class. This will throw a RuntimeException
081: * if called on an unresolved or untyped OID.
082: *
083: * @see #isResolved
084: * @see #resolve
085: */
086: public ClassMetaData getClassMetaData();
087:
088: /**
089: * Get whatever meta data is currently available for our class. The
090: * actual class may be a subclass of this. This will return null for
091: * an untyped OID.
092: */
093: public ClassMetaData getAvailableClassMetaData();
094:
095: /**
096: * Get the meta data for the least derived class in our heirachy.
097: * This is getAvailableClassMetaData().top but this method can be
098: * hardcoded in a generated class. This will return null for
099: * an untyped OID.
100: */
101: public ClassMetaData getBaseClassMetaData();
102:
103: /**
104: * Return the index of our PC class in the meta data. This can be
105: * called on an unresolved OID and the actual class may
106: * be a subclass of the class for the returned index.
107: * This is getAvailableClassMetaData().index but this method can be
108: * hardcoded in a generated class.
109: */
110: public int getClassIndex();
111:
112: /**
113: * Get the identity type of the class we are referencing. It is ok to
114: * call this for an unresolved OID as the identity type is the same for
115: * all classes in a heirachy.
116: */
117: public int getIdentityType();
118:
119: /**
120: * Populate this OID from the array of Objects supplied. These will
121: * come from some sort of key generator (e.g. a JdbcKeyGenerator).
122: * This is used to construct OIDs for newly created objects. Note that
123: * data may contain extra garbage objects from previously usages.
124: */
125: public void copyKeyFields(Object[] data);
126:
127: /**
128: * Return a copy of the oid.
129: */
130: public OID copy();
131:
132: /**
133: * Fill in this OID from an instance of the objectid-class for the
134: * heirachy.
135: */
136: public void fillFromPK(Object pk);
137:
138: /**
139: * Fill this OID from its toString. The classid will have already been
140: * parsed out with index indicating the first character after the
141: * separator.
142: */
143: public void fillFromIDString(String idString, int index);
144:
145: /**
146: * Fill this OID from the given id. If objectIdClass is mapped then 'id' will
147: * be assumed to be a instance of the objectIdClass, else 'id' is assumed to
148: * be a 'pk' for a class with a single pk field.
149: * @param id
150: */
151: public OID fillFromIDObject(Object id);
152:
153: /**
154: * Encode the 'primary key' of this OID as a String. This is used for
155: * pretty printing OIDs in the workbench.
156: */
157: public String toPkString();
158:
159: /**
160: * Encode the 'primary key' of this OID as a String. This is used for
161: * debugging.
162: */
163: public String toSString();
164:
165: /**
166: * Get the toString of this OID even if it has not been resolved.
167: */
168: public String toStringImp();
169:
170: /**
171: * The IBM VMs have a problem with unimplemented interface methods in
172: * classes so we need this.
173: */
174: public int compareTo(Object o);
175:
176: /**
177: * Return the primary key stored in this OID as an int. This will only
178: * be called for datastore identity classes.
179: */
180: public long getLongPrimaryKey();
181:
182: /**
183: * Set the primary key stored in this OID as an int. This will only be
184: * called for datastore identity classes.
185: */
186: public void setLongPrimaryKey(long pk);
187:
188: /**
189: * Populate an instance of the objectid-class for our class from this
190: * OID. This must throw a JDOFatalInternalException if invoked on an
191: * OID for a datastore identity class.
192: */
193: public void populateObjectIdClassInstance(Object o);
194:
195: /**
196: * Get the classId from the available class meta data or -1 if this is
197: * an untyped OID.
198: */
199: public int getAvailableClassId();
200:
201: }
|