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.JavaModel;
21  import org.apache.jdo.model.java.JavaType;
22  
23  
24  /***
25   * A JDOModel instance bundles a number of JDOClass instances used by an 
26   * application. It provides factory methods to create and retrieve JDOClass 
27   * instances. A fully qualified class name must be unique within a JDOModel 
28   * instance. The model supports multiple classes having the same fully qualified 
29   * name by different JDOModel instances.
30   *
31   * @author Michael Bouschen
32   * @version 2.0
33   */
34  public interface JDOModel
35      extends JDOElement
36  {
37      /*** 
38       * The method returns a JDOClass instance for the specified package name.
39       * If this JDOModel contains the corresponding JDOPackage instance,
40       * the existing instance is returned. Otherwise, it creates a new JDOPackage
41       * instance and returns the new instance.
42       * @param packageName the name of the JDOPackage instance 
43       * to be returned
44       * @return a JDOPackage instance for the specified package name
45       * @exception ModelException if impossible
46       */
47      publicJDOPackage createJDOPackage(String packageName)/package-summary.html">ong> JDOPackage createJDOPackage(String packageName)
48          throws ModelException;
49  
50      /*** 
51       * The method returns the JDOPackage instance for the specified package 
52       * name, if present. The method returns <code>null</code> if it cannot 
53       * find a JDOPackage instance for the specified name. 
54       * @param packageName the name of the JDOPackage instance 
55       * to be returned
56       * @return a JDOPackage instance for the specified package name 
57       * or <code>null</code> if not present
58       */
59      publicJDOPackage getJDOPackage(String packageName)/package-summary.html">ong> JDOPackage getJDOPackage(String packageName);
60  
61      /***
62       * Returns the collection of JDOPackage instances declared by this JDOModel 
63       * in the format of an array.
64       * @return the packages declared by this JDOModel
65       */
66      public JDOPackage[] getDeclaredPackages();
67  
68      /***
69       * The method returns a JDOClass instance for the specified fully qualified
70       * class name. If this JDOModel contains the corresponding JDOClass instance,
71       * the existing instance is returned. Otherwise, it creates a new JDOClass 
72       * instance, sets its declaringModel and returns the new instance.
73       * <p>
74       * Whether this method reads XML metatdata or not is determined at
75       * JDOModel creation time (see flag <code>loadXMLMetadataDefault</code> 
76       * in {@link JDOModelFactory#getJDOModel(JavaModel javaModel, boolean
77       * loadXMLMetadataDefault)}). Invoking this method is method is equivalent
78       * to <code>createJDOClass(className, loadXMLMetadataDefault)</code>.
79       * @param className the fully qualified class name of the JDOClass
80       * instance to be returned
81       * @return a JDOClass instance for the specified class name
82       * @exception ModelException if impossible
83       */
84      public JDOClass createJDOClass(String className)
85          throws ModelException;
86  
87      /***
88       * The method returns a JDOClass instance for the specified fully qualified
89       * class name. If this JDOModel contains the corresponding JDOClass instance,
90       * the existing instance is returned. Otherwise, if the flag loadXMLMetadata
91       * is set to <code>true</code> the method tries to find the JDOClass 
92       * instance by reading the XML metadata. If it could not be found the method
93       * creates a new JDOClass instance, sets its declaringModel and returns the 
94       * instance.
95       * @param className the fully qualified class name of the JDOClass instance 
96       * to be returned
97       * @param loadXMLMetadata indicates whether to read XML metatdata or not
98       * @return a JDOClass instance for the specified class name
99       * @exception ModelException if impossible
100      */
101     public JDOClass createJDOClass(String className, boolean loadXMLMetadata)
102         throws ModelException;
103 
104     /***
105      * The method returns the JDOClass instance for the specified fully 
106      * qualified class name if present. The method returns <code>null</code> 
107      * if it cannot find a JDOClass instance for the specified name. 
108      * <p>
109      * Whether this method reads XML metatdata or not is determined at
110      * JDOModel creation time (see flag <code>loadXMLMetadataDefault</code> 
111      * in {@link JDOModelFactory#getJDOModel(JavaModel javaModel, boolean
112      * loadXMLMetadataDefault)}). Invoking this method is method is equivalent
113      * to <code>createJDOClass(className, loadXMLMetadataDefault)</code>.
114      * @param className the fully qualified class name of the JDOClass
115      * instance to be returned
116      * @return a JDOClass instance for the specified class name 
117      * or <code>null</code> if not present
118      */
119     public JDOClass getJDOClass(String className);
120 
121     /***
122      * The method returns the JDOClass instance for the specified fully 
123      * qualified class name if present. If the flag loadXMLMetadata is set 
124      * to <code>true</code> the method tries to find the JDOClass instance by 
125      * reading the XML metadata. The method returns null if it cannot find a 
126      * JDOClass instance for the specified name.
127      * @param className the fully qualified class name of the JDOClass instance 
128      * to be returned
129      * @param loadXMLMetadata indicates whether to read XML metatdata or not
130      * @return a JDOClass instance for the specified class name
131      * or <code>null</code> if not present
132      */
133     public JDOClass getJDOClass(String className, boolean loadXMLMetadata);
134 
135     /***
136      * The method returns the JDOClass instance for the specified short name
137      * (see {@link JDOClass#getShortName()}) or <code>null</code> if it cannot
138      * find a JDOClass instance with the specified short name. 
139      * <p>
140      * The method searches the list of JDOClasses currently managed by this
141      * JDOModel instance. It does not attempt to load any metadata if it
142      * cannot find a JDOClass instance with the specified short name. The
143      * metadata for a JDOClass returned by this method must have been loaded
144      * before by any of the methods
145      * {@link #createJDOClass(String className)},
146      * {@link #createJDOClass(String className, boolean loadXMLMetadataDefault)},
147      * {@link #getJDOClass(String className)}, or
148      * {@link #getJDOClass(String className, boolean loadXMLMetadataDefault)}.
149      * @param shortName the short name of the JDOClass instance to be returned
150      * @return a JDOClass instance for the specified short name 
151      * or <code>null</code> if not present
152      */
153     public JDOClass getJDOClassForShortName(String shortName);
154 
155     /***
156      * Returns the collection of JDOClass instances declared by this JDOModel 
157      * in the format of an array.
158      * @return the classes declared by this JDOModel
159      */
160     public JDOClass[] getDeclaredClasses();
161 
162     /***
163      * Returns the JavaModel bound to this JDOModel instance.
164      * @return the JavaModel
165      */
166     public JavaModel getJavaModel();
167     
168     /***
169      * Sets the JavaModel for this JDOModel instance.
170      * @param javaModel the JavaModel
171      */
172     public void setJavaModel(JavaModel javaModel);
173 
174     /***
175      * Returns the parent JDOModel instance of this JDOModel.
176      * @return the parent JDOModel
177      */
178     public JDOModel getParent();
179 
180     /***
181      * This method returns the JDOClass instance that defines the specified type
182      * as its objectId class. In the case of an inheritance hierarchy it returns 
183      * the top most persistence-capable class of the hierarchy (see 
184      * {@link JDOClass#getPersistenceCapableSuperclass}).
185      * @param objectIdClass the type representation of the ObjectId class
186      * @return the JDOClass defining the specified class as ObjectId class
187      */
188     public JDOClass getJDOClassForObjectIdClass(JavaType objectIdClass);
189 }