View Javadoc

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