Save This Page
Home » jdo2-model-2.3-ea-src » org.apache.jdo.model.jdo » [javadoc | source]
    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   }

Save This Page
Home » jdo2-model-2.3-ea-src » org.apache.jdo.model.jdo » [javadoc | source]