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