001// *************************************************************************************************************************** 002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file * 003// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file * 004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance * 005// * with the License. You may obtain a copy of the License at * 006// * * 007// * http://www.apache.org/licenses/LICENSE-2.0 * 008// * * 009// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an * 010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the * 011// * specific language governing permissions and limitations under the License. * 012// *************************************************************************************************************************** 013package org.apache.juneau.xml.annotation; 014 015import static java.lang.annotation.ElementType.*; 016import static java.lang.annotation.RetentionPolicy.*; 017 018import java.lang.annotation.*; 019 020/** 021 * Annotation for specifying various XML options for the XML and RDF/XML serializers. 022 * 023 * <p> 024 * Can be applied to Java packages, types, fields, and methods. 025 * 026 * <p> 027 * Can be used for the following: 028 * <ul> 029 * <li>Override the child element name on the XML representation of collection or array properties. 030 * <li>Specify the XML namespace on a package, class, or method. 031 * <li>Override the XML format on a POJO. 032 * </ul> 033 */ 034@Documented 035@Target({TYPE,FIELD,METHOD}) 036@Retention(RUNTIME) 037@Inherited 038public @interface Xml { 039 040 /** 041 * Sets the name of the XML child elements for bean properties of type collection and array. 042 * 043 * <p> 044 * Applies only to collection and array bean properties. 045 * 046 * <h5 class='section'>Example:</h5> 047 * <p class='bcode w800'> 048 * <jk>public class</jk> MyBean { 049 * <ja>@Xml</ja>(childName=<js>"child"</js>} 050 * <jk>public</jk> String[] <jf>children</jf> = {<js>"foo"</js>,<js>"bar"</js>}; 051 * } 052 * </p> 053 * 054 * <p> 055 * Without the <ja>@Xml</ja> annotation, serializing this bean as XML would have produced the following... 056 * <p class='bcode w800'> 057 * <xt><object></xt> 058 * <xt><children></xt> 059 * <xt><string></xt>foo<xt></string></xt> 060 * <xt><string></xt>bar<xt></string></xt> 061 * <xt></children></xt> 062 * <xt></object></xt> 063 * </p> 064 * 065 * <p> 066 * With the annotations, serializing this bean as XML produces the following... 067 * <p class='bcode w800'> 068 * <xt><object></xt> 069 * <xt><children></xt> 070 * <xt><child></xt>foo<xt></child></xt> 071 * <xt><child></xt>bar<xt></child></xt> 072 * <xt></children></xt> 073 * <xt></object></xt> 074 * </p> 075 */ 076 String childName() default ""; 077 078 /** 079 * The {@link XmlFormat} to use for serializing this object type. 080 * 081 * <h5 class='section'>Example:</h5> 082 * <p class='bcode w800'> 083 * <jk>public class</jk> MyBean { 084 * 085 * <jc>// Normally, bean properties would be rendered as child elements of the bean element.</jc> 086 * <jc>// Override so that it's rendered as a "f1='123'" attribute on the bean element instead.</jc> 087 * <ja>@Xml</ja>(format=XmlFormat.<jsf>ATTR</jsf>} 088 * <jk>public int</jk> f1 = 123; 089 * 090 * <jc>// Normally, bean URL properties would be rendered as XML attributes on the bean element.</jc> 091 * <jc>// Override so that it's rendered as an <href>http://foo</href> child element instead.</jc> 092 * <ja>@Beanp</ja>(uri=<jk>true</jk>) 093 * <ja>@Xml</ja>(format=XmlFormat.<jsf>ELEMENT</jsf>} 094 * <jk>public</jk> URL <jf>href</jf> = <jk>new</jk> URL(<js>"http://foo"</js>); 095 * 096 * <jc>// Normally, collection properties would be grouped under a single <children> child element on the bean element.</jc> 097 * <jc>// Override so that entries are directly children of the bean element with each entry having an element name of <child>.</jc> 098 * <ja>@Xml</ja>(format=XmlFormat.<jsf>COLLAPSED</jsf>, childName=<js>"child"</js>} 099 * <jk>public</jk> String[] <jf>children</jf> = <js>"foo"</js>,<js>"bar"</js>}; 100 * } 101 * </p> 102 * 103 * <p> 104 * Without the <ja>@Xml</ja> annotations, serializing this bean as XML would have produced the following... 105 * <p class='bcode w800'> 106 * <xt><object</xt> <xa>href</xa>=<js>'http://foo'</js><xt>></xt> 107 * <xt><f1></xt>123<xt></f1></xt> 108 * <xt><children></xt> 109 * <xt><string></xt>foo<xt></string></xt> 110 * <xt><string></xt>bar<xt></string></xt> 111 * <xt></children></xt> 112 * <xt></object></xt> 113 * </p> 114 * 115 * <p> 116 * With the annotations, serializing this bean as XML produces the following... 117 * <p class='bcode w800'> 118 * <xt><object</xt> <xa>f1</xa>=<js>'123'</js><xt>></xt> 119 * <xt><href></xt>http://foo<xt></href></xt> 120 * <xt><child></xt>foo<xt></child></xt> 121 * <xt><child></xt>bar<xt></child></xt> 122 * <xt></object></xt> 123 * </p> 124 */ 125 XmlFormat format() default XmlFormat.DEFAULT; 126 127 /** 128 * Sets the namespace URI of this property or class. 129 * 130 * <p> 131 * Must be matched with a {@link #prefix()} annotation on this object, a parent object, or a {@link XmlNs @XmlNs} with the 132 * same name through the {@link XmlSchema#xmlNs() @XmlSchema(xmlNs)} annotation on the package. 133 */ 134 String namespace() default ""; 135 136 /** 137 * Dynamically apply this annotation to the specified classes/methods/fields. 138 * 139 * <p> 140 * Used in conjunction with the {@link XmlConfig#applyXml()}. 141 * It is ignored when the annotation is applied directly to classes/methods/fields. 142 * 143 * <h5 class='section'>Valid patterns:</h5> 144 * <ul class='spaced-list'> 145 * <li>Classes: 146 * <ul> 147 * <li>Fully qualified: 148 * <ul> 149 * <li><js>"com.foo.MyClass"</js> 150 * </ul> 151 * <li>Fully qualified inner class: 152 * <ul> 153 * <li><js>"com.foo.MyClass$Inner1$Inner2"</js> 154 * </ul> 155 * <li>Simple: 156 * <ul> 157 * <li><js>"MyClass"</js> 158 * </ul> 159 * <li>Simple inner: 160 * <ul> 161 * <li><js>"MyClass$Inner1$Inner2"</js> 162 * <li><js>"Inner1$Inner2"</js> 163 * <li><js>"Inner2"</js> 164 * </ul> 165 * </ul> 166 * <li>Methods: 167 * <ul> 168 * <li>Fully qualified with args: 169 * <ul> 170 * <li><js>"com.foo.MyClass.myMethod(String,int)"</js> 171 * <li><js>"com.foo.MyClass.myMethod(java.lang.String,int)"</js> 172 * <li><js>"com.foo.MyClass.myMethod()"</js> 173 * </ul> 174 * <li>Fully qualified: 175 * <ul> 176 * <li><js>"com.foo.MyClass.myMethod"</js> 177 * </ul> 178 * <li>Simple with args: 179 * <ul> 180 * <li><js>"MyClass.myMethod(String,int)"</js> 181 * <li><js>"MyClass.myMethod(java.lang.String,int)"</js> 182 * <li><js>"MyClass.myMethod()"</js> 183 * </ul> 184 * <li>Simple: 185 * <ul> 186 * <li><js>"MyClass.myMethod"</js> 187 * </ul> 188 * <li>Simple inner class: 189 * <ul> 190 * <li><js>"MyClass$Inner1$Inner2.myMethod"</js> 191 * <li><js>"Inner1$Inner2.myMethod"</js> 192 * <li><js>"Inner2.myMethod"</js> 193 * </ul> 194 * </ul> 195 * <li>Fields: 196 * <ul> 197 * <li>Fully qualified: 198 * <ul> 199 * <li><js>"com.foo.MyClass.myField"</js> 200 * </ul> 201 * <li>Simple: 202 * <ul> 203 * <li><js>"MyClass.myField"</js> 204 * </ul> 205 * <li>Simple inner class: 206 * <ul> 207 * <li><js>"MyClass$Inner1$Inner2.myField"</js> 208 * <li><js>"Inner1$Inner2.myField"</js> 209 * <li><js>"Inner2.myField"</js> 210 * </ul> 211 * </ul> 212 * <li>A comma-delimited list of anything on this list. 213 * </ul> 214 * 215 * <ul class='seealso'> 216 * <li class='link'>{@doc DynamicallyAppliedAnnotations} 217 * </ul> 218 */ 219 String on() default ""; 220 221 /** 222 * Sets the XML prefix of this property or class. 223 * 224 * <ul class='spaced-list'> 225 * <li> 226 * When applied to a {@link ElementType#TYPE}, namespace is applied to all properties in the class, and all 227 * subclasses of the class. 228 * <li> 229 * When applied to bean properties on {@link ElementType#METHOD} and {@link ElementType#FIELD}, applies 230 * to the bean property. 231 * </ul> 232 * 233 * <p> 234 * Must either be matched to a {@link #namespace()} annotation on the same object, parent object, or a 235 * {@link XmlNs @XmlNs} with the same name through the {@link XmlSchema#xmlNs() @XmlSchema(xmlNs)} annotation on the package. 236 */ 237 String prefix() default ""; 238}