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