Save This Page
Home » jdo2-model-2.3-ea-src » org.apache.jdo.model.java » [javadoc | source]
    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   }

Save This Page
Home » jdo2-model-2.3-ea-src » org.apache.jdo.model.java » [javadoc | source]