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