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