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 }