View Javadoc

1   /*
2    * Copyright 2005 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at 
7    * 
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software 
11   * distributed under the License is distributed on an "AS IS" BASIS, 
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
13   * See the License for the specific language governing permissions and 
14   * limitations under the License.
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 }