org.xchain.annotations

Annotation Type Attribute

@Target(value=METHOD)
@Retention(value=RUNTIME)
@Inherited
@Documented
public @interface Attribute

Binds an abstract method to an xml attribute for a Command. When a command has an abstract method marked with the annotation, XChains will engineer all of the code needed to access the value described by the attribute from a JXPathContext.

Methods marked with this annotation must meet the following requirements:

• The method must be abstract.
• The method must take a JXPathContext as its first parameter.
• If the method has two parameters, the second parameter must be of type java.lang.Class and the annotation's type attribute must be AttributeType.JXPATH_VALUE.
• The method must not have more than two parameters.

Basic usage:

To bind a method to an attribute, two things must be specified. First the name of the attribute must be specified. Secondly, the way to treat the attributes value must be specified. This can be accomplished with the localName and type attributes of this annotation. Here is an example:

   @Attribute(localName="attr", type=AttributeType.JXPATH_VALUE)
   public abstract Object getAttr(JXPathContext context);
 

This method binds the attribute "attr" in the default namespace and defines its value to be an XPath. The engineered method will include a call to JXPathContext.getValue(String, Class) where the xpath is the value of the attribute "attr" and the class is java.lang.Object.

Defining a default value for an attribute:

When defining a default value for an attribute, the defaultValue attribute of the annotation must be defined. If the default value uses any prefixes, then the defaultPrefixMappings attribute must also be included on the annotation and it must include the prefixes required for the default value. For example:

   @Attribute(localName="attr", type=AttributeType.JXPATH_VALUE, defaultValue="example:function()", defaultPrefixMappings={"xmlns:example='http://www.xchain.org/example'"}
   public abstract Object getAttr(JXPathContext context);
 

If the attribute "attr" is not specified, then the default prefix mappings will be registered with the context and the attribute will be evaluated as though it had the value "example:function()". Once the evaluation is done, then all of the default prefix mappings will be unregistered.

Marking an attribute as required:

When defining that an attribute is required, the required attribute of the annotation must be defined to be true. If this part of the annotation is defined, then an XChain will not load if the attribute is missing. For example:

   @Attribute(localName="attr", type=AttributeType.JXPATH_VALUE, required=true}
   public abstract Object getAttr(JXPathContext context);
 

If the attribute "attr" is not specified, then any attempt to load a catalog containing that command will fail with an exception.

Author:

Mike Moulton, Christian Trimble

Required Element Summary

Required Elements

Modifier and Type	Required Element and Description
java.lang.String	localName Defines the local name component of this attribute's QName.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
PrefixMapping[]	defaultPrefixMappings Defines the prefix mapping context for the default value.
java.lang.String	defaultValue Defines the default value for this attribute.
java.lang.String	namespaceUri Defines the namespace uri component of this attributes QName.
boolean	required Defines if this attribute is required.
AttributeType	type Defines the type of this attributes value.

Element Detail

localName

public abstract java.lang.String localName

Defines the local name component of this attribute's QName.

Returns:

the local name component of this attribute's QName.

namespaceUri

public abstract java.lang.String namespaceUri

Defines the namespace uri component of this attributes QName.

Returns:

the namespace uri component of this attribute's QName.

Default:

""

type

public abstract AttributeType type

Defines the type of this attributes value.

Returns:

the type of this attributes value.

Default:

org.xchain.annotations.AttributeType.JXPATH_VALUE

defaultValue

public abstract java.lang.String defaultValue

Defines the default value for this attribute.

Returns:

the default value for this attribute.

Default:

""

defaultPrefixMappings

public abstract PrefixMapping[] defaultPrefixMappings

Defines the prefix mapping context for the default value. The values of this array are defined like namespace prefixes in an xml document. Here is an example that binds the prefixes "one" and "two" to the namespaces "http://www.xchain.org/one" and "http://www.xchain.org/two", respectively.

   defaultPrefixMapping={"xmlns:one='http://www.xchain.org/one'", "xmlns:two='http://www.xchain.org/two'"}
 

Returns:

the prefix mapping context for the default value.

Default:

{}

required

public abstract boolean required

Defines if this attribute is required. A value of true means that this attribute is required. A value of false means that this attribute is not required. The default value if false.

Returns:

true if this attribute is required, false otherwise.

Default:

false