View Javadoc

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