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