Package org.apache.juneau.xml.annotation

Annotation Interface Xml

@Documented
@Target({TYPE,FIELD,METHOD})
@Retention(RUNTIME)
@Inherited
@Repeatable(Array.class)
@ContextApply(Apply.class)
public @interface Xml

Annotation for specifying various XML options for the XML and RDF/XML serializers.

Can be used in the following locations:

• Marshalled classes/methods/fields/packages.
• @Rest-annotated classes and @RestOp-annotated methods when an on() value is specified.

Can be used for the following:

• Override the child element name on the XML representation of collection or array properties.
• Specify the XML namespace on a package, class, or method.
• Override the XML format on a POJO.

See Also:

• XML Basics

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
String	childName	Sets the name of the XML child elements for bean properties of type collection and array.
String[]	description	Optional description for the exposed API.
XmlFormat	format	The XmlFormat to use for serializing this object type.
String	namespace	Sets the namespace URI of this property or class.
String[]	on	Dynamically apply this annotation to the specified classes/methods/fields.
Class<?>[]	onClass	Dynamically apply this annotation to the specified classes.
String	prefix	Sets the XML prefix of this property or class.

Element Details

childName

String childName

Sets the name of the XML child elements for bean properties of type collection and array.

Applies only to collection and array bean properties.

Example:

public class MyBean { @Xml(childName="child"} public String[] children = {"foo","bar"}; }

Without the @Xml annotation, serializing this bean as XML would have produced the following...

<object> <children> <string>foo</string> <string>bar</string> </children> </object>

With the annotations, serializing this bean as XML produces the following...

<object> <children> <child>foo</child> <child>bar</child> </children> </object>

Returns:

The annotation value.

Default:

""

description

String[] description

Optional description for the exposed API.

Returns:

The annotation value.

Since:

9.2.0

Default:

{}

format

XmlFormat format

The XmlFormat to use for serializing this object type.

Example:

public class MyBean { // Normally, bean properties would be rendered as child elements of the bean element. // Override so that it's rendered as a "f1='123'" attribute on the bean element instead. @Xml(format=XmlFormat.ATTR} public int f1 = 123; // Normally, bean URL properties would be rendered as XML attributes on the bean element. // Override so that it's rendered as an <href>http://foo</href> child element instead. @Beanp(uri=true) @Xml(format=XmlFormat.ELEMENT} public URL href = new URL("http://foo"); // Normally, collection properties would be grouped under a single <children> child element on the bean element. // Override so that entries are directly children of the bean element with each entry having an element name of <child>. @Xml(format=XmlFormat.COLLAPSED, childName="child"} public String[] children = "foo","bar"}; }

Without the @Xml annotations, serializing this bean as XML would have produced the following...

<object href='http://foo'> <f1>123</f1> <children> <string>foo</string> <string>bar</string> </children> </object>

With the annotations, serializing this bean as XML produces the following...

<object f1='123'> <href>http://foo</href> <child>foo</child> <child>bar</child> </object>

Returns:

The annotation value.

Default:

DEFAULT

namespace

String namespace

Sets the namespace URI of this property or class.

Must be matched with a prefix() annotation on this object, a parent object, or a @XmlNs with the same name through the @XmlSchema(xmlNs) annotation on the package.

Returns:

The annotation value.

Default:

""

on

String[] on

Dynamically apply this annotation to the specified classes/methods/fields.

Used in conjunction with BeanContext.Builder.applyAnnotations(Class...) to dynamically apply an annotation to an existing class/method/field. It is ignored when the annotation is applied directly to classes/methods/fields.

Valid patterns:

• Classes:
  • Fully qualified:
    • "com.foo.MyClass"
  • Fully qualified inner class:
    • "com.foo.MyClass$Inner1$Inner2"
  • Simple:
    • "MyClass"
  • Simple inner:
    • "MyClass$Inner1$Inner2"
    • "Inner1$Inner2"
    • "Inner2"
• Methods:
  • Fully qualified with args:
    • "com.foo.MyClass.myMethod(String,int)"
    • "com.foo.MyClass.myMethod(java.lang.String,int)"
    • "com.foo.MyClass.myMethod()"
  • Fully qualified:
    • "com.foo.MyClass.myMethod"
  • Simple with args:
    • "MyClass.myMethod(String,int)"
    • "MyClass.myMethod(java.lang.String,int)"
    • "MyClass.myMethod()"
  • Simple:
    • "MyClass.myMethod"
  • Simple inner class:
    • "MyClass$Inner1$Inner2.myMethod"
    • "Inner1$Inner2.myMethod"
    • "Inner2.myMethod"
• Fields:
  • Fully qualified:
    • "com.foo.MyClass.myField"
  • Simple:
    • "MyClass.myField"
  • Simple inner class:
    • "MyClass$Inner1$Inner2.myField"
    • "Inner1$Inner2.myField"
    • "Inner2.myField"
• A comma-delimited list of anything on this list.

See Also:

• Dynamically Applied Annotations

Returns:

The annotation value.

Default:

{}

onClass

Class<?>[] onClass

Dynamically apply this annotation to the specified classes.

Identical to on() except allows you to specify class objects instead of a strings.

See Also:

• Dynamically Applied Annotations

Returns:

The annotation value.

Default:

{}

prefix

String prefix

Sets the XML prefix of this property or class.

• When applied to a ElementType.TYPE, namespace is applied to all properties in the class, and all subclasses of the class.
• When applied to bean properties on ElementType.METHOD and ElementType.FIELD, applies to the bean property.

Must either be matched to a namespace() annotation on the same object, parent object, or a @XmlNs with the same name through the @XmlSchema(xmlNs) annotation on the package.

Returns:

The annotation value.

Default:

""