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