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.parser;
018
019import static java.lang.annotation.ElementType.*;
020import static java.lang.annotation.RetentionPolicy.*;
021
022import java.lang.annotation.*;
023import java.nio.charset.*;
024
025import org.apache.juneau.marshall.*;
026import org.apache.juneau.marshall.html.*;
027import org.apache.juneau.marshall.json.*;
028import org.apache.juneau.marshall.msgpack.*;
029import org.apache.juneau.marshall.uon.*;
030import org.apache.juneau.marshall.xml.*;
031
032/**
033 * Annotation for specifying config properties defined in {@link Parser}, {@link InputStreamParser}, and {@link ReaderParser}.
034 *
035 * <p>
036 * Used primarily for specifying bean configuration properties on REST classes and methods.
037 *
038 * <h2 class='section'>See Also:</h2><ul>
039 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SerializersAndParsers">Serializers and Parsers</a>
040 * </ul>
041 */
042@Target({ TYPE, METHOD })
043@Retention(RUNTIME)
044@Inherited
045@ContextApply({ ParserConfigAnnotation.ParserApply.class, ParserConfigAnnotation.InputStreamParserApply.class, ParserConfigAnnotation.ReaderParserApply.class })
046public @interface ParserConfig {
047
048   /**
049    * Auto-close streams.
050    *
051    * <p>
052    * If <js>"true"</js>, <l>InputStreams</l> and <l>Readers</l> passed into parsers will be closed
053    * after parsing is complete.
054    *
055    * <ul class='values'>
056    *    <li><js>"true"</js>
057    *    <li><js>"false"</js> (default)
058    * </ul>
059    *
060    * <h4 class='section'>Notes:</h4><ul>
061    *    <li class='note'>
062    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"${C:myConfigVar}"</js>).
063    * </ul>
064    *
065    * <h4 class='section'>See Also:</h4><ul>
066    *    <li class='jm'>{@link Parser.Builder#autoCloseStreams()}
067    * </ul>
068    *
069    * @return The annotation value.
070    */
071   String autoCloseStreams() default "";
072
073   /**
074    * Binary input format.
075    *
076    * <p>
077    * When using the {@link Parser#read(Object,Class)} method on stream-based parsers and the input is a string, this defines the format to use
078    * when converting the string into a byte array.
079    *
080    * <ul class='values'>
081    *    <li><js>"SPACED_HEX"</js>
082    *    <li><js>"HEX"</js> (default)
083    *    <li><js>"BASE64"</js>
084    * </ul>
085    *
086    * <h4 class='section'>Notes:</h4><ul>
087    *    <li class='note'>
088    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"${C:myConfigVar}"</js>).
089    * </ul>
090    *
091    * <h4 class='section'>See Also:</h4><ul>
092    *    <li class='jm'>{@link InputStreamParser.Builder#binaryFormat(BinaryFormat)}
093    * </ul>
094    *
095    * @return The annotation value.
096    */
097   String binaryFormat() default "";
098
099   /**
100    * Debug output lines.
101    *
102    * <p>
103    * When parse errors occur, this specifies the number of lines of input before and after the
104    * error location to be printed as part of the exception message.
105    *
106    * <h4 class='section'>Notes:</h4><ul>
107    *    <li class='note'>
108    *       Format: integer
109    *    <li class='note'>
110    *       Default: 5
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    * <h4 class='section'>See Also:</h4><ul>
116    *    <li class='jm'>{@link Parser.Builder#debugOutputLines(int)}
117    * </ul>
118    *
119    * @return The annotation value.
120    */
121   String debugOutputLines() default "";
122
123   /**
124    * Parser listener.
125    *
126    * <p>
127    * Class used to listen for errors and warnings that occur during parsing.
128    *
129    * <h4 class='section'>See Also:</h4><ul>
130    *    <li class='jm'>{@link Parser.Builder#listener(Class)}
131    * </ul>
132    *
133    * @return The annotation value.
134    */
135   Class<? extends ParserListener> listener() default ParserListener.Void.class;
136
137   /**
138    * Optional rank for this config.
139    *
140    * <p>
141    * Can be used to override default ordering and application of config annotations.
142    *
143    * @return The annotation value.
144    */
145   int rank() default 0;
146
147   /**
148    * Input stream charset.
149    *
150    * <p>
151    * The character set to use for converting <c>InputStreams</c> and byte arrays to readers.
152    *
153    * <p>
154    * Used when passing in input streams and byte arrays to {@link Parser#read(Object, Class)}.
155    *
156    * <h4 class='section'>Notes:</h4><ul>
157    *    <li class='note'>
158    *       <js>"DEFAULT"</js> can be used to indicate the JVM default file system charset.
159    *    <li class='note'>
160    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"${C:myConfigVar}"</js>).
161    * </ul>
162    *
163    * <h4 class='section'>See Also:</h4><ul>
164    *    <li class='jm'>{@link ReaderParser.Builder#streamCharset(Charset)}
165    * </ul>
166    *
167    * @return The annotation value.
168    */
169   String streamCharset() default "";
170
171   /**
172    * Trim parsed strings.
173    *
174    * <p>
175    * If <js>"true"</js>, string values will be trimmed of whitespace using {@link String#trim()} before being added to
176    * the POJO.
177    *
178    * <ul class='values'>
179    *    <li><js>"true"</js>
180    *    <li><js>"false"</js> (default)
181    * </ul>
182    *
183    * <h4 class='section'>Notes:</h4><ul>
184    *    <li class='note'>
185    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"${C:myConfigVar}"</js>).
186    * </ul>
187    *
188    * <h4 class='section'>See Also:</h4><ul>
189    *    <li class='jm'>{@link Parser.Builder#trimStrings()}
190    * </ul>
191    *
192    * @return The annotation value.
193    */
194   String trimStrings() default "";
195
196   /**
197    * Include input snippet in parse errors.
198    *
199    * <p>
200    * When <js>"true"</js>, {@link ParseException} messages include the lines of input around the error location.
201    * Off by default; debug mode alone does not enable it.
202    *
203    * <h4 class='section'>Notes:</h4><ul>
204    *    <li class='note'>
205    *       Format: boolean
206    *    <li class='note'>
207    *       Default: false
208    *    <li class='note'>
209    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"${C:myConfigVar}"</js>).
210    * </ul>
211    *
212    * <h4 class='section'>See Also:</h4><ul>
213    *    <li class='jm'>{@link Parser.Builder#includeInputInErrors()}
214    * </ul>
215    *
216    * @return The annotation value.
217    */
218   String includeInputInErrors() default "";
219
220   /**
221    * Default per-property null-coercion policy applied during parsing.
222    *
223    * <p>
224    * Juneau's analog of Jackson's <c>JsonSetter.Value.forValueNulls(...)</c> at the
225    * <c>ObjectMapper</c> level.  Applied as the fallback when no per-property
226    * {@link MarshalledProp#nulls() @MarshalledProp(nulls=…)} is configured.
227    *
228    * <ul class='values'>
229    *    <li><js>"LEAVE"</js> (default) — pass {@code null} through unchanged.
230    *    <li><js>"EMPTY"</js> — substitute the type's empty value (empty {@link String}/{@link java.util.Collection}/
231    *       {@link java.util.Map}, primitive default for primitives, {@code Optional.empty()} for {@link java.util.Optional}).
232    *    <li><js>"DEFAULT"</js> — substitute the bean-constructed default for the property.
233    *    <li><js>"SKIP"</js> — do not call the setter at all.
234    * </ul>
235    *
236    * <h4 class='section'>Notes:</h4><ul>
237    *    <li class='note'>
238    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"${C:myConfigVar}"</js>).
239    * </ul>
240    *
241    * <h4 class='section'>See Also:</h4><ul>
242    *    <li class='jm'>{@link Parser.Builder#nulls(Nulls)}
243    * </ul>
244    *
245    * @return The annotation value.
246    * @since 10.0.0
247    */
248   String nulls() default "";
249
250   /**
251    * Unbuffered.
252    *
253    * <p>
254    * If <js>"true"</js>, don't use internal buffering during parsing.
255    *
256    * <p>
257    * This is useful in cases when you want to parse the same input stream or reader multiple times
258    * because it may contain multiple independent POJOs to parse.
259    * <br>Buffering would cause the parser to read past the current POJO in the stream.
260    *
261    * <ul class='values'>
262    *    <li><js>"true"</js>
263    *    <li><js>"false"</js> (default)
264    * </ul>
265    *
266    * <h4 class='section'>Notes:</h4><ul>
267    *    <li class='note'>
268    *       This only allows for multi-input streams for the following parsers:
269    *       <ul>
270    *          <li class='jc'>{@link JsonParser}
271    *          <li class='jc'>{@link UonParser}
272    *       </ul>
273    *       It has no effect on the following parsers:
274    *       <ul>
275    *          <li class='jc'>{@link MsgPackParser} - It already doesn't use buffering.
276    *          <li class='jc'>{@link XmlParser}, {@link HtmlParser} - These use StAX which doesn't allow for more than one root element anyway.
277    *          <li>RDF parsers - These read everything into an internal model before any parsing begins.
278    *       </ul>
279    *    <li class='note'>
280    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"${C:myConfigVar}"</js>).
281    * </ul>
282    *
283    * <h4 class='section'>See Also:</h4><ul>
284    *    <li class='jm'>{@link Parser.Builder#unbuffered()}
285    * </ul>
286    *
287    * @return The annotation value.
288    */
289   String unbuffered() default "";
290}