JAnnotation (Castor JavaDoc)

java.lang.Object
- org.exolab.javasource.JAnnotation

public final class JAnnotation
extends java.lang.Object

JAnnotation represents a single annotation against a code element. The methods described on the JAnnotatedElement interface are used to associate JAnnotation's with various other objects in this package describing Java code elements.

The print method outputs annotations in various forms (as described in the Java Language Specification Third Edition) based on the methods called.

For "Marker Annotation", construct with the appropriate JAnnotationType.

   JAnnotationType preliminaryType = new JAnnotationType("Preliminary");
   JAnnotation preliminary = new JAnnotation(preliminaryType);

outputs

   @Preliminary()

For "Single Element Annotation", construct as above and call the setValue(value) method to set the value of the "value" element of the annotation type.

   JAnnotationType copyrightType = new JAnnotationType("Copyright");
   JAnnotation copyright = new JAnnotation(copyrightType);
   copyright.setValue("\"2002 Yoyodyne Systems, Inc., All rights reserved.\"");

outputs

   @Copyright("2002 Yoyodyne Propulsion Systems, Inc., All rights reserved.")

For "Normal Annotation," construct as above then call the appropriate setValue methods that accept an "elementName" parameter.

   JAnnotationType requestType = new JAnnotationType("RequestForEnhancement");
   JAnnotation request = new JAnnotation(requestType);
   request.setElementValue("id", "2868724");
   request.setElementValue("synopsis", "\"Provide time-travel functionality\"");
   request.setElementValue("engineer", "\"Mr. Peabody\"");
   request.setElementValue("date", "\"4/1/2004\"");

outputs

   @RequestForEnhancement(
       id       = 2868724,
       sysopsis = "Provide time-travel functionality",
       engineer = "Mr. Peabody",
       date     = "4/1/2004")

"Complex" annotations are also supported via the various setValue methods that take a JAnnotation object.

   JAnnotationType nameType = new JAnnotationType("Name");
   JAnnotationType authorType = new JAnnotationType("Author");
   JAnnotation author = new JAnnotation(authorType);
   JAnnotation name = new JAnnotation(nameType);
   name.setElementValue("first", "\"Joe\"");
   name.setElementValue("last", "\"Hacker\"");
   author.setValue(name);

outputs

   @Author(@Name(
       first = "Joe",
       last  = "Hacker"))

Finally annotation elements whose types are arrays are supported via the setValue methods that take arrays:

   JAnnotationType endorsersType = new JAnnotationType("Endorsers");
   JAnnotation endorsers = new JAnnotation(endorsersType);
   endorsers.setValue(new String[] { "\"Children\"", "\"Unscrupulous dentists\""});

outputs

   @Endorsers(
       {
           "Children",
           "Unscrupulous dentists"
       })

Note: Conditional element values are not currently supported. However the setValue methods taking String values can be used to output this construct literally if desired.

Version:: $Revision: 8009 $ $Date: 2006-04-25 16:09:10 -0600 (Tue, 25 Apr 2006) $
Author:: Andrew Fawcett

Field Summary

Fields
Modifier and Type Field Description

static java.lang.String VALUE
Name of a single element.

Fields
Modifier and Type	Field	Description
`static java.lang.String`	`VALUE`	Name of a single element.

Constructor Summary

Constructors
Constructor Description

JAnnotation(JAnnotationType annotationType)
Constructs a JAnnotation for the given annotation type.

Constructors
Constructor	Description
`JAnnotation(JAnnotationType annotationType)`	Constructs a JAnnotation for the given annotation type.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`JAnnotationType`	`getAnnotationType()`	Returns the JAnnotationType associated with this JAnnotation.
`java.lang.String[]`	`getElementNames()`	Returns the names of the elements set by this annotation.
`java.lang.String`	`getElementValue(java.lang.String elementName)`	For the provided element name, returns the annotation element value when it is a String.
`JAnnotation`	`getElementValueAnnotation(java.lang.String elementName)`	For the provided element name, returns the annotation element value when it is a JAnnotation.
`JAnnotation[]`	`getElementValueAnnotationList(java.lang.String elementName)`	For the provided element name, returns the annotation element value when it is an array of JAnnotation.
`java.lang.String[]`	`getElementValueList(java.lang.String elementName)`	For the provided element name, returns the annotation element value when it is an array of String.
`java.lang.Object`	`getElementValueObject(java.lang.String elementName)`	Returns the given annotation element value as Object, typically used if the value type is not known.
`java.lang.String`	`getValue()`	Returns the annotation element value when it is a String.
`JAnnotation`	`getValueAnnotation()`	Returns the annotation element value when it is an annotation.
`void`	`print(JSourceWriter jsw)`	Prints the source code for this JAnnotation to the given JSourceWriter.
`void`	`setElementValue(java.lang.String elementName, java.lang.String stringValue)`	Adds an annotation element name=value pair.
`void`	`setElementValue(java.lang.String elementName, java.lang.String[] stringValues)`	Adds an annotation element name=list pair.
`void`	`setElementValue(java.lang.String elementName, JAnnotation annotationValue)`	Adds an annotation element name=annotation pair.
`void`	`setElementValue(java.lang.String elementName, JAnnotation[] annotationValues)`	Adds an annotation element name=array of annotations.
`void`	`setValue(java.lang.String stringValue)`	Sets the "value" annotation element value.
`void`	`setValue(java.lang.String[] stringValue)`	Sets the "value" annotation element value as a list.
`void`	`setValue(JAnnotation annotationValue)`	Sets the "value" annotation element value as an annotation.
`void`	`setValue(JAnnotation[] annotationValues)`	Sets the "value" annotation element value as a list of annotation values.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - VALUE
```
public static final java.lang.String VALUE
```
    Name of a single element.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - JAnnotation
```
public JAnnotation(JAnnotationType annotationType)
```
    Constructs a JAnnotation for the given annotation type.
    
    Parameters:
    
    annotationType - Annotation type.
- Method Detail
  - getAnnotationType
```
public JAnnotationType getAnnotationType()
```
    Returns the JAnnotationType associated with this JAnnotation.
    
    Returns:
    
    The JAnnotationType associated with this JAnnotation..
  - setValue
```
public void setValue(java.lang.String stringValue)
```
    Sets the "value" annotation element value.
    
    Parameters:
    
    stringValue - Literal String value.
  - setValue
```
public void setValue(java.lang.String[] stringValue)
```
    Sets the "value" annotation element value as a list.
    
    Parameters:
    
    stringValue - Array of literal String values.
  - setValue
```
public void setValue(JAnnotation annotationValue)
```
    Sets the "value" annotation element value as an annotation.
    
    Parameters:
    
    annotationValue - JAnnotation to be used as this JAnnotation's value.
  - setValue
```
public void setValue(JAnnotation[] annotationValues)
```
    Sets the "value" annotation element value as a list of annotation values.
    
    Parameters:
    
    annotationValues - Array of JAnnotations to be used as this JAnnotation's value.
  - setElementValue
```
public void setElementValue(java.lang.String elementName,
                            java.lang.String stringValue)
```
    Adds an annotation element name=value pair.
    
    Parameters:
    
    elementName - Name of this annotation element.
    
    stringValue - Value of this annotation element.
  - setElementValue
```
public void setElementValue(java.lang.String elementName,
                            java.lang.String[] stringValues)
```
    Adds an annotation element name=list pair.
    
    Parameters:
    
    elementName - Name of this annotation element.
    
    stringValues - String array value of this annotation element.
  - setElementValue
```
public void setElementValue(java.lang.String elementName,
                            JAnnotation annotationValue)
```
    Adds an annotation element name=annotation pair.
    
    Parameters:
    
    elementName - Name of this annotation element.
    
    annotationValue - Annotation to be used as the value.
  - setElementValue
```
public void setElementValue(java.lang.String elementName,
                            JAnnotation[] annotationValues)
```
    Adds an annotation element name=array of annotations.
    
    Parameters:
    
    elementName - Name of this annotation element.
    
    annotationValues - Array of annotations to be used as the value.
  - getValue
```
public java.lang.String getValue()
```
    Returns the annotation element value when it is a String.
    
    Returns:
    
    The annotation element value.
  - getValueAnnotation
```
public JAnnotation getValueAnnotation()
```
    Returns the annotation element value when it is an annotation.
    
    Returns:
    
    The annotation element value when it is an annotation.
  - getElementValue
```
public java.lang.String getElementValue(java.lang.String elementName)
```
    For the provided element name, returns the annotation element value when it is a String.
    
    Parameters:
    
    elementName - Element to return the value of.
    
    Returns:
    
    The annotation element value.
  - getElementValueList
```
public java.lang.String[] getElementValueList(java.lang.String elementName)
```
    For the provided element name, returns the annotation element value when it is an array of String.
    
    Parameters:
    
    elementName - Element to return the value of.
    
    Returns:
    
    The annotation element value.
  - getElementValueObject
```
public java.lang.Object getElementValueObject(java.lang.String elementName)
```
    Returns the given annotation element value as Object, typically used if the value type is not known. This will either be a String or JAnnotation or an array of String or an array of JAnnotation.
    
    Parameters:
    
    elementName - Element to return the value of.
    
    Returns:
    
    Annotation element value as Object.
  - getElementValueAnnotation
```
public JAnnotation getElementValueAnnotation(java.lang.String elementName)
```
    For the provided element name, returns the annotation element value when it is a JAnnotation.
    
    Parameters:
    
    elementName - Element to return the value of.
    
    Returns:
    
    The annotation element value.
  - getElementValueAnnotationList
```
public JAnnotation[] getElementValueAnnotationList(java.lang.String elementName)
```
    For the provided element name, returns the annotation element value when it is an array of JAnnotation.
    
    Parameters:
    
    elementName - Element to return the value of.
    
    Returns:
    
    The annotation element value.
  - getElementNames
```
public java.lang.String[] getElementNames()
```
    Returns the names of the elements set by this annotation.
    
    Returns:
    
    Array of element names.
  - print
```
public void print(JSourceWriter jsw)
```
    Prints the source code for this JAnnotation to the given JSourceWriter.
    
    Parameters:
    
    jsw - the JSourceWriter to print to. Must not be null.

Class JAnnotation

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

VALUE

Constructor Detail

JAnnotation

Method Detail

getAnnotationType

setValue

setValue

setValue

setValue

setElementValue

setElementValue

setElementValue

setElementValue

getValue

getValueAnnotation

getElementValue

getElementValueList

getElementValueObject

getElementValueAnnotation

getElementValueAnnotationList

getElementNames

print