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