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