org.apache.jdo.impl.enhancer.meta
Interface EnhancerMetaData

All Known Subinterfaces:
ExtendedMetaData
All Known Implementing Classes:
EnhancerMetaDataBaseModel, EnhancerMetaDataJDOModelImpl, EnhancerMetaDataPropertyImpl, EnhancerMetaDataTimer

public interface EnhancerMetaData

Provides the JDO meta information neccessary for byte-code enhancement.

Please note: This interface deals with fully qualified names in the JVM notation, that is, with '/' as package separator character  (instead of '.').


Field Summary
static int CHECK_READ
          The JDO field flags.
static int CHECK_WRITE
           
static int MEDIATE_READ
           
static int MEDIATE_WRITE
           
static int SERIALIZABLE
           
 
Method Summary
 void declareField(java.lang.String classPath, java.lang.String fieldName, java.lang.String fieldSig)
          Declares a field to the JDO model passing its type information.
 java.lang.String getDeclaringClass(java.lang.String classPath, java.lang.String fieldName)
          Returns the JVM-qualified name of the specified field's declaring class.
 int getFieldFlags(java.lang.String classPath, java.lang.String fieldName)
          Returns the field flags for a declared field of a class.
 int[] getFieldFlags(java.lang.String classPath, java.lang.String[] fieldNames)
          Returns the field flags for some declared, managed fields of a class.
 int getFieldNumber(java.lang.String classPath, java.lang.String fieldName)
          Returns the unique field index of a declared, managed field of a class.
 int[] getFieldNumber(java.lang.String classPath, java.lang.String[] fieldNames)
          Returns the unique field index of some declared, managed fields of a class.
 java.lang.String getKeyClass(java.lang.String classPath)
          Returns the name of the key class of a class.
 java.lang.String[] getKeyFields(java.lang.String classPath)
          Returns an array of field names of all key fields of a class.
 java.lang.String[] getManagedFields(java.lang.String classPath)
          Returns an array of field names of all declared persistent and transactional fields of a class.
 java.lang.String getPersistenceCapableRootClass(java.lang.String classPath)
          Returns the name of the persistence-capable root class of a class.
 java.lang.String getPersistenceCapableSuperClass(java.lang.String classPath)
          Returns the name of the persistence-capable superclass of a class.
 java.lang.String getSuperKeyClass(java.lang.String classPath)
          Returns the name of the key class of the next persistence-capable superclass that defines one.
 boolean isDefaultFetchGroupField(java.lang.String classPath, java.lang.String fieldName)
          Returns whether a field of a class is part of the default fetch group.
 boolean isKeyField(java.lang.String classPath, java.lang.String fieldName)
          Returns whether a field of a class is key.
 boolean isKnownNonManagedField(java.lang.String classPath, java.lang.String fieldName, java.lang.String fieldSig)
          Returns whether a field of a class is known to be non-managed.
 boolean isKnownUnenhancableClass(java.lang.String classPath)
          Returns whether a class is not to be modified by the enhancer.
 boolean isManagedField(java.lang.String classPath, java.lang.String fieldName)
          Returns whether a field of a class is transient transactional or persistent.
 boolean isPersistenceCapableClass(java.lang.String classPath)
          Returns whether a class is persistence-capable.
 boolean isPersistenceCapableRootClass(java.lang.String classPath)
          Returns whether a class is persistence-capable root class.
 boolean isPersistentField(java.lang.String classPath, java.lang.String fieldName)
          Returns whether a field of a class is persistent.
 boolean isSerializableClass(java.lang.String classPath)
          Returns whether a class implements java.io.Serializable.
 boolean isTransactionalField(java.lang.String classPath, java.lang.String fieldName)
          Returns whether a field of a class is transient transactional.
 

Field Detail

CHECK_READ

public static final int CHECK_READ
The JDO field flags.

See Also:
Constant Field Values

MEDIATE_READ

public static final int MEDIATE_READ
See Also:
Constant Field Values

CHECK_WRITE

public static final int CHECK_WRITE
See Also:
Constant Field Values

MEDIATE_WRITE

public static final int MEDIATE_WRITE
See Also:
Constant Field Values

SERIALIZABLE

public static final int SERIALIZABLE
See Also:
Constant Field Values
Method Detail

isKnownUnenhancableClass

public boolean isKnownUnenhancableClass(java.lang.String classPath)
                                 throws EnhancerMetaDataUserException,
                                        EnhancerMetaDataFatalError
Returns whether a class is not to be modified by the enhancer.

It is an error if an unenhanceable class is persistence-capable (or persistence-aware). The following holds: isKnownUnenhancableClass(classPath) ==> !isPersistenceCapableClass(classPath)

Parameters:
classPath - the non-null JVM-qualified name of the class
Returns:
true if this class is known to be unmodifiable; otherwise false
Throws:
EnhancerMetaDataUserException
EnhancerMetaDataFatalError
See Also:
isPersistenceCapableClass(String)

isPersistenceCapableClass

public boolean isPersistenceCapableClass(java.lang.String classPath)
                                  throws EnhancerMetaDataUserException,
                                         EnhancerMetaDataFatalError
Returns whether a class is persistence-capable.

If a persistence-capable class is also known to be unenhancable, an exception is thrown. The following holds: isPersistenceCapableClass(classPath) ==> !isKnownUnenhancableClass(classPath)

Parameters:
classPath - the non-null JVM-qualified name of the class
Returns:
true if this class is persistence-capable; otherwise false
Throws:
EnhancerMetaDataUserException
EnhancerMetaDataFatalError
See Also:
isKnownUnenhancableClass(String)

isSerializableClass

public boolean isSerializableClass(java.lang.String classPath)
                            throws EnhancerMetaDataUserException,
                                   EnhancerMetaDataFatalError
Returns whether a class implements java.io.Serializable.

Parameters:
classPath - the non-null JVM-qualified name of the class
Returns:
true if this class is serializable; otherwise false
Throws:
EnhancerMetaDataUserException
EnhancerMetaDataFatalError

getPersistenceCapableSuperClass

public java.lang.String getPersistenceCapableSuperClass(java.lang.String classPath)
                                                 throws EnhancerMetaDataUserException,
                                                        EnhancerMetaDataFatalError
Returns the name of the persistence-capable superclass of a class.

The following holds: (String s = getPersistenceCapableSuperClass(classPath)) != null ==> isPersistenceCapableClass(classPath) && !isPersistenceCapableRootClass(classPath)

Parameters:
classPath - the non-null JVM-qualified name of the class
Returns:
the name of the PC superclass or null if there is none
Throws:
EnhancerMetaDataUserException
EnhancerMetaDataFatalError
See Also:
isPersistenceCapableClass(String), getPersistenceCapableRootClass(String)

getKeyClass

public java.lang.String getKeyClass(java.lang.String classPath)
                             throws EnhancerMetaDataUserException,
                                    EnhancerMetaDataFatalError
Returns the name of the key class of a class.

The following holds: (String s = getKeyClass(classPath)) != null ==> !isPersistenceCapableClass(s) && isPersistenceCapableClass(classPath)

Parameters:
classPath - the non-null JVM-qualified name of the class
Returns:
the name of the key class or null if there is none
Throws:
EnhancerMetaDataUserException
EnhancerMetaDataFatalError
See Also:
isPersistenceCapableClass(String)

getManagedFields

public java.lang.String[] getManagedFields(java.lang.String classPath)
                                    throws EnhancerMetaDataUserException,
                                           EnhancerMetaDataFatalError
Returns an array of field names of all declared persistent and transactional fields of a class.

The position of the field names in the result array corresponds to their unique field index as returned by getFieldNumber such that these equations hold:

getFieldNumber(getManagedFields(classPath)[i]) == i

getManagedFields(classPath)[getFieldNumber(fieldName)] == fieldName

This method requires all fields having been declared by declareField().

Parameters:
classPath - the non-null JVM-qualified name of the class
Returns:
an array of all declared persistent and transactional fields of a class
Throws:
EnhancerMetaDataUserException
EnhancerMetaDataFatalError
See Also:
getFieldNumber(String, String), declareField(String, String, String)

getDeclaringClass

public java.lang.String getDeclaringClass(java.lang.String classPath,
                                          java.lang.String fieldName)
                                   throws EnhancerMetaDataUserException,
                                          EnhancerMetaDataFatalError
Returns the JVM-qualified name of the specified field's declaring class. The method first checks whether the class of the specified classPath (the JVM-qualified name) declares such a field. If yes, classPath is returned. Otherwise, it checks its superclasses. The method returns null for an unkown field.

Parameters:
classPath - the non-null JVM-qualified name of the class
fieldName - the non-null name of the field
Returns:
the JVM-qualified name of the declararing class of the field, or null if there is no such field.
Throws:
EnhancerMetaDataUserException
EnhancerMetaDataFatalError

declareField

public void declareField(java.lang.String classPath,
                         java.lang.String fieldName,
                         java.lang.String fieldSig)
                  throws EnhancerMetaDataUserException,
                         EnhancerMetaDataFatalError
Declares a field to the JDO model passing its type information.

By the new JDO model, it's a requirement to declare fields to the model for their type information before any field information based on persistence-modifiers can be retrieved. This method passes a field's type information to the underlying JDO model.

There's one important exception: The method isKnownNonManagedField() may be called at any time.

The class must be persistence-capable, otherwise an exception is thrown.

Parameters:
classPath - the non-null JVM-qualified name of the class
fieldName - the non-null name of the field
fieldSig - the non-null JVM signature of the field
Throws:
EnhancerMetaDataUserException
EnhancerMetaDataFatalError
See Also:
isPersistenceCapableClass(String)

isKnownNonManagedField

public boolean isKnownNonManagedField(java.lang.String classPath,
                                      java.lang.String fieldName,
                                      java.lang.String fieldSig)
                               throws EnhancerMetaDataUserException,
                                      EnhancerMetaDataFatalError
Returns whether a field of a class is known to be non-managed.

This method differs from isManagedField() in that a field may or may not be managed if its not known as non-managed. The following holds (not vice versa!): isKnownNonManagedField(classPath, fieldName, fieldSig) ==> !isManagedField(classPath, fieldName)

This method doesn't require the field having been declared by declareField().

Parameters:
classPath - the non-null JVM-qualified name of the class
fieldName - the non-null name of the field
fieldSig - the non-null type signature of the field
Returns:
true if this field is known to be non-managed; otherwise false
Throws:
EnhancerMetaDataUserException
EnhancerMetaDataFatalError
See Also:
isManagedField(String, String), declareField(String, String, String)

isManagedField

public boolean isManagedField(java.lang.String classPath,
                              java.lang.String fieldName)
                       throws EnhancerMetaDataUserException,
                              EnhancerMetaDataFatalError
Returns whether a field of a class is transient transactional or persistent.

A managed field must not be known as non-managed and must be either transient transactional or persistent. The following holds: isManagedField(classPath, fieldName) ==> !isKnownNonManagedField(classPath, fieldName, fieldSig) && (isPersistentField(classPath, fieldName) ^ isTransactionalField(classPath, fieldName))

This method requires the field having been declared by declareField().

Parameters:
classPath - the non-null JVM-qualified name of the class
fieldName - the non-null name of the field
Returns:
true if this field is managed; otherwise false
Throws:
EnhancerMetaDataUserException
EnhancerMetaDataFatalError
See Also:
isKnownNonManagedField(String, String, String), isPersistentField(String, String), isTransactionalField(String, String), isPersistenceCapableClass(String)

isTransactionalField

public boolean isTransactionalField(java.lang.String classPath,
                                    java.lang.String fieldName)
                             throws EnhancerMetaDataUserException,
                                    EnhancerMetaDataFatalError
Returns whether a field of a class is transient transactional.

A transient transactional field cannot be persistent. The following holds: isTransactionalField(classPath, fieldName) ==> isManagedField(classPath, fieldName) && !isPersistentField(classPath, fieldName)

This method requires the field having been declared by declareField().

Parameters:
classPath - the non-null JVM-qualified name of the class
fieldName - the non-null name of the field
Returns:
true if this field is transactional; otherwise false
Throws:
EnhancerMetaDataUserException
EnhancerMetaDataFatalError
See Also:
isManagedField(String, String), declareField(String, String, String)

isPersistentField

public boolean isPersistentField(java.lang.String classPath,
                                 java.lang.String fieldName)
                          throws EnhancerMetaDataUserException,
                                 EnhancerMetaDataFatalError
Returns whether a field of a class is persistent.

A persistent field cannot be transient transactional. The following holds: isPersistentField(classPath, fieldName) ==> isManagedField(classPath, fieldName) && !isTransactionalField(classPath, fieldName)

This method requires the field having been declared by declareField().

Parameters:
classPath - the non-null JVM-qualified name of the class
fieldName - the non-null name of the field
Returns:
true if this field is persistent; otherwise false
Throws:
EnhancerMetaDataUserException
EnhancerMetaDataFatalError
See Also:
isManagedField(String, String), declareField(String, String, String)

isKeyField

public boolean isKeyField(java.lang.String classPath,
                          java.lang.String fieldName)
                   throws EnhancerMetaDataUserException,
                          EnhancerMetaDataFatalError
Returns whether a field of a class is key.

A key field must be persistent. The following holds: isKeyField(classPath, fieldName) ==> isPersistentField(classPath, fieldName) && !isDefaultFetchGroupField(classPath, fieldName)

This method requires the field having been declared by declareField().

Parameters:
classPath - the non-null JVM-qualified name of the class
fieldName - the non-null name of the field
Returns:
true if this field is key; otherwise false
Throws:
EnhancerMetaDataUserException
EnhancerMetaDataFatalError
See Also:
isPersistentField(String, String), declareField(String, String, String)

isDefaultFetchGroupField

public boolean isDefaultFetchGroupField(java.lang.String classPath,
                                        java.lang.String fieldName)
                                 throws EnhancerMetaDataUserException,
                                        EnhancerMetaDataFatalError
Returns whether a field of a class is part of the default fetch group.

A field in the default fetch group must be persistent. The following holds: isDefaultFetchGroupField(classPath, fieldName) ==> isPersistentField(classPath, fieldName) && !isKeyField(classPath, fieldName)

This method requires the field having been declared by declareField().

Parameters:
classPath - the non-null JVM-qualified name of the class
fieldName - the non-null name of the field
Returns:
true if this field is part of the default fetch group; otherwise false
Throws:
EnhancerMetaDataUserException
EnhancerMetaDataFatalError
See Also:
isPersistentField(String, String), declareField(String, String, String)

getFieldNumber

public int getFieldNumber(java.lang.String classPath,
                          java.lang.String fieldName)
                   throws EnhancerMetaDataUserException,
                          EnhancerMetaDataFatalError
Returns the unique field index of a declared, managed field of a class.

The following holds: int i = getFieldFlags(classPath, fieldName); i > 0 ==> getManagedFields(classPath)[i] == fieldName

This method requires the field having been declared by declareField().

Parameters:
classPath - the non-null JVM-qualified name of the class
fieldName - the non-null name of the field
Returns:
the non-negative, unique field index or -1 if the field is non-managed
Throws:
EnhancerMetaDataUserException
EnhancerMetaDataFatalError
See Also:
getManagedFields(String), declareField(String, String, String)

getFieldFlags

public int getFieldFlags(java.lang.String classPath,
                         java.lang.String fieldName)
                  throws EnhancerMetaDataUserException,
                         EnhancerMetaDataFatalError
Returns the field flags for a declared field of a class.

The following holds for the field flags: int f = getFieldFlags(classPath, fieldName); !isManagedField(classPath, fieldName) ==> (f & CHECK_READ == 0) && (f & MEDIATE_READ == 0) && (f & CHECK_WRITE == 0) && (f & MEDIATE_WRITE == 0) isTransactionalField(classPath, fieldName) ==> (f & CHECK_READ == 0) && (f & MEDIATE_READ == 0) && (f & CHECK_WRITE != 0) && (f & MEDIATE_WRITE == 0) isKeyField(classPath, fieldName) ==> (f & CHECK_READ == 0) && (f & MEDIATE_READ == 0) && (f & CHECK_WRITE == 0) && (f & MEDIATE_WRITE != 0) isDefaultFetchGroupField(classPath, fieldName) ==> (f & CHECK_READ != 0) && (f & MEDIATE_READ != 0) && (f & CHECK_WRITE == 0) && (f & MEDIATE_WRITE == 0) isPersistentField(classPath, fieldName) && isKeyField(classPath, fieldName) && isDefaultFetchGroupField(classPath, fieldName) ==> (f & CHECK_READ == 0) && (f & MEDIATE_READ == 0) && (f & CHECK_WRITE != 0) && (f & MEDIATE_WRITE != 0)

This method requires the field having been declared by declareField().

Parameters:
classPath - the non-null JVM-qualified name of the class
fieldName - the non-null name of the field
Returns:
the field flags for this field
Throws:
EnhancerMetaDataUserException
EnhancerMetaDataFatalError
See Also:
declareField(String, String, String)

isPersistenceCapableRootClass

public boolean isPersistenceCapableRootClass(java.lang.String classPath)
                                      throws EnhancerMetaDataUserException,
                                             EnhancerMetaDataFatalError
Returns whether a class is persistence-capable root class.

The following holds: isPersistenceCapableRootClass(classPath) <==> isPersistenceCapableClass(classPath) && getPersistenceCapableSuperClass(classPath) == null

Parameters:
classPath - the non-null JVM-qualified name of the class
Returns:
true if this class is persistence-capable and does not derive from another persistence-capable class; otherwise false
Throws:
EnhancerMetaDataUserException
EnhancerMetaDataFatalError

getPersistenceCapableRootClass

public java.lang.String getPersistenceCapableRootClass(java.lang.String classPath)
                                                throws EnhancerMetaDataUserException,
                                                       EnhancerMetaDataFatalError
Returns the name of the persistence-capable root class of a class.

The following holds: (String s = getPersistenceCapableRootClass(classPath)) != null ==> isPersistenceCapableClass(classPath) && getPersistenceCapableSuperClass(classPath) == null

Parameters:
classPath - the non-null JVM-qualified name of the class
Returns:
the name of the least-derived persistence-capable class that is equal to or a super class of the argument class; if the argument class is not persistence-capable, null is returned.
Throws:
EnhancerMetaDataUserException
EnhancerMetaDataFatalError

getSuperKeyClass

public java.lang.String getSuperKeyClass(java.lang.String classPath)
                                  throws EnhancerMetaDataUserException,
                                         EnhancerMetaDataFatalError
Returns the name of the key class of the next persistence-capable superclass that defines one.

The following holds: (String s = getSuperKeyClass(classPath)) != null ==> !isPersistenceCapableClass(s) && isPersistenceCapableClass(classPath) && !isPersistenceCapableRootClass(classPath)

Parameters:
classPath - the non-null JVM-qualified name of the class
Returns:
the name of the key class or null if there is none
Throws:
EnhancerMetaDataUserException
EnhancerMetaDataFatalError
See Also:
getKeyClass(String), getPersistenceCapableSuperClass(String)

getKeyFields

public java.lang.String[] getKeyFields(java.lang.String classPath)
                                throws EnhancerMetaDataUserException,
                                       EnhancerMetaDataFatalError
Returns an array of field names of all key fields of a class.

This method requires all fields having been declared by declareField().

Parameters:
classPath - the non-null JVM-qualified name of the class
Returns:
an array of all declared key fields of a class
Throws:
EnhancerMetaDataUserException
EnhancerMetaDataFatalError
See Also:
declareField(String, String, String)

getFieldNumber

public int[] getFieldNumber(java.lang.String classPath,
                            java.lang.String[] fieldNames)
                     throws EnhancerMetaDataUserException,
                            EnhancerMetaDataFatalError
Returns the unique field index of some declared, managed fields of a class.

This method requires all fields having been declared by declareField().

Parameters:
classPath - the non-null JVM-qualified name of the class
fieldNames - the non-null array of names of the declared fields
Returns:
the non-negative, unique field indices
Throws:
EnhancerMetaDataUserException
EnhancerMetaDataFatalError
See Also:
declareField(String, String, String)

getFieldFlags

public int[] getFieldFlags(java.lang.String classPath,
                           java.lang.String[] fieldNames)
                    throws EnhancerMetaDataUserException,
                           EnhancerMetaDataFatalError
Returns the field flags for some declared, managed fields of a class.

This method requires all fields having been declared by declareField().

Parameters:
classPath - the non-null JVM-qualified name of the class
fieldNames - the non-null array of names of the declared fields
Returns:
the field flags for the fields
Throws:
EnhancerMetaDataUserException
EnhancerMetaDataFatalError
See Also:
declareField(String, String, String)


Copyright © 2005-2007 Apache Software Foundation. All Rights Reserved.