org.apache.myfaces.orchestra.conversation.annotations
Annotation Type ConversationRequire


@Target(value=TYPE)
@Retention(value=RUNTIME)
public @interface ConversationRequire

Can be used to prevent access to a view where the expected bean state (ie conversation) does not exist, and redirect instead to another view.

This annotation is expected to be applied only to classes that are also a ViewController (i.e. have the ViewController annotation applied, or use one of the other mechanisms the Orchestra ViewController framework supports for mapping views to controller beans). This annotation has no effect when applied to a class that is not acting as a view controller.

When a workflow passes through a number of different views, all views except the first one will expect a conversation to exist, with the beans in that conversation holding appropriate state. If the conversation does not exist then the view will fail to work correctly. Possible causes for this kind of invalid state include:

To resolve these issues, a bean can use the Orchestra ViewController to configure itself as being associated with specific views, then use this ConversationRequire annotation to declare what conversation(s) it expects to exist. When an associated view is activated and the conversation does not exist then a redirect immediately occurs to the specified page - which is usually set to the first page in the relevant workflow.


Required Element Summary
 java.lang.String[] conversationNames
          One or many conversation names the view require as prerequesite.
 
Optional Element Summary
 java.lang.String[] entryPointViewIds
          A list of viewIds which cause this annotation to be ignored.
 java.lang.String navigationAction
          The logical navigation rule to execute if one of the conversations is not running.
 java.lang.String redirect
          The servlet url to redirect to if one of the conversations is not running.
 

Element Detail

conversationNames

public abstract java.lang.String[] conversationNames
One or many conversation names the view require as prerequesite. If one of the configured conversations is not active a redirect or navigationAction will be issued.

redirect

public abstract java.lang.String redirect
The servlet url to redirect to if one of the conversations is not running. Use either this or navigationAction.

Default:
""

navigationAction

public abstract java.lang.String navigationAction
The logical navigation rule to execute if one of the conversations is not running.

In a JSF environment, the specified name must be configured as as a global navigation rule in the application's faces-config.xml file.

Default:
""

entryPointViewIds

public abstract java.lang.String[] entryPointViewIds
A list of viewIds which cause this annotation to be ignored. If this is defined, and the current viewId matches any of the specified viewIds, then no checks for active conversations is done.

A ViewController with this annotation may be referenced from multiple views, eg in a "wizard" type page-flow. In this case, certain conversations are expected to exist in all pages except the first, but for the first ("entry") page of the wizard, they will not exist and the check should not be done. In this scenario, the viewId of the "entry" page can be added to the ignoredViews property of the annotation.

Note that this property does require java code to contain explicit viewIds, which causes tight coupling between view "templates" and java code. However this property is not mandatory; an alternative is to have just a single ViewController per view, in which case this is not needed. State that needs to be shared between views can be on a separate bean.

Default:
""


Copyright © 2009 The Apache Software Foundation. All Rights Reserved.