View Javadoc

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one
    3    * or more contributor license agreements.  See the NOTICE file
    4    * distributed with this work for additional information
    5    * regarding copyright ownership.  The ASF licenses this file
    6    * to you under the Apache License, Version 2.0 (the
    7    * "License"); you may not use this file except in compliance
    8    * with the License.  You may obtain a copy of the License at
    9    *
    10   *   http://www.apache.org/licenses/LICENSE-2.0
    11   *
    12   * Unless required by applicable law or agreed to in writing,
    13   * software distributed under the License is distributed on an
    14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    15   * KIND, either express or implied.  See the License for the
    16   * specific language governing permissions and limitations
    17   * under the License.
    18   */
    19
    20  package org.apache.myfaces.orchestra.conversation.annotations;
    21
    22  import java.lang.annotation.Target;
    23  import java.lang.annotation.ElementType;
    24  import java.lang.annotation.Retention;
    25  import java.lang.annotation.RetentionPolicy;
    26
    27  /**
    28   * Can be used to prevent access to a view where the expected bean state
    29   * (ie conversation) does not exist, and redirect instead to another view.
    30   * <p>
    31   * This annotation is expected to be applied only to classes that are also
    32   * a ViewController (i.e. have the ViewController annotation applied, or
    33   * use one of the other mechanisms the Orchestra ViewController framework
    34   * supports for mapping views to controller beans). This annotation has no
    35   * effect when applied to a class that is not acting as a view controller.
    36   * <p>
    37   * When a workflow passes through a number of different views, all views
    38   * except the first one will expect a conversation to exist, with the
    39   * beans in that conversation holding appropriate state. If the
    40   * conversation does not exist then the view will fail to work correctly.
    41   * Possible causes for this kind of invalid state include:
    42   * <ul>
    43   * <li>A user selecting a bookmark
    44   * <li>A user directly manipulating a URL
    45   * <li>A conversation expiring
    46   * </ul>
    47   * <p>
    48   * To resolve these issues, a bean can use the Orchestra ViewController
    49   * to configure itself as being associated with specific views, then
    50   * use this ConversationRequire annotation to declare what conversation(s)
    51   * it expects to exist. When an associated view is activated and the
    52   * conversation does not exist then a redirect immediately occurs to the
    53   * specified page - which is usually set to the first page in the relevant
    54   * workflow.
    55   */
    56  @Target(value = {ElementType.TYPE})
    57  @Retention(value = RetentionPolicy.RUNTIME)
    58  public @interface ConversationRequire
    59  {
    60      /**
    61       * One or many conversation names the view require as prerequesite.
    62       * If one of the configured conversations is not active a redirect or
    63       * navigationAction will be issued.
    64       */
    65      String[] conversationNames();
    66
    67      /**
    68       * The servlet url to redirect to if one of the conversations is not running.
    69       * Use either this <i>or</i> navigationAction.
    70       */
    71      String redirect() default "";
    72
    73      /**
    74       * The logical navigation rule to execute if one of the conversations is not running.
    75       * <p>
    76       * In a JSF environment, the specified name must be configured as as a global navigation
    77       * rule in the application's faces-config.xml file.
    78       */
    79      String navigationAction() default "";
    80
    81      /**
    82       * A list of viewIds which cause this annotation to be ignored. If this is defined,
    83       * and the current viewId matches any of the specified viewIds, then no checks for
    84       * active conversations is done.
    85       * <p>
    86       * A ViewController with this annotation may be referenced from multiple views, eg
    87       * in a "wizard" type page-flow. In this case, certain conversations are expected
    88       * to exist in all pages except the first, but for the first ("entry") page of the
    89       * wizard, they will not exist and the check should not be done. In this scenario,
    90       * the viewId of the "entry" page can be added to the ignoredViews property of
    91       * the annotation.
    92       * <p>
    93       * Note that this property does require java code to contain explicit viewIds,
    94       * which causes tight coupling between view "templates" and java code. However
    95       * this property is not mandatory; an alternative is to have just a single
    96       * ViewController per view, in which case this is not needed. State that needs
    97       * to be shared between views can be on a separate bean.
    98       */
    99      String[] entryPointViewIds() default "";
    100 }