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.ModelFatalException;
21  import org.apache.jdo.model.jdo.JDOClass;
22  
23  
24  /***
25   * A JavaType instance represents a type as defined in the Java
26   * language. The interface defines interrogative methods to check whether a
27   * type is primitive, an interface or array, is a JDO supported collection
28   * or map, is a value or trackable class, is a persistence capable class,
29   * etc. Furthermore it defines methods to get detailed information about 
30   * the type such as name, modifiers, superclass and the JDO meta data if
31   * this type represent a persistence capable class.
32   * <p>
33   * Different environments (runtime, enhancer, development) will have 
34   * different JavaType implementations to provide answers to the various
35   * methods. 
36   * 
37   * @author Michael Bouschen
38   * @since JDO 1.0.1
39   */
40  public interface JavaType extends JavaElement
41  {
42      /*** 
43       * Returns <code>true</code> if this JavaType represents a primitive
44       * type. 
45       * <p>
46       * There are eight primitive types: <code>boolean</code>,
47       * <code>byte</code>, <code>short</code>, <code>int</code>,
48       * <code>long</code>, <code>char</code>, 
49       * <code>float</code>, <code>double</code>.
50       * @return <code>true</code> if this JavaType represents a primitive
51       * type; <code>false</code> otherwise.
52       */
53      public boolean isPrimitive();
54  
55      /*** 
56       * Returns <code>true</code> if this JavaType represents an integral
57       * type. 
58       * <p>
59       * There are five are integral types: <code>byte</code>, 
60       * <code>short</code>, <code>int</code>, <code>long</code>, and
61       * <code>char</code>.
62       * @return <code>true</code> if this JavaType represents an integral
63       * type; <code>false</code> otherwise.
64       */
65      public boolean isIntegral();
66   
67      /***
68       * Returns <code>true</code> if this JavaType represents a floating
69       * point type. 
70       * <p>
71       * There are two are floating point types:
72       * <code>float</code> and <code>double</code>.
73       * @return <code>true</code> if this JavaType represents a floating
74       * point type; <code>false</code> otherwise.
75       */
76      public boolean isFloatingPoint();
77  
78      /*** 
79       * Determines if this JavaType object represents an interface type.
80       * @return <code>true</code> if this object represents an interface type; 
81       * <code>false</code> otherwise.
82       */
83      public boolean isInterface();
84      
85      /*** 
86       * Determines if this JavaType object represents an array type.
87       * @return <code>true</code> if this object represents an array type; 
88       * <code>false</code> otherwise.
89       */
90      public boolean isArray();
91  
92      /*** 
93       * Returns <code>true</code> if this JavaType represents a Java wrapper
94       * class type. 
95       * <p>
96       * There are eight Java wrapper class types: 
97       * <code>java.lang.Boolean</code>, <code>java.lang.Byte</code>, 
98       * <code>java.lang.Short</code>, <code>java.lang.Integer</code>, 
99       * <code>java.lang.Long</code>, <code>java.lang.Character</code>, 
100      * <code>java.lang.Float</code>, <code>java.lang.Double</code>.
101      * @return <code>true</code> if this JavaType represents a Java wrapper
102      * class type; <code>false</code> otherwise.
103      */
104     public boolean isWrapperClass();
105  
106     /*** 
107      * Returns <code>true</code> if this JavaType represents a JDO
108      * supported collection type. The JDO specification allows the
109      * following collection interfaces and classes as types of persistent 
110      * fields (see section 6.4.3 Persistent fields):
111      * <ul>
112      * <li><code>java.util.Collection</code>, <code>java.util.Set</code>, 
113      * <code>java.util.List</code>
114      * <li><code>java.util.HashSet</code>, <code>java.util.TreeSet</code>
115      * <li><code>java.util.ArrayList</code>, <code>java.util.LinkedList</code>
116      * <li><code>java.util.Vector</code>, <code>java.util.Stack</code>
117      * </ul> 
118      * @return <code>true</code> if this JavaType represents a JDO
119      * supported collection; <code>false</code> otherwise.
120      */
121     public boolean isJDOSupportedCollection();
122     
123     /*** 
124      * Returns <code>true</code> if this JavaType represents a JDO
125      * supported map type. The JDO specification allows the
126      * following map interfaces and classes as types of persistent 
127      * fields (see section 6.4.3 Persistent fields):
128      * <ul>
129      * <li><code>java.util.Map</code>
130      * <li><code>java.util.HashMap</code>, <code>java.util.TreeMap</code>
131      * <li> <code>java.util.Hashtable</code>, <code>java.util.Properties</code> 
132      * </ul> 
133      * @return <code>true</code> if this JavaType represents a JDO
134      * supported map; <code>false</code> otherwise.
135      */
136     public boolean isJDOSupportedMap();
137 
138     /***
139      * Returns <code>true</code> if this JavaType represents a trackable
140      * Java class. A JDO implementation may replace a persistent field of
141      * a trackable type with an assignment compatible instance of its own
142      * implementation of this type which notifies the owning FCO of any
143      * change of this field. 
144      * <p>
145      * The following types are trackable types:
146      * <ul>
147      * <li>JDO supported collection types
148      * <li>JDO supported map types
149      * <li><code>java.util.Date</code>, <code>java.sql.Date</code>, 
150      * <code>java.sql.Time</code>, <code>java.sql.Timestamp</code>
151      * <li><code>java.util.BitSet</code>
152      * </ul> 
153      * @return <code>true</code> if this JavaType represents a trackable
154      * Java class, <code>false</code> otherwise.
155      */
156     public boolean isTrackable();
157     
158     /*** 
159      * Returns <code>true</code> if this JavaType represents a type whose
160      * values may be treated as values rather than references during
161      * storing. A value type is either a primitive type or a type a JDO
162      * implementation may treat as SCO and the type is not one the
163      * following types: array, JDO supported collection and JDO supported
164      * map. 
165      * <p>
166      * The following classes are value types:
167      * <ul>
168      * <li>primitive types
169      * <li>Java wrapper class types
170      * <li><code>java.lang.Number</code>, <code>java.lang.String</code>
171      * <li><code>java.util.Locale</code>
172      * <li><code>java.math.BigDecimal</code>, <code>java.math.BigInteger</code>
173      * <li><code>java.util.Date</code>, <code>java.sql.Date</code>, 
174      * <code>java.sql.Time</code>, <code>java.sql.Timestamp</code>
175      * <li><code>java.util.BitSet</code>
176      * </ul> 
177      * @return <code>true</code> if this JavaType represents a value type;
178      * <code>false</code> otherwise.
179      */
180     public boolean isValue();
181 
182     /***
183      * Returns <code>true</code> if this JavaType represents an orderable
184      * type as specified in JDO.
185      * <p>
186      * The following types are orderable:
187      * <ul>
188      * <li>primitive types except <code>boolean</code>
189      * <li>Java wrapper class types except <code>java.lang.Boolean</code>
190      * <li><code>java.lang.String</code>
191      * <li><code>java.math.BigDecimal</code>, <code>java.math.BigInteger</code>
192      * <li><code>java.util.Date</code>, <code>java.sql.Date</code>, 
193      * <code>java.sql.Time</code>, <code>java.sql.Timestamp</code>
194      * </ul> 
195      * Note, this method does not check whether this JavaType implements
196      * the Comparable interface.
197      * @return <code>true</code> if this JavaType represents an orderable
198      * type; <code>false</code> otherwise.
199      */
200     public boolean isOrderable();
201 
202     /*** 
203      * Returns <code>true</code> if this JavaType represents a persistence
204      * capable class.
205      * <p>
206      * A {@link org.apache.jdo.model.ModelFatalException} indicates a
207      * problem accessing the JDO meta data for this JavaType.
208      * @return <code>true</code> if this JavaType represents a persistence
209      * capable class; <code>false</code> otherwise.
210      * @exception ModelFatalException if there is a problem accessing the
211      * JDO metadata
212      */
213     public boolean isPersistenceCapable()
214         throws ModelFatalException;
215 
216     /***
217      * Returns true if this JavaType is compatible with the specified
218      * JavaType. 
219      * @param javaType the type this JavaType is checked with.
220      * @return <code>true</code> if this is compatible with the specified
221      * type; <code>false</code> otherwise.
222      */
223     public boolean isCompatibleWith(JavaType javaType);
224     
225     /***
226      * Returns the name of the type. If this type represents a class or
227      * interface, the name is fully qualified.
228      * @return type name
229      */
230     public String getName();
231 
232     /***
233      * Returns the Java language modifiers for the field represented by
234      * this JavaType, as an integer. The java.lang.reflect.Modifier class
235      * should be used to decode the modifiers. 
236      * @return the Java language modifiers for this JavaType
237      */
238     public int getModifiers();
239 
240     /*** 
241      * Returns the JavaType representing the superclass of the entity
242      * represented by this JavaType. If this JavaType represents either the 
243      * Object class, an interface, a primitive type, or <code>void</code>, 
244      * then <code>null</code> is returned. If this object represents an
245      * array class then the JavaType instance representing the Object class
246      * is returned.  
247      * @return the superclass of the class represented by this JavaType.
248      */
249     public JavaType getSuperclass();
250 
251     /***
252      * Returns the JDOClass instance if this JavaType represents a
253      * persistence capable class. The method returns <code>null</code>, 
254      * if this JavaType does not represent a persistence capable class.
255      * <p>
256      * A {@link org.apache.jdo.model.ModelFatalException} indicates a
257      * problem accessing the JDO meta data for this JavaType.
258      * @return the JDOClass instance if this JavaType represents a
259      * persistence capable class; <code>null</code> otherwise.
260      * @exception ModelFatalException if there is a problem accessing the
261      * JDO metadata
262      */
263     public JDOClass getJDOClass()
264         throws ModelFatalException;
265     
266     /*** 
267      * Returns the JavaType representing the component type of an array. 
268      * If this JavaType does not represent an array type this method
269      * returns <code>null</code>.
270      * @return the JavaType representing the component type of this
271      * JavaType if this class is an array; <code>null</code> otherwise. 
272      */ 
273     public JavaType getArrayComponentType();
274 
275     /***
276      * Returns a JavaField instance that reflects the field with the
277      * specified name of the class or interface represented by this
278      * JavaType instance. The method returns <code>null</code>, if the
279      * class or interface (or one of its superclasses) does not have a
280      * field with that name.
281      * @param name the name of the field 
282      * @return the JavaField instance for the specified field in this class
283      * or <code>null</code> if there is no such field.
284      */
285     public JavaField getJavaField(String name);
286 
287     /***
288      * Returns an array of JavaField instances representing the declared
289      * fields of the class represented by this JavaType instance. Note, this
290      * method does not return JavaField instances representing inherited
291      * fields. 
292      * @return an array of declared JavaField instances. 
293      */
294     public JavaField[] getDeclaredJavaFields();
295 
296     /***
297      * Returns a JavaProperty instance that reflects the property with the
298      * specified name of the class or interface represented by this
299      * JavaType instance. The method returns <code>null</code>, if the
300      * class or interface (or one of its superclasses) does not have a
301      * property with that name.
302      * @param name the name of the property 
303      * @return the JavaProperty instance for the specified property in this
304      * class or <code>null</code> if there is no such property.
305      */
306     public JavaProperty getJavaProperty(String name);
307 
308     /***
309      * Returns an array of JavaProperty instances representing the declared
310      * properties of the class represented by this JavaType instance. Note,
311      * this method does not return JavaProperty instances representing inherited
312      * properties. 
313      * @return an array of declared JavaProperty instances. 
314      */
315     public JavaProperty[] getDeclaredJavaProperties();
316     
317 
318 }