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.uon.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.serializer.*;
022import org.apache.juneau.uon.*;
023import org.apache.juneau.urlencoding.*;
024
025/**
026 * Annotation for specifying config properties defined in {@link UonSerializer} and {@link UonParser}.
027 *
028 * <p>
029 * Used primarily for specifying bean configuration properties on REST classes and methods.
030 *
031 * <h5 class='section'>See Also:</h5><ul>
032 *    <li class='link'><a class="doclink" href="../../../../../index.html#jm.UonDetails">UON Details</a>
033 * </ul>
034 */
035@Target({TYPE,METHOD})
036@Retention(RUNTIME)
037@Inherited
038@ContextApply({UonConfigAnnotation.SerializerApply.class,UonConfigAnnotation.ParserApply.class})
039public @interface UonConfig {
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    * @return The annotation value.
048    */
049   int rank() default 0;
050
051   //-------------------------------------------------------------------------------------------------------------------
052   // UonCommon
053   //-------------------------------------------------------------------------------------------------------------------
054
055   //-------------------------------------------------------------------------------------------------------------------
056   // UonParser
057   //-------------------------------------------------------------------------------------------------------------------
058
059   /**
060    * Decode <js>"%xx"</js> sequences.
061    *
062    * <p>
063    * Specify <js>"true"</js> if URI encoded characters should be decoded, <js>"false"</js> if they've already been decoded
064    * before being passed to this parser.
065    *
066    * <ul class='values'>
067    *    <li><js>"true"</js> (default for {@link UrlEncodingParser})
068    *    <li><js>"false"</js> (default for {@link UonParser})
069    * </ul>
070    *
071    * <h5 class='section'>Notes:</h5><ul>
072    *    <li class='note'>
073    *       Supports <a class="doclink" href="../../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
074    * </ul>
075    *
076    * <h5 class='section'>See Also:</h5><ul>
077    *    <li class='jm'>{@link org.apache.juneau.uon.UonParser.Builder#decoding()}
078    * </ul>
079    *
080    * @return The annotation value.
081    */
082   String decoding() default "";
083
084   /**
085    * Validate end.
086    *
087    * <p>
088    * If <js>"true"</js>, after parsing a POJO from the input, verifies that the remaining input in
089    * the stream consists of only comments or whitespace.
090    *
091    * <ul class='values'>
092    *    <li><js>"true"</js>
093    *    <li><js>"false"</js> (default)
094    * </ul>
095    *
096    * <h5 class='section'>Notes:</h5><ul>
097    *    <li class='note'>
098    *       Supports <a class="doclink" href="../../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
099    * </ul>
100
101    * <h5 class='section'>See Also:</h5><ul>
102    *    <li class='jm'>{@link org.apache.juneau.uon.UonParser.Builder#validateEnd()}
103    * </ul>
104    *
105    * @return The annotation value.
106    */
107   String validateEnd() default "";
108
109   //-------------------------------------------------------------------------------------------------------------------
110   // UonSerializer
111   //-------------------------------------------------------------------------------------------------------------------
112
113   /**
114    * Add <js>"_type"</js> properties when needed.
115    *
116    * <p>
117    * If <js>"true"</js>, then <js>"_type"</js> properties will be added to beans if their type cannot be inferred
118    * through reflection.
119    *
120    * <p>
121    * When present, this value overrides the {@link org.apache.juneau.serializer.Serializer.Builder#addBeanTypes()} setting and is
122    * provided to customize the behavior of specific serializers in a {@link SerializerSet}.
123    *
124    * <ul class='values'>
125    *    <li><js>"true"</js>
126    *    <li><js>"false"</js> (default)
127    * </ul>
128    *
129    * <h5 class='section'>Notes:</h5><ul>
130    *    <li class='note'>
131    *       Supports <a class="doclink" href="../../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
132    * </ul>
133    *
134    * <h5 class='section'>See Also:</h5><ul>
135    *    <li class='jm'>{@link org.apache.juneau.uon.UonSerializer.Builder#addBeanTypesUon()}
136    * </ul>
137    *
138    * @return The annotation value.
139    */
140   String addBeanTypes() default "";
141
142   /**
143    * Encode non-valid URI characters.
144    *
145    * <p>
146    * Encode non-valid URI characters with <js>"%xx"</js> constructs.
147    *
148    * <p>
149    * If <js>"true"</js>, non-valid URI characters will be converted to <js>"%xx"</js> sequences.
150    * <br>Set to <js>"false"</js> if parameter value is being passed to some other code that will already perform
151    * URL-encoding of non-valid URI characters.
152    *
153    * <ul class='values'>
154    *    <li><js>"true"</js> (default for {@link UrlEncodingSerializer})
155    *    <li><js>"false"</js> (default for {@link UonSerializer})
156    * </ul>
157    *
158    * <h5 class='section'>Notes:</h5><ul>
159    *    <li class='note'>
160    *       Supports <a class="doclink" href="../../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
161    * </ul>
162    *
163    * <h5 class='section'>See Also:</h5><ul>
164    *    <li class='jm'>{@link org.apache.juneau.uon.UonSerializer.Builder#encoding()}
165    * </ul>
166    *
167    * @return The annotation value.
168    */
169   String encoding() default "";
170
171   /**
172    * Format to use for query/form-data/header values.
173    *
174    * <p>
175    * Specifies the format to use for URL GET parameter keys and values.
176    *
177    * <ul class='values'>
178    *    <li><js>"UON"</js> (default) - Use UON notation for parameters.
179    *    <li><js>"PLAINTEXT"</js> - Use plain text for parameters.
180    * </ul>
181    *
182    * <h5 class='section'>Notes:</h5><ul>
183    *    <li class='note'>
184    *       Supports <a class="doclink" href="../../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
185    * </ul>
186    *
187    * <h5 class='section'>See Also:</h5><ul>
188    *    <li class='jm'>{@link org.apache.juneau.uon.UonSerializer.Builder#paramFormat(ParamFormat)}
189    * </ul>
190    *
191    * @return The annotation value.
192    */
193   String paramFormat() default "";
194}