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