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