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.parser.annotation; 014 015import static java.lang.annotation.ElementType.*; 016import static java.lang.annotation.RetentionPolicy.*; 017 018import java.lang.annotation.*; 019import java.nio.charset.*; 020 021import org.apache.juneau.*; 022import org.apache.juneau.annotation.*; 023import org.apache.juneau.html.*; 024import org.apache.juneau.json.*; 025import org.apache.juneau.msgpack.*; 026import org.apache.juneau.parser.*; 027import org.apache.juneau.uon.*; 028import org.apache.juneau.xml.*; 029 030/** 031 * Annotation for specifying config properties defined in {@link Parser}, {@link InputStreamParser}, and {@link ReaderParser}. 032 * 033 * <p> 034 * Used primarily for specifying bean configuration properties on REST classes and methods. 035 * 036 * <h5 class='section'>See Also:</h5><ul> 037 * <li class='link'><a class="doclink" href="../../../../../index.html#jm.SerializersAndParsers">Serializers and Parsers</a> 038 * </ul> 039 */ 040@Target({TYPE,METHOD}) 041@Retention(RUNTIME) 042@Inherited 043@ContextApply({ParserConfigAnnotation.ParserApply.class,ParserConfigAnnotation.InputStreamParserApply.class,ParserConfigAnnotation.ReaderParserApply.class}) 044public @interface ParserConfig { 045 046 /** 047 * Optional rank for this config. 048 * 049 * <p> 050 * Can be used to override default ordering and application of config annotations. 051 * 052 * @return The annotation value. 053 */ 054 int rank() default 0; 055 056 //------------------------------------------------------------------------------------------------------------------- 057 // InputStreamParser 058 //------------------------------------------------------------------------------------------------------------------- 059 060 /** 061 * Binary input format. 062 * 063 * <p> 064 * When using the {@link Parser#parse(Object,Class)} method on stream-based parsers and the input is a string, this defines the format to use 065 * when converting the string into a byte array. 066 * 067 * <ul class='values'> 068 * <li><js>"SPACED_HEX"</js> 069 * <li><js>"HEX"</js> (default) 070 * <li><js>"BASE64"</js> 071 * </ul> 072 * 073 * <h5 class='section'>Notes:</h5><ul> 074 * <li class='note'> 075 * Supports <a class="doclink" href="../../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 076 * </ul> 077 * 078 * <h5 class='section'>See Also:</h5><ul> 079 * <li class='jm'>{@link org.apache.juneau.parser.InputStreamParser.Builder#binaryFormat(BinaryFormat)} 080 * </ul> 081 * 082 * @return The annotation value. 083 */ 084 String binaryFormat() default ""; 085 086 //------------------------------------------------------------------------------------------------------------------- 087 // Parser 088 //------------------------------------------------------------------------------------------------------------------- 089 090 /** 091 * Auto-close streams. 092 * 093 * <p> 094 * If <js>"true"</js>, <l>InputStreams</l> and <l>Readers</l> passed into parsers will be closed 095 * after parsing is complete. 096 * 097 * <ul class='values'> 098 * <li><js>"true"</js> 099 * <li><js>"false"</js> (default) 100 * </ul> 101 * 102 * <h5 class='section'>Notes:</h5><ul> 103 * <li class='note'> 104 * Supports <a class="doclink" href="../../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 105 * </ul> 106 * 107 * <h5 class='section'>See Also:</h5><ul> 108 * <li class='jm'>{@link org.apache.juneau.parser.Parser.Builder#autoCloseStreams()} 109 * </ul> 110 * 111 * @return The annotation value. 112 */ 113 String autoCloseStreams() default ""; 114 115 /** 116 * Debug output lines. 117 * 118 * <p> 119 * When parse errors occur, this specifies the number of lines of input before and after the 120 * error location to be printed as part of the exception message. 121 * 122 * <h5 class='section'>Notes:</h5><ul> 123 * <li class='note'> 124 * Format: integer 125 * <li class='note'> 126 * Default: 5 127 * <li class='note'> 128 * Supports <a class="doclink" href="../../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 129 * </ul> 130 * 131 * <h5 class='section'>See Also:</h5><ul> 132 * <li class='jm'>{@link org.apache.juneau.parser.Parser.Builder#debugOutputLines(int)} 133 * </ul> 134 * 135 * @return The annotation value. 136 */ 137 String debugOutputLines() default ""; 138 139 /** 140 * Parser listener. 141 * 142 * <p> 143 * Class used to listen for errors and warnings that occur during parsing. 144 * 145 * <h5 class='section'>See Also:</h5><ul> 146 * <li class='jm'>{@link org.apache.juneau.parser.Parser.Builder#listener(Class)} 147 * </ul> 148 * 149 * @return The annotation value. 150 */ 151 Class<? extends ParserListener> listener() default ParserListener.Void.class; 152 153 /** 154 * Strict mode. 155 * 156 * <p> 157 * If <js>"true"</js>, strict mode for the parser is enabled. 158 * 159 * <p> 160 * Strict mode can mean different things for different parsers. 161 * 162 * <table class='styled'> 163 * <tr><th>Parser class</th><th>Strict behavior</th></tr> 164 * <tr> 165 * <td>All reader-based parsers</td> 166 * <td> 167 * When enabled, throws {@link ParseException ParseExceptions} on malformed charset input. 168 * Otherwise, malformed input is ignored. 169 * </td> 170 * </tr> 171 * <tr> 172 * <td>{@link JsonParser}</td> 173 * <td> 174 * When enabled, throws exceptions on the following invalid JSON syntax: 175 * <ul> 176 * <li>Unquoted attributes. 177 * <li>Missing attribute values. 178 * <li>Concatenated strings. 179 * <li>Javascript comments. 180 * <li>Numbers and booleans when Strings are expected. 181 * <li>Numbers valid in Java but not JSON (e.g. octal notation, etc...) 182 * </ul> 183 * </td> 184 * </tr> 185 * </table> 186 * 187 * <ul class='values'> 188 * <li><js>"true"</js> 189 * <li><js>"false"</js> (default) 190 * </ul> 191 * 192 * <h5 class='section'>Notes:</h5><ul> 193 * <li class='note'> 194 * Supports <a class="doclink" href="../../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 195 * </ul> 196 * 197 * <h5 class='section'>See Also:</h5><ul> 198 * <li class='jm'>{@link org.apache.juneau.parser.Parser.Builder#strict()} 199 * </ul> 200 * 201 * @return The annotation value. 202 */ 203 String strict() default ""; 204 205 /** 206 * Trim parsed strings. 207 * 208 * <p> 209 * If <js>"true"</js>, string values will be trimmed of whitespace using {@link String#trim()} before being added to 210 * the POJO. 211 * 212 * <ul class='values'> 213 * <li><js>"true"</js> 214 * <li><js>"false"</js> (default) 215 * </ul> 216 * 217 * <h5 class='section'>Notes:</h5><ul> 218 * <li class='note'> 219 * Supports <a class="doclink" href="../../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 220 * </ul> 221 * 222 * <h5 class='section'>See Also:</h5><ul> 223 * <li class='jm'>{@link org.apache.juneau.parser.Parser.Builder#trimStrings()} 224 * </ul> 225 * 226 * @return The annotation value. 227 */ 228 String trimStrings() default ""; 229 230 /** 231 * Unbuffered. 232 * 233 * <p> 234 * If <js>"true"</js>, don't use internal buffering during parsing. 235 * 236 * <p> 237 * This is useful in cases when you want to parse the same input stream or reader multiple times 238 * because it may contain multiple independent POJOs to parse. 239 * <br>Buffering would cause the parser to read past the current POJO in the stream. 240 * 241 * <ul class='values'> 242 * <li><js>"true"</js> 243 * <li><js>"false"</js> (default) 244 * </ul> 245 * 246 * <h5 class='section'>Notes:</h5><ul> 247 * <li class='note'> 248 * This only allows for multi-input streams for the following parsers: 249 * <ul> 250 * <li class='jc'>{@link JsonParser} 251 * <li class='jc'>{@link UonParser} 252 * </ul> 253 * It has no effect on the following parsers: 254 * <ul> 255 * <li class='jc'>{@link MsgPackParser} - It already doesn't use buffering. 256 * <li class='jc'>{@link XmlParser}, {@link HtmlParser} - These use StAX which doesn't allow for more than one root element anyway. 257 * <li>RDF parsers - These read everything into an internal model before any parsing begins. 258 * </ul> 259 * <li class='note'> 260 * Supports <a class="doclink" href="../../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 261 * </ul> 262 * 263 * <h5 class='section'>See Also:</h5><ul> 264 * <li class='jm'>{@link org.apache.juneau.parser.Parser.Builder#unbuffered()} 265 * </ul> 266 * 267 * @return The annotation value. 268 */ 269 String unbuffered() default ""; 270 271 //------------------------------------------------------------------------------------------------------------------- 272 // ReaderParser 273 //------------------------------------------------------------------------------------------------------------------- 274 275 /** 276 * File charset. 277 * 278 * <p> 279 * The character set to use for reading <c>Files</c> from the file system. 280 * 281 * <p> 282 * Used when passing in files to {@link Parser#parse(Object, Class)}. 283 * 284 * <h5 class='section'>Notes:</h5><ul> 285 * <li class='note'> 286 * <js>"DEFAULT"</js> can be used to indicate the JVM default file system charset. 287 * <li class='note'> 288 * Supports <a class="doclink" href="../../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 289 * </ul> 290 * 291 * <h5 class='section'>See Also:</h5><ul> 292 * <li class='jm'>{@link org.apache.juneau.parser.ReaderParser.Builder#fileCharset(Charset)} 293 * </ul> 294 * 295 * @return The annotation value. 296 */ 297 String fileCharset() default ""; 298 299 /** 300 * Input stream charset. 301 * 302 * <p> 303 * The character set to use for converting <c>InputStreams</c> and byte arrays to readers. 304 * 305 * <p> 306 * Used when passing in input streams and byte arrays to {@link Parser#parse(Object, Class)}. 307 * 308 * <h5 class='section'>Notes:</h5><ul> 309 * <li class='note'> 310 * <js>"DEFAULT"</js> can be used to indicate the JVM default file system charset. 311 * <li class='note'> 312 * Supports <a class="doclink" href="../../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 313 * </ul> 314 * 315 * <h5 class='section'>See Also:</h5><ul> 316 * <li class='jm'>{@link org.apache.juneau.parser.ReaderParser.Builder#streamCharset(Charset)} 317 * </ul> 318 * 319 * @return The annotation value. 320 */ 321 String streamCharset() default ""; 322}