Before.java

/* Copyright 2005-2006 Tim Fennell
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package net.sourceforge.stripes.action;

import net.sourceforge.stripes.controller.LifecycleStage;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * <p>
 * Specifies that the annotated method should be run <i>before</i> the specified
 * {@link LifecycleStage}(s). More than one LifecycleStage can be specified, in
 * which case the method will be run before each stage. If no LifecycleStage is
 * specified then the default is to execute the method before
 * {@link LifecycleStage#EventHandling}. {@link LifecycleStage#RequestInit} and
 * {@link LifecycleStage#ActionBeanResolution}
 * <b>cannot</b> be specified because there is no ActionBean to run a method on
 * before the ActionBean has been resolved!</p>
 *
 * <p>
 * The method may have any name, any access specifier (public, private etc.) and
 * must take no arguments. Methods may return values; if the value is a
 * {@link net.sourceforge.stripes.action.Resolution} it will be used immediately
 * to terminate the request. Any other values returned will be ignored.</p>
 *
 * <p>
 * Examples:</p>
 * <pre>
 * // Runs before the event handling method has been run
 * {@literal @Before}
 * public void doStuff() {
 *    ...
 * }
 *
 * // Runs before binding and validation are executed
 * {@literal @Before(stages = LifecycleStage.BindingAndValidation)}
 * public void doPreValidationStuff() {
 *    ...
 * }
 *
 * // Runs twice, once before each validation-related stage
 * {@literal @}Before(stages = {LifecycleStage.BindingAndValidation, LifecycleStage.CustomValidation})
 * public void doMorePreValidationStuff() {
 *    ...
 * }
 * </pre>
 *
 * @see net.sourceforge.stripes.action.After
 * @see net.sourceforge.stripes.controller.BeforeAfterMethodInterceptor
 * @author Jeppe Cramon
 * @since Stripes 1.3
 */
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD})
@Inherited
@Documented
public @interface Before {

    /**
     * One or more lifecycle stages before which the method should be called.
     * 
     * @return One or more lifecycle stages before which the method should be called.
     */
    LifecycleStage[] stages() default LifecycleStage.EventHandling;

    /**
     * Allows the method to be restricted to one or more events. By default the
     * method will be executed on all events. Can be used to specify one or more
     * events to apply the method to (e.g. on={"save", "update"}), or to specify
     * one or more events <i>not</i> to apply the method to (e.g. on="!delete").
     * 
     * @return the list of event names before which the method should be called.
     */
    String[] on() default {};
}