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.xml.annotation; 018 019import static java.lang.annotation.ElementType.*; 020import static java.lang.annotation.RetentionPolicy.*; 021 022import java.lang.annotation.*; 023 024import javax.xml.stream.*; 025import javax.xml.stream.util.*; 026 027import org.apache.juneau.annotation.*; 028import org.apache.juneau.collections.*; 029import org.apache.juneau.serializer.*; 030import org.apache.juneau.xml.*; 031 032/** 033 * Annotation for specifying config properties defined in {@link XmlSerializer}, {@link XmlDocSerializer}, and {@link XmlParser}. 034 * 035 * <p> 036 * Used primarily for specifying bean configuration properties on REST classes and methods. 037 * 038 * <h5 class='section'>See Also:</h5><ul> 039 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/XmlBasics">XML Basics</a> 040 * </ul> 041 */ 042@Target({TYPE,METHOD}) 043@Retention(RUNTIME) 044@Inherited 045@ContextApply({XmlConfigAnnotation.SerializerApply.class,XmlConfigAnnotation.ParserApply.class}) 046public @interface XmlConfig { 047 048 /** 049 * Optional rank for this config. 050 * 051 * <p> 052 * Can be used to override default ordering and application of config annotations. 053 * 054 * @return The annotation value. 055 */ 056 int rank() default 0; 057 058 //------------------------------------------------------------------------------------------------------------------- 059 // XmlCommon 060 //------------------------------------------------------------------------------------------------------------------- 061 062 //------------------------------------------------------------------------------------------------------------------- 063 // XmlParser 064 //------------------------------------------------------------------------------------------------------------------- 065 066 /** 067 * XML event allocator. 068 * 069 * <p> 070 * Associates an {@link XMLEventAllocator} with this parser. 071 * 072 * <h5 class='section'>See Also:</h5><ul> 073 * <li class='jm'>{@link org.apache.juneau.xml.XmlParser.Builder#eventAllocator(Class)} 074 * </ul> 075 * 076 * @return The annotation value. 077 */ 078 Class<? extends XMLEventAllocator> eventAllocator() default XmlEventAllocator.Void.class; 079 080 /** 081 * Preserve root element during generalized parsing. 082 * 083 * <p> 084 * If <js>"true"</js>, when parsing into a generic {@link JsonMap}, the map will contain a single entry whose key 085 * is the root element name. 086 * 087 * <ul class='values'> 088 * <li><js>"true"</js> 089 * <li><js>"false"</js> (default) 090 * </ul> 091 * 092 * <h5 class='section'>Notes:</h5><ul> 093 * <li class='note'> 094 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 095 * </ul> 096 * 097 * <h5 class='section'>See Also:</h5><ul> 098 * <li class='jm'>{@link org.apache.juneau.xml.XmlParser.Builder#preserveRootElement()} 099 * </ul> 100 * 101 * @return The annotation value. 102 */ 103 String preserveRootElement() default ""; 104 105 /** 106 * XML reporter. 107 * 108 * <p> 109 * Associates an {@link XMLReporter} with this parser. 110 * 111 * <h5 class='section'>Notes:</h5><ul> 112 * <li class='note'> 113 * Reporters are not copied to new parsers during a clone. 114 * </ul> 115 * 116 * <h5 class='section'>See Also:</h5><ul> 117 * <li class='jm'>{@link org.apache.juneau.xml.XmlParser.Builder#reporter(Class)} 118 * </ul> 119 * 120 * @return The annotation value. 121 */ 122 Class<? extends XMLReporter> reporter() default XmlReporter.Void.class; 123 124 /** 125 * XML resolver. 126 * 127 * <p> 128 * Associates an {@link XMLResolver} with this parser. 129 * 130 * <h5 class='section'>See Also:</h5><ul> 131 * <li class='jm'>{@link org.apache.juneau.xml.XmlParser.Builder#resolver(Class)} 132 * </ul> 133 * 134 * @return The annotation value. 135 */ 136 Class<? extends XMLResolver> resolver() default XmlResolver.Void.class; 137 138 /** 139 * Enable validation. 140 * 141 * <p> 142 * If <js>"true"</js>, XML document will be validated. 143 * 144 * <p> 145 * See {@link XMLInputFactory#IS_VALIDATING} for more info. 146 * 147 * <ul class='values'> 148 * <li><js>"true"</js> 149 * <li><js>"false"</js> (default) 150 * </ul> 151 * 152 * <h5 class='section'>Notes:</h5><ul> 153 * <li class='note'> 154 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 155 * </ul> 156 * 157 * <h5 class='section'>See Also:</h5><ul> 158 * <li class='jm'>{@link org.apache.juneau.xml.XmlParser.Builder#validating()} 159 * </ul> 160 * 161 * @return The annotation value. 162 */ 163 String validating() default ""; 164 165 //------------------------------------------------------------------------------------------------------------------- 166 // XmlSerializer 167 //------------------------------------------------------------------------------------------------------------------- 168 169 /** 170 * Add <js>"_type"</js> properties when needed. 171 * 172 * <p> 173 * If <js>"true"</js>, then <js>"_type"</js> properties will be added to beans if their type cannot be inferred 174 * through reflection. 175 * 176 * <p> 177 * When present, this value overrides the {@link org.apache.juneau.serializer.Serializer.Builder#addBeanTypes()} setting and is 178 * provided to customize the behavior of specific serializers in a {@link SerializerSet}. 179 * 180 * <ul class='values'> 181 * <li><js>"true"</js> 182 * <li><js>"false"</js> (default) 183 * </ul> 184 * 185 * <h5 class='section'>Notes:</h5><ul> 186 * <li class='note'> 187 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 188 * </ul> 189 * 190 * <h5 class='section'>See Also:</h5><ul> 191 * <li class='jm'>{@link org.apache.juneau.xml.XmlSerializer.Builder#addBeanTypesXml()} 192 * </ul> 193 * 194 * @return The annotation value. 195 */ 196 String addBeanTypes() default ""; 197 198 /** 199 * Add namespace URLs to the root element. 200 * 201 * <p> 202 * Use this setting to add {@code xmlns:x} attributes to the root element for the default and all mapped namespaces. 203 * 204 * <ul class='values'> 205 * <li><js>"true"</js> 206 * <li><js>"false"</js> (default) 207 * </ul> 208 * 209 * <h5 class='section'>Notes:</h5><ul> 210 * <li class='note'> 211 * This setting is ignored if {@link org.apache.juneau.xml.XmlSerializer.Builder#enableNamespaces()} is not enabled. 212 * <li class='note'> 213 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 214 * </ul> 215 * 216 * <h5 class='section'>See Also:</h5><ul> 217 * <li class='jm'>{@link org.apache.juneau.xml.XmlSerializer.Builder#addNamespaceUrisToRoot()} 218 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/XmlNamespaces">Namespaces</a> 219 * </ul> 220 * 221 * @return The annotation value. 222 */ 223 String addNamespaceUrisToRoot() default ""; 224 225 /** 226 * Don't auto-detect namespace usage. 227 * 228 * <p> 229 * Don't detect namespace usage before serialization. 230 * 231 * <p> 232 * Used in conjunction with {@link org.apache.juneau.xml.XmlSerializer.Builder#addNamespaceUrisToRoot()} to reduce the list of namespace URLs appended to the 233 * root element to only those that will be used in the resulting document. 234 * 235 * <p> 236 * If disabled, then the data structure will first be crawled looking for namespaces that will be encountered before 237 * the root element is serialized. 238 * 239 * <p> 240 * This setting is ignored if {@link org.apache.juneau.xml.XmlSerializer.Builder#enableNamespaces()} is not enabled. 241 * 242 * <ul class='values'> 243 * <li><js>"true"</js> 244 * <li><js>"false"</js> (default) 245 * </ul> 246 * 247 * <h5 class='section'>Notes:</h5><ul> 248 * <li class='warn'> 249 * Auto-detection of namespaces can be costly performance-wise. 250 * <br>In high-performance environments, it's recommended that namespace detection be 251 * disabled, and that namespaces be manually defined through the {@link org.apache.juneau.xml.XmlSerializer.Builder#namespaces(Namespace...)} property. 252 * <li class='note'> 253 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 254 * </ul> 255 * 256 * <h5 class='section'>See Also:</h5><ul> 257 * <li class='jm'>{@link org.apache.juneau.xml.XmlSerializer.Builder#disableAutoDetectNamespaces()} 258 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/XmlNamespaces">Namespaces</a> 259 * </ul> 260 * 261 * @return The annotation value. 262 */ 263 String disableAutoDetectNamespaces() default ""; 264 265 /** 266 * Default namespace. 267 * 268 * <p> 269 * Specifies the default namespace URI for this document. 270 * 271 * <h5 class='section'>Notes:</h5><ul> 272 * <li class='note'> 273 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 274 * </ul> 275 * 276 * <h5 class='section'>See Also:</h5><ul> 277 * <li class='jm'>{@link org.apache.juneau.xml.XmlSerializer.Builder#defaultNamespace(Namespace)} 278 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/XmlNamespaces">Namespaces</a> 279 * </ul> 280 * 281 * @return The annotation value. 282 */ 283 String defaultNamespace() default ""; 284 285 /** 286 * Enable support for XML namespaces. 287 * 288 * <p> 289 * If not enabled, XML output will not contain any namespaces regardless of any other settings. 290 * 291 * <ul class='values'> 292 * <li><js>"true"</js> 293 * <li><js>"false"</js> (default) 294 * </ul> 295 * 296 * <h5 class='section'>Notes:</h5><ul> 297 * <li class='note'> 298 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 299 * </ul> 300 * 301 * <h5 class='section'>See Also:</h5><ul> 302 * <li class='jm'>{@link org.apache.juneau.xml.XmlSerializer.Builder#enableNamespaces()} 303 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/XmlNamespaces">Namespaces</a> 304 * </ul> 305 * 306 * @return The annotation value. 307 */ 308 String enableNamespaces() default ""; 309 310 /** 311 * Default namespaces. 312 * 313 * <p> 314 * The default list of namespaces associated with this serializer. 315 * 316 * <h5 class='section'>Notes:</h5><ul> 317 * <li class='note'> 318 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 319 * </ul> 320 * 321 * <h5 class='section'>See Also:</h5><ul> 322 * <li class='jm'>{@link org.apache.juneau.xml.XmlSerializer.Builder#namespaces(Namespace...)} 323 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/XmlNamespaces">Namespaces</a> 324 * </ul> 325 * 326 * @return The annotation value. 327 */ 328 String[] namespaces() default {}; 329}