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