1
2
3
4
5
6
7
8
9
10
11
12
13
14
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 }