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