    001// Licensed under the Apache License, Version 2.0 (the "License");
    002// you may not use this file except in compliance with the License.
    003// You may obtain a copy of the License at
    004//
    005// http://www.apache.org/licenses/LICENSE-2.0
    006//
    007// Unless required by applicable law or agreed to in writing, software
    008// distributed under the License is distributed on an "AS IS" BASIS,
    009// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    010// See the License for the specific language governing permissions and
    011// limitations under the License.
    012
    013package org.apache.tapestry5.annotations;
    014
    015import org.apache.tapestry5.http.services.Request;
    016import org.apache.tapestry5.internal.transform.OnEventWorker;
    017import org.apache.tapestry5.ioc.annotations.UseWith;
    018
    019import java.lang.annotation.Documented;
    020import java.lang.annotation.Retention;
    021import java.lang.annotation.Target;
    022
    023import static java.lang.annotation.ElementType.PARAMETER;
    024import static java.lang.annotation.RetentionPolicy.RUNTIME;
    025import static org.apache.tapestry5.ioc.annotations.AnnotationUseContext.*;
    026
    027/**
    028 * Annotation that may be placed on parameters of event handler methods.
    029 * Annotated parameters will be {@linkplain Request#getParameter(String) extracted from the request},
    030 * then {@linkplain org.apache.tapestry5.ValueEncoder converted} to the type of the parameter. Such parameters are separate
    031 * from ordinary context parameters (extracted from the Request path). Typically, this is used when
    032 * client-side JavaScript adds a query parameter to a request to communicate some information from the client
    033 * side to the server side.
    034 *
    035 * Individual fields may also be directly mapped to query parameters using the {@link ActivationRequestParameter} annotation.
    036 *
    037 * @since 5.2.0
    038 * @see OnEventWorker
    039 */
    040@Target(
    041{ PARAMETER })
    042@Retention(RUNTIME)
    043@Documented
    044@UseWith(
    045{ COMPONENT, MIXIN, PAGE })
    046public @interface RequestParameter
    047{
    048    /** The name of the query parameter to extract from the request. */
    049    String value();
    050
    051    /**
    052     * If false (the default), then an exception is thrown when the query parameter is read, if it is blank (null or an
    053     * empty string). If true, then blank values are allowed and will be passed through the appropriate {@link org.apache.tapestry5.ValueEncoder}
    054     * implementation.
    055     */
    056    boolean allowBlank() default false;
    057}