0001: /*
0002: * Licensed to the Apache Software Foundation (ASF) under one or more
0003: * contributor license agreements. See the NOTICE file distributed with
0004: * this work for additional information regarding copyright ownership.
0005: * The ASF licenses this file to You under the Apache License, Version 2.0
0006: * (the "License"); you may not use this file except in compliance with
0007: * the License. You may obtain a copy of the License at
0008: *
0009: * http://www.apache.org/licenses/LICENSE-2.0
0010: *
0011: * Unless required by applicable law or agreed to in writing, software
0012: * distributed under the License is distributed on an "AS IS" BASIS,
0013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0014: * See the License for the specific language governing permissions and
0015: * limitations under the License.
0016: *
0017: * $Header:$
0018: */
0019: package org.apache.beehive.netui.pageflow.annotations;
0020:
0021: import java.lang.annotation.Target;
0022: import java.lang.annotation.Retention;
0023: import java.lang.annotation.Inherited;
0024:
0025: import static java.lang.annotation.ElementType.TYPE;
0026: import static java.lang.annotation.ElementType.METHOD;
0027: import static java.lang.annotation.ElementType.FIELD;
0028: import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
0029: import static java.lang.annotation.RetentionPolicy.RUNTIME;
0030: import static java.lang.annotation.RetentionPolicy.SOURCE;
0031:
0032: /**
0033: * Wrapper interface for all Page Flow annotations.
0034: */
0035: public interface Jpf {
0036: /**
0037: * Enumeration used by {@link Controller#multipartHandler()} to determine the type of multipart handler.
0038: */
0039: public enum MultipartHandler {
0040: /** Indicates that multipart handling is disabled in this Controller. **/
0041: disabled,
0042:
0043: /** Indicates that multipart requests will be processed in-memory for this Controller. */
0044: memory,
0045:
0046: /** Indicates that multipart requests will be processed on disk for this Controller. */
0047: disk
0048: }
0049:
0050: /**
0051: * Enumeration used by {@link Forward#navigateTo()}, {@link SimpleAction#navigateTo()}, and
0052: * {@link ConditionalForward#navigateTo()} to determine the next navigation point.
0053: */
0054: public enum NavigateTo {
0055: /** Indicates that the next page shown should be the most recent one shown. */
0056: currentPage,
0057:
0058: /** Indicates that the next page shown should be the one before the most recent one shown. */
0059: previousPage,
0060:
0061: /** Indicates that the previous action should be re-run. **/
0062: previousAction,
0063:
0064: /** Either {@link #currentPage} or {@link #previousPage} should be used instead. */
0065: @Deprecated
0066: page
0067: }
0068:
0069: /**
0070: * Enumeration used by {@link Controller#validatorVersion} to determine the version of Commons Validator that is
0071: * being used. This affects the format of generated Commons Validator configuration files.
0072: */
0073: public enum ValidatorVersion {
0074: /** Indicates that Commons Validator version 1.0 is being used. */
0075: oneZero,
0076:
0077: /** Indicates that Commons Validator version 1.1 is being used. */
0078: oneOne
0079: }
0080:
0081: /**
0082: * Main class-level annotation required to be present on all page flow
0083: * ({@link org.apache.beehive.netui.pageflow.PageFlowController}-derived) and shared flow
0084: * ({@link org.apache.beehive.netui.pageflow.SharedFlowController}-derived) classes.
0085: */
0086: @Target(TYPE)
0087: @Retention(RUNTIME)
0088: public @interface Controller {
0089: //-----------------------
0090: // Optional attributes...
0091: //-----------------------
0092:
0093: /**
0094: * Array of declarative catches, which can reroute to a page or to a handler method ({@link ExceptionHandler})
0095: * when a particular exception is thrown.
0096: */
0097: Catch[] catches() default {};
0098:
0099: /**
0100: * Array of additional webapp-relative file paths to be added to the <code>pathnames</code> property of the
0101: * ValidatorPlugIn initialization in the generated Struts config XML for this controller.
0102: */
0103: String[] customValidatorConfigs() default {};
0104:
0105: /**
0106: * Array of Forwards that can be used from any action ({@link Action} or {@link SimpleAction}) or
0107: * exception handler ({@link ExceptionHandler}) in this controller. An action or exception handler method
0108: * uses a forward by returning a {@link org.apache.beehive.netui.pageflow.Forward} object whose name matches
0109: * the one in the Forward annotation. A simple action uses a forward by naming it in the
0110: * {@link SimpleAction#forwardRef} attribute.
0111: */
0112: Forward[] forwards() default {};
0113:
0114: /**
0115: * If set to <code>true</code>, a {@link org.apache.beehive.netui.pageflow.NotLoggedInException} will be thrown
0116: * for any action ({@link Action} or {@link SimpleAction}) in this controller when the current
0117: * {@link org.apache.beehive.netui.pageflow.handler.LoginHandler} returns <code>null</code> for
0118: * <code>getUserPrincipal</code>. The default LoginHandler simply calls <code>getUserPrincipal</code> on
0119: * {@link javax.servlet.http.HttpServletRequest}.
0120: */
0121: boolean loginRequired() default false;
0122:
0123: /**
0124: * If set to <code>true</code>, then this page flow does not get discarded when another page flow is hit
0125: * (only valid for {@link org.apache.beehive.netui.pageflow.PageFlowController}s). It ramains stored in the
0126: * background, and is reinstated when it is requested again. Long-lived page flows may be deleted using
0127: * {@link org.apache.beehive.netui.pageflow.PageFlowUtils#removeLongLivedPageFlow}.
0128: */
0129: boolean longLived() default false;
0130:
0131: /**
0132: * Array of message bundles used by this controller. Any message key (like those in validation messages) refers
0133: * to a message in one of the listed bundles.
0134: */
0135: MessageBundle[] messageBundles() default {};
0136:
0137: /**
0138: * A value that determines the type of multipart handling for actions ({@link Action} or {@link SimpleAction})
0139: * in this controller. <i>For security, multipart handling is disabled by default.</i>.
0140: */
0141: MultipartHandler multipartHandler() default MultipartHandler.disabled;
0142:
0143: /**
0144: * If set to <code>true</code>, then this is a reusable, modular flow that can be "nested" during other flows.
0145: * It has entry points (actions with optional form bean arguments), and exit points ({@link Forward},
0146: * {@link SimpleAction}, or {@link ConditionalForward} annotations that have <code>returnAction</code>
0147: * attributes).
0148: */
0149: boolean nested() default false;
0150:
0151: /**
0152: * If set to <code>true</code>, then by default all actions ({@link Action} or {@link SimpleAction}) in this
0153: * controller have "promised" that they will not modify member data. In containers that support clustering,
0154: * this allows the framework to avoid serializing the controller instance for session failover after the
0155: * method is run. This is a performance optimization; it does not have an effect on the behavior of the
0156: * action itself.
0157: */
0158: boolean readOnly() default false;
0159:
0160: /**
0161: * Array of roles allowed to access actions in this controller. If this array is non-empty, then two
0162: * exceptions may be thrown when an action ({@link Action} or {@link SimpleAction}) in this controller is
0163: * raised:
0164: * <ul>
0165: * <li>
0166: * A {@link org.apache.beehive.netui.pageflow.NotLoggedInException} will be thrown when the current
0167: * {@link org.apache.beehive.netui.pageflow.handler.LoginHandler} returns <code>null</code> for
0168: * <code>getUserPrincipal</code>. The default LoginHandler simply calls
0169: * <code>getUserPrincipal</code> on {@link javax.servlet.http.HttpServletRequest}.
0170: * </li>
0171: * <li>
0172: * An {@link org.apache.beehive.netui.pageflow.UnfulfilledRolesException} will be thrown when the
0173: * current {@link org.apache.beehive.netui.pageflow.handler.LoginHandler} returns
0174: * <code>false</code> from <code>isUserInRole</code> for each of the roles in the list. The
0175: * default LoginHandler simply calls <code>isUserInRole</code> on
0176: * {@link javax.servlet.http.HttpServletRequest}.
0177: * </li>
0178: * </ul>
0179: */
0180: String[] rolesAllowed() default {};
0181:
0182: /**
0183: * Array of shared flow references used by a page flow. Each one maps a local shared flow name to an actual
0184: * shared flow type. Referenced shared flows add common actions (addressed in the form
0185: * "<i>shared-flow-name</i>.<i>shared-flow-action-name</i>") and fallback exception handlers, and can provide
0186: * a location for shared state.
0187: */
0188: SharedFlowRef[] sharedFlowRefs() default {};
0189:
0190: /**
0191: * Array of simple actions.
0192: */
0193: SimpleAction[] simpleActions() default {};
0194:
0195: /**
0196: * Location of the "Struts merge" file, whose elements/attributes override those in the Struts config XML file
0197: * generated from this controller. The path is relative to this controller, or, if it starts with '/', is
0198: * relative to a source root.
0199: */
0200: String strutsMerge() default "";
0201:
0202: /**
0203: * Array of webapp-relative paths to Tiles Definitions Config XML files. Definitions within these files may
0204: * be referenced in {@link Forward#tilesDefinition}, {@link SimpleAction#tilesDefinition}, or
0205: * {@link ConditionalForward#tilesDefinition}.
0206: */
0207: String[] tilesDefinitionsConfigs() default {};
0208:
0209: /**
0210: * Array of validation rules on a per-bean (class) basis. An action ({@link Action} or {@link SimpleAction})
0211: * that accepts a form bean can trigger validation rules for any of these bean types.
0212: * @see ValidateRequired
0213: * @see ValidateMinLength
0214: * @see ValidateMaxLength
0215: * @see ValidateMask
0216: * @see ValidateType
0217: * @see ValidateDate
0218: * @see ValidateRange
0219: * @see ValidateCreditCard
0220: * @see ValidateEmail
0221: * @see ValidateValidWhen
0222: * @see ValidateCustomRule
0223: */
0224: ValidatableBean[] validatableBeans() default {};
0225:
0226: /**
0227: * Location of the "Validator merge" file, whose elements/attributes override those in the ValidatorPlugIn
0228: * config XML file generated from this controller. The path is relative to this controller, or, if it starts
0229: * with '/', is relative to a source root.
0230: */
0231: String validatorMerge() default "";
0232:
0233: /**
0234: * The version of the commons-validator DTD to use for the ValidatorPlugIn config XML generated from this
0235: * controller.
0236: */
0237: ValidatorVersion validatorVersion() default ValidatorVersion.oneZero;
0238:
0239: /**
0240: * This relates to any local path (does not start with "/") inherited from a {@link SimpleAction},
0241: * {@link Action}, {@link Forward}, etc. in a base class. Normally, this path would be relative to the
0242: * <strong>current</strong> controller. When this value is set to <code>true</code>, then the path is
0243: * relative to the <strong>base class</strong> controller.
0244: */
0245: boolean inheritLocalPaths() default false;
0246: }
0247:
0248: /**
0249: * Declaration of a shared flow reference, which maps a local shared flow name to an actual shared flow type.
0250: * Referenced shared flows add common actions (addressed in the form
0251: * "<i>shared-flow-name</i>.<i>shared-flow-action-name</i>") and fallback exception handlers, and can provide
0252: * a location for shared state. This annotation is used within {@link Controller}.
0253: */
0254: @Target(ANNOTATION_TYPE)
0255: @Retention(RUNTIME)
0256: public @interface SharedFlowRef {
0257: /**
0258: * The local name of the shared flow reference.
0259: */
0260: String name();
0261:
0262: /**
0263: * The actual type of the shared flow.
0264: */
0265: Class type();
0266: }
0267:
0268: /**
0269: * Annotation used within {@link SimpleAction} to forward conditionally, based on the evaluation of a JSP 2.0-style
0270: * expression.
0271: */
0272: @Target(ANNOTATION_TYPE)
0273: @Retention(RUNTIME)
0274: public @interface ConditionalForward {
0275: //-----------------------
0276: // Required attributes...
0277: //-----------------------
0278:
0279: /**
0280: * The JSP 2.0-style expression (e.g., <code>${pageFlow.myProperty}</code> that will trigger this forward. If
0281: * the expression evaluates to <code>true</code>, then the forward will be used.
0282: */
0283: String condition();
0284:
0285: //-----------------------
0286: // Optional attributes...
0287: //-----------------------
0288:
0289: /**
0290: * The name of an action to forward to. Mutually-exclusive with {@link #path}, {@link #navigateTo},
0291: * {@link #returnAction}, and {@link #tilesDefinition}.
0292: */
0293: String action() default "";
0294:
0295: /**
0296: * When set to <code>true</code>, then this Forward will redirect to a path that is external to the
0297: * current webapp; for example, the following path would redirect to /dir/mypage.jsp in webapp "/myapp":
0298: * <blockquote>
0299: * <code>path="/myapp/dir/mypage.jsp", externalRedirect=true</code>
0300: * </blockquote>
0301: * With <code>externalRedirect</code> set to <code>false</code>, the path above would forward to
0302: * /myapp/dir/mypage.jsp under the <i>current</i> webapp. Note that <code>externalRedirect=true</code>
0303: * implies that <code>redirect=true</code>.
0304: */
0305: boolean externalRedirect() default false;
0306:
0307: /**
0308: * The forward name, which is optional for ConditionalForwards.
0309: */
0310: String name() default "";
0311:
0312: /**
0313: * A symbolic name for the page/action to which to navigate. Mutually-exclusive with {@link #path},
0314: * {@link #returnAction}, {@link #action}, and {@link #tilesDefinition}.
0315: * @see NavigateTo
0316: */
0317: NavigateTo navigateTo() default NavigateTo.currentPage;
0318:
0319: /**
0320: * The type of form bean that will be passed along (to a page or to another action) with this forward. A new
0321: * instance of the given class will be created.
0322: */
0323: Class outputFormBeanType() default Void.class;
0324:
0325: /**
0326: * The name of a member variable whose value will be passed along (to a page or to another action) with this
0327: * forward.
0328: */
0329: String outputFormBean() default "";
0330:
0331: /**
0332: * The forward path. Mutually-exclusive with {@link #navigateTo}, {@link #returnAction}, {@link #action},
0333: * and {@link #tilesDefinition}.
0334: */
0335: String path() default "";
0336:
0337: /**
0338: * If <code>true</code>, there will be a browser redirect (not a server forward) to the destination path.
0339: */
0340: boolean redirect() default false;
0341:
0342: /**
0343: * If <code>true</code>, the original URL query string will be restored when the previous page or action is
0344: * run. Only valid when the <code>navigateTo</code> attribute is used.
0345: */
0346: boolean restoreQueryString() default false;
0347:
0348: /**
0349: * The action to be invoked on the calling page flow. Mutually-exclusive with {@link #path},
0350: * {@link #navigateTo}, {@link #action}, and {@link #tilesDefinition}, and only valid in a nested page flow
0351: * ({@link Controller#nested} must be <code>true</code>).
0352: */
0353: String returnAction() default "";
0354:
0355: /**
0356: * A Tiles definition to forward to. The Tiles definition is found in one of the config files specified with
0357: * {@link Controller#tilesDefinitionsConfigs}. Mutually-exclusive with {@link #path}, {@link #navigateTo},
0358: * {@link #returnAction}, and {@link #action}.
0359: */
0360: String tilesDefinition() default "";
0361: }
0362:
0363: /**
0364: * Optional class-level annotation that can store tool-specific view properties.
0365: */
0366: @Target(TYPE)
0367: @Retention(SOURCE)
0368: public @interface ViewProperties {
0369: String[] value() default {};
0370: }
0371:
0372: /**
0373: * <p>
0374: * Method-level annotation that configures an action method. This annotation is required for a method to be
0375: * recognized as an action. Nearly every action will define a list of forwards through the {@link #forwards}
0376: * attribute. An example of an action method is shown below:
0377: * <blockquote>
0378: * <code>
0379: * @Jpf.Action(<br/>
0380: * forwards={<br/>
0381: * @Jpf.Forward(name="page1", page="page1.jsp"),<br/>
0382: * @Jpf.Forward(name="page2", page="page2.jsp")<br/>
0383: * },<br/>
0384: * validationErrorForward=@Jpf.Forward(name="failure", navigateTo=Jpf.NavigateTo.currentPage)<br/>
0385: * )<br/>
0386: * public Forward someAction(MyFormBean bean)<br/>
0387: * {<br/>
0388: * if (...)<br/>
0389: * return new Forward("page1");<br/>
0390: * else<br/>
0391: * return new Forward("page2");<br/>
0392: * }
0393: * </code>
0394: * </blockquote>
0395: * </p>
0396: * <p>
0397: * For actions that do not require Java code (for example, a begin action that simply
0398: * forwards to a particular page), {@link SimpleAction} can be used instead.
0399: * </p>
0400: *
0401: * @see SimpleAction
0402: */
0403: @Target(METHOD)
0404: @Retention(RUNTIME)
0405: public @interface Action {
0406: /**
0407: * Array of declarative catches, which can reroute to a page or to a handler method ({@link ExceptionHandler})
0408: * when a particular exception is thrown.
0409: */
0410: Catch[] catches() default {};
0411:
0412: /**
0413: * Enable or disable form validation for this action. If {@link #validationErrorForward} is set while
0414: * <code>doValidation</code> is not, then validation is enabled automatically.
0415: */
0416: boolean doValidation() default false;
0417:
0418: /**
0419: * Array of Forwards that can be used from this action. The method uses a forward by returning a
0420: * {@link org.apache.beehive.netui.pageflow.Forward} object whose name matches the one in the Forward
0421: * annotation. When an action method returns <code>null</code>, no forwarding is done.
0422: */
0423: Forward[] forwards() default {};
0424:
0425: /**
0426: * If set to <code>true</code>, a {@link org.apache.beehive.netui.pageflow.NotLoggedInException} will be thrown
0427: * for this action when the current {@link org.apache.beehive.netui.pageflow.handler.LoginHandler} returns
0428: * <code>null</code> for <code>getUserPrincipal</code>. The default LoginHandler simply calls
0429: * <code>getUserPrincipal</code> on {@link javax.servlet.http.HttpServletRequest}.
0430: */
0431: boolean loginRequired() default false;
0432:
0433: /**
0434: * <p>
0435: * Use a session-scoped token to prevent multiple submits to this action. When the server detects a double
0436: * submit on the token, a {@link org.apache.beehive.netui.pageflow.DoubleSubmitException} is thrown.
0437: * </p>
0438: * <p>
0439: * This is a server-side solution that guards against double processing; however, it is still a good
0440: * idea to supplement this with a client-side solution to prevent double-submits from happening in the first
0441: * place (an example of this is the <code>disableSecondClick</code> attribute on the NetUI Button tag, which
0442: * disables the button through JavaScript as soon as it is pressed).
0443: * </p>
0444: */
0445: boolean preventDoubleSubmit() default false;
0446:
0447: /**
0448: * If set to <code>true</code>, then by default this action has "promised" that it will not modify member data.
0449: * In containers that support clustering, this allows the framework to avoid serializing the controller
0450: * instance for session failover after the action is run. This is a performance optimization; it does not have
0451: * an effect on the behavior of the action itself.
0452: */
0453: boolean readOnly() default false;
0454:
0455: /**
0456: * Array of roles allowed to access this action. If this array is non-empty, then two exceptions may be thrown
0457: * when the action is raised:
0458: * <ul>
0459: * <li>
0460: * A {@link org.apache.beehive.netui.pageflow.NotLoggedInException} will be thrown when the current
0461: * {@link org.apache.beehive.netui.pageflow.handler.LoginHandler} returns <code>null</code> for
0462: * <code>getUserPrincipal</code>. The default LoginHandler simply calls
0463: * <code>getUserPrincipal</code> on {@link javax.servlet.http.HttpServletRequest}.
0464: * </li>
0465: * <li>
0466: * An {@link org.apache.beehive.netui.pageflow.UnfulfilledRolesException} will be thrown when the
0467: * current {@link org.apache.beehive.netui.pageflow.handler.LoginHandler} returns
0468: * <code>false</code> from <code>isUserInRole</code> for each of the roles in the list. The
0469: * default LoginHandler simply calls <code>isUserInRole</code> on
0470: * {@link javax.servlet.http.HttpServletRequest}.
0471: * </li>
0472: * </ul>
0473: */
0474: String[] rolesAllowed() default {};
0475:
0476: /**
0477: * If set, then the form bean for this action method will be the named member variable, rather than a
0478: * newly-created instance. This is referred to as a "flow-scoped form bean". Note that if the member variable
0479: * is null, it will be set with a new instance of the correct type.
0480: */
0481: String useFormBean() default "";
0482:
0483: /**
0484: * Array of validation rules that are applied to properties on this action's form bean.
0485: * @see ValidateRequired
0486: * @see ValidateMinLength
0487: * @see ValidateMaxLength
0488: * @see ValidateMask
0489: * @see ValidateType
0490: * @see ValidateDate
0491: * @see ValidateRange
0492: * @see ValidateCreditCard
0493: * @see ValidateEmail
0494: * @see ValidateValidWhen
0495: * @see ValidateCustomRule
0496: */
0497: ValidatableProperty[] validatableProperties() default {};
0498:
0499: /**
0500: * The Forward used when form bean validation fails. Setting this value automatically enables validation for
0501: * this action method, unless {@link #doValidation} is set to <code>false</code>. Validation is always
0502: * disabled when this value is not set.
0503: */
0504: Forward validationErrorForward() default @Jpf.Forward(name="");
0505: }
0506:
0507: /**
0508: * A "simple" action, which defines its behavior wholly through an annotation, rather than through a method. This
0509: * is useful when an action does not require any Java code to run (for example, a begin action that simply forwards
0510: * to a particular page). Actions that <i>do</i> require Java code are built using methods annotated with
0511: * {@link Action}.
0512: *
0513: * @see Action
0514: */
0515: @Target(ANNOTATION_TYPE)
0516: @Retention(RUNTIME)
0517: public @interface SimpleAction {
0518: //-----------------------
0519: // Required attributes...
0520: //-----------------------
0521:
0522: /**
0523: * The action name.
0524: */
0525: String name();
0526:
0527: //---------------------------------------------
0528: // Optional attributes, like those on Action...
0529: //---------------------------------------------
0530:
0531: /**
0532: * Array of declarative catches, which can reroute to a page or to a handler method ({@link ExceptionHandler})
0533: * when a particular exception is thrown.
0534: */
0535: Catch[] catches() default {};
0536:
0537: /**
0538: * Array of conditional forwards. Each one is triggered by a JSP 2.0-style expression evaluating to
0539: * <code>true</code>. The conditions are evaluated in order, so if more than one would evaluate to
0540: * <code>true</code>, the first one wins.
0541: */
0542: ConditionalForward[] conditionalForwards() default {};
0543:
0544: /**
0545: * Enable or disable form validation for this action. If {@link #validationErrorForward} is set while
0546: * <code>doValidation</code> is not, then validation is enabled automatically.
0547: */
0548: boolean doValidation() default false;
0549:
0550: /**
0551: * <p>
0552: * The name of a class-level forward (a {@link Forward} in {@link Controller#forwards}) which will serve as the
0553: * destination for this simple action. Mutually-exclusive with with {@link #action}, {@link #path},
0554: * {@link #navigateTo}, {@link #returnAction}, and {@link #tilesDefinition}.
0555: * </p>
0556: * <p>
0557: * If this simple action handles the return from a nested page flow that was shown in a popup window, then
0558: * the <code>forwardRef</code> attribute can be set to the special value "_auto". This causes the framework to
0559: * write out the correct javascript to close the popup window instead of forwarding to another page.
0560: * </p>
0561: */
0562: String forwardRef() default "";
0563:
0564: /**
0565: * If set to <code>true</code>, a {@link org.apache.beehive.netui.pageflow.NotLoggedInException} will be thrown
0566: * for this action when the current {@link org.apache.beehive.netui.pageflow.handler.LoginHandler} returns
0567: * <code>null</code> for <code>getUserPrincipal</code>. The default LoginHandler simply calls
0568: * <code>getUserPrincipal</code> on {@link javax.servlet.http.HttpServletRequest}.
0569: */
0570: boolean loginRequired() default false;
0571:
0572: /**
0573: * <p>
0574: * Use a session-scoped token to prevent multiple submits to this action. When the server detects a double
0575: * submit on the token, a {@link org.apache.beehive.netui.pageflow.DoubleSubmitException} is thrown.
0576: * </p>
0577: * <p>
0578: * This is a server-side solution that guards against double processing; however, it is still a good
0579: * idea to supplement this with a client-side solution to prevent double-submits from happening in the first
0580: * place (an example of this is the <code>disableSecondClick</code> attribute on the NetUI Button tag, which
0581: * disables the button through JavaScript as soon as it is pressed).
0582: * </p>
0583: */
0584: boolean preventDoubleSubmit() default false;
0585:
0586: /**
0587: * If set to <code>true</code>, then by default this action has "promised" that it will not modify member data.
0588: * In containers that support clustering, this allows the framework to avoid serializing the controller
0589: * instance for session failover after the action is run. This is a performance optimization; it does not have
0590: * an effect on the behavior of the action itself.
0591: */
0592: boolean readOnly() default false;
0593:
0594: /**
0595: * Array of roles allowed to access this action. If this array is non-empty, then two exceptions may be thrown
0596: * when the action is raised:
0597: * <ul>
0598: * <li>
0599: * A {@link org.apache.beehive.netui.pageflow.NotLoggedInException} will be thrown when the current
0600: * {@link org.apache.beehive.netui.pageflow.handler.LoginHandler} returns <code>null</code> for
0601: * <code>getUserPrincipal</code>. The default LoginHandler simply calls
0602: * <code>getUserPrincipal</code> on {@link javax.servlet.http.HttpServletRequest}.
0603: * </li>
0604: * <li>
0605: * An {@link org.apache.beehive.netui.pageflow.UnfulfilledRolesException} will be thrown when the
0606: * current {@link org.apache.beehive.netui.pageflow.handler.LoginHandler} returns
0607: * <code>false</code> from <code>isUserInRole</code> for each of the roles in the list. The
0608: * default LoginHandler simply calls <code>isUserInRole</code> on
0609: * {@link javax.servlet.http.HttpServletRequest}.
0610: * </li>
0611: * </ul>
0612: */
0613: String[] rolesAllowed() default {};
0614:
0615: /**
0616: * If set, then the form bean for this action method will be the named member variable, rather than a
0617: * newly-created instance. This is referred to as a "flow-scoped form bean". Note that if the member variable
0618: * is null, it will be set with a new instance of the correct type. Mutually exclusive with
0619: * {@link #useFormBeanType}.
0620: */
0621: String useFormBean() default "";
0622:
0623: /**
0624: * The type of form bean to use for this action. A new instance of the given class will be created when this
0625: * action is run. Mutually exclusive with {@link #useFormBean}.
0626: */
0627: Class useFormBeanType() default Void.class;
0628:
0629: /**
0630: * Array of validation rules that are applied to properties on this action's form bean.
0631: */
0632: ValidatableProperty[] validatableProperties() default {};
0633:
0634: /**
0635: * The Forward used when form bean validation fails. Setting this value automatically enables validation for
0636: * this action method, unless {@link #doValidation} is set to <code>false</code>. Validation is always
0637: * disabled when this value is not set.
0638: */
0639: Forward validationErrorForward() default @Jpf.Forward(name="");
0640:
0641: //----------------------------------------------
0642: // Optional attributes, like those on Forward...
0643: //----------------------------------------------
0644:
0645: /**
0646: * The name of an action to forward to. Mutually-exclusive with {@link #path}, {@link #navigateTo},
0647: * {@link #returnAction}, {@link #tilesDefinition}, and {@link #forwardRef}.
0648: */
0649: String action() default "";
0650:
0651: /**
0652: * When set to <code>true</code>, then this Forward will redirect to a path that is external to the
0653: * current webapp; for example, the following path would redirect to /dir/mypage.jsp in webapp "/myapp":
0654: * <blockquote>
0655: * <code>path="/myapp/dir/mypage.jsp", externalRedirect=true</code>
0656: * </blockquote>
0657: * With <code>externalRedirect</code> set to <code>false</code>, the path above would forward to
0658: * /myapp/dir/mypage.jsp under the <i>current</i> webapp. Note that <code>externalRedirect=true</code>
0659: * implies that <code>redirect=true</code>.
0660: */
0661: boolean externalRedirect() default false;
0662:
0663: /**
0664: * A symbolic name for the page/action to which to navigate. Mutually-exclusive with {@link #path},
0665: * {@link #returnAction}, {@link #action}, {@link #tilesDefinition}, and {@link #forwardRef}.
0666: * @see NavigateTo
0667: */
0668: NavigateTo navigateTo() default NavigateTo.currentPage;
0669:
0670: /**
0671: * The type of form bean that will be passed along (to a page or to another action) with this forward. The
0672: * actual form bean instance is provided on the {@link org.apache.beehive.netui.pageflow.Forward} object that
0673: * is returned from the action method ({@link Action}) or the exception handler method
0674: * ({@link ExceptionHandler}). If that object has no output form bean, then a new instance of the given type
0675: * will be created.
0676: */
0677: Class outputFormBeanType() default Void.class;
0678:
0679: /**
0680: * The name of a member variable whose value will be passed along (to a page or to another action) with this
0681: * forward.
0682: */
0683: String outputFormBean() default "";
0684:
0685: /**
0686: * The forward path. Mutually-exclusive with {@link #navigateTo}, {@link #returnAction}, {@link #action},
0687: * {@link #tilesDefinition}, and {@link #forwardRef}.
0688: */
0689: String path() default "";
0690:
0691: /**
0692: * If <code>true</code>, there will be a browser redirect (not a server forward) to the destination path.
0693: */
0694: boolean redirect() default false;
0695:
0696: /**
0697: * If <code>true</code>, the original URL query string will be restored when the previous page or action is
0698: * run. Only valid when the <code>navigateTo</code> attribute is used.
0699: */
0700: boolean restoreQueryString() default false;
0701:
0702: /**
0703: * The action to be invoked on the calling page flow. Mutually-exclusive with {@link #path},
0704: * {@link #navigateTo}, {@link #action}, {@link #tilesDefinition}, and {@link #forwardRef}, and only valid in a
0705: * nested page flow ({@link Controller#nested} must be <code>true</code>).
0706: */
0707: String returnAction() default "";
0708:
0709: /**
0710: * A Tiles definition to forward to. The Tiles definition is found in one of the config files specified with
0711: * {@link Controller#tilesDefinitionsConfigs}. Mutually-exclusive with {@link #path}, {@link #navigateTo},
0712: * {@link #returnAction}, {@link #action}, and {@link #forwardRef}.
0713: */
0714: String tilesDefinition() default "";
0715: }
0716:
0717: /**
0718: * A declarative "catch" for exceptions thrown from actions ({@link Action}, {@link SimpleAction}).
0719: */
0720: @Target(ANNOTATION_TYPE)
0721: @Retention(RUNTIME)
0722: public @interface Catch {
0723: //-----------------------
0724: // Required attributes...
0725: //-----------------------
0726:
0727: /**
0728: * The type of Throwable to handle.
0729: */
0730: Class<? extends Throwable> type();
0731:
0732: //-----------------------
0733: // Optional attributes...
0734: //-----------------------
0735:
0736: /**
0737: * The exception handler method ({@link ExceptionHandler}) to invoke. Mutually exclusive with {@link #path}.
0738: */
0739: String method() default "";
0740:
0741: /**
0742: * The JSP 2.0-style expression (e.g., <code>${pageFlow.myProperty}</code> or literal string message. This
0743: * message is used in two ways:
0744: * <ul>
0745: * <li>It is sent as an argument to the handler method, if {@link #method} is specified.</li>
0746: * <li>
0747: * It is used as the message in an {@link org.apache.struts.action.ActionMessage} object within
0748: * an {@link org.apache.struts.action.ActionErrors} that is stored in request attribute
0749: * {@link org.apache.struts.Globals#ERROR_KEY}. The ActionMessage's key is the value of
0750: * {@link #messageKey}, if set, or the full class name of the exception type otherwise.
0751: * </li>
0752: * </ul>
0753: */
0754: String message() default "";
0755:
0756: /**
0757: * A message resource within a message bundle {@link MessageBundle} that is used to look up the message. The
0758: * message is used in two ways:
0759: * <ul>
0760: * <li>It is sent as an argument to the handler method, if {@link #method} is specified.</li>
0761: * <li>
0762: * It is used as the message in an {@link org.apache.struts.action.ActionMessage} object within
0763: * an {@link org.apache.struts.action.ActionErrors} that is stored in request attribute
0764: * {@link org.apache.struts.Globals#ERROR_KEY}. <i>The value of <code>messageKey</code> is also
0765: * used as the ActionMessage's key.</i>
0766: * </li>
0767: * </ul>
0768: */
0769: String messageKey() default "";
0770:
0771: /**
0772: * The destination URI to forward to. Mututally exclusive with {@link #method}. For more {@link Forward}-style
0773: * options, use the {@link #method} attribute.
0774: */
0775: String path() default "";
0776: }
0777:
0778: /**
0779: * Method-level annotation that configures an exception handler method, which is invoked when a {@link Catch} is
0780: * triggered. This annotation is required for a method to be recognized as an exception handler.
0781: */
0782: @Target(METHOD)
0783: @Retention(RUNTIME)
0784: public @interface ExceptionHandler {
0785: /**
0786: * Array of Forwards that can be used from this exception handler. The method uses a forward by returning a
0787: * {@link org.apache.beehive.netui.pageflow.Forward} object whose name matches the one in the Forward
0788: * annotation. When an exception handler method returns <code>null</code>, no forwarding is done.
0789: */
0790: Forward[] forwards() default {};
0791:
0792: /**
0793: * If set to <code>true</code>, then by default this exception handler has "promised" that it will not modify
0794: * member data. In containers that support clustering, this allows the framework to avoid serializing the
0795: * controller instance for session failover after the method is run. This is a performance optimization; it
0796: * does not have an effect on the behavior of the exception handler itself.
0797: */
0798: boolean readOnly() default false;
0799: }
0800:
0801: /**
0802: * A destination that is used by actions ({@link Action}, {@link SimpleAction}) and exception handlers
0803: * {@link ExceptionHandler}.
0804: */
0805: @Target(ANNOTATION_TYPE)
0806: @Retention(RUNTIME)
0807: public @interface Forward {
0808: //-----------------------
0809: // Required attributes...
0810: //-----------------------
0811:
0812: /**
0813: * The forward name. An action method ({@link Action}) or an exception handler method
0814: * ({@link ExceptionHandler}) can use this forward by returning a
0815: * {@link org.apache.beehive.netui.pageflow.Forward} object that is initialized with this name.
0816: */
0817: String name();
0818:
0819: //-----------------------
0820: // Optional attributes...
0821: //-----------------------
0822:
0823: /**
0824: * The name of an action to forward to. Mutually-exclusive with {@link #path}, {@link #navigateTo},
0825: * {@link #returnAction}, and {@link #tilesDefinition}.
0826: */
0827: String action() default "";
0828:
0829: /**
0830: * Array of action output declarations to be associated with this Forward. An actual action output is passed on
0831: * a {@link org.apache.beehive.netui.pageflow.Forward} object. An action output supplies a "page input" in a
0832: * page, where it is accessed by databinding to
0833: * <code>${pageInput.</code><i>action-output-name</i><code>}</code>.
0834: */
0835: ActionOutput[] actionOutputs() default {};
0836:
0837: /**
0838: * When set to <code>true</code>, then this Forward will redirect to a path that is external to the
0839: * current webapp; for example, the following path would redirect to /dir/mypage.jsp in webapp "/myapp":
0840: * <blockquote>
0841: * <code>path="/myapp/dir/mypage.jsp", externalRedirect=true</code>
0842: * </blockquote>
0843: * With <code>externalRedirect</code> set to <code>false</code>, the path above would forward to
0844: * /myapp/dir/mypage.jsp under the <i>current</i> webapp. Note that <code>externalRedirect=true</code>
0845: * implies that <code>redirect=true</code>.
0846: */
0847: boolean externalRedirect() default false;
0848:
0849: /**
0850: * A symbolic name for the page/action to which to navigate. Mutually-exclusive with {@link #path},
0851: * {@link #returnAction}, {@link #action}, and {@link #tilesDefinition}.
0852: * @see NavigateTo
0853: */
0854: NavigateTo navigateTo() default NavigateTo.currentPage;
0855:
0856: /**
0857: * The type of form bean that will be passed along (to a page or to another action) with this forward. The
0858: * actual form bean instance is provided on the {@link org.apache.beehive.netui.pageflow.Forward} object that
0859: * is returned from the action method ({@link Action}) or the exception handler method
0860: * ({@link ExceptionHandler}). If that object has no output form bean, then a new instance of the given type
0861: * will be created.
0862: */
0863: Class outputFormBeanType() default Void.class;
0864:
0865: /**
0866: * The name of a member variable whose value will be passed along (to a page or to another action) with this
0867: * forward.
0868: */
0869: String outputFormBean() default "";
0870:
0871: /**
0872: * The forward path. Mutually-exclusive with {@link #navigateTo}, {@link #returnAction}, {@link #action},
0873: * and {@link #tilesDefinition}.
0874: */
0875: String path() default "";
0876:
0877: /**
0878: * If <code>true</code>, there will be a browser redirect (not a server forward) to the destination path.
0879: */
0880: boolean redirect() default false;
0881:
0882: /**
0883: * If <code>true</code>, the original URL query string will be restored when the previous page or action is
0884: * run. Only valid when the <code>navigateTo</code> attribute is used.
0885: */
0886: boolean restoreQueryString() default false;
0887:
0888: /**
0889: * The action to be invoked on the calling page flow. Mutually-exclusive with {@link #path},
0890: * {@link #navigateTo}, {@link #action}, and {@link #tilesDefinition}, and only valid in a nested page flow
0891: * ({@link Controller#nested} must be <code>true</code>).
0892: */
0893: String returnAction() default "";
0894:
0895: /**
0896: * A Tiles definition to forward to. The Tiles definition is found in one of the config files specified with
0897: * {@link Controller#tilesDefinitionsConfigs}. Mutually-exclusive with {@link #path}, {@link #navigateTo},
0898: * {@link #returnAction}, and {@link #action}.
0899: */
0900: String tilesDefinition() default "";
0901: }
0902:
0903: /**
0904: * An action output, which is declared in a {@link Jpf.Forward @Jpf.Forward} annotation and passed from an action
0905: * method on a {@link org.apache.beehive.netui.pageflow.Forward} object. An action output may be used as a
0906: * "page input" in a page, where it is accessed by databinding to
0907: * <code>${pageInput.</code><i>action-output-name</i><code>}</code>. The benefit of action outputs (over setting
0908: * request attributes) is that the annotations are visible to tools, and that there is runtime checking of type and
0909: * required-presence.
0910: */
0911: @Target(ANNOTATION_TYPE)
0912: @Retention(RUNTIME)
0913: public @interface ActionOutput {
0914: /**
0915: * The name of the action output. This is the <i>action-output-name</i> in the databinding expression
0916: * <code>${pageInput.</code><i>action-output-name</i><code>}</code>.
0917: */
0918: String name();
0919:
0920: /**
0921: * The type of the action output. This will be checked by the runtime if the server is not in production mode,
0922: * and if the type check fails, a {@link org.apache.beehive.netui.pageflow.MismatchedActionOutputException}
0923: * will be thrown.
0924: */
0925: Class type();
0926:
0927: /**
0928: * A String version of the type information that can be used by tools or as runtime-accessable information,
0929: * particularly to add generics to the type (generics are "erased" during compilation and are not available
0930: * to the runtime through reflection).
0931: */
0932: String typeHint() default "";
0933:
0934: /**
0935: * If <code>true</code>, a {@link org.apache.beehive.netui.pageflow.MissingActionOutputException} will be thrown
0936: * when the associated {@link org.apache.beehive.netui.pageflow.Forward} object does not include a value for
0937: * this named action output.
0938: */
0939: boolean required() default true;
0940: }
0941:
0942: /**
0943: * Annotation used within {@link Controller} to declare a message bundle for use in the page flow.
0944: */
0945: @Target(ANNOTATION_TYPE)
0946: @Retention(RUNTIME)
0947: public @interface MessageBundle {
0948: /**
0949: * The path to the message bundle, as a ServletContext resource. This may be specified with either '/' or'.'
0950: * as the separator, e.g., <code>bundlePath="foo.bar.MyMessages"</code> or
0951: * <code>bundlePath="foo/bar/MyMessages"</code> (in both cases, foo/bar/MyMessages.properties would be found
0952: * on classpath).
0953: */
0954: String bundlePath();
0955:
0956: /**
0957: * <p>
0958: * The name associated with the bundle; if this is <i>not</i> specified, then the bundle becomes the "default
0959: * bundle" for the page flow, and all validation messages implicitly reference it.
0960: * </p>
0961: * <p>
0962: * Named message bundles are databound to with expressions like
0963: * <code>${bundle.</code><i>bundle-name</i><code>.someMessage}</code>, while the default message bundle is
0964: * databound to with expressions like <code>${bundle.default.someMessage}</code>.
0965: * </p>
0966: */
0967: String bundleName() default "";
0968: }
0969:
0970: /**
0971: * A message argument used within field validation annotations.
0972: * @see ValidateRequired
0973: * @see ValidateMinLength
0974: * @see ValidateMaxLength
0975: * @see ValidateMask
0976: * @see ValidateType
0977: * @see ValidateDate
0978: * @see ValidateRange
0979: * @see ValidateCreditCard
0980: * @see ValidateEmail
0981: * @see ValidateValidWhen
0982: * @see ValidateCustomRule
0983: */
0984: @Target(ANNOTATION_TYPE)
0985: @Retention(RUNTIME)
0986: public @interface MessageArg {
0987: /**
0988: * The JSP 2.0-style expression (e.g., <code>${pageFlow.myProperty}</code>) or literal string that will be used
0989: * as the message argument. Mutually-exclusive with {@link #argKey}.
0990: */
0991: String arg() default "";
0992:
0993: /**
0994: * A key in the default message bundle or in the bundle specified by {@link #bundleName} that will be
0995: * used to look up the argument. Mutually-exclusive with {@link #arg}.
0996: * @see MessageBundle
0997: */
0998: String argKey() default "";
0999:
1000: /**
1001: * The name of the message bundle in which to look up the argument value. Requires {@link #argKey} to be set.
1002: * @see MessageBundle
1003: */
1004: String bundleName() default "";
1005:
1006: /**
1007: * The position of this argument in the associated message; for example, position 2 would replace the string
1008: * <code>{2}</code> in the message. This defaults to the position in the containing <code>messageArgs</code>
1009: * array.
1010: */
1011: int position() default -1;
1012: }
1013:
1014: /**
1015: * A validation rule that will fail if it is applied to a property that has no value.
1016: * Used within {@link ValidatableProperty} and {@link ValidationLocaleRules}.
1017: */
1018: @Target(ANNOTATION_TYPE)
1019: @Retention(RUNTIME)
1020: public @interface ValidateRequired {
1021: /**
1022: * If set to <code>false</code>, then this rule will not be applied.
1023: */
1024: boolean enabled() default true;
1025:
1026: /**
1027: * The JSP 2.0-style expression (e.g., <code>${pageFlow.myProperty}</code>) or literal string that will be used
1028: * as the error message. Mutually-exclusive with {@link #messageKey}.
1029: */
1030: String message() default "";
1031:
1032: /**
1033: * A key in the default message bundle or in the bundle specified by {@link #bundleName} that will be
1034: * used to look up the error message. Mutually-exclusive with {@link #message}.
1035: * @see MessageBundle
1036: */
1037: String messageKey() default "";
1038:
1039: /**
1040: * The name of the message bundle in which to look up the error message. Requires {@link #messageKey} to be set.
1041: * @see MessageBundle
1042: */
1043: String bundleName() default "";
1044:
1045: /**
1046: * An array of message arguments, which will be used for the message obtained from {@link #message} or
1047: * {@link #messageKey}, whichever is specified.
1048: */
1049: MessageArg[] messageArgs() default {};
1050: }
1051:
1052: /**
1053: * A validation rule that will fail if it is applied to a property that has a non-empty value whose length is less
1054: * than a given number of characters.
1055: * Used within {@link ValidatableProperty} and {@link ValidationLocaleRules}.
1056: */
1057: @Target(ANNOTATION_TYPE)
1058: @Retention(RUNTIME)
1059: public @interface ValidateMinLength {
1060: /**
1061: * If set to <code>false</code>, then this rule will not be applied.
1062: */
1063: boolean enabled() default true;
1064:
1065: /**
1066: * The minimum number of characters for the property value.
1067: */
1068: int chars();
1069:
1070: /**
1071: * The JSP 2.0-style expression (e.g., <code>${pageFlow.myProperty}</code>) or literal string that will be used
1072: * as the error message. Mutually-exclusive with {@link #messageKey}.
1073: */
1074: String message() default "";
1075:
1076: /**
1077: * A key in the default message bundle or in the bundle specified by {@link #bundleName} that will be
1078: * used to look up the error message. Mutually-exclusive with {@link #message}.
1079: * @see MessageBundle
1080: */
1081: String messageKey() default "";
1082:
1083: /**
1084: * The name of the message bundle in which to look up the error message. Requires {@link #messageKey} to be set.
1085: * @see MessageBundle
1086: */
1087: String bundleName() default "";
1088:
1089: /**
1090: * An array of message arguments, which will be used for the message obtained from {@link #message} or
1091: * {@link #messageKey}, whichever is specified.
1092: */
1093: MessageArg[] messageArgs() default {};
1094: }
1095:
1096: /**
1097: * A validation rule that will fail if it is applied to a property that has a non-empty value whose length is
1098: * greater than a given number of characters.
1099: * Used within {@link ValidatableProperty} and {@link ValidationLocaleRules}.
1100: */
1101: @Target(ANNOTATION_TYPE)
1102: @Retention(RUNTIME)
1103: public @interface ValidateMaxLength {
1104: /**
1105: * If set to <code>false</code>, then this rule will not be applied.
1106: */
1107: boolean enabled() default true;
1108:
1109: /**
1110: * The maximum number of characters for the property value.
1111: */
1112: int chars();
1113:
1114: /**
1115: * The JSP 2.0-style expression (e.g., <code>${pageFlow.myProperty}</code>) or literal string that will be used
1116: * as the error message. Mutually-exclusive with {@link #messageKey}.
1117: */
1118: String message() default "";
1119:
1120: /**
1121: * A key in the default message bundle or in the bundle specified by {@link #bundleName} that will be
1122: * used to look up the error message. Mutually-exclusive with {@link #message}.
1123: * @see MessageBundle
1124: */
1125: String messageKey() default "";
1126:
1127: /**
1128: * The name of the message bundle in which to look up the error message. Requires {@link #messageKey} to be set.
1129: * @see MessageBundle
1130: */
1131: String bundleName() default "";
1132:
1133: /**
1134: * An array of message arguments, which will be used for the message obtained from {@link #message} or
1135: * {@link #messageKey}, whichever is specified.
1136: */
1137: MessageArg[] messageArgs() default {};
1138: }
1139:
1140: /**
1141: * A validation rule that will fail if it is applied to a property that has a non-empty value which does not match
1142: * a given regular expression.
1143: * Used within {@link ValidatableProperty} and {@link ValidationLocaleRules}.
1144: */
1145: @Target(ANNOTATION_TYPE)
1146: @Retention(RUNTIME)
1147: public @interface ValidateMask {
1148: /**
1149: * If set to <code>false</code>, then this rule will not be applied.
1150: */
1151: boolean enabled() default true;
1152:
1153: /**
1154: * The regular expression that must be matched.
1155: */
1156: String regex();
1157:
1158: /**
1159: * The JSP 2.0-style expression (e.g., <code>${pageFlow.myProperty}</code>) or literal string that will be used
1160: * as the error message. Mutually-exclusive with {@link #messageKey}.
1161: */
1162: String message() default "";
1163:
1164: /**
1165: * A key in the default message bundle or in the bundle specified by {@link #bundleName} that will be
1166: * used to look up the error message. Mutually-exclusive with {@link #message}.
1167: * @see MessageBundle
1168: */
1169: String messageKey() default "";
1170:
1171: /**
1172: * The name of the message bundle in which to look up the error message. Requires {@link #messageKey} to be set.
1173: * @see MessageBundle
1174: */
1175: String bundleName() default "";
1176:
1177: /**
1178: * An array of message arguments, which will be used for the message obtained from {@link #message} or
1179: * {@link #messageKey}, whichever is specified.
1180: */
1181: MessageArg[] messageArgs() default {};
1182: }
1183:
1184: /**
1185: * A validation rule that will fail if it is applied to a property that has a non-empty value which cannot be
1186: * converted to a given primitive type.
1187: * Used within {@link ValidatableProperty} and {@link ValidationLocaleRules}.
1188: */
1189: @Target(ANNOTATION_TYPE)
1190: @Retention(RUNTIME)
1191: public @interface ValidateType {
1192: /**
1193: * If set to <code>false</code>, then this rule will not be applied.
1194: */
1195: boolean enabled() default true;
1196:
1197: /**
1198: * The type to which the property must be convertible; must be a primitive type, e.g., <code>int.class</code>.
1199: */
1200: Class type();
1201:
1202: /**
1203: * The JSP 2.0-style expression (e.g., <code>${pageFlow.myProperty}</code>) or literal string that will be used
1204: * as the error message. Mutually-exclusive with {@link #messageKey}.
1205: */
1206: String message() default "";
1207:
1208: /**
1209: * A key in the default message bundle or in the bundle specified by {@link #bundleName} that will be
1210: * used to look up the error message. Mutually-exclusive with {@link #message}.
1211: * @see MessageBundle
1212: */
1213: String messageKey() default "";
1214:
1215: /**
1216: * The name of the message bundle in which to look up the error message. Requires {@link #messageKey} to be set.
1217: * @see MessageBundle
1218: */
1219: String bundleName() default "";
1220:
1221: /**
1222: * An array of message arguments, which will be used for the message obtained from {@link #message} or
1223: * {@link #messageKey}, whichever is specified.
1224: */
1225: MessageArg[] messageArgs() default {};
1226: }
1227:
1228: /**
1229: * A validation rule that will fail if it is applied to a property that has a non-empty value which is not a date
1230: * in a given format.
1231: * Used within {@link ValidatableProperty} and {@link ValidationLocaleRules}.
1232: */
1233: @Target(ANNOTATION_TYPE)
1234: @Retention(RUNTIME)
1235: public @interface ValidateDate {
1236: /**
1237: * If set to <code>false</code>, then this rule will not be applied.
1238: */
1239: boolean enabled() default true;
1240:
1241: /**
1242: * The date pattern which will be used to initialize a <code>java.text.SimpleDateFormat</code>.
1243: */
1244: String pattern();
1245:
1246: /**
1247: * If set to <code>true</code>, then every element of the date must match the pattern exactly; for example,
1248: * "9/10/1973" would not match the pattern "MM/dd/yyyy".
1249: */
1250: boolean strict() default false;
1251:
1252: /**
1253: * The JSP 2.0-style expression (e.g., <code>${pageFlow.myProperty}</code>) or literal string that will be used
1254: * as the error message. Mutually-exclusive with {@link #messageKey}.
1255: */
1256: String message() default "";
1257:
1258: /**
1259: * A key in the default message bundle or in the bundle specified by {@link #bundleName} that will be
1260: * used to look up the error message. Mutually-exclusive with {@link #message}.
1261: * @see MessageBundle
1262: */
1263: String messageKey() default "";
1264:
1265: /**
1266: * The name of the message bundle in which to look up the error message. Requires {@link #messageKey} to be set.
1267: * @see MessageBundle
1268: */
1269: String bundleName() default "";
1270:
1271: /**
1272: * An array of message arguments, which will be used for the message obtained from {@link #message} or
1273: * {@link #messageKey}, whichever is specified.
1274: */
1275: MessageArg[] messageArgs() default {};
1276: }
1277:
1278: /**
1279: * A validation rule that will fail if it is applied to a property that has a non-empty value which is not a number
1280: * within a given range.
1281: * Used within {@link ValidatableProperty} and {@link ValidationLocaleRules}.
1282: */
1283: @Target(ANNOTATION_TYPE)
1284: @Retention(RUNTIME)
1285: public @interface ValidateRange {
1286: /**
1287: * If set to <code>false</code>, then this rule will not be applied.
1288: */
1289: boolean enabled() default true;
1290:
1291: /**
1292: * The minimum integer value; requires {@link #maxInt}, and mutually-exclusive with {@link #minFloat}.
1293: */
1294: long minInt() default 0;
1295:
1296: /**
1297: * The maximum integer value; requires {@link #minInt}, and mutually-exclusive with {@link #maxFloat}.
1298: */
1299: long maxInt() default -1;
1300:
1301: /**
1302: * The minimum floating-point value; requires {@link #maxFloat}, and mutually-exclusive with {@link #minInt}.
1303: */
1304: double minFloat() default 0;
1305:
1306: /**
1307: * The maximum floating-point value; requires {@link #minFloat}, and mutually-exclusive with {@link #maxInt}.
1308: */
1309: double maxFloat() default -1;
1310:
1311: /**
1312: * The JSP 2.0-style expression (e.g., <code>${pageFlow.myProperty}</code>) or literal string that will be used
1313: * as the error message. Mutually-exclusive with {@link #messageKey}.
1314: */
1315: String message() default "";
1316:
1317: /**
1318: * A key in the default message bundle or in the bundle specified by {@link #bundleName} that will be
1319: * used to look up the error message. Mutually-exclusive with {@link #message}.
1320: * @see MessageBundle
1321: */
1322: String messageKey() default "";
1323:
1324: /**
1325: * The name of the message bundle in which to look up the error message. Requires {@link #messageKey} to be set.
1326: * @see MessageBundle
1327: */
1328: String bundleName() default "";
1329:
1330: /**
1331: * An array of message arguments, which will be used for the message obtained from {@link #message} or
1332: * {@link #messageKey}, whichever is specified.
1333: */
1334: MessageArg[] messageArgs() default {};
1335: }
1336:
1337: /**
1338: * A validation rule that will fail if it is applied to a property that has a non-empty value which is not a valid
1339: * credit card number. Note that this performs checks against the string only; it does not consult any sort of
1340: * service to verify the actual credit card number.
1341: * Used within {@link ValidatableProperty} and {@link ValidationLocaleRules}.
1342: */
1343: @Target(ANNOTATION_TYPE)
1344: @Retention(RUNTIME)
1345: public @interface ValidateCreditCard {
1346: /**
1347: * If set to <code>false</code>, then this rule will not be applied.
1348: */
1349: boolean enabled() default true;
1350:
1351: /**
1352: * The JSP 2.0-style expression (e.g., <code>${pageFlow.myProperty}</code>) or literal string that will be used
1353: * as the error message. Mutually-exclusive with {@link #messageKey}.
1354: */
1355: String message() default "";
1356:
1357: /**
1358: * A key in the default message bundle or in the bundle specified by {@link #bundleName} that will be
1359: * used to look up the error message. Mutually-exclusive with {@link #message}.
1360: * @see MessageBundle
1361: */
1362: String messageKey() default "";
1363:
1364: /**
1365: * The name of the message bundle in which to look up the error message. Requires {@link #messageKey} to be set.
1366: * @see MessageBundle
1367: */
1368: String bundleName() default "";
1369:
1370: /**
1371: * An array of message arguments, which will be used for the message obtained from {@link #message} or
1372: * {@link #messageKey}, whichever is specified.
1373: */
1374: MessageArg[] messageArgs() default {};
1375: }
1376:
1377: /**
1378: * A validation rule that will fail if it is applied to a property that has a non-empty value which is not a valid
1379: * email address. Note that this performs checks against the string only; it does not consult any sort of service
1380: * to verify the actual address.
1381: * Used within {@link ValidatableProperty} and {@link ValidationLocaleRules}.
1382: */
1383: @Target(ANNOTATION_TYPE)
1384: @Retention(RUNTIME)
1385: public @interface ValidateEmail {
1386: /**
1387: * If set to <code>false</code>, then this rule will not be applied.
1388: */
1389: boolean enabled() default true;
1390:
1391: /**
1392: * The JSP 2.0-style expression (e.g., <code>${pageFlow.myProperty}</code>) or literal string that will be used
1393: * as the error message. Mutually-exclusive with {@link #messageKey}.
1394: */
1395: String message() default "";
1396:
1397: /**
1398: * A key in the default message bundle or in the bundle specified by {@link #bundleName} that will be
1399: * used to look up the error message. Mutually-exclusive with {@link #message}.
1400: * @see MessageBundle
1401: */
1402: String messageKey() default "";
1403:
1404: /**
1405: * The name of the message bundle in which to look up the error message. Requires {@link #messageKey} to be set.
1406: * @see MessageBundle
1407: */
1408: String bundleName() default "";
1409:
1410: /**
1411: * An array of message arguments, which will be used for the message obtained from {@link #message} or
1412: * {@link #messageKey}, whichever is specified.
1413: */
1414: MessageArg[] messageArgs() default {};
1415: }
1416:
1417: /**
1418: * A validation rule that will fail when it is applied to a property that has a non-empty value, and when a given
1419: * expression does not evaluate to <code>true</code>.
1420: * Used within {@link ValidatableProperty} and {@link ValidationLocaleRules}.
1421: */
1422: @Target(ANNOTATION_TYPE)
1423: @Retention(RUNTIME)
1424: public @interface ValidateValidWhen {
1425: /**
1426: * If set to <code>false</code>, then this rule will not be applied.
1427: */
1428: boolean enabled() default true;
1429:
1430: /**
1431: * The JSP 2.0-style expression (e.g., <code>${actionForm.someProperty==pageFlow.anotherProperty}</code>) that
1432: * must evaluate to <code>true</code>.
1433: */
1434: String condition(); // required
1435:
1436: /**
1437: * The JSP 2.0-style expression (e.g., <code>${pageFlow.myProperty}</code>) or literal string that will be used
1438: * as the error message. Mutually-exclusive with {@link #messageKey}.
1439: */
1440: String message() default "";
1441:
1442: /**
1443: * A key in the default message bundle or in the bundle specified by {@link #bundleName} that will be
1444: * used to look up the error message. Mutually-exclusive with {@link #message}.
1445: * @see MessageBundle
1446: */
1447: String messageKey() default "";
1448:
1449: /**
1450: * The name of the message bundle in which to look up the error message. Requires {@link #messageKey} to be set.
1451: * @see MessageBundle
1452: */
1453: String bundleName() default "";
1454:
1455: /**
1456: * An array of message arguments, which will be used for the message obtained from {@link #message} or
1457: * {@link #messageKey}, whichever is specified.
1458: */
1459: MessageArg[] messageArgs() default {};
1460: }
1461:
1462: /**
1463: * A validation rule that will fail when it is applied to a property that has a non-empty value that is an invalid
1464: * URL.
1465: * Used within {@link ValidatableProperty} and {@link ValidationLocaleRules}.
1466: */
1467: @Target(ANNOTATION_TYPE)
1468: @Retention(RUNTIME)
1469: public @interface ValidateURL {
1470: /**
1471: * If set to <code>false</code>, then this rule will not be applied.
1472: */
1473: boolean enabled() default true;
1474:
1475: /**
1476: * If <code>true</code>, then all schemes are allowed. Mutually-exclusive with {@link #schemes}.
1477: */
1478: boolean allowAllSchemes() default false;
1479:
1480: /**
1481: * An array of schemes that are allowed in the URL. Defaults to <code>{"http", "https", "ftp"}</code>.
1482: * Mutually-exclusive with {@link #allowAllSchemes}.
1483: */
1484: String[] schemes() default { "http", "https", "ftp" };
1485:
1486: /**
1487: * If <code>true</code>, then double '/' characters are allowed in the URL.
1488: */
1489: boolean allowTwoSlashes() default false;
1490:
1491: /**
1492: * If <code>true</code>, then fragments are <strong>not</strong> allowed.
1493: */
1494: boolean disallowFragments() default false;
1495:
1496: /**
1497: * The JSP 2.0-style expression (e.g., <code>${pageFlow.myProperty}</code>) or literal string that will be used
1498: * as the error message. Mutually-exclusive with {@link #messageKey}.
1499: */
1500: String message() default "";
1501:
1502: /**
1503: * A key in the default message bundle or in the bundle specified by {@link #bundleName} that will be
1504: * used to look up the error message. Mutually-exclusive with {@link #message}.
1505: * @see MessageBundle
1506: */
1507: String messageKey() default "";
1508:
1509: /**
1510: * The name of the message bundle in which to look up the error message. Requires {@link #messageKey} to be set.
1511: * @see MessageBundle
1512: */
1513: String bundleName() default "";
1514:
1515: /**
1516: * An array of message arguments, which will be used for the message obtained from {@link #message} or
1517: * {@link #messageKey}, whichever is specified.
1518: */
1519: MessageArg[] messageArgs() default {};
1520: }
1521:
1522: /**
1523: * A variable name/value that is used by {@link ValidateCustomRule}.
1524: */
1525: @Target(ANNOTATION_TYPE)
1526: @Retention(RUNTIME)
1527: public @interface ValidateCustomVariable {
1528: /**
1529: * The variable name.
1530: */
1531: String name();
1532:
1533: /**
1534: * The variable value.
1535: */
1536: String value();
1537: }
1538:
1539: /**
1540: * A validation rule that will fail when a given custom ValidatorPlugIn rule fails.
1541: * Used within {@link ValidatableProperty} and {@link ValidationLocaleRules}.
1542: */
1543: @Target(ANNOTATION_TYPE)
1544: @Retention(RUNTIME)
1545: public @interface ValidateCustomRule {
1546: /**
1547: * The name of the custom rule to run. This rule may be specified in a ValidatorPlugIn config that is declared
1548: * with {@link Controller#customValidatorConfigs}.
1549: */
1550: String rule();
1551:
1552: /**
1553: * An array of variables that will be passed to the custom rule.
1554: */
1555: ValidateCustomVariable[] variables() default {};
1556:
1557: /**
1558: * The JSP 2.0-style expression (e.g., <code>${pageFlow.myProperty}</code>) or literal string that will be used
1559: * as the error message. Mutually-exclusive with {@link #messageKey}.
1560: */
1561: String message() default "";
1562:
1563: /**
1564: * A key in the default message bundle or in the bundle specified by {@link #bundleName} that will be
1565: * used to look up the error message. Mutually-exclusive with {@link #message}.
1566: * @see MessageBundle
1567: */
1568: String messageKey() default "";
1569:
1570: /**
1571: * The name of the message bundle in which to look up the error message. Requires {@link #messageKey} to be set.
1572: * @see MessageBundle
1573: */
1574: String bundleName() default "";
1575:
1576: /**
1577: * An array of message arguments, which will be used for the message obtained from {@link #message} or
1578: * {@link #messageKey}, whichever is specified.
1579: */
1580: MessageArg[] messageArgs() default {};
1581: }
1582:
1583: /**
1584: * A set of validation rules that will be applied for a particular locale. Used within a
1585: * {@link ValidatableProperty}.
1586: */
1587: @Target(ANNOTATION_TYPE)
1588: @Retention(RUNTIME)
1589: public @interface ValidationLocaleRules {
1590: /** A {@link ValidateRequired} rule that will be applied for the given locale. */
1591: ValidateRequired validateRequired() default @ValidateRequired(enabled=false);
1592:
1593: /** A {@link ValidateMinLength} rule that will be applied for the given locale. */
1594: ValidateMinLength validateMinLength() default @ValidateMinLength(enabled=false,chars=-1);
1595:
1596: /** A {@link ValidateMaxLength} rule that will be applied for the given locale. */
1597: ValidateMaxLength validateMaxLength() default @ValidateMaxLength(enabled=false,chars=-1);
1598:
1599: /** A {@link ValidateMask} rule that will be applied for the given locale. */
1600: ValidateMask validateMask() default @ValidateMask(enabled=false,regex="");
1601:
1602: /** A {@link ValidateType} rule that will be applied for the given locale. */
1603: ValidateType validateType() default @ValidateType(enabled=false,type=void.class);
1604:
1605: /** A {@link ValidateDate} rule that will be applied for the given locale. */
1606: ValidateDate validateDate() default @ValidateDate(enabled=false,pattern="");
1607:
1608: /** A {@link ValidateRange} rule that will be applied for the given locale. */
1609: ValidateRange validateRange() default @ValidateRange(enabled=false);
1610:
1611: /** A {@link ValidateCreditCard} rule that will be applied for the given locale. */
1612: ValidateCreditCard validateCreditCard() default @ValidateCreditCard(enabled=false);
1613:
1614: /** A {@link ValidateEmail} rule that will be applied for the given locale. */
1615: ValidateEmail validateEmail() default @ValidateEmail(enabled=false);
1616:
1617: /** A {@link ValidateValidWhen} rule that will be applied for the given locale. */
1618: ValidateValidWhen validateValidWhen() default @ValidateValidWhen(enabled=false,condition="");
1619:
1620: /** A {@link ValidateURL} rule that will be applied for the given locale. */
1621: ValidateURL validateURL() default @ValidateURL(enabled=false);
1622:
1623: /** A {@link ValidateCustomRule} rule that will be applied for the given locale. */
1624: ValidateCustomRule[] validateCustomRules() default {};
1625:
1626: /**
1627: * The language of the locale for which to apply the rules. Mutually-exclusive with
1628: * {@link #applyToUnhandledLocales}.
1629: */
1630: String language() default "";
1631:
1632: /**
1633: * The country of the locale for which to apply the rules. Requires {@link #language}.
1634: */
1635: String country() default "";
1636:
1637: /**
1638: * The variant of the locale for which to apply the rules. Requires {@link #language}.
1639: */
1640: String variant() default "";
1641:
1642: /**
1643: * If set to <code>true</code>, then these rules will be run only for a locale that has <i>no rules</i> defined
1644: * for it specifically. Mutually-exclusive with {@link #language}.
1645: */
1646: boolean applyToUnhandledLocales() default false;
1647: }
1648:
1649: /**
1650: * A set of validation rules that will be applied against a property. Used directly on a property getter method,
1651: * or within a {@link Action}, {@link SimpleAction}, or {@link ValidatableBean} annotation. Contains rules to be
1652: * applied for every locale, and sets of locale-specific rules.
1653: */
1654: @Target({ANNOTATION_TYPE,METHOD})
1655: @Retention(RUNTIME)
1656: public @interface ValidatableProperty {
1657: /**
1658: * The name of the property to run rules against. When this annotation is used on a property getter method,
1659: * <code>propertyName</code> is illegal because the property name is inferred from the method name.
1660: */
1661: String propertyName() default "";
1662:
1663: /**
1664: * The JSP 2.0-style expression (e.g., <code>${bundle.default.someMessageResource}</code>) or literal string
1665: * that will be used as the first argument to all error messages for this property. When this is specified,
1666: * the individual rules can avoid providing specific messages; instead, a default message will be used.
1667: * Mutually-exclusive with {@link #displayNameKey}.
1668: */
1669: String displayName() default "";
1670:
1671: /**
1672: * A key in the default message bundle or in the bundle specified by {@link MessageBundle#bundleName} that will be
1673: * used as the first argument to all error messages for this property. When this is specified,
1674: * the individual rules can avoid providing specific messages; instead, a default message will be used.
1675: * Mutually-exclusive with {@link #displayName}.
1676: * @see MessageBundle
1677: */
1678: String displayNameKey() default "";
1679:
1680: /** A {@link ValidateRequired} rule that will be applied for all locales. */
1681: ValidateRequired validateRequired() default @ValidateRequired(enabled=false);
1682:
1683: /** A {@link ValidateMinLength} rule that will be applied for all locales. */
1684: ValidateMinLength validateMinLength() default @ValidateMinLength(enabled=false,chars=-1);
1685:
1686: /** A {@link ValidateMaxLength} rule that will be applied for all locales. */
1687: ValidateMaxLength validateMaxLength() default @ValidateMaxLength(enabled=false,chars=-1);
1688:
1689: /** A {@link ValidateMask} rule that will be applied for all locales. */
1690: ValidateMask validateMask() default @ValidateMask(enabled=false,regex="");
1691:
1692: /** A {@link ValidateType} rule that will be applied for all locales. */
1693: ValidateType validateType() default @ValidateType(enabled=false,type=void.class);
1694:
1695: /** A {@link ValidateDate} rule that will be applied for all locales. */
1696: ValidateDate validateDate() default @ValidateDate(enabled=false,pattern="");
1697:
1698: /** A {@link ValidateRange} rule that will be applied for all locales. */
1699: ValidateRange validateRange() default @ValidateRange(enabled=false);
1700:
1701: /** A {@link ValidateCreditCard} rule that will be applied for all locales. */
1702: ValidateCreditCard validateCreditCard() default @ValidateCreditCard(enabled=false);
1703:
1704: /** A {@link ValidateEmail} rule that will be applied for all locales. */
1705: ValidateEmail validateEmail() default @ValidateEmail(enabled=false);
1706:
1707: /** A {@link ValidateValidWhen} rule that will be applied for all locales. */
1708: ValidateValidWhen validateValidWhen() default @ValidateValidWhen(enabled=false,condition="");
1709:
1710: /** A {@link ValidateURL} rule that will be applied for all locales. */
1711: ValidateURL validateURL() default @ValidateURL(enabled=false);
1712:
1713: /** A {@link ValidateCustomRule} rule that will be applied for all locales. */
1714: ValidateCustomRule[] validateCustomRules() default {};
1715:
1716: /**
1717: * An array of sets of locale-specific validation rules.
1718: */
1719: ValidationLocaleRules[] localeRules() default {};
1720: }
1721:
1722: /**
1723: * A set of validatable property definitions that will be applied against particular bean type. Used in
1724: * {@link Controller#validatableBeans}.
1725: */
1726: @Target(ANNOTATION_TYPE)
1727: @Retention(RUNTIME)
1728: public @interface ValidatableBean {
1729: /**
1730: * The bean type for which the validation rules will apply.
1731: */
1732: Class type();
1733:
1734: /**
1735: * An array of properties on which to run validation rules.
1736: */
1737: ValidatableProperty[] validatableProperties();
1738: }
1739:
1740: /**
1741: * An optional class-level annotation that can be used on form bean classes with validation rules. It allows the
1742: * form bean class to define its own message bundle that will be used when a message is not found in the default
1743: * message bundle for the page flow in which a validation error message is generated.
1744: */
1745: @Target(TYPE)
1746: @Retention(RUNTIME)
1747: @Inherited
1748: public @interface FormBean {
1749: /**
1750: * The path to the message bundle, as a ServletContext resource. This may be specified with either '/' or'.'
1751: * as the separator, e.g., <code>bundlePath="foo.bar.MyMessages"</code> or
1752: * <code>bundlePath="foo/bar/MyMessages"</code> (in both cases, foo/bar/MyMessages.properties would be found
1753: * on classpath).
1754: */
1755: String messageBundle() default "";
1756: }
1757:
1758: /**
1759: * An annotation that causes a field to get automatically initialized with a reference to a
1760: * {@link org.apache.beehive.netui.pageflow.SharedFlowController}. The annotation is valid within a page flow
1761: * ({@link org.apache.beehive.netui.pageflow.PageFlowController} or a JavaServer Faces backing bean
1762: * {@link org.apache.beehive.netui.pageflow.FacesBackingBean}.
1763: */
1764: @Target(FIELD)
1765: @Retention(RUNTIME)
1766: public @interface SharedFlowField {
1767: /**
1768: * The name of the shared flow, as declared in {@link SharedFlowRef#name} on {@link Controller}.
1769: */
1770: String name();
1771: }
1772:
1773: /**
1774: * An annotation that causes a field to get automatically initialized with a reference to the current
1775: * {@link org.apache.beehive.netui.pageflow.PageFlowController}. The annotation is valid within a JavaServer Faces
1776: * backing class.
1777: */
1778: @Target(FIELD)
1779: @Retention(RUNTIME)
1780: public @interface PageFlowField {
1781: }
1782:
1783: /**
1784: * A class-level annotation that denotes a JavaServer Faces backing bean. An instance of this class will be
1785: * created whenever a corresponding JSF path is requested (e.g., an instance of foo.MyPage will be created for the
1786: * webapp-relative path "/foo/MyPage.faces"). The instance will be released (removed from the user session) when
1787: * a non-matching path is requested. Faces backing beans can hold component references and event/command handlers.
1788: * The bean instance can be databound to with a JSF-style expression like <code>#{backing.myComponent}</code>.
1789: *
1790: * @see CommandHandler
1791: */
1792: @Target(TYPE)
1793: @Retention(RUNTIME)
1794: public @interface FacesBacking {
1795: }
1796:
1797: /**
1798: * Method-level annotation that configures a JavaServerFaces command handler which intends to raise Page Flow
1799: * actions. Valid inside a JSF backing bean. The method signature is the standard one for a JSF command handler:
1800: * <blockquote>
1801: * <code>public String myCommandHandler()</code>
1802: * </blockquote>
1803: * where the <code>String</code> returned is the name of a Page Flow action.
1804: *
1805: * @see FacesBacking
1806: */
1807: @Target(METHOD)
1808: @Retention(RUNTIME)
1809: public @interface CommandHandler {
1810: /**
1811: * An array of RaiseAction annotations, which cause form beans to be sent when particular Page Flow actions
1812: * are raised.
1813: */
1814: RaiseAction[] raiseActions() default {};
1815: }
1816:
1817: /**
1818: * An annotation used within {@link CommandHandler} to specify that a form bean should be sent when a particular
1819: * Page Flow action is raised.
1820: */
1821: @Target(ANNOTATION_TYPE)
1822: @Retention(RUNTIME)
1823: public @interface RaiseAction {
1824: /**
1825: * The name of the Page Flow action.
1826: */
1827: String action();
1828:
1829: /**
1830: * The name of a member variable that will be sent when the action specified with {@link #action} is raised.
1831: */
1832: String outputFormBean() default "";
1833: }
1834: }
|