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