001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.juneau.marshall.xml; 018 019import static java.lang.annotation.ElementType.*; 020import static java.lang.annotation.RetentionPolicy.*; 021 022import java.lang.annotation.*; 023 024/** 025 * Annotation for specifying various XML options for the XML and RDF/XML serializers. 026 * 027 * <p> 028 * Can be used in the following locations: 029 * <ul> 030 * <li>Marshalled classes/methods/fields/packages. 031 * <li><ja>@Rest</ja>-annotated classes and <ja>@RestOp</ja>-annotated methods when used with {@link XmlApply @XmlApply}. 032 * </ul> 033 * 034 * <p> 035 * Can be used for the following: 036 * <ul> 037 * <li>Override the child element name on the XML representation of collection or array properties. 038 * <li>Specify the XML namespace on a package, class, or method. 039 * <li>Override the XML format on a POJO. 040 * </ul> 041 * 042 * <h5 class='section'>See Also:</h5><ul> 043 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/XmlSupport">XML</a> 044 * </ul> 045 */ 046@Documented 047@Target({ TYPE, FIELD, METHOD }) 048@Retention(RUNTIME) 049@Inherited 050public @interface Xml { 051 052 /** 053 * Sets the name of the XML child elements for bean properties of type collection and array. 054 * 055 * <p> 056 * Applies only to collection and array bean properties. 057 * 058 * <h5 class='section'>Example:</h5> 059 * <p class='bjava'> 060 * <jk>public class</jk> MyBean { 061 * <ja>@Xml</ja>(childName=<js>"child"</js>} 062 * <jk>public</jk> String[] <jf>children</jf> = {<js>"foo"</js>,<js>"bar"</js>}; 063 * } 064 * </p> 065 * 066 * <p> 067 * Without the <ja>@Xml</ja> annotation, serializing this bean as XML would have produced the following... 068 * <p class='bxml'> 069 * <xt><object></xt> 070 * <xt><children></xt> 071 * <xt><string></xt>foo<xt></string></xt> 072 * <xt><string></xt>bar<xt></string></xt> 073 * <xt></children></xt> 074 * <xt></object></xt> 075 * </p> 076 * 077 * <p> 078 * With the annotations, serializing this bean as XML produces the following... 079 * <p class='bxml'> 080 * <xt><object></xt> 081 * <xt><children></xt> 082 * <xt><child></xt>foo<xt></child></xt> 083 * <xt><child></xt>bar<xt></child></xt> 084 * <xt></children></xt> 085 * <xt></object></xt> 086 * </p> 087 * 088 * @return The annotation value. 089 */ 090 String childName() default ""; 091 092 /** 093 * Optional description for the exposed API. 094 * 095 * @return The annotation value. 096 * @since 9.2.0 097 */ 098 String[] description() default {}; 099 100 /** 101 * The {@link XmlFormat} to use for serializing this object type. 102 * 103 * <h5 class='section'>Example:</h5> 104 * <p class='bjava'> 105 * <jk>public class</jk> MyBean { 106 * 107 * <jc>// Normally, bean properties would be rendered as child elements of the bean element.</jc> 108 * <jc>// Override so that it's rendered as a "f1='123'" attribute on the bean element instead.</jc> 109 * <ja>@Xml</ja>(format=XmlFormat.<jsf>ATTR</jsf>} 110 * <jk>public int</jk> <jf>f1</jf> = 123; 111 * 112 * <jc>// Normally, bean URL properties would be rendered as XML attributes on the bean element.</jc> 113 * <jc>// Override so that it's rendered as an <href>http://foo</href> child element instead.</jc> 114 * <ja>@BeanProp</ja>(uri=<jk>true</jk>) 115 * <ja>@Xml</ja>(format=XmlFormat.<jsf>ELEMENT</jsf>} 116 * <jk>public</jk> URL <jf>href</jf> = <jk>new</jk> URL(<js>"http://foo"</js>); 117 * 118 * <jc>// Normally, collection properties would be grouped under a single <children> child element on the bean element.</jc> 119 * <jc>// Override so that entries are directly children of the bean element with each entry having an element name of <child>.</jc> 120 * <ja>@Xml</ja>(format=XmlFormat.<jsf>COLLAPSED</jsf>, childName=<js>"child"</js>} 121 * <jk>public</jk> String[] <jf>children</jf> = <js>"foo"</js>,<js>"bar"</js>}; 122 * } 123 * </p> 124 * 125 * <p> 126 * Without the <ja>@Xml</ja> annotations, serializing this bean as XML would have produced the following... 127 * <p class='bxml'> 128 * <xt><object</xt> <xa>href</xa>=<js>'http://foo'</js><xt>></xt> 129 * <xt><f1></xt>123<xt></f1></xt> 130 * <xt><children></xt> 131 * <xt><string></xt>foo<xt></string></xt> 132 * <xt><string></xt>bar<xt></string></xt> 133 * <xt></children></xt> 134 * <xt></object></xt> 135 * </p> 136 * 137 * <p> 138 * With the annotations, serializing this bean as XML produces the following... 139 * <p class='bxml'> 140 * <xt><object</xt> <xa>f1</xa>=<js>'123'</js><xt>></xt> 141 * <xt><href></xt>http://foo<xt></href></xt> 142 * <xt><child></xt>foo<xt></child></xt> 143 * <xt><child></xt>bar<xt></child></xt> 144 * <xt></object></xt> 145 * </p> 146 * 147 * @return The annotation value. 148 */ 149 XmlFormat format() default XmlFormat.DEFAULT; 150 151 /** 152 * Sets the namespace URI of this property or class. 153 * 154 * <p> 155 * Must be matched with a {@link #prefix()} annotation on this object, a parent object, or a {@link XmlNs @XmlNs} with the 156 * same name through the {@link XmlSchema#xmlNs() @XmlSchema(xmlNs)} annotation on the package. 157 * 158 * @return The annotation value. 159 */ 160 String namespace() default ""; 161 162 /** 163 * Sets the XML prefix of this property or class. 164 * 165 * <ul class='spaced-list'> 166 * <li> 167 * When applied to a {@link ElementType#TYPE}, namespace is applied to all properties in the class, and all 168 * subclasses of the class. 169 * <li> 170 * When applied to bean properties on {@link ElementType#METHOD} and {@link ElementType#FIELD}, applies 171 * to the bean property. 172 * </ul> 173 * 174 * <p> 175 * Must either be matched to a {@link #namespace()} annotation on the same object, parent object, or a 176 * {@link XmlNs @XmlNs} with the same name through the {@link XmlSchema#xmlNs() @XmlSchema(xmlNs)} annotation on the package. 177 * 178 * @return The annotation value. 179 */ 180 String prefix() default ""; 181}