// *************************************************************************************************************************** | |
// * 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. | |
* | |
* <p> | |
* Can be applied to Java packages, types, fields, and methods. | |
* | |
* <p> | |
* Can be used for the following: | |
* <ul> | |
* <li>Override the child element name on the XML representation of collection or array properties. | |
* <li>Specify the XML namespace on a package, class, or method. | |
* <li>Override the XML format on a POJO. | |
* </ul> | |
*/ | |
@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. | |
* | |
* <p> | |
* Applies only to collection and array bean properties. | |
* | |
* <h5 class='section'>Example:</h5> | |
* <p class='bcode w800'> | |
* <jk>public class</jk> MyBean { | |
* <ja>@Xml</ja>(childName=<js>"child"</js>} | |
* <jk>public</jk> String[] <jf>children</jf> = {<js>"foo"</js>,<js>"bar"</js>}; | |
* } | |
* </p> | |
* | |
* <p> | |
* Without the <ja>@Xml</ja> annotation, serializing this bean as XML would have produced the following... | |
* <p class='bcode w800'> | |
* <xt><object></xt> | |
* <xt><children></xt> | |
* <xt><string></xt>foo<xt></string></xt> | |
* <xt><string></xt>bar<xt></string></xt> | |
* <xt></children></xt> | |
* <xt></object></xt> | |
* </p> | |
* | |
* <p> | |
* With the annotations, serializing this bean as XML produces the following... | |
* <p class='bcode w800'> | |
* <xt><object></xt> | |
* <xt><children></xt> | |
* <xt><child></xt>foo<xt></child></xt> | |
* <xt><child></xt>bar<xt></child></xt> | |
* <xt></children></xt> | |
* <xt></object></xt> | |
* </p> | |
*/ | |
String childName() default ""; | |
/** | |
* The {@link XmlFormat} to use for serializing this object type. | |
* | |
* <h5 class='section'>Example:</h5> | |
* <p class='bcode w800'> | |
* <jk>public class</jk> MyBean { | |
* | |
* <jc>// Normally, bean properties would be rendered as child elements of the bean element.</jc> | |
* <jc>// Override so that it's rendered as a "f1='123'" attribute on the bean element instead.</jc> | |
* <ja>@Xml</ja>(format=XmlFormat.<jsf>ATTR</jsf>} | |
* <jk>public int</jk> f1 = 123; | |
* | |
* <jc>// Normally, bean URL properties would be rendered as XML attributes on the bean element.</jc> | |
* <jc>// Override so that it's rendered as an <href>http://foo</href> child element instead.</jc> | |
* <ja>@Beanp</ja>(uri=<jk>true</jk>) | |
* <ja>@Xml</ja>(format=XmlFormat.<jsf>ELEMENT</jsf>} | |
* <jk>public</jk> URL <jf>href</jf> = <jk>new</jk> URL(<js>"http://foo"</js>); | |
* | |
* <jc>// Normally, collection properties would be grouped under a single <children> child element on the bean element.</jc> | |
* <jc>// Override so that entries are directly children of the bean element with each entry having an element name of <child>.</jc> | |
* <ja>@Xml</ja>(format=XmlFormat.<jsf>COLLAPSED</jsf>, childName=<js>"child"</js>} | |
* <jk>public</jk> String[] <jf>children</jf> = <js>"foo"</js>,<js>"bar"</js>}; | |
* } | |
* </p> | |
* | |
* <p> | |
* Without the <ja>@Xml</ja> annotations, serializing this bean as XML would have produced the following... | |
* <p class='bcode w800'> | |
* <xt><object</xt> <xa>href</xa>=<js>'http://foo'</js><xt>></xt> | |
* <xt><f1></xt>123<xt></f1></xt> | |
* <xt><children></xt> | |
* <xt><string></xt>foo<xt></string></xt> | |
* <xt><string></xt>bar<xt></string></xt> | |
* <xt></children></xt> | |
* <xt></object></xt> | |
* </p> | |
* | |
* <p> | |
* With the annotations, serializing this bean as XML produces the following... | |
* <p class='bcode w800'> | |
* <xt><object</xt> <xa>f1</xa>=<js>'123'</js><xt>></xt> | |
* <xt><href></xt>http://foo<xt></href></xt> | |
* <xt><child></xt>foo<xt></child></xt> | |
* <xt><child></xt>bar<xt></child></xt> | |
* <xt></object></xt> | |
* </p> | |
*/ | |
XmlFormat format() default XmlFormat.DEFAULT; | |
/** | |
* Sets the namespace URI of this property or class. | |
* | |
* <p> | |
* 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. | |
*/ | |
String namespace() default ""; | |
/** | |
* Dynamically apply this annotation to the specified classes/methods/fields. | |
* | |
* <p> | |
* Used in conjunction with the {@link XmlConfig#applyXml()}. | |
* It is ignored when the annotation is applied directly to classes/methods/fields. | |
* | |
* <h5 class='section'>Valid patterns:</h5> | |
* <ul class='spaced-list'> | |
* <li>Classes: | |
* <ul> | |
* <li>Fully qualified: | |
* <ul> | |
* <li><js>"com.foo.MyClass"</js> | |
* </ul> | |
* <li>Fully qualified inner class: | |
* <ul> | |
* <li><js>"com.foo.MyClass$Inner1$Inner2"</js> | |
* </ul> | |
* <li>Simple: | |
* <ul> | |
* <li><js>"MyClass"</js> | |
* </ul> | |
* <li>Simple inner: | |
* <ul> | |
* <li><js>"MyClass$Inner1$Inner2"</js> | |
* <li><js>"Inner1$Inner2"</js> | |
* <li><js>"Inner2"</js> | |
* </ul> | |
* </ul> | |
* <li>Methods: | |
* <ul> | |
* <li>Fully qualified with args: | |
* <ul> | |
* <li><js>"com.foo.MyClass.myMethod(String,int)"</js> | |
* <li><js>"com.foo.MyClass.myMethod(java.lang.String,int)"</js> | |
* <li><js>"com.foo.MyClass.myMethod()"</js> | |
* </ul> | |
* <li>Fully qualified: | |
* <ul> | |
* <li><js>"com.foo.MyClass.myMethod"</js> | |
* </ul> | |
* <li>Simple with args: | |
* <ul> | |
* <li><js>"MyClass.myMethod(String,int)"</js> | |
* <li><js>"MyClass.myMethod(java.lang.String,int)"</js> | |
* <li><js>"MyClass.myMethod()"</js> | |
* </ul> | |
* <li>Simple: | |
* <ul> | |
* <li><js>"MyClass.myMethod"</js> | |
* </ul> | |
* <li>Simple inner class: | |
* <ul> | |
* <li><js>"MyClass$Inner1$Inner2.myMethod"</js> | |
* <li><js>"Inner1$Inner2.myMethod"</js> | |
* <li><js>"Inner2.myMethod"</js> | |
* </ul> | |
* </ul> | |
* <li>Fields: | |
* <ul> | |
* <li>Fully qualified: | |
* <ul> | |
* <li><js>"com.foo.MyClass.myField"</js> | |
* </ul> | |
* <li>Simple: | |
* <ul> | |
* <li><js>"MyClass.myField"</js> | |
* </ul> | |
* <li>Simple inner class: | |
* <ul> | |
* <li><js>"MyClass$Inner1$Inner2.myField"</js> | |
* <li><js>"Inner1$Inner2.myField"</js> | |
* <li><js>"Inner2.myField"</js> | |
* </ul> | |
* </ul> | |
* <li>A comma-delimited list of anything on this list. | |
* </ul> | |
* | |
* <ul class='seealso'> | |
* <li class='link'>{@doc juneau-marshall.DynamicallyAppliedAnnotations} | |
* </ul> | |
*/ | |
String on() default ""; | |
/** | |
* Sets the XML prefix of this property or class. | |
* | |
* <ul class='spaced-list'> | |
* <li> | |
* When applied to a {@link ElementType#TYPE}, namespace is applied to all properties in the class, and all | |
* subclasses of the class. | |
* <li> | |
* When applied to bean properties on {@link ElementType#METHOD} and {@link ElementType#FIELD}, applies | |
* to the bean property. | |
* </ul> | |
* | |
* <p> | |
* 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. | |
*/ | |
String prefix() default ""; | |
} |