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