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.urlencoding.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.urlencoding.*;
022
023/**
024 * Annotation for specifying config properties defined in {@link UrlEncodingSerializer} and {@link UrlEncodingParser}.
025 *
026 * <p>
027 * Used primarily for specifying bean configuration properties on REST classes and methods.
028 *
029 * <h5 class='section'>See Also:</h5><ul>
030 *    <li class='link'><a class="doclink" href="../../../../../index.html#jm.UrlEncodingDetails">URL-Encoding Details</a>
031 * </ul>
032 */
033@Target({TYPE,METHOD})
034@Retention(RUNTIME)
035@Inherited
036@ContextApply({UrlEncodingConfigAnnotation.SerializerApply.class,UrlEncodingConfigAnnotation.ParserApply.class})
037public @interface UrlEncodingConfig {
038
039   /**
040    * Optional rank for this config.
041    *
042    * <p>
043    * Can be used to override default ordering and application of config annotations.
044    *
045    * @return The annotation value.
046    */
047   int rank() default 0;
048
049   //-------------------------------------------------------------------------------------------------------------------
050   // UrlEncodingCommon
051   //-------------------------------------------------------------------------------------------------------------------
052
053   //-------------------------------------------------------------------------------------------------------------------
054   // UrlEncodingSerializer
055   //-------------------------------------------------------------------------------------------------------------------
056
057   /**
058    * Parser bean property collections/arrays as separate key/value pairs.
059    *
060    * <p>
061    * This is the parser-side equivalent of the {@link org.apache.juneau.urlencoding.UrlEncodingSerializer.Builder#expandedParams()} setting.
062    *
063    * <p>
064    * If <js>"false"</js>, serializing the array <c>[1,2,3]</c> results in <c>?key=$a(1,2,3)</c>.
065    * <br>If <js>"true"</js>, serializing the same array results in <c>?key=1&amp;key=2&amp;key=3</c>.
066    *
067    * <ul class='values'>
068    *    <li><js>"true"</js>
069    *    <li><js>"false"</js> (default)
070    * </ul>
071    *
072    * <h5 class='section'>Notes:</h5><ul>
073    *    <li class='warn'>
074    *       If parsing multi-part parameters, it's highly recommended to use Collections or Lists
075    *       as bean property types instead of arrays since arrays have to be recreated from scratch every time a value
076    *       is added to it.
077    *    <li class='note'>
078    *       This option only applies to beans.
079    *    <li class='note'>
080    *       Supports <a class="doclink" href="../../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
081    * </ul>
082    *
083    * <h5 class='section'>See Also:</h5><ul>
084    *    <li class='jm'>{@link org.apache.juneau.urlencoding.UrlEncodingSerializer.Builder#expandedParams()}
085    * </ul>
086    *
087    * @return The annotation value.
088    */
089   String expandedParams() default "";
090
091   //-------------------------------------------------------------------------------------------------------------------
092   // UrlEncodingParser
093   //-------------------------------------------------------------------------------------------------------------------
094}