1
2
3
4
5
6
7
8
9
10
11
12
13
14
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
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
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
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
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 }