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

Fields

Modifier and Type	Field and Description
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

Methods

Modifier and Type	Method and Description
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

static final int CHECK_READ

The JDO field flags.

See Also:

Constant Field Values

MEDIATE_READ

static final int MEDIATE_READ

See Also:

Constant Field Values

CHECK_WRITE

static final int CHECK_WRITE

See Also:

Constant Field Values

MEDIATE_WRITE

static final int MEDIATE_WRITE

See Also:

Constant Field Values

SERIALIZABLE

static final int SERIALIZABLE

See Also:

Constant Field Values

Method Detail

isKnownUnenhancableClass

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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)