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}