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.*;
/**
* Annotation for specifying various XML options for the XML and RDF/XML serializers.
*
*
* Can be applied to Java packages, types, fields, and methods.
*
*
* 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.
*
*/
@Documented
@Target({TYPE,FIELD,METHOD})
@Retention(RUNTIME)
@Inherited
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>
*
*/
String childName() 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} with the same name through the {@link XmlSchema#xmlNs()} annotation on the package.
*/
String prefix() 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} with the
* same name through the {@link XmlSchema#xmlNs()} annotation on the package.
*/
String namespace() 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.
* @BeanProperty (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>
*
*/
XmlFormat format() default XmlFormat.DEFAULT;
}