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.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 }