1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18 package org.apache.jdo.model.jdo;
19
20 import org.apache.jdo.model.ModelException;
21 import org.apache.jdo.model.java.JavaType;
22
23
24 /***
25 * A JDOClass instance represents the JDO metadata of a persistence-capable
26 * class.
27 *
28 * @author Michael Bouschen
29 * @version 2.0
30 */
31 public interface JDOClass
32 extends JDOMember
33 {
34 /***
35 * Get the short name of this JDOClass. The short name defaults to the
36 * unqualified class name, if not explicitly set by method
37 * {@link #setShortName(String shortName)}.
38 * @return the short name of this JDOClass.
39 */
40 public String getShortName();
41
42 /***
43 * Set the short name of this JDOClass.
44 * @param shortName the short name.
45 * @exception ModelException if impossible
46 */
47 public void setShortName(String shortName)
48 throws ModelException;
49
50 /***
51 * Get the JDO identity type of this JDOClass.
52 * The identity type of the least-derived persistence-capable class defines
53 * the identity type for all persistence-capable classes that extend it.
54 * The identity type of the least-derived persistence-capable class is
55 * defaulted to {@link JDOIdentityType#APPLICATION} if objectid-class is
56 * specified, and {@link JDOIdentityType#DATASTORE}, if not.
57 * @return the JDO identity type, one of
58 * {@link JDOIdentityType#APPLICATION},
59 * {@link JDOIdentityType#DATASTORE}, or
60 * {@link JDOIdentityType#NONDURABLE}
61 */
62 public int getIdentityType();
63
64 /***
65 * Set the object identity type of this JDOClass.
66 * @param identityType an integer indicating the JDO identity type, one of:
67 * {@link JDOIdentityType#APPLICATION},
68 * {@link JDOIdentityType#DATASTORE}, or
69 * {@link JDOIdentityType#NONDURABLE}
70 * @exception ModelException if impossible
71 */
72 public void setIdentityType(int identityType)
73 throws ModelException;
74
75 /***
76 * Get the JavaType representation of the object identity class
77 * (primary key class) for this JDOClass.
78 * @return the JavaType representation of the object identity class.
79 */
80 public JavaType getObjectIdClass();
81
82 /***
83 * Set the JavaType representation of the object identity class
84 * (primary key class) for this JDOClass.
85 * @param objectIdClass the JavaType representation of the
86 * object identity class.
87 * @exception ModelException if impossible
88 */
89 public void setObjectIdClass(JavaType objectIdClass)
90 throws ModelException;
91
92 /***
93 * Get the fully qualified name of the object identity class
94 * (primary key class) declared for this JDOClass.
95 * Please note, this method returns a non null class name, only if the
96 * JDO metadata defines an objectIdClass for exactly the pc class
97 * represented by this JDOClass. If there is no objectIdClass defines for
98 * this JDOClass, but any of the pc-superclasses defines an objectIdClass,
99 * this method returns <code>null</code>. This is different from method
100 * {@link #getObjectIdClass} which returns a non-null value, if the
101 * superclass defines a objectIdClass.
102 * @return the name of the object identity class.
103 */
104 public String getDeclaredObjectIdClassName();
105
106 /***
107 * Set the fully qualified name of the object identity class
108 * (primary key class) declared for this JDOClass.
109 * @param declaredObjectIdClassName the name of the object identity class
110 * @exception ModelException if impossible
111 */
112 public void setDeclaredObjectIdClassName(String declaredObjectIdClassName)
113 throws ModelException;
114
115 /***
116 * Determines whether an extent must be managed for the
117 * persistence-capable class described by this JDOClass.
118 * @return <code>true</true> if this class must manage an extent;
119 * <code>false</code> otherwise
120 */
121 public boolean requiresExtent();
122
123 /***
124 * Set whether an extent must be managed for the
125 * persistence-capable class described by this JDOClass.
126 * @param requiresExtent <code>true</code> if this class must manage
127 * an extent; <code>false</code> otherwise
128 * @exception ModelException if impossible
129 */
130 public void setRequiresExtent(boolean requiresExtent)
131 throws ModelException;
132
133 /***
134 * Get the fully qualified class name of the persistence-capable superclass
135 * of the persistence-capable class described by this JDOClass. If this
136 * class does not have a persistence-capable superclass then
137 * <code>null</code> is returned.
138 * @return the fully qualified name of the persistence-capable superclass
139 * or <code>null</code> if there is no persistence-capable superclass
140 */
141 public String getPersistenceCapableSuperclassName();
142
143 /***
144 * Set the fully qualified class name of the persistence-capable superclass
145 * of the persistence-capable class described by this JDOClass.
146 * @param pcSuperclassName the fully qualified name of the
147 * persistence-capable superclass
148 * @exception ModelException if impossible
149 */
150 public void setPersistenceCapableSuperclassName(String pcSuperclassName)
151 throws ModelException;
152
153 /***
154 * Provides the JavaType representaion corresponding to this JDOClass.
155 * <p>
156 * Note the difference between Object.getClass) and this method. The
157 * former returns the class of the object in hand, this returns the class
158 * of the object represented by this meta data.
159 * @return the JavaType object corresponding to this JDOClass.
160 */
161 public JavaType getJavaType();
162
163 /***
164 * Set the JavaType representation corresponding to this JDOClass.
165 * @param javaType the JavaType representation for this JDOClass.
166 * @exception ModelException if impossible
167 */
168 public void setJavaType(JavaType javaType)
169 throws ModelException;
170
171 /***
172 * Determines whether the XML metadata for the class represented by this
173 * JDOClass has been loaded.
174 * @return <code>true</code> if XML metadata is loaded;
175 * <code>false</code> otherwise
176 */
177 public boolean isXMLMetadataLoaded();
178
179 /***
180 * Sets the flag indicating that the class XML metadata for this
181 * JDOClass is loaded to <code>true</code>.
182 */
183 public void setXMLMetadataLoaded();
184
185 /***
186 * Remove the supplied member from the collection of members maintained by
187 * this JDOClass.
188 * @param member the member to be removed
189 * @exception ModelException if impossible
190 */
191 public void removeDeclaredMember(JDOMember member)
192 throws ModelException;
193
194 /***
195 * Returns the collection of JDOMember instances declared by this JDOClass
196 * in form of an array.
197 * @return the members declared by this JDOClass
198 */
199 public JDOMember[] getDeclaredMembers();
200
201 /***
202 * Returns the declaring JDOModel of this JDOClass.
203 * @return the JDOModel that owns this JDOClass
204 */
205 public JDOModel getDeclaringModel();
206
207 /***
208 * Set the declaring JDOModel for this JDOClass.
209 * @param model the declaring JDOModel of this JDOClass
210 */
211 public void setDeclaringModel(JDOModel model);
212
213 /***
214 * Returns the JDOClass instance for the persistence-capable superclass
215 * of this JDOClass. If this class does not have a persistence-capable
216 * superclass then <code>null</code> is returned.
217 * @return the JDClass instance of the persistence-capable superclass
218 * or <code>null</code> if there is no persistence-capable superclass
219 */
220 public JDOClass getPersistenceCapableSuperclass();
221
222 /***
223 * Set the JDOClass for the persistence-capable superclass
224 * of this JDOClass.
225 * @param pcSuperclass the JDClass instance of the persistence-capable
226 * superclass
227 * @exception ModelException if impossible
228 */
229 public void setPersistenceCapableSuperclass(JDOClass pcSuperclass)
230 throws ModelException;
231
232 /***
233 * Returns the JDOPackage instance corresponding to the package name
234 * of this JDOClass.
235 * @return the JDOPackage instance of this JDOClass.
236 */
237 public JDOPackage getJDOPackage();
238
239 /***
240 * Sets the JDOPackage instance corresponding to the package name
241 * of this JDOClass.
242 * @param jdoPackage the JDOPackage of this JDOClass.
243 */
244 public void setJDOPackage(JDOPackage jdoPackage);
245
246 /***
247 * This method returns a JDOField instance for the field with the specified
248 * name. If this JDOClass already declares such a field, the existing
249 * JDOField instance is returned. Otherwise, it creates a new JDOField
250 * instance, sets its declaring JDOClass and returns the new instance.
251 * @param name the name of the field
252 * @return a JDOField instance for the specified field name
253 * @exception ModelException if impossible
254 */
255 public JDOField createJDOField(String name)
256 throws ModelException;
257
258 /***
259 * This method returns a JDOProperty instance for the property with the
260 * specified name. If this JDOClass already declares such a property, the
261 * existing JDOProperty instance is returned. Otherwise, it creates a new
262 * JDOProperty instance, sets its declaring JDOClass and returns the new
263 * instance.
264 * @param name the name of the property
265 * @return a JDOProperty instance for the specified property
266 * @exception ModelException if impossible
267 */
268 public JDOProperty createJDOProperty(String name)
269 throws ModelException;
270
271 /***
272 * This method returns a JDOProperty instance for the property with the
273 * specified name and associated field. If this JDOClass already declares
274 * such a property the existing JDOProperty instance is returned. If it
275 * declares a property with the specified name but different associated
276 * field, then a ModelException is thrown. If there is no such property,
277 * the method creates a new JDOProperty instance, sets its declaring
278 * JDOClass and associated field and returns the new instance.
279 * @param name the name of the property
280 * @param associatedField the associated JDOField
281 * @return a JDOProperty instance for the specified property
282 * @exception ModelException if impossible
283 */
284 public JDOProperty createJDOProperty(String name, JDOField associatedField)
285 throws ModelException;
286
287 /***
288 * This method returns a JDOClass instance representing an inner class of
289 * this JDOClass If this JDOClass already declares such an inner class,
290 * the existing JDOClass instance is returned. Otherwise, it creates a new
291 * JDOClass instance, sets its declaring JDOClass and returns the new
292 * instance.
293 * @param name the name of the inner class
294 * @exception ModelException if impossible
295 */
296 public JDOClass createJDOClass(String name)
297 throws ModelException;
298
299 /***
300 * Returns the collection of JDOClass instances declared by this JDOClass.
301 * @return the classes declared by this JDOClass
302 */
303 public JDOClass[] getDeclaredClasses();
304
305 /***
306 * Returns the collection of JDOField instances declared by this JDOClass
307 * in the form of an array. This does not include inherited fields.
308 * @return the fields declared by this JDOClass
309 */
310 public JDOField[] getDeclaredFields();
311
312 /***
313 * Returns the collection of managed JDOField instances declared by this
314 * JDOClass in the form of an array. The returned array does not include
315 * inherited fields. A field is a managed field, if it has the
316 * persistence-modifier {@link PersistenceModifier#PERSISTENT} or
317 * {@link PersistenceModifier#TRANSACTIONAL}. The position of the fields
318 * in the returned array equals their relative field number as returned by
319 * {@link JDOField#getRelativeFieldNumber()}. The following holds true for
320 * any field in the returned array:
321 * <ul>
322 * <li> <code>getDeclaredManagedFields()[i].getRelativeFieldNumber()
323 * == i</code>
324 * <li> <code>getDeclaredManagedFields()[field.getRelativeFieldNumber()]
325 * == field</code>
326 * </ul>
327 * @return the managed fields declared by this JDOClass
328 */
329 public JDOField[] getDeclaredManagedFields();
330
331 /***
332 * Returns the collection of managed JDOField instances of this JDOClass
333 * in the form of an array. The returned array includes inherited fields.
334 * A field is a managed field, if it has the persistence-modifier
335 * {@link PersistenceModifier#PERSISTENT} or
336 * {@link PersistenceModifier#TRANSACTIONAL}. The position of the fields
337 * in the returned array equals their absolute field number as returned by
338 * {@link JDOField#getFieldNumber()}. The following holds true for any
339 * field in the returned array:
340 * <ul>
341 * <li> <code>getManagedFields()[i].getFieldNumber() == i</code>
342 * <li> <code>getManagedFields()[field.getFieldNumber()] == field</code>
343 * </ul>
344 * @return the managed fields of this JDOClass
345 */
346 public JDOField[] getManagedFields();
347
348 /***
349 * Returns the collection of persistent JDOField instances of this JDOClass
350 * in the form of an array. The returned array includes inherited fields.
351 * A field is a persistent field, if it has the persistence-modifier
352 * {@link PersistenceModifier#PERSISTENT}.
353 * Please note, the position of the fields in the returned array might not
354 * equal their absolute field number as returned by
355 * {@link JDOField#getFieldNumber()}.
356 * @return the persistent fields of this JDOClass
357 */
358 public JDOField[] getPersistentFields();
359
360 /***
361 * Returns the collection of identifying fields of this JDOClass in the form
362 * of an array. The method returns the JDOField instances defined as
363 * primary key fields (see {@link JDOField#isPrimaryKey}).
364 * @return the identifying fields of this JDOClass
365 */
366 public JDOField[] getPrimaryKeyFields();
367
368 /***
369 * Returns the collection of persistent relationship fields of this JDOClass
370 * in the form of an array. The method returns the JDOField instances
371 * defined as relationship (method {@link JDOField#getRelationship} returns
372 * a non null value) and having the persistence-modifier
373 * {@link PersistenceModifier#PERSISTENT}.
374 * @return the persistent relationship fields of this JDOClass
375 */
376 public JDOField[] getPersistentRelationshipFields();
377
378 /***
379 * Returns the collection of default fetch group fields of this JDOClass
380 * in the form of an array. The method returns the JDOField instances
381 * defined as part of the default fetch group
382 * (method {@link JDOField#isDefaultFetchGroup} returns <code>true</code>.
383 * @return the default fetch group fields of this JDOClass
384 * @since 1.1
385 */
386 public JDOField[] getDefaultFetchGroupFields();
387
388 /***
389 * Returns an array of absolute field numbers of the managed fields of this
390 * JDOClass. The returned array includes field numbers of inherited fields.
391 * A field is a managed field, if it has the persistence-modifier
392 * {@link PersistenceModifier#PERSISTENT} or
393 * {@link PersistenceModifier#TRANSACTIONAL}.
394 * Only managed fields have a valid field number, thus the field number in
395 * the returned array equals its index:
396 * <br>
397 * <code>getManagedFields()[i] == i</code>
398 */
399 public int[] getManagedFieldNumbers();
400
401 /***
402 * Returns an array of absolute field numbers of the persistent fields of
403 * this JDOClass. The returned array includes field numbers of inherited
404 * fields. A persistent field has the persistence-modifier
405 * {@link PersistenceModifier#PERSISTENT}.
406 */
407 public int[] getPersistentFieldNumbers();
408
409 /***
410 * Returns an array of absolute field numbers of the identifying fields
411 * of this JDOClass. A field number is included in the returned array,
412 * iff the corresponding JDOField instance is defined as primary key field
413 * (see {@link JDOField#isPrimaryKey}).
414 * @return array of numbers of the identifying fields
415 */
416 public int[] getPrimaryKeyFieldNumbers();
417
418 /***
419 * Returns an array of absolute field numbers of the non identifying,
420 * persistent fields of this JDOClass. A field number is included in the
421 * returned array, iff the corresponding JDOField instance is persistent and
422 * not a not a primary key field (see {@link JDOField#isPrimaryKey}).
423 * A field is a persistent field, if it has the persistence-modifier
424 * {@link PersistenceModifier#PERSISTENT} or
425 * (see {@link JDOField#getPersistenceModifier}).
426 * @return array of numbers of the non identifying, persistent fields
427 */
428 public int[] getPersistentNonPrimaryKeyFieldNumbers();
429
430 /***
431 * Returns an array of absolute field numbers of persistent relationship
432 * fields of this JDOClass. A field number is included in the returned
433 * array, iff the corresponding JDOField instance is a relationship (method
434 * {@link JDOField#getRelationship} returns a non null value) and has the
435 * persistence-modifier {@link PersistenceModifier#PERSISTENT}.
436 * @return the field numbers of the persistent relationship fields
437 */
438 public int[] getPersistentRelationshipFieldNumbers();
439
440 /***
441 * Returns an array of absolute field numbers of persistent, serializable
442 * fields of this JDOClass. A field number is included in the returned
443 * array, iff the corresponding JDOField instance is serializable (method
444 * {@link JDOField#isSerializable} returns <code>true</code>) and has the
445 * persistence-modifier {@link PersistenceModifier#PERSISTENT}.
446 * @return the field numbers of serializable fields
447 */
448 public int[] getPersistentSerializableFieldNumbers();
449
450 /***
451 * Returns JDOField metadata for a particular managed field specified by
452 * field name. It returns <code>null</code> if the specified name does not
453 * denote a managed field of this JDOClass. The field name may be
454 * unqualified and or qualified (see {@link #getField(String fieldName)}).
455 * @param fieldName the name of the managed field for which field metadata
456 * is needed.
457 * @return JDOField metadata for the managed field or <code>null</code>
458 * if there is no such field.
459 */
460 public JDOField getManagedField(String fieldName);
461
462 /***
463 * Returns JDOField metadata for a particular field specified by field name.
464 * It returns <code>null</code> if the specified name does not denote a
465 * field of this JDOClass.
466 * <p>
467 * The method supports lookup by unqualified and by qualified field name.
468 * <ul>
469 * <li> In the case of an unqualified field name the method starts checking
470 * this JDOClass for a field with the specified name. If this class does not
471 * define such a field, it checks the inheritance hierarchy starting with
472 * its direct persistence-capable superclass. The method finds the first
473 * field with the specified name in a bootom-up lookup of the inheritance
474 * hierarchy. Hidden fields are not visible.
475 * <li> In the case of a qualified field name the method assumes a fully
476 * qualified class name (called qualifier class) as the field qualifier.
477 * The qualifier class must be a either this class or a persistence-capable
478 * superclass (direct or indirect) of this class. Then the method searches
479 * the field definition in the inheritance hierarchy staring with the
480 * qualifier class. Any field declarations with the same name in subclasses
481 * of the qualifier class are not considered. This form allows accessing
482 * fields hidden by subclasses. The method returns <code>null</code> if the
483 * qualifier class does not denote a valid class or if the qualifier class
484 * is not a persistence-capable superclass of this class.
485 * </ul>
486 * @param fieldName the unqualified or qualified name of field for which
487 * field metadata is needed.
488 * @return JDOField metadata for the field or <code>null</code>
489 * if there is no such field.
490 */
491 public JDOField getField(String fieldName);
492
493 /***
494 * Provides metadata for a particular field specified by the absolute field
495 * number. The field number must be a valid absolute field number for this
496 * JDOClass: <code>0 <= fieldNumber < this.getManagedFields().length</code>
497 * If the field number is valid the returned JDoField instance denotes a
498 * managed field, meaning the field has the persistence-modifier
499 * {@link PersistenceModifier#PERSISTENT} or
500 * {@link PersistenceModifier#TRANSACTIONAL}. If the field number is not
501 * valid then the method returns <code>null</code>.
502 * @param fieldNumber the number for which field metadata is needed.
503 * @return JDOField metadata for the field or <code>null</code>
504 * if there is no such field.
505 */
506 public JDOField getField(int fieldNumber);
507
508 /***
509 * Returns JDOField metadata for a particular declared field specified by
510 * field name. Please note, the method does not return inherited fields.
511 * The field name must not be qualified by a class name. The method returns
512 * <code>null</code> if the field name does not denote a field declared by
513 * JDOClass.
514 * @param fieldName the unqualified name of field for which field metadata
515 * is needed.
516 * @return JDOField metadata for the field or <code>null</code>
517 * if there is no such field declared by this JDOClass.
518 */
519 public JDOField getDeclaredField(String fieldName);
520
521 /***
522 * Returns JDOProperty metadata for a property with the specified name
523 * having an associated JDOField. The method returns <code>null</code>, if
524 * the name does not denote a property with an associated JDOField of this
525 * JDOClass. Please note, the method does not check for properties without
526 * an associated JDOField. It will return <code>null</code> if there is
527 * a property with the specified name, but this property does not have an
528 * associated JDOField.
529 * @param name the name of property with an associated JDOField for which
530 * metadata is needed.
531 * @return JDOProperty metadata for the property with an associated
532 * JDOField or <code>null</code> if there is no such property.
533 */
534 public JDOProperty getAssociatedProperty(String name);
535
536 /***
537 * Returns JDOProperty metadata for a property having the specified
538 * JDOField as associated JDOField. The method returns <code>null</code>,
539 * if this JDOClass does not have a property with the specified JDOField
540 * as associated JDOField.
541 * @param JDOField the assoaciated JDOField of the property for which
542 * metadata is needed.
543 * @return JDOProperty metadata for the property the specified JDOField as
544 * associated JDOField or <code>null</code> if there is no such property.
545 */
546 public JDOProperty getAssociatedProperty(JDOField field);
547
548 /***
549 * Returns the number of managed fields declared in the class represented
550 * by this JDOClass. This does not include inherited fields.
551 * @return number of declared managed fields
552 */
553 public int getDeclaredManagedFieldCount();
554
555 /***
556 * Returns the number of inherited managed fields for the class
557 * represented by this JDOClass.
558 * @return number of inherited managed fields
559 */
560 public int getInheritedManagedFieldCount();
561
562 /***
563 * Returns the number of managed fields for the class represented by this
564 * JDOClass. The value returned by this method is equal to
565 * <code>getDeclaredManagedFieldCount() +
566 * getInheritedManagedFieldCount()</code>.
567 * @return number of managed fields
568 */
569 public int getManagedFieldCount();
570
571 /***
572 * Returns the package name including a terminating dot if this class has a
573 * package. The method returns the empty string if this class is in the
574 * default package.
575 * @return package prefix for this class.
576 */
577 public String getPackagePrefix();
578
579 /***
580 * Returns the least-derived (topmost) persistence-capable class in the
581 * hierarchy of this JDOClass. It returns this JDOClass if it has no
582 * persistence-capable superclass.
583 * @return the topmost persistence-capable class in the hierarchy.
584 */
585 public JDOClass getPersistenceCapableRootClass();
586 }