001: /**********************************************************************
002: Copyright (c) 2006 Erik Bengtson and others. All rights reserved.
003: Licensed under the Apache License, Version 2.0 (the "License");
004: you may not use this file except in compliance with the License.
005: You may obtain a copy of the License at
006:
007: http://www.apache.org/licenses/LICENSE-2.0
008:
009: Unless required by applicable law or agreed to in writing, software
010: distributed under the License is distributed on an "AS IS" BASIS,
011: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012: See the License for the specific language governing permissions and
013: limitations under the License.
014:
015: Contributors:
016: ...
017: **********************************************************************/package org.jpox.api;
018:
019: import java.util.Map;
020:
021: import org.jpox.ClassLoaderResolver;
022: import org.jpox.ObjectManager;
023: import org.jpox.StateManager;
024: import org.jpox.exceptions.JPOXException;
025: import org.jpox.metadata.AbstractClassMetaData;
026: import org.jpox.state.LifeCycleState;
027:
028: /**
029: * Adapter to allow the JPOX core runtime to expose multiple APIs to clients.
030: *
031: * @version $Revision: 1.24 $
032: */
033: public interface ApiAdapter {
034: // ------------------------------ Object Lifecycle --------------------------------
035:
036: /**
037: * Method to create a new StateManager for the ObjectManager and class.
038: * @param om ObjectManager
039: * @param acmd MetaData for the class/interface
040: */
041: StateManager newStateManager(ObjectManager om,
042: AbstractClassMetaData acmd);
043:
044: /**
045: * Returns the LifeCycleState for the state constant.
046: * @param stateType the type as integer
047: * @return the type as LifeCycleState object
048: */
049: LifeCycleState getLifeCycleState(int stateType);
050:
051: /**
052: * Accessor for whether the passed object is persistent.
053: * @param obj The object
054: * @return Whether it is persistent
055: */
056: boolean isPersistent(Object obj);
057:
058: /**
059: * Accessor for whether the passed object is new.
060: * @param obj The object
061: * @return Whether it is new
062: */
063: boolean isNew(Object obj);
064:
065: /**
066: * Accessor for whether the passed object is dirty.
067: * @param obj The object
068: * @return Whether it is dirty
069: */
070: boolean isDirty(Object obj);
071:
072: /**
073: * Accessor for whether the passed object is deleted.
074: * @param obj The object
075: * @return Whether it is deleted
076: */
077: boolean isDeleted(Object obj);
078:
079: /**
080: * Accessor for whether the passed object is detached.
081: * @param obj The object
082: * @return Whether it is detached
083: */
084: boolean isDetached(Object obj);
085:
086: /**
087: * Accessor for whether the passed object is transactional.
088: * @param obj The object
089: * @return Whether it is transactional
090: */
091: boolean isTransactional(Object obj);
092:
093: /**
094: * Method to return if the passed object is persistable using this API.
095: * @param obj The object
096: * @return Whether it is persistable
097: */
098: boolean isPersistable(Object obj);
099:
100: /**
101: * Utility method to check if the specified class is of a type that can be persisted for this API.
102: * @param cls The class to check
103: * @return Whether the class is persistable using this API.
104: */
105: boolean isPersistable(Class cls);
106:
107: /**
108: * Method to return if the passed object is detachable using this API.
109: * @param obj The object
110: * @return Whether it is detachable
111: */
112: boolean isDetachable(Object obj);
113:
114: /**
115: * Accessor for the object state.
116: * @param obj Object
117: * @return The state ("persistent-clean", "detached-dirty" etc)
118: */
119: String getObjectState(Object obj);
120:
121: // ------------------------------ Object Identity --------------------------------
122:
123: /**
124: * Method to return the object identity for the passed persistable object.
125: * Returns null if it is not persistable, or has no identity.
126: * @param obj The object
127: * @return The identity
128: */
129: Object getIdForObject(Object obj);
130:
131: /**
132: * Method to return the object version for the passed persistable object.
133: * Returns null if it is not persistable, or not versioned.
134: * @param obj The object
135: * @return The version
136: */
137: Object getVersionForObject(Object obj);
138:
139: /**
140: * Utility to check if a primary-key class is valid.
141: * Will throw a InvalidPrimaryKeyException if it is invalid, otherwise returning true.
142: * @param pkClass The Primary Key class
143: * @param cmd AbstractClassMetaData for the PersistenceCapable class
144: * @param clr the ClassLoaderResolver
145: * @param noOfPkFields Number of primary key fields
146: * @return Whether it is valid
147: */
148: boolean isValidPrimaryKeyClass(Class pkClass,
149: AbstractClassMetaData cmd, ClassLoaderResolver clr,
150: int noOfPkFields);
151:
152: /**
153: * Accessor for whether the passed identity is a valid single-field application-identity for this API.
154: * @return Whether it is valid
155: */
156: boolean isSingleFieldIdentity(Object id);
157:
158: /**
159: * Accessor for whether the passed class name is a valid single-field application-identity for this API.
160: * @param className Name of the class
161: * @return Whether it is valid
162: */
163: boolean isSingleFieldIdentityClass(String className);
164:
165: /**
166: * Accessor for the class name to use for identities when there is a single Long/long field.
167: * @return Class name of identity class
168: */
169: String getSingleFieldIdentityClassNameForLong();
170:
171: /**
172: * Accessor for the class name to use for identities when there is a single Integer/int field.
173: * @return Class name of identity class
174: */
175: String getSingleFieldIdentityClassNameForInt();
176:
177: /**
178: * Accessor for the class name to use for identities when there is a single Short/short field.
179: * @return Class name of identity class
180: */
181: String getSingleFieldIdentityClassNameForShort();
182:
183: /**
184: * Accessor for the class name to use for identities when there is a single Byte/byte field.
185: * @return Class name of identity class
186: */
187: String getSingleFieldIdentityClassNameForByte();
188:
189: /**
190: * Accessor for the class name to use for identities when there is a single Character/char field.
191: * @return Class name of identity class
192: */
193: String getSingleFieldIdentityClassNameForChar();
194:
195: /**
196: * Accessor for the class name to use for identities when there is a single String field.
197: * @return Class name of identity class
198: */
199: String getSingleFieldIdentityClassNameForString();
200:
201: /**
202: * Accessor for the class name to use for identities when there is a single Object field.
203: * @return Class name of identity class
204: */
205: String getSingleFieldIdentityClassNameForObject();
206:
207: /**
208: * Accessor for the target class for the specified single field identity.
209: * @param id The identity
210: * @return The target class
211: */
212: Class getTargetClassForSingleFieldIdentity(Object id);
213:
214: /**
215: * Accessor for the target class name for the specified single field identity.
216: * @param id The identity
217: * @return The target class name
218: */
219: String getTargetClassNameForSingleFieldIdentity(Object id);
220:
221: /**
222: * Accessor for the key object for the specified single field identity.
223: * @param id The identity
224: * @return The key object
225: */
226: Object getTargetKeyForSingleFieldIdentity(Object id);
227:
228: /**
229: * Accessor for the type of the single field application-identity key given the single field identity type.
230: * @param idType Single field identity type
231: * @return key type
232: */
233: Class getKeyTypeForSingleFieldIdentityType(Class idType);
234:
235: /**
236: * Utility to create a new SingleFieldIdentity using reflection when you know the
237: * type of the PersistenceCapable, and also which SingleFieldIdentity, and the value of the key.
238: * @param idType Type of SingleFieldIdentity
239: * @param pcType Type of the PersistenceCapable
240: * @param value The value for the identity (the Long, or Int, or ... etc).
241: * @return The single field identity
242: * @throws JPOXException if invalid input is received
243: */
244: Object getNewSingleFieldIdentity(Class idType, Class pcType,
245: Object value);
246:
247: /**
248: * Method to create a new object identity for the passed object with the supplied MetaData.
249: * Only applies to application-identity cases.
250: * @param pc The persistable object
251: * @param cmd Its metadata
252: * @return The new identity object
253: */
254: Object getNewApplicationIdentityObjectId(Object pc,
255: AbstractClassMetaData cmd);
256:
257: /**
258: * Method to return a new object identity for the specified class, and key (possibly toString() output).
259: * @param cls Persistable class
260: * @param key form of the object id
261: * @return The object identity
262: */
263: Object getNewApplicationIdentityObjectId(Class cls, Object key);
264:
265: // ------------------------------ Persistence --------------------------------
266:
267: /**
268: * Whether the API allows (re-)persistence of a deleted object.
269: * @return Whether you can call persist on a deleted object
270: */
271: boolean allowPersistOfDeletedObject();
272:
273: /**
274: * Whether the API allows deletion of a non-persistent object.
275: * @return Whether you can call delete on an object not yet persisted
276: */
277: boolean allowDeleteOfNonPersistentObject();
278:
279: /**
280: * Whether the API allows reading a field of a deleted object.
281: * @return Whether you can read after deleting
282: */
283: boolean allowReadFieldOfDeletedObject();
284:
285: /**
286: * Whether the API requires clearing of the fields of an object when it is deleted.
287: * @return Whether to clear loaded fields at delete
288: */
289: boolean clearLoadedFlagsOnDeleteObject();
290:
291: /**
292: * Method to return the default setting for cascading persist of a field
293: * @return default persist cascade setting.
294: */
295: boolean getDefaultCascadePersistForField();
296:
297: /**
298: * Method to return the default setting for cascading update of a field
299: * @return default cascade update setting.
300: */
301: boolean getDefaultCascadeUpdateForField();
302:
303: /**
304: * Method to return the default setting for cascading delete of a field
305: * @return default cascade delete setting.
306: */
307: boolean getDefaultCascadeDeleteForField();
308:
309: /**
310: * Method to return the default setting for cascading refresh of a field
311: * @return default cascade refresh setting.
312: */
313: boolean getDefaultCascadeRefreshForField();
314:
315: /**
316: * Method to return a set of default properties for the factory (PMF, EMF, etc)
317: * @return The default properties (if any) for this API
318: */
319: Map getDefaultFactoryProperties();
320:
321: // ------------------------------ StateManager --------------------------------
322:
323: /**
324: * Accessor for the object id from the StateManager for this object.
325: * @param sm StateManager
326: * @return object id
327: */
328: Object getObjectId(StateManager sm);
329:
330: /**
331: * Accessor for the version from the StateManager for this object.
332: * @param sm StateManager
333: */
334: Object getVersion(StateManager sm);
335:
336: /**
337: * Accessor for whether a field is loaded for the object managed by the StateManager
338: * @param sm StateManager
339: * @param fieldNumber Number of the field
340: * @return Whether it is loaded
341: */
342: boolean isLoaded(StateManager sm, int fieldNumber);
343:
344: /**
345: * Accessor for the persistence manager for this object.
346: * The returned object will be a JDO PersistenceManager (if using JDO), or an
347: * EntityManager (if using JPA), or null if not managed.
348: * @param obj The object
349: * @return The persistence manager
350: */
351: Object getPersistenceManager(Object obj);
352:
353: /**
354: * Method to make the field dirty in the object.
355: * @param obj Object
356: * @param fieldName Name of the field to make dirty
357: */
358: void makeFieldDirty(Object obj, String fieldName);
359: }
|