001package io.avaje.http.api;
002
003import java.lang.annotation.Retention;
004import java.lang.annotation.Target;
005
006import static java.lang.annotation.ElementType.METHOD;
007import static java.lang.annotation.ElementType.PARAMETER;
008import static java.lang.annotation.RetentionPolicy.RUNTIME;
009
010/**
011 * A parameter that is a bean containing form parameters.
012 * <p>
013 * The properties on the bean are by default treated as form parameters.
014 * If they have no other annotations like <code>@QueryParam</code>, or
015 * <code>@Header</code> etc they are populated as form parameters.
016 * </p>
017 * <p>
018 * The properties can have other annotations like <code>@QueryParam</code>,
019 * <code>@Header</code>, <code>@Cookie</code>, <code>@Default</code>.
020 * </p>
021 * <p>
022 * We would explicitly annotate a property with <code>@FormParam</code> if
023 * the form property name is snake case or similar that doesn't map to a
024 * valid java/kotlin variable.
025 * </p>
026 *
027 * <h4>Example 1</h4>
028 * <p>
029 * Simple form bean, properties default to form parameters matching the property name.
030 * </p>
031 *
032 * <pre>{@code
033 *   public class MyForm {
034 *
035 *     public String id;
036 *     public String name;
037 *   }
038 *
039 *   ...
040 *
041 *   @Post
042 *   void postForm(@Form MyForm fooForm) {
043 *
044 *     ...
045 *   }
046 *
047 * }</pre>
048 *
049 * <h4>Example 2</h4>
050 * <p>
051 * Form bean with various annotations.
052 * </p>
053 *
054 * <pre>{@code
055 *   public class MyForm {
056 *
057 *     @FormParam("start-date")
058 *     public LocalDate startDate;
059 *
060 *     @Default("Fred")
061 *     public String myName;
062 *
063 *     @Cookie
064 *     public String lastActive;
065 *   }
066 *
067 * }</pre>
068 */
069@Target(value={PARAMETER,METHOD})
070@Retention(value=RUNTIME)
071public @interface Form {
072
073}