    001    // Copyright 2010 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
    015    package org.apache.tapestry5.annotations;
    016
    017    import static java.lang.annotation.ElementType.PARAMETER;
    018    import static java.lang.annotation.RetentionPolicy.RUNTIME;
    019    import static org.apache.tapestry5.ioc.annotations.AnnotationUseContext.COMPONENT;
    020    import static org.apache.tapestry5.ioc.annotations.AnnotationUseContext.MIXIN;
    021    import static org.apache.tapestry5.ioc.annotations.AnnotationUseContext.PAGE;
    022
    023    import java.lang.annotation.Documented;
    024    import java.lang.annotation.Retention;
    025    import java.lang.annotation.Target;
    026
    027    import org.apache.tapestry5.internal.transform.OnEventWorker;
    028    import org.apache.tapestry5.ioc.annotations.UseWith;
    029    import org.apache.tapestry5.ioc.services.TypeCoercer;
    030    import 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 TypeCoercer coerced} 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 })
    051    public @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.
    059         */
    060        boolean allowBlank() default false;
    061    }