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