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