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.internal.transform.OnEventWorker;
016import org.apache.tapestry5.ioc.annotations.UseWith;
017import org.apache.tapestry5.services.Request;
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}