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.java;
18  
19  import org.apache.jdo.model.ModelException;
20  import org.apache.jdo.model.ModelFatalException;
21  
22  /***
23   * The JavaModelFactory is the interface to use to obtain JavaModel
24   * instances. It defines methods to create and retrieve JavaModel
25   * instances. Furthermore it defines a convenience method to retrieve a
26   * JavaType by an implementation specific type description. 
27   * 
28   * @author Michael Bouschen
29   * @since 1.0.1
30   * @version 2.0
31   */
32  public interface JavaModelFactory 
33  {
34      /***
35       * Creates a new empty JavaModel instance. A factory implementation may
36       * use the specified key when caching the new JavaModel instance. 
37       * <p>
38       * Each JavaModelFactory imposes its own restrictions for the keys to
39       * cache JavaModel instances. Some implementations will allow only keys
40       * of a certain type. Some implementations will prohibit
41       * <code>null</code> keys. Attempting to use an ineligible key will
42       * result in a {@link org.apache.jdo.model.ModelException}. This means
43       * the specified key is of an inappropriate type for this
44       * JavaModelFactory or if the key is <code>null</code> and this 
45       * JavaModelFactory does not support <code>null</code> keys.
46       * @param key the key that may be used to cache the returned JavaModel
47       * instance. 
48       * @return a new JavaModel instance.
49       * @exception ModelException if impossible; the key is of an
50       * inappropriate type or the key is <code>null</code> and this
51       * JavaModelFactory does not support <code>null</code> keys.
52       */
53      public JavaModel createJavaModel(Object key)
54          throws ModelException;
55  
56      /***
57       * Returns the JavaModel instance for the specified key.
58       * <p>
59       * The method throws a {@link org.apache.jdo.model.ModelFatalException},
60       * if the specified key is of an inappropriate type for this
61       * JavaModelFactory or if the key is <code>null</code> and this
62       * JavaModelFactory does not support <code>null</code> keys.
63       * @param key the key used to cache the returned JavaModel instance.
64       * @return a JavaModel instance for the specified key.
65       * @exception ModelFatalException the key is of an inappropriate type
66       * or the key is <code>null</code> and this JavaModelFactory does not
67       * support <code>null</code> keys.
68       */
69      public JavaModel getJavaModel(Object key)
70          throws ModelFatalException;
71  
72      /***
73       * Removes the specified javaModel from the JavaModel cache. Note, if
74       * there are multiple entries in the cache with the specified javaModel
75       * as value, then all of them get removed. The method does not have an
76       * effect, if this factory does not have the specified javaModel.
77       * @param javaModel the JavaModel to be removed.
78       * @since 2.0
79       */
80      public void removeJavaModel(JavaModel javaModel)
81          throws ModelException;
82  
83      /***
84       * Removes the JavaModel for the specified key from the JavaModel
85       * cache. The method does not have an effect, if this factory does not 
86       * have a JavaModel for the the specified key.
87       * @param key the key used to find the JavaModel instance to be removed.
88       * @since 2.0
89       */
90      public void removeJavaModel(Object key)
91          throws ModelException;
92  
93      /***
94       * Returns a JavaType instance for the specified type description
95       * (optional operation). This method is a convenience method and a
96       * short cut for <code>getJavaModel(key).getJavaType(typeName)</code>. 
97       * If the factory supports this method, it needs to be able to get the
98       * key for the JavaModel lookup and the type name for the JavaType
99       * lookup from the specified typeDesc. An example for such an type
100      * description is the java.lang.Class instance in the runtime
101      * environment. 
102      * <p>
103      * The method throws a {@link org.apache.jdo.model.ModelFatalException}, 
104      * if this factory does not support this short cut or if it does not
105      * support the specified type description.
106      * @param typeDesc the type description.
107      * @return a JavaType instance for the specified type.
108      * @exception ModelFatalException this factory does not support this
109      * short cut or does not support the specified type description.
110      */
111     public JavaType getJavaType(Object typeDesc)
112         throws ModelFatalException;
113 }