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.impl.enhancer.meta;
18  
19  
20  /***
21   * Provides the JDO meta information neccessary for byte-code enhancement.
22   * <p>
23   * <b>Please note: This interface deals with fully qualified names in the
24   * JVM notation, that is, with '/' as package separator character&nbsp;
25   * (instead of '.').</b>
26   */
27  public interface EnhancerMetaData
28  {
29      /***
30       * The JDO field flags.
31       */
32      int CHECK_READ    = 0x01;
33      int MEDIATE_READ  = 0x02;
34      int CHECK_WRITE   = 0x04;
35      int MEDIATE_WRITE = 0x08;
36      int SERIALIZABLE  = 0x10;
37  
38      // ----------------------------------------------------------------------
39      // Class Metadata
40      // ----------------------------------------------------------------------
41  
42      /***
43       * Returns whether a class is not to be modified by the enhancer.
44       * <P>
45       * It is an error if an unenhanceable class is persistence-capable
46       * (or persistence-aware).  The following holds:
47       *   isKnownUnenhancableClass(classPath)
48       *       ==> !isPersistenceCapableClass(classPath)
49       * @param classPath the non-null JVM-qualified name of the class
50       * @return true if this class is known to be unmodifiable; otherwise false
51       * @see #isPersistenceCapableClass(String)
52       */
53      boolean isKnownUnenhancableClass(String classPath)
54          throws EnhancerMetaDataUserException, EnhancerMetaDataFatalError;
55  
56      /***
57       * Returns whether a class is persistence-capable.
58       * <P>
59       * If a persistence-capable class is also known to be unenhancable,
60       * an exception is thrown.
61       * The following holds:
62       *   isPersistenceCapableClass(classPath)
63       *       ==> !isKnownUnenhancableClass(classPath)
64       * @param classPath the non-null JVM-qualified name of the class
65       * @return true if this class is persistence-capable; otherwise false
66       * @see #isKnownUnenhancableClass(String)
67       */
68      boolean isPersistenceCapableClass(String classPath)
69          throws EnhancerMetaDataUserException, EnhancerMetaDataFatalError;
70  
71      /***
72       * Returns whether a class implements java.io.Serializable.
73       * @param classPath the non-null JVM-qualified name of the class
74       * @return true if this class is serializable; otherwise false
75       */
76      boolean isSerializableClass(String classPath)
77          throws EnhancerMetaDataUserException, EnhancerMetaDataFatalError;
78  
79      /***
80       * Returns the name of the persistence-capable superclass of a class.
81       * <P>
82       * The following holds:
83       *   (String s = getPersistenceCapableSuperClass(classPath)) != null
84       *       ==> isPersistenceCapableClass(classPath)
85       *           && !isPersistenceCapableRootClass(classPath)
86       * @param classPath the non-null JVM-qualified name of the class
87       * @return the name of the PC superclass or null if there is none
88       * @see #isPersistenceCapableClass(String)
89       * @see #getPersistenceCapableRootClass(String)
90       */
91      String getPersistenceCapableSuperClass(String classPath)
92          throws EnhancerMetaDataUserException, EnhancerMetaDataFatalError;
93  
94      /***
95       * Returns the name of the key class of a class.
96       * <P>
97       * The following holds:
98       *   (String s = getKeyClass(classPath)) != null
99       *       ==> !isPersistenceCapableClass(s)
100      *           && isPersistenceCapableClass(classPath)
101      * @param classPath the non-null JVM-qualified name of the class
102      * @return the name of the key class or null if there is none
103      * @see #isPersistenceCapableClass(String)
104      */
105     String getKeyClass(String classPath)
106         throws EnhancerMetaDataUserException, EnhancerMetaDataFatalError;
107 
108     /***
109      * Returns an array of field names of all declared persistent and
110      * transactional fields of a class.
111      * <P>
112      * The position of the field names in the result array corresponds
113      * to their unique field index as returned by getFieldNumber such that
114      * these equations hold:
115      * <P> getFieldNumber(getManagedFields(classPath)[i]) == i
116      * <P> getManagedFields(classPath)[getFieldNumber(fieldName)] == fieldName
117      * <P>
118      * This method requires all fields having been declared by
119      * declareField().
120      * @param classPath the non-null JVM-qualified name of the class
121      * @return an array of all declared persistent and transactional
122      *         fields of a class
123      * @see #getFieldNumber(String, String)
124      * @see #declareField(String, String, String)
125      */
126     String[] getManagedFields(String classPath)
127         throws EnhancerMetaDataUserException, EnhancerMetaDataFatalError;
128 
129     // ----------------------------------------------------------------------
130     // Field Metadata
131     // ----------------------------------------------------------------------
132 
133     /*** 
134      * Returns the JVM-qualified name of the specified field's declaring
135      * class. The method first checks whether the class of the specified
136      * classPath (the JVM-qualified name) declares such a field. If yes,
137      * classPath is returned. Otherwise, it checks its superclasses. The
138      * method returns <code>null</code> for an unkown field.
139      * @param classPath the non-null JVM-qualified name of the class
140      * @param fieldName the non-null name of the field
141      * @return the JVM-qualified name of the declararing class of the
142      * field, or <code>null</code> if there is no such field.
143      */
144     String getDeclaringClass(String classPath, String fieldName)
145         throws EnhancerMetaDataUserException, EnhancerMetaDataFatalError; 
146 
147     /***
148      * Declares a field to the JDO model passing its type information.
149      * <P>
150      * By the new JDO model, it's a requirement to declare fields to
151      * the model for their type information before any field information
152      * based on persistence-modifiers can be retrieved.  This method
153      * passes a field's type information to the underlying JDO model.
154      * <P>
155      * There's one important exception: The method isKnownNonManagedField()
156      * may be called at any time.
157      * <P>
158      * The class must be persistence-capable, otherwise an exception
159      * is thrown.
160      * @param classPath the non-null JVM-qualified name of the class
161      * @param fieldName the non-null name of the field
162      * @param fieldSig the non-null JVM signature of the field
163      * @see #isPersistenceCapableClass(String)
164      */
165     void declareField(String classPath, String fieldName, String fieldSig)
166         throws EnhancerMetaDataUserException, EnhancerMetaDataFatalError;
167 
168     /***
169      * Returns whether a field of a class is known to be non-managed.
170      * <P>
171      * This method differs from isManagedField() in that a field may or
172      * may not be managed if its not known as non-managed.
173      * The following holds (not vice versa!):
174      *   isKnownNonManagedField(classPath, fieldName, fieldSig)
175      *       ==> !isManagedField(classPath, fieldName)
176      * <P>
177      * This method doesn't require the field having been declared by
178      * declareField().
179      * @param classPath the non-null JVM-qualified name of the class
180      * @param fieldName the non-null name of the field
181      * @param fieldSig the non-null type signature of the field
182      * @return true if this field is known to be non-managed; otherwise false
183      * @see #isManagedField(String, String)
184      * @see #declareField(String, String, String)
185      */
186     boolean isKnownNonManagedField(String classPath,
187                                    String fieldName,
188                                    String fieldSig)
189         throws EnhancerMetaDataUserException, EnhancerMetaDataFatalError;
190 
191     /***
192      * Returns whether a field of a class is transient transactional
193      * or persistent.
194      * <P>
195      * A managed field must not be known as non-managed and must be either
196      * transient transactional or persistent.  The following holds:
197      *   isManagedField(classPath, fieldName)
198      *       ==> !isKnownNonManagedField(classPath, fieldName, fieldSig)
199      *           && (isPersistentField(classPath, fieldName)
200      *               ^ isTransactionalField(classPath, fieldName))
201      * <P>
202      * This method requires the field having been declared by declareField().
203      * @param classPath the non-null JVM-qualified name of the class
204      * @param fieldName the non-null name of the field
205      * @return true if this field is managed; otherwise false
206      * @see #isKnownNonManagedField(String, String, String)
207      * @see #isPersistentField(String, String)
208      * @see #isTransactionalField(String, String)
209      * @see #isPersistenceCapableClass(String)
210      */
211     boolean isManagedField(String classPath, String fieldName)
212         throws EnhancerMetaDataUserException, EnhancerMetaDataFatalError;
213 
214     /***
215      * Returns whether a field of a class is transient
216      * transactional.
217      * <P>
218      * A transient transactional field cannot be persistent.
219      * The following holds:
220      *   isTransactionalField(classPath, fieldName)
221      *       ==> isManagedField(classPath, fieldName)
222      *           && !isPersistentField(classPath, fieldName)
223      * <P>
224      * This method requires the field having been declared by declareField().
225      * @param classPath the non-null JVM-qualified name of the class
226      * @param fieldName the non-null name of the field
227      * @return true if this field is transactional; otherwise false
228      * @see #isManagedField(String, String)
229      * @see #declareField(String, String, String)
230      */
231     boolean isTransactionalField(String classPath, String fieldName)
232         throws EnhancerMetaDataUserException, EnhancerMetaDataFatalError;
233 
234     /***
235      * Returns whether a field of a class is persistent.
236      * <P>
237      * A persistent field cannot be transient transactional.
238      * The following holds:
239      *   isPersistentField(classPath, fieldName)
240      *       ==> isManagedField(classPath, fieldName)
241      *           && !isTransactionalField(classPath, fieldName)
242      * <P>
243      * This method requires the field having been declared by declareField().
244      * @param classPath the non-null JVM-qualified name of the class
245      * @param fieldName the non-null name of the field
246      * @return true if this field is persistent; otherwise false
247      * @see #isManagedField(String, String)
248      * @see #declareField(String, String, String)
249      */
250     boolean isPersistentField(String classPath, String fieldName)
251         throws EnhancerMetaDataUserException, EnhancerMetaDataFatalError;
252 
253     /***
254      * Returns whether a field of a class is key.
255      * <P>
256      * A key field must be persistent.
257      * The following holds:
258      *   isKeyField(classPath, fieldName)
259      *       ==> isPersistentField(classPath, fieldName)
260      *           && !isDefaultFetchGroupField(classPath, fieldName)
261      * <P>
262      * This method requires the field having been declared by declareField().
263      * @param classPath the non-null JVM-qualified name of the class
264      * @param fieldName the non-null name of the field
265      * @return true if this field is key; otherwise false
266      * @see #isPersistentField(String, String)
267      * @see #declareField(String, String, String)
268      */
269     boolean isKeyField(String classPath, String fieldName)
270         throws EnhancerMetaDataUserException, EnhancerMetaDataFatalError;
271 
272     /***
273      * Returns whether a field of a class is part of the
274      * default fetch group.
275      * <P>
276      * A field in the default fetch group must be persistent.
277      * The following holds:
278      *   isDefaultFetchGroupField(classPath, fieldName)
279      *       ==> isPersistentField(classPath, fieldName)
280      *           && !isKeyField(classPath, fieldName)
281      * <P>
282      * This method requires the field having been declared by declareField().
283      * @param classPath the non-null JVM-qualified name of the class
284      * @param fieldName the non-null name of the field
285      * @return true if this field is part of the
286      *         default fetch group; otherwise false
287      * @see #isPersistentField(String, String)
288      * @see #declareField(String, String, String)
289      */
290     boolean isDefaultFetchGroupField(String classPath, String fieldName)
291         throws EnhancerMetaDataUserException, EnhancerMetaDataFatalError;
292 
293     /***
294      * Returns the unique field index of a declared, managed field of a
295      * class.
296      * <P>
297      * The following holds:
298      *   int i = getFieldFlags(classPath, fieldName);
299      *   i > 0  ==>  getManagedFields(classPath)[i] == fieldName
300      * <P>
301      * This method requires the field having been declared by declareField().
302      * @param classPath the non-null JVM-qualified name of the class
303      * @param fieldName the non-null name of the field
304      * @return the non-negative, unique field index or -1 if the field
305      *         is non-managed
306      * @see #getManagedFields(String)
307      * @see #declareField(String, String, String)
308      */
309     int getFieldNumber(String classPath, String fieldName)
310         throws EnhancerMetaDataUserException, EnhancerMetaDataFatalError;
311 
312     /***
313      * Returns the field flags for a declared field of a class.
314      * <P>
315      * The following holds for the field flags:
316      *   int f = getFieldFlags(classPath, fieldName);
317      *
318      *   !isManagedField(classPath, fieldName)
319      *       ==> (f & CHECK_READ == 0) && (f & MEDIATE_READ == 0) &&
320      *           (f & CHECK_WRITE == 0) && (f & MEDIATE_WRITE == 0)
321      *
322      *   isTransactionalField(classPath, fieldName)
323      *       ==> (f & CHECK_READ == 0) && (f & MEDIATE_READ == 0) &&
324      *           (f & CHECK_WRITE != 0) && (f & MEDIATE_WRITE == 0)
325      *
326      *   isKeyField(classPath, fieldName)
327      *       ==> (f & CHECK_READ == 0) && (f & MEDIATE_READ == 0) &&
328      *           (f & CHECK_WRITE == 0) && (f & MEDIATE_WRITE != 0)
329      *
330      *   isDefaultFetchGroupField(classPath, fieldName)
331      *       ==> (f & CHECK_READ != 0) && (f & MEDIATE_READ != 0) &&
332      *           (f & CHECK_WRITE == 0) && (f & MEDIATE_WRITE == 0)
333      *
334      *   isPersistentField(classPath, fieldName)
335      *   && isKeyField(classPath, fieldName)
336      *   && isDefaultFetchGroupField(classPath, fieldName)
337      *       ==> (f & CHECK_READ == 0) && (f & MEDIATE_READ == 0) &&
338      *           (f & CHECK_WRITE != 0) && (f & MEDIATE_WRITE != 0)
339      * <P>
340      * This method requires the field having been declared by declareField().
341      * @param classPath the non-null JVM-qualified name of the class
342      * @param fieldName the non-null name of the field
343      * @return the field flags for this field
344      * @see #declareField(String, String, String)
345      */
346     int getFieldFlags(String classPath, String fieldName)
347         throws EnhancerMetaDataUserException, EnhancerMetaDataFatalError;
348 
349     // ----------------------------------------------------------------------
350     // Convenience Methods
351     // ----------------------------------------------------------------------
352 
353     /***
354      * Returns whether a class is persistence-capable root class.
355      * <P>
356      * The following holds:
357      *   isPersistenceCapableRootClass(classPath)
358      *     <==> isPersistenceCapableClass(classPath)
359      *          && getPersistenceCapableSuperClass(classPath) == null
360      * @param classPath the non-null JVM-qualified name of the class
361      * @return true if this class is persistence-capable and does not
362      *         derive from another persistence-capable class; otherwise false
363      */
364     boolean isPersistenceCapableRootClass(String classPath)
365         throws EnhancerMetaDataUserException, EnhancerMetaDataFatalError;
366 
367     /***
368      * Returns the name of the persistence-capable root class of a class.
369      * <P>
370      * The following holds:
371      *   (String s = getPersistenceCapableRootClass(classPath)) != null
372      *       ==> isPersistenceCapableClass(classPath)
373      *           && getPersistenceCapableSuperClass(classPath) == null
374      * @param classPath the non-null JVM-qualified name of the class
375      * @return the name of the least-derived persistence-capable class that
376      *         is equal to or a super class of the argument class; if the
377      *         argument class is not persistence-capable, null is returned.
378      */
379     String getPersistenceCapableRootClass(String classPath)
380         throws EnhancerMetaDataUserException, EnhancerMetaDataFatalError;
381 
382     /***
383      * Returns the name of the key class of the next persistence-capable
384      * superclass that defines one.
385      * <P>
386      * The following holds:
387      *   (String s = getSuperKeyClass(classPath)) != null
388      *       ==> !isPersistenceCapableClass(s)
389      *           && isPersistenceCapableClass(classPath)
390      *           && !isPersistenceCapableRootClass(classPath)
391      * @param classPath the non-null JVM-qualified name of the class
392      * @return the name of the key class or null if there is none
393      * @see #getKeyClass(String)
394      * @see #getPersistenceCapableSuperClass(String)
395      */
396     String getSuperKeyClass(String classPath)
397         throws EnhancerMetaDataUserException, EnhancerMetaDataFatalError;
398 
399     /***
400      * Returns an array of field names of all key fields of a class.
401      * <P>
402      * This method requires all fields having been declared by declareField().
403      * @param classPath the non-null JVM-qualified name of the class
404      * @return an array of all declared key fields of a class
405      * @see #declareField(String, String, String)
406      */
407     String[] getKeyFields(String classPath)
408         throws EnhancerMetaDataUserException, EnhancerMetaDataFatalError;
409 
410     /***
411      * Returns the unique field index of some declared, managed fields of a
412      * class.
413      * <P>
414      * This method requires all fields having been declared by declareField().
415      * @param classPath the non-null JVM-qualified name of the class
416      * @param fieldNames the non-null array of names of the declared fields
417      * @return the non-negative, unique field indices
418      * @see #declareField(String, String, String)
419      */
420     int[] getFieldNumber(String classPath, String[] fieldNames)
421         throws EnhancerMetaDataUserException, EnhancerMetaDataFatalError;
422 
423     /***
424      * Returns the field flags for some declared, managed fields of a class.
425      * <P>
426      * This method requires all fields having been declared by declareField().
427      * @param classPath the non-null JVM-qualified name of the class
428      * @param fieldNames the non-null array of names of the declared fields
429      * @return the field flags for the fields
430      * @see #declareField(String, String, String)
431      */
432     int[] getFieldFlags(String classPath, String[] fieldNames)
433         throws EnhancerMetaDataUserException, EnhancerMetaDataFatalError;
434 }