com.orchestranetworks.interactions
Class InteractionHelper

java.lang.Object
  com.orchestranetworks.interactions.InteractionHelper

public final class InteractionHelper

extends Object

This class provides methods for implementing a UI Service that has been declared as an interaction.

An interaction allows to easily and formally integrate a UI Service into the workflow. It consists in a "component approach": this class allows to manage an interaction, independently from the calling context. Particularly, it ensures secure data sharing between the calling context and EBX.Manager. It also provides static checking and introspection methods.

Life cycle

The expected input and output parameters are specified at design-time and they are valuated at runtime (see "declaration" sections below).

The input parameters are dynamically displayed from the service declaration at design-time. The declared input parameters are not checked at design-time. At runtime, it is up to the implementation of the service to check the actually required input parameters (for example, to throw an exception). The service can access these input parameters by means of the method getInputParameters(Session).

When the interaction is set to the 'complete' state - that is, when the user submits his final updates - the output parameters are added to the persistent interaction log. To do this, the service must invoke the method complete(com.orchestranetworks.interactions.InteractionHelper.ParametersMap, Session).

As long as the interaction is not in the 'complete' state (meaning that the user must perform some work), the interaction cannot be finalized. If there is no specific work to do in the interaction, it can be set to the 'complete' state as soon as the first service request is handled. Once the interaction is 'complete', the user can either 'accept' or 'reject' it.

By default, 'reject' is disabled (the 'reject' button is not displayed). In workflow, reject can be enabled in the user task definition.

Service declaration - Module services

Module services must be defined in module.xml file. The service documentation and its expected parameters must be defined. If the service type contains the token workflow, the service will be available to the workflow's user task definitions.

For a branch-level service, parameter 'branch' is required.

<service name="myService">
	<resourcePath>/service.jsp</resourcePath>
	<type>branch workflow</type>
	<documentation xml:lang="fr-FR">
		<label>Libellé service</label>
		<description>
			Ce service permet de ...
		</description>
	</documentation>
	<documentation xml:lang="en-US">
		<label>Service label</label>
		<description>
			This service allows ...
		</description>
	</documentation>
	<properties>
     <property name="branch" input="true">
			<documentation xml:lang="fr-FR">
				<label>Branche</label>
			</documentation>
			<documentation xml:lang="en-US">
				<label>Branch</label>
				<description>
					This parameter allows to ...
				</description>
			</documentation>
		</property>
		<property name="param1" input="true">
			<documentation xml:lang="fr-FR">
				<label>Mon paramètre d'entrée</label>
				<description>
					Ce paramètre ...
				</description>
			</documentation>
			<documentation xml:lang="en-US">
				<label>My input parameter</label>
				<description>
					This parameter allows to ...
				</description>
			</documentation>
		</property>
		<property name="param2" output="true">
			<documentation xml:lang="fr-FR">
				<label>Mon paramètre de sortie</label>
				<description>
					Ce paramètre ...
				</description>
			</documentation>
			<documentation xml:lang="en-US">
				<label>My output parameter</label>
				<description>
					This parameter allows to ...
				</description>
			</documentation>
		</property>
	</properties>
</service>
  

Service declaration - Adaptation services

Adaptation services are declared in the schema document but, for being identified as interactions, their declaration must be enriched in module.xml file. Their expected parameters must be defined (the documentation is already specified in the schema). Once an adaptation service is defined in module.xml, it will be automatically offered in workflow's user task definitions.

For a schema-level service, parameters 'branch' and 'instance' are required.

<serviceLink serviceName="myService">
	<importFromSchema>/WEB-INF/ebx/schema/schema.xsd</importFromSchema>
	<properties>
     <property name="branch" input="true">
			<documentation xml:lang="fr-FR">
				<label>Branche</label>
			</documentation>
			<documentation xml:lang="en-US">
				<label>Branch</label>
				<description>
					This parameter allows to ...
				</description>
			</documentation>
		</property>
     <property name="instance" input="true">
			<documentation xml:lang="fr-FR">
				<label>Adaptation</label>
			</documentation>
			<documentation xml:lang="en-US">
				<label>Adaptation</label>
				<description>
					This parameter allows to ...
				</description>
			</documentation>
		</property>
		<property name="param1" input="true">
			<documentation xml:lang="fr-FR">
				<label>Mon paramètre d'entrée</label>
				<description>
					Ce paramètre ...
				</description>
			</documentation>
			<documentation xml:lang="en-US">
				<label>My input parameter</label>
				<description>
					This parameter allows to ...
				</description>
			</documentation>
		</property>
		<property name="param2" output="true">
			<documentation xml:lang="fr-FR">
				<label>Mon paramètre de sortie</label>
					<description>
						Ce paramètre ...
					</description>
			</documentation>
			<documentation xml:lang="en-US">
				<label>My output parameter</label>
				<description>
					This parameter allows to ...
				</description>
			</documentation>
		</property>
	</properties>
</serviceLink>
  

Service extension

It is possible to extend services already declared in module.xml: the user can define their own label, description and add properties. Service extension is available for built-in services, module services and adaptation services.

For built-in services, the user cannot extend output properties (only input properties). The 'extends' attribute is the service key of the built-in extended service: ServiceKey. For the default service, the 'extends' attribute must be empty.

For a module service and for an adaptation service, the service extension and extended service must be defined in the same module.xml file. The 'extends' attribute is the name of the extended service.

For an adaptation service, the user must specify the schema location of the extended service.

It is not possible to extend a service extension.

<serviceExtension name="serviceBuiltInCreationExtended" extends="@creation" >
	<documentation xml:lang="fr-FR">
		<label>Extension du service de création</label>
		<description>
			Ce service ...
		</description>
	</documentation>
	<documentation xml:lang="en-US">
		<label>Built in creation service extension</label>
		<description>
			This service ...
		</description>
	</documentation>
	<properties>
		<property name="paramAdded" input="true">
			<documentation xml:lang="fr-FR">
				<label>Paramètre ajouté</label>
				<description>
					Ce paramètre ...
				</description>
			</documentation>
			<documentation xml:lang="en-US">
				<label>Added parameter</label>
				<description>
					This parameter ...
				</description>
			</documentation>
		</property>
	</properties>
</serviceExtension>
<serviceExtension name="serviceBuiltInDefaultExtended" extends="" >
	<documentation xml:lang="fr-FR">
		<label>Extension du service par défaut</label>
		<description>
			Ce service ...
		</description>
	</documentation>
	<documentation xml:lang="en-US">
		<label>Built in default service extension</label>
		<description>
			This service ...
		</description>
	</documentation>
	<properties>
		<property name="paramAdded" input="true">
			<documentation xml:lang="fr-FR">
				<label>Paramètre ajouté</label>
				<description>
					Ce paramètre ...
				</description>
			</documentation>
			<documentation xml:lang="en-US">
				<label>Added parameter</label>
				<description>
					This parameter ...
				</description>
			</documentation>
		</property>
	</properties>
</serviceExtension>
<serviceExtension name="moduleService" extends="serviceName" >
	<documentation xml:lang="fr-FR">
		<label>Extension d'un service du module</label>
		<description>
			Ce service ...
		</description>
	</documentation>
	<documentation xml:lang="en-US">
		<label>Module service extension</label>
		<description>
			This service ...
		</description>
	</documentation>
	<properties>
		<property name="paramAddedInput" input="true">
			<documentation xml:lang="fr-FR">
				<label>Paramètre ajouté</label>
				<description>
					Ce paramètre ...
				</description>
			</documentation>
			<documentation xml:lang="en-US">
				<label>Added parameter</label>
				<description>
					This parameter ...
				</description>
			</documentation>
		</property>
		<property name="paramAddedOutput" output="true">
			<documentation xml:lang="fr-FR">
				<label>Paramètre ajouté</label>
				<description>
					Ce paramètre ...
				</description>
			</documentation>
			<documentation xml:lang="en-US">
				<label>Added parameter</label>
				<description>
					This parameter ...
				</description>
			</documentation>
		</property>
	</properties>
</serviceExtension>
<serviceExtension name="schemaService" extends="serviceName" fromSchema="/WEB-INF/ebx/schema/schema.xsd" >
	<documentation xml:lang="fr-FR">
		<label>Extension d'un service d'adaptation</label>
		<description>
			Ce service ...
		</description>
	</documentation>
	<documentation xml:lang="en-US">
		<label>Adaptation service extension</label>
		<description>
			This service ...
		</description>
	</documentation>
	<properties>
		<property name="paramAdded" input="true">
			<documentation xml:lang="fr-FR">
				<label>Paramètre ajouté</label>
				<description>
					Ce paramètre ...
				</description>
			</documentation>
			<documentation xml:lang="en-US">
				<label>Added parameter</label>
				<description>
					This parameter ...
				</description>
			</documentation>
		</property>
		<property name="paramAddedOutput" output="true">
			<documentation xml:lang="fr-FR">
				<label>Paramètre ajouté</label>
				<description>
					Ce paramètre ...
				</description>
			</documentation>
			<documentation xml:lang="en-US">
				<label>Added parameter</label>
				<description>
					This parameter ...
				</description>
			</documentation>
		</property>
	</properties>
</serviceExtension>
  

(see javadoc from package com.orchestranetworks.workflow)

Nested Class Summary

static class

InteractionHelper.ParametersMap Contains the parameters of the interaction.

Constructor Summary

InteractionHelper()

Method Summary

static void	complete(InteractionHelper.ParametersMap outputParameters, Session aSession) Sets the interaction to the 'complete' state.
static InteractionHelper.ParametersMap	getInputParameters(Session aSession) Returns the initial input parameters of the current interaction.
static InteractionHelper.ParametersMap	getInternalParameters(Session aSession) Returns the internals parameters of the current interaction.
static boolean	isComplete(Session aSession) Returns true if the current interaction has been set as complete.
static void	setInternalParameters(InteractionHelper.ParametersMap internalParameters, Session aSession) Sets the internal parameters.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InteractionHelper

public InteractionHelper()

Method Detail

getInputParameters

public static InteractionHelper.ParametersMap getInputParameters(Session aSession)
                                                          throws InteractionException

Returns the initial input parameters of the current interaction.

Parameters:

aSession - the session of the currently executing service.

Returns:

the input parameters map, if session is enabled as an interaction; else returns null.

Throws:

InteractionException

getInternalParameters

public static InteractionHelper.ParametersMap getInternalParameters(Session aSession)
                                                             throws InteractionException

Returns the internals parameters of the current interaction. Map is not automatically initialized (null by default). Use setInternalParameters(com.orchestranetworks.interactions.InteractionHelper.ParametersMap, Session) in order to initialize it.

Parameters:

aSession - the session of the currently executing service.

Returns:

the internal parameters map, if session is enabled as an interaction and if the map has been initialized; else returns null.

Throws:

InteractionException

setInternalParameters

public static void setInternalParameters(InteractionHelper.ParametersMap internalParameters,
                                         Session aSession)
                                  throws InteractionException

Sets the internal parameters.

Parameters:

internalParameters - specifies the technical parameters, used for the execution of the service.

aSession - the session of the currently executing service.

Throws:

InteractionException

complete

public static void complete(InteractionHelper.ParametersMap outputParameters,
                            Session aSession)
                     throws InteractionException

Sets the interaction to the 'complete' state.

The interaction must be in 'complete' state, so that the 'Accept' button is displayed. For more information, see interaction's life cycle.

Parameters:

outputParameters - specifies the result of the interaction; it must conform to the declaration of the service (properties with the output attribute set to true).

aSession - the session of the currently executing service.

Throws:

InteractionException - if the session is not enabled as an interaction, or if an output parameter is not found in the associated service declaration.

isComplete

public static boolean isComplete(Session aSession)
                          throws InteractionException

Returns true if the current interaction has been set as complete.

Parameters:

aSession - the session of the currently executing service.

Returns:

true if the interaction has been set as complete, else returns false.

Throws:

InteractionException

See Also:

complete(com.orchestranetworks.interactions.InteractionHelper.ParametersMap, Session)