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}