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