com.bea.util.jam
Interface JAnnotationValue

public interface JAnnotationValue

Represents a member value of a JAnnotation.

A note regarding enums

The presence of metadata of 'enum' types poses a bit of a challenge in the untyped view of metadata that is presented by JAnnotationValue. Because JAM cannot assume that the enum definitions have been compiled, it is not possible for JAM to return an instance of an enumuerated type. In other words, it is not possible for JAnnotationValue to provide an asEnum() method.

If JAM encounters an annotation value of an enumerated type, it will represent it with a JAnnotationValue such that calling myAnnotationValue.getType().isEnumType() will return true. Moreover, calling myAnnotationValue.asString() will return the name of the enumeration field, exactly as it appears in the type declaration.

getName

String getName()

getType

JClass getType()

asAnnotation

JAnnotation asAnnotation()

If this member is complex (i.e. an instance of another annotation type), this method returns a representation of the annotation instance. Returns null in all other samples. This method always returns null if the annotation is a javdoc tag, as such tags only support one level of nesting.

asClass

JClass asClass()

Returns the value of this member as a JClass. Returns null if the value cannot be understood as a class name or if the type of the member is known to be something other than java.lang.Class.

asString

String asString()

Returns the String value of the annotation. If the value is known to be a simple, non-array type other than String, it will be converted in a resonable manner (with an appropriate toString() or String.valueOf() method). If the value is known to be complex or is an array, this method will return null.

If no type information is available for the annotation member (i.e. it's a javadoc tag), then the raw textual value of the member is returned.

asInt

int asInt()
          throws NumberFormatException

Returns the member's value as an int. If the value is not known to be an int, (because it's a javadoc tag or because it's a 175 annotation member of a type other than int) asString() is called. If the result is null, NumberFormatException is thrown. Otherwise, the String is converted to an int with Integer.valueOf(), which again may throw NumberFormatException.

Throws:

NumberFormatException

asBoolean

boolean asBoolean()
                  throws IllegalArgumentException

Returns the member's value as a boolean. If necessary, type conversion is performed in a similar manner as described for asInt(), except that IllegalArgumentException is thrown instead of NumberFormatException.

Throws:

IllegalArgumentException

asLong

long asLong()
            throws NumberFormatException

Returns the member's value as a long. If necessary, type conversion is performed in a similar manner as described for asInt().

Throws:

NumberFormatException

asShort

short asShort()
              throws NumberFormatException

Returns the member's value as a short. If necessary, type conversion is performed in a similar manner as described for asInt().

Throws:

NumberFormatException

asDouble

double asDouble()
                throws NumberFormatException

Returns the member's value as a double. If necessary, type conversion is performed in a similar manner as described for asInt().

Throws:

NumberFormatException

asFloat

float asFloat()
              throws NumberFormatException

Returns the member's value as a float. If necessary, type conversion is performed in a similar manner as described for asInt().

Throws:

NumberFormatException

asByte

byte asByte()
            throws NumberFormatException

Returns the member's value as a byte. If necessary, type conversion is performed in a similar manner as described for asInt().

Throws:

NumberFormatException

asChar

char asChar()
            throws IllegalArgumentException

Returns the member's value as a char. If necessary, type conversion is performed by calling getStringValue(). If the result is null or is a String that is not exactly of length 1, IllegalArgumentException is thrown.

Throws:

IllegalArgumentException

asClassArray

JClass[] asClassArray()

If this member is known to be an array of classes, returns an array of JClass representations of those classes. If the memeber is known to be an array of a simple non-array type, this method will call asStringArray() and attempt to return a JClass by treating each string in the returned array as a qualified classname. Returns null otherwise.

This method always returns null for javadoc tags.

asAnnotationArray

JAnnotation[] asAnnotationArray()

If this member is known to be an array of annotations (i.e. complex, nested types), this method returns an array containing each complex value as a JAnnotation. Returns null in all other samples.

This method always returns null for javadoc tags.

asStringArray

String[] asStringArray()

Returns this member's value as an array of Strings. If this member is not of an array type, or is an array of arrays or complex annotations, this method returns null. If it is an array of a simple, non-array type other than String, conversion on each component will be attempted as described under getStringValue().

This method always returns null for javadoc tags.

asIntArray

int[] asIntArray()
                 throws NumberFormatException

Returns this member's value as an array of ints. If this member is not of an array type, or is an array of arrays or complex annotations, this method returns null. If it is an array of a simple, non-array type other than int, conversion on each component will be attempted as described under getIntValue().

This method always returns null for javadoc tags.

Throws:

NumberFormatException

asBooleanArray

boolean[] asBooleanArray()
                         throws IllegalArgumentException

Returns this member's value as an array of booleans. If necessary, type conversion is performed in a similar manner as described for asIntArray(), except that IllegalArgumentException may be thrown instead of NumberFormatException.

This method always returns null for javadoc tags.

Throws:

IllegalArgumentException

asShortArray

short[] asShortArray()
                     throws NumberFormatException

Returns this member's value as an array of shorts. If necessary, type conversion is performed in a similar manner as described for asIntArray().

This method always returns null for javadoc tags.

Throws:

NumberFormatException

asLongArray

long[] asLongArray()
                   throws NumberFormatException

Returns this member's value as an array of longs. If necessary, type conversion is performed in a similar manner as described for asIntArray().

This method always returns null for javadoc tags.

Throws:

NumberFormatException

asDoubleArray

double[] asDoubleArray()
                       throws NumberFormatException

Returns this member's value as an array of doubles. If necessary, type conversion is performed in a similar manner as described for asIntArray().

This method always returns null for javadoc tags.

Throws:

NumberFormatException

asFloatArray

float[] asFloatArray()
                     throws NumberFormatException

Returns this member's value as an array of floats. If necessary, type conversion is performed in a similar manner as described for asIntArray().

This method always returns null for javadoc tags.

Throws:

NumberFormatException

asByteArray

byte[] asByteArray()
                   throws NumberFormatException

Returns this member's value as an array of bytes. If necessary, type conversion is performed in a similar manner as described for asIntArray().

This method always returns null for javadoc tags.

Throws:

NumberFormatException

asCharArray

char[] asCharArray()
                   throws IllegalArgumentException

Returns this member's value as an array of bytes. If necessary, type conversion is performed in a similar manner as described for asIntArray() and asChar()..

This method always returns null for javadoc tags.

Throws:

IllegalArgumentException

isDefaultValueUsed

boolean isDefaultValueUsed()

Returns true if the member's value was not explicitly set in the annotation instance but was instead taken from the member definition's default.

Note that not all JAM implementations may be able to distinguish the case where the value is explicitly declared to be the same value as the member's default from the case where the value is not declared and the value is implicitly default. In this event, this method will return true if and only if the effective value of the annotation is the same as the default value (regardless of how that value was declared).

getValue

Object getValue()

Deprecated. DO NOT CALL THIS METHOD. IT WILL BE REMOVED SOON. This method is a bad thing because it forces/allows the caller to make assumptions about how the annotation value is actually represented in the underlying implementation. Please use a combination of getType() and the various as...() methods instead.