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 }