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 }