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