org.apache.juneau.xml.annotation.Xml Maven / Gradle / Ivy
// ***************************************************************************************************************************
// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file *
// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file *
// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance *
// * with the License. You may obtain a copy of the License at *
// * *
// * http://www.apache.org/licenses/LICENSE-2.0 *
// * *
// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an *
// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the *
// * specific language governing permissions and limitations under the License. *
// ***************************************************************************************************************************
package org.apache.juneau.xml.annotation;
import static java.lang.annotation.ElementType.*;
import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
import org.apache.juneau.annotation.*;
/**
* 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 {@link #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 Details
*
*/
@Documented
@Target({TYPE,FIELD,METHOD})
@Retention(RUNTIME)
@Inherited
@Repeatable(XmlAnnotation.Array.class)
@ContextApply(XmlAnnotation.Apply.class)
public @interface Xml {
/**
* 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>
*
*
* @return The annotation value.
*/
String childName() default "";
/**
* The {@link 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>
*
*
* @return The annotation value.
*/
XmlFormat format() default XmlFormat.DEFAULT;
/**
* Sets the namespace URI of this property or class.
*
*
* Must be matched with a {@link #prefix()} annotation on this object, a parent object, or a {@link XmlNs @XmlNs} with the
* same name through the {@link XmlSchema#xmlNs() @XmlSchema(xmlNs)} annotation on the package.
*
* @return The annotation value.
*/
String namespace() default "";
/**
* Dynamically apply this annotation to the specified classes/methods/fields.
*
*
* Used in conjunction with {@link org.apache.juneau.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:
*
* @return The annotation value.
*/
String[] on() default {};
/**
* Dynamically apply this annotation to the specified classes.
*
*
* Identical to {@link #on()} except allows you to specify class objects instead of a strings.
*
*
See Also:
*
* @return The annotation value.
*/
Class[] onClass() default {};
/**
* Sets the XML prefix of this property or class.
*
*
* -
* When applied to a {@link ElementType#TYPE}, namespace is applied to all properties in the class, and all
* subclasses of the class.
*
-
* When applied to bean properties on {@link ElementType#METHOD} and {@link ElementType#FIELD}, applies
* to the bean property.
*
*
*
* Must either be matched to a {@link #namespace()} annotation on the same object, parent object, or a
* {@link XmlNs @XmlNs} with the same name through the {@link XmlSchema#xmlNs() @XmlSchema(xmlNs)} annotation on the package.
*
* @return The annotation value.
*/
String prefix() default "";
}