Package weblogic.descriptor.annotation

Class PropertyAnnotations

java.lang.Object

weblogic.descriptor.annotation.GlobalAnnotations

weblogic.descriptor.annotation.PropertyAnnotations

public class PropertyAnnotations
extends GlobalAnnotations

Defines annotations that can be specified in a getter or setter method comment to contribute to the defintion of a bean property.

Field Summary

Fields

Modifier and Type	Field	Description
static AnnotationDefinition	AGGREGATE	Indicates that the annotated property is an aggregate of other child properties defined in the containing bean.
static AnnotationDefinition	COMPONENT_NAME	Explicitly specifies the component name of the annotated array property.
static AnnotationDefinition	DEFAULT	Specifies the default value for the annotated property.
static AnnotationDefinition	DEFERRED_VALIDATOR	Specifies a custom method to be called as part of on-demand validation for the bean that defined the annotated property.
static AnnotationDefinition	DERIVED_DEFAULT	Specifies an expression from which to derive the default value for the annotated property.
static AnnotationDefinition	ENUMERATION	Indicates the set of String constants that the annotated String property is constrained to.
static AnnotationDefinition	INITIALIZER	Specifies the initial value to be persisted for the annotated property.
static AnnotationDefinition	KEY	Indicates that the value of the annotated property acts as the unique key for this bean.
static AnnotationDefinition	KEY_CHOICE	Indicates that the value of the annotated property may act as a unique key for this bean.
static AnnotationDefinition	KEY_COMPONENT	Indicates that the value of the annotated property act as one component in a compound key for this bean.
static AnnotationDefinition	LEGAL_MAX	Specifies the maximum value allowed for the annotated property.
static AnnotationDefinition	LEGAL_MIN	Specifies the minimum value allowed for the annotated property.
static AnnotationDefinition	LEGAL_ZERO_LENGTH	Specifies whether the annotated string property may have a zero length.
static AnnotationDefinition	MERGERULE	This annotation is used to define mergeRules for descriptor merging.
static AnnotationDefinition	META_DATA	Deprecated.
static AnnotationDefinition	NULLABLE	Indicates whether the annotated String property may have a null value.
static AnnotationDefinition	PREPROCESSOR	This annotation is useful for introducing a pre-processing steps in the setter before the value is actually set to the property.
static AnnotationDefinition	PRESERVE_WHITE_SPACE	Specifies that whitespace in the value of the annotated String (or String[]) property be preserved.
static AnnotationDefinition	PRODUCTION_DEFAULT	Specifies the default value for the annotated property when used in production mode.
static AnnotationDefinition	REFERENCE	Indicates that the bean(s) held by this property is a reference rather than a child.
static AnnotationDefinition	REMOVE_VALIDATOR	Specifies a custom method to be called to validate the remove of a reference property or destroy of child property.
static AnnotationDefinition	REQUIRED	Indicates whether the annotated property must be assigned an explicit value.
static AnnotationDefinition	TRANSIENT	Indicates that the annotated property is not persisted.
static AnnotationDefinition	UN_SET_VALUE	Can be used with @legalValues to specify a value that would we returned in case the property is not set, or can be used with a setter to mark the property to unset Usage: @unSetValue someValue
static AnnotationDefinition	VALIDATE_PROPERTY_DECLARATION	Deprecated.
static AnnotationDefinition	VALIDATOR	Specifies a custom method to be called to validate the annotated property.
static AnnotationDefinition	XML_ELEMENT_NAME	Explictly specifies the xml element name to be used in the schema definition for the annotated property.

Fields inherited from class weblogic.descriptor.annotation.GlobalAnnotations

CONFIGURABLE, DYNAMIC, EXCLUDE, OBSOLETE, OWNER, ROLE_ALLOWED, ROLE_EXCLUDED, ROLE_PERMIT_ALL, VISIBLE_TO_PARTITION

Method Summary

Modifier and Type	Method	Description
static AnnotationDefinition	getAnnotationDefinition(java.lang.String alias)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

AGGREGATE

public static final AnnotationDefinition AGGREGATE

Indicates that the annotated property is an aggregate of other child properties defined in the containing bean. This annotation specifies a list of properties that are aggregated by this property. Each property in this list must meet the following conditions:

1. the property type must be an instance of the aggregate property
2. the property type must define the same key as all other properties ] in this aggregate
names containing all properties that that this property will aggregate. All properties in this list must be instances of the type of this property. An aggregate property must define a getter method and may define a lookup method. *

The default algorithm for computing the component name is as follows:

• If the name is a regular plural form, convert it to its singular form.
• If the name is not a regular plural form, assume the same name for the component. This will work in cases where the name is actually singular. It will break in cases where this is an irregular plural.
Use this annotation to handle the case where the property name is an irregular plural.

See weblogic.descriptor.example.ExampleRootBean#getChildren for an example use of this annotation.

Usage: @componentName "componentName"

Usage: @wld:property componentName = "componentName"

COMPONENT_NAME

public static final AnnotationDefinition COMPONENT_NAME

Explicitly specifies the component name of the annotated array property. The component name is used to match the property getter with add/remove and createDestroy methods. While the getter property is typically named as plural, methods for manipluating the components are typically named in the singular. For example, a getter for an array of names may be called getNames() while an adder might be called addName().

The default algorithm for computing the component name is as follows:

• If the name is a regular plural form, convert it to its singular form.
• If the name is not a regular plural form, assume the same name for the component. This will work in cases where the name is actually singular. It will break in cases where this is an irregular plural.

Use this annotation to handle the case where the property name is an irregular plural.

See weblogic.descriptor.example.ExampleRootBean#getChildren for an example use of this annotation.

Usage: @componentName "componentName"

Usage: @wld:property componentName = "componentName"

DEFAULT

public static final AnnotationDefinition DEFAULT

Specifies the default value for the annotated property. Note that value must be a constant of the proper type. It may be either literal or symbolic. If the constant is symbolic it is evaluated as if it were referred to outside of the comment block in the interface declaration.

Default: The default value for a primitive property (when this annotation is not present) is specified by JLS Initial Values of Variables. The default value for a String property is null.

Usage: @default value

Usage: @wld:property default = value

DERIVED_DEFAULT

public static final AnnotationDefinition DERIVED_DEFAULT

Specifies an expression from which to derive the default value for the annotated property. The getter expression is a chain of one or more getters that result in a value of the required type. Each but the last (i.e., non-terminal) must return a bean or array of beans. If any non-terminal returns null or an empty array, the derived default is considered invalid and normal default processing is used to determine the default value (see #DEFAULT).

Usage: @derivedDefault getterExpression

Usage: @wld:property derivedDefaut = getterExpression

PRODUCTION_DEFAULT

public static final AnnotationDefinition PRODUCTION_DEFAULT

Specifies the default value for the annotated property when used in production mode.

Default: Value specified by DEFAULT annotation

Usage: @productionDefault value

Usage: @production-mode-default value

Usage: @wld:property productionDefault = value

See Also:

DEFAULT

INITIALIZER

public static final AnnotationDefinition INITIALIZER

Specifies the initial value to be persisted for the annotated property. When a bean containing the property is created in an editable descriptor, the property will be initialized with this value and marked as modified. When the XML document is written, this value will be written (unless the value was overwritten). This annotation is typically used in cunjunction with REQUIRED to initialize a property that must appear in the XML document.

Note that this annotation is different than DEFAULT in that it specifies a value to be written while default specifies a value to be used if none has been explicitly set.

Usage: @initializer expression

Usage: @wld:property initializer = expression

VALIDATOR

public static final AnnotationDefinition VALIDATOR

Specifies a custom method to be called to validate the annotated property. The method must be a static method that is accessible to the generated bean class. It must have the following form (where ParamType is the property type or the type of setter's parameter):

public static void methodName(ParamType param) throws IllegalArgumentException;

See weblogic.descriptor.example.ExampleValidationBean#setURI for an example use of this annotation and weblogic.descriptor.example.ExampleCustomValidator#validateURI for an example of a validator method.

Usage: @validator validatorMethod

Usage: @wld:property validator = validatorMethod The validator can have parameters. Keyword "self" is replaced by bean instance 'this' & "value" is replaced by the value the property is being set to. Also, 'void' is replaced by 'null' and 'customizerField' is replaced by the fieldname of the customizer property is the bean has been customized. Usage: @validator validatorMethod(self, value) In such cases, the validator must be declared apporpriately.

public static void validatorMethod(BeanType bean, PropertyType value) throws IllegalArgumentException;

DEFERRED_VALIDATOR

public static final AnnotationDefinition DEFERRED_VALIDATOR

Specifies a custom method to be called as part of on-demand validation for the bean that defined the annotated property. Altough this annotation is made on a property, the specified method is only called during on-demand validation. The method must be static and accessible to the generated bean class. It must have the following form:

public static void methodName(BeanType bean);

See weblogic.descriptor.example.ExampleValidationBean#setMinimum for an example use of this annotation and weblogic.descriptor.example.ExampleCustomValidator#validateMinLessThanMax for an example of a deferred validator method.

Usage: @deferredValidator validatorMethod

Usage: @wld:property deferredValidator = validatorMethod The validator can have parameters. All the keywords supported on VALIDATOR are supported for this annotation as well, except 'value' is replaced by the getter of the property. See VALIDATOR Usage: @deferredValidator validatorMethod(self, value) In such cases, the validator must be declared apporpriately.

public static void validatorMethod(BeanType bean, PropertyType value) throws IllegalArgumentException;

LEGAL_MAX

public static final AnnotationDefinition LEGAL_MAX

Specifies the maximum value allowed for the annotated property. See weblogic.descriptor.example.ExampleValidationBean#setConstrainedInt for an example use of this annotation.

Usage: @legalMax value

Usage: @wld:property max = value

LEGAL_MIN

public static final AnnotationDefinition LEGAL_MIN

Specifies the minimum value allowed for the annotated property. See weblogic.descriptor.example.ExampleValidationBean#setConstrainedInt for an example use of this annotation.

Usage: @legalMin value

Usage: @wld:property min = value

LEGAL_ZERO_LENGTH

public static final AnnotationDefinition LEGAL_ZERO_LENGTH

Specifies whether the annotated string property may have a zero length. See weblogic.descriptor.example.ExampleValidationBean#setNonEmptyString for an example use of this annotation.

Default: true

Usage: @legalZeroLength booleanValue

Usage: @wld:property zeroLength = booleanValue

NULLABLE

public static final AnnotationDefinition NULLABLE

Indicates whether the annotated String property may have a null value. See weblogic.descriptor.example.ExampleValidationBean#setNonNullString for an example use of this annotation.

Default: false

Usage: @nullable

Usage: @wld:property nullable = booleanValue

Usage: @legalNull

ENUMERATION

public static final AnnotationDefinition ENUMERATION

Indicates the set of String constants that the annotated String property is constrained to. See weblogic.descriptor.example.ExampleValidationBean#setEnumeratedString for an example use of this annotation.

Default: By default a String property is not constrained.

Usage: @enumeration = s1,[s2,...,sN]

Usage: @wld:property enumeration = s1,[s2,...,sN]

Usage: @legalValues = s1,[s2,...,sN]

PRESERVE_WHITE_SPACE

public static final AnnotationDefinition PRESERVE_WHITE_SPACE

Specifies that whitespace in the value of the annotated String (or String[]) property be preserved. Without this annotation, leading and trailing whitespace is removed.

Usage: @preserveWhiteSpace

Usage: @wld:property preserveWhiteSpace = booleanValue

REQUIRED

public static final AnnotationDefinition REQUIRED

Indicates whether the annotated property must be assigned an explicit value.

Default: false

Usage: @required

Usage: @wld:property required = booleanValue

KEY

public static final AnnotationDefinition KEY

Indicates that the value of the annotated property acts as the unique key for this bean. Specifically, the value of this property is guaranteed to be unique among all instances of this bean that are elements of the same array property.

In order to qualify as a key, a property must meet one of the following criteria:

• is an instance of int, String, or String[]
• is an instance of DescriptorBean and the particular bean has a designated key.

Note that there may be only one key property defined for a bean. To accomodate cases where more than one property must be considered for the key, see KEY_CHOICE and KEY_COMPONENT Usage: @key

Usage: @wld:property key = booleanValue

KEY_CHOICE

public static final AnnotationDefinition KEY_CHOICE

Indicates that the value of the annotated property may act as a unique key for this bean. This annotation is a variation on KEY that may be used when one of several bean properties may act as a key. A bean may designate multiple key choices but only if its defintion guarantees that no more that one of these properties will be set on a particular instance of the bean. Whichever property is set on a particular instance will act as the key.

Usage: @keyChoice

Usage: @wld:property keyChoice = booleanValue

KEY_COMPONENT

public static final AnnotationDefinition KEY_COMPONENT

Indicates that the value of the annotated property act as one component in a compound key for this bean. This annotation is a variation on KEY that may be used when a key is made up of multiple porperties. A bean may designate multiple key components. These components are aggregated to produce a single key.

In order to qualify as a key component, a property must meet one of the following criteria:

• is an instance of int, boolean, String, or String[]
• is an instance of DescriptorBean and the particular bean has a designated key.

Usage: @keyComponent

Usage: @wld:property keyComponent = booleanValue

REFERENCE

public static final AnnotationDefinition REFERENCE

Indicates that the bean(s) held by this property is a reference rather than a child. Any property that has an adder or setter and no creator is considered a reference by default.

Usage: @reference

Usage: @wld:property reference = booleanValue

TRANSIENT

public static final AnnotationDefinition TRANSIENT

Indicates that the annotated property is not persisted. Special care must be taken with transient properties. Because thay must be computed (rather than read from a document) and there are no rules constraining their values, transient properties are largely ignored by the descriptor framework. In particular such properties are:

• ignored when diff'ing two versions of a descriptor
• ignored when applying a new version of a descriptor to an existing descriptor
• ignored when cloning DescriptorBean.createChildCopy(java.lang.String, weblogic.descriptor.DescriptorBean))

While not strictly necessary, we recommend that transient properties be implemented with a custom implementation. This enforces the fact that they must be computed and are not copied.

Default: false

Usage: @transient

Usage: @wld:property transient = booleanValue

XML_ELEMENT_NAME

public static final AnnotationDefinition XML_ELEMENT_NAME

Explictly specifies the xml element name to be used in the schema definition for the annotated property. By default the element name will be derived by:

1. Starting with the java property name or the COMPONENT_NAME if the property is an array of beans. Inserting a '-' before each capital letter that is preceeded by a lowercase letter
2. Converting all capital letters to lowercase

For example, FooBar becomes foo-bar

Usage: @xmlElementName String

Usage: @wld:property xmlElementName = String

REMOVE_VALIDATOR

public static final AnnotationDefinition REMOVE_VALIDATOR

Specifies a custom method to be called to validate the remove of a reference property or destroy of child property. The method must be a static method that is accessible to the generated bean class. It can be applied only on remove or destrory methods of a property. It must have the following form:

public static void methodName(BeanType bean) throws IllegalArgumentException;

See weblogic.descriptor.example.ExampleCustomValidator#validateURI for an example of a validator method.

Usage: @removeValidator validatorMethod

Usage: @wld:property removeValidator = validatorMethod The remove validator can be parameterized and the annotation supports all the keywords like VALIDATOR. See VALIDATOR

VALIDATE_PROPERTY_DECLARATION

@Deprecated
public static final AnnotationDefinition VALIDATE_PROPERTY_DECLARATION

Deprecated.

For intenal use of Beangen. Used to indicate if the beangen should refrain from doing validation checks on this property declaration. If set to false, beangen would not apply property type specific rules on this property's declaration. The support for this annotation may be disconinued in the future.

Usage: @validatePropertyDeclaration booleanValue

Usage: @wld:property validatePropertyDeclaration = booleanValue

UN_SET_VALUE

public static final AnnotationDefinition UN_SET_VALUE

Can be used with @legalValues to specify a value that would we returned in case the property is not set, or can be used with a setter to mark the property to unset Usage: @unSetValue someValue

Usage: @wld:property unSetValue = someValue

PREPROCESSOR

public static final AnnotationDefinition PREPROCESSOR

This annotation is useful for introducing a pre-processing steps in the setter before the value is actually set to the property. The value of the annotaion should be a java expression that evaluates to something that is assignable to the property. Multiple instance of this annotation can be placed on the property and all of them would be used.

Usage: @preprocessor expression

Usage: @wld:property preprocessor = expression The value of this annotation can have variables that are replaced by appropriate values during code generation. The variable set supported is same as that for VALIDATOR annotation. See VALIDATOR Note that as of now this annotation is supported only for String and int properties. This annotation can be applied to array properties as well. Also note that the onus of making sure that the there is no Exception while executing the java expression is on the user of the annotation.

MERGERULE

public static final AnnotationDefinition MERGERULE

This annotation is used to define mergeRules for descriptor merging. for eg: when library descriptors get merged with the webapp descriptors. Usage: @mergeRule someValue

META_DATA

@Deprecated
public static final AnnotationDefinition META_DATA

Deprecated.

Experimental Annotation. Please don't use this.

Method Detail

getAnnotationDefinition

public static AnnotationDefinition getAnnotationDefinition(java.lang.String alias)