Scribble.orgCommunity Documentation

Chapter 4. Java Services

4.1. Generating
4.1.1. Extension Classes
4.1.2. Reporting Errors
4.1.3. The Extension Context
4.2. Deploying
4.3. Testing
4.3.1. Changes in version 1.6

4.1. Generating

The 'Choreography->Generate->Java' menu item, selected from the context menu for the appropriate choreography description, will generate extension stub code for each participant, for the appropriate extension points in the choreography description.

The appropriate extension points can be:

The extension classes described in this section can be developed to include the business logic, and also reference other classes within the same project, referenced libraries and other linked projects.

When the 'Choreography->Generate->Java' menu item is selected, if the current project is not a Java project, then it will be converted into one. This will involve creating a new top level source folder 'pi4soa' which will contain the generated stubs. These stubs will be generated in a sub-package beneath the '{basePackage}.{participant}.{choreo}'. The name of the class is derived from the relevant activity's name (or description) field. The base package is derived from the namespace of the participant, which if not explicitly defined will be the choreography's target namespace.

The service endpoint extensions are named after the participant, rather than the choreography package, as the participant may be used (eventually) within multiple choreography packages.

When a silent action is projected to a service endpoint, a Java source file will be created for class {basePackage}.{participant}.{choreo}.{silentActionName}Activity. The base package is derived from the namespace of the participant, which if not explicitly defined will be the choreography's target namespace.

This class will implement the interface org.pi4soa.service.extension.SilentActivityExtension. This interface has a single method that can be implemented to provide the custom functionality associated with the silent action. This method is called 'process', and takes the extension context as the single parameter.

Where the variable has not been defined for an interaction exchange, the service endpoint implementation must determine the source information to be sent. A Java source file will be projected for the class {basePackage}.{participant}.{choreo}.{exchangeName}Send. The base package is derived from the namespace of the participant, which if not explicitly defined will be the choreography's target namespace.

This class will implement the interface org.pi4soa.service.extension.SendActivityExtension. This interface has a single method that can be implemented to provide the custom functionality for sending the message. This method is called 'getMessageContent', and takes the extension context as the single parameter and returns the value of the message contents to be sent.

If the message contents is not currently available to be sent, then the extension method can throw the org.pi4soa.service.UnresolvedConstrainException exception. This will cause the activity to be suspended, and resumed at a later time.

There are two ways in which the session (and activity) can be resumed. The first is where the session is requested to process another event, which may result in the activity being re-evaluated. If the activity is still not ready to return its information, then it should re-throw the exception.

The second approach is where the activity wishes to pro-actively inform the state machine that it is now ready to return its information. To achieve this, the extension should obtain a 'ServiceInformationReference' instance from the extension context, and store it until the information is available. When the information becomes available, then the stored reference should be passed to the ServiceContainer using the 'reEvaluate' method. This will result in the send activity being re-evaluated, and thus returning the available information.

Where the variable has not been defined for an interaction exchange, the service endpoint implementation must determine the received information should be handled. A Java source file will be projected for the class {basePackage}.{participant}.{choreo}.{exchangeName}Receive. The base package is derived from the namespace of the participant, which if not explicitly defined will be the choreography's target namespace.

This class will implement the interface org.pi4soa.service.extension.ReceiveActivityExtension. This interface has a single method that can be implemented to provide the custom functionality associated with receiving the message. This method is called 'processMessage', and takes the extension context and message as parameters.

Non observable conditions may occur in a number of situations within a choreography description. If an activity with an expression field (conditional, when, while) does not declare an expression, or if the expression is only relevant to some of the participants associated with a choreography, then a projection will have a non-observable condition. This also may occur where a choice contains non-conditional elements, to enable a participant to decide which element should be chosen.

For each non-observable condition a Java source file will be created for the class {basePackage}.{participant}.{choreo}.{conditionName}Predicate, where the conditionName may be directly related to the conditional activity or the choice element (if not a conditional activity). The base package is derived from the namespace of the participant, which if not explicitly defined will be the choreography's target namespace.

This class will implement the interface org.pi4soa.service.extension.PredicateExtension. This interface has a single method that can be implemented to provide the non-observable decision. This method is called 'isSatisfied', and takes the extension context as a parameter and returns the boolean result.

If the decision cannot be made at the current time, due to the lack of required information, then an org.pi4soa.service.UnresolvedConstraintException exception should be thrown. If associated with a 'when' activity, then the activity will block awaiting the required information. Otherwise, this exception will result in the choreography failing.

When a service, that has been marked as 'stateless', is projected to a service endpoint, a Java source file will be created for each operation on the service type, based on the class name {basePackage}.{participant}.{serviceType}.{operationName}Invoke. The base package is derived from the namespace of the participant, which if not explicitly defined will be the choreography's target namespace. Only the local part of the serviceType is used.

Each class will implement the interface org.pi4soa.service.extension.SynchronousInvokeExtension. This interface has a single method that can be implemented to provide the custom functionality associated with invoking the operation on the service type. This method is called 'invoke', and takes the extension context and the received message as parameters. The method then returns the value to be placed in a response from the invoked operation, or null if the invoked operation has no return message (i.e. a one-way operation).

When a channel declaration is projected to a service endpoint, and that service endpoint represents the client side of that channel, then a Java source file will be created for class {basePackage}.{participant}.{choreo}.{channelName}Channel. The base package is derived from the namespace of the participant, which if not explicitly defined will be the choreography's target namespace.

This class will implement the interface org.pi4soa.service.extension.ChannelCreationExtension. This interface has a single method that can be implemented to provide the custom functionality associated with obtaining an endpoint reference. This method is called 'discover', and takes the extension context, service type, endpoint reference type, and the org.pi4soa.service.registry.ServiceRegistry implementation as parameters.

The default implementation for this method will simply invoke the 'discover' method on the supplied service registry implementation, using the service and endpoint reference type information. This method implementation only needs to be changed if the endpoint reference discovery needs to be based on different (or additional) information.

The extension code can report errors to the behavioral state machine by raising an exception of the type org.pi4soa.service.ServicException. This exception is associated with an 'exception type' QName, which is used by the state machine to trigger an appropriate exception handler. If an exception handler cannot be located within the choreography that executed the extension, then the exception is recursively propagated to the parent choreography, until either an exception handler is found, or the complete service session has terminated.

The ServiceException provides multiple constructors, one of which takes two string parameters, the first for the description of the exception and the second representing the fully qualified (QName) of the exception type.

The extension context provides useful service session related capabilities and is supplied to all of the extension stub methods. The context interface is org.pi4soa.service.extensions.ExtensionContext.

The capabilities include:

The context provides the ability to get and set variable information associated with the service session.

The context provides methods for reporting details from the extensions. These details are sent to the Service Tracker mechanism which may then subsequently distribute the information to a central monitoring facility.

4.2. Deploying

When the 'Choreography->Deploy->Java' menu item is selected, a generic deployment dialog will be displayed, which is customized to request information specific to the deployment target selected in the choreography description (or project's) properties.

A common aspect of the generic deployment dialog is the lefthand tree panel that displays the list of services to be deployed. Initially all of the services will be selected, which is indicated by a tick in the checkbox associated with the services.

To select or unselect a service, the checkbox accompanying the service name should be used. If all services should be selected or unselected, then the checkbox associated with the root tree node 'Services' should be used.

When a particular service name is selected, the deployment information for that particular service will be presented in the righthand panel.

The final part of the deployment dialog is the general information that applies to the deployment, independent of any particular service. This information is presented in the bottom panel. This information will generally include a 'destination' location to store a Jar containing the deployment information for the list of selected services.

If any errors are detected with the information supplied by the user, then an error message will be displayed and the 'ok' button will be disabled.

4.3. Testing

The Java service testing option enables the choreography description to be executed.

First step is to ensure the project has been configured with an appropriate "pi4soa.xml" file, located in the project's classpath, to define what "client message handler" should be used when running the test. A "message handler" is the transport API used by the pi4soa runtime. Implementations currently exist for Axis and J2EE MDB. Details of configuring the "pi4soa.xml" are provided in the Administrators documentation section for the relevant technologies.

Second step is to provide the service registry information necessary to allow the pi4soa runtime to locate the service(s) being interacted with. The discovery is based on matching the service type (i.e. fully qualified interface name) against a URL to locate the service. For example, if an interface is defined as '{http://www.pi4soa.org}TestService', where the namespace is specified in the braces, then a file called 'pi4soa_service_registry.properties' must be located within the project's classpath with the following entry: 

{http\://www.pi4soa.org}TestService=http://localhost:8080/axis/services/TestService

The first thing to note is that the 'http' is followed by a backslash '\', which is required to ensure that the property file treats the complete interface name (up to the '=') as the key. The value for the interface name key is the URL to the remote service.

Note

It is also possible to provide service registry information in an XML representation, in a file called "pi4soa_service_registry.xml". The structure of this file is explained in the Administrators documentation section.

When the Choreography->Test->Java menu item is selected, associated with a choreography description, a dialog window is presented.

The first item in the dialog window is the 'type' selector. This value identifies where the choreography will executed. This can either be: 


internal
		all choreography participants are executed locally within the Eclipse environment
 
distributed
		remote (distributed) execution where only the client participant is
    	executed in the Eclipse environment and the other participants are executed
    	in a remote environment (e.g. Axis)

The second part of the service testing dialog is used to specify an optional test data file. This information will be used to supply the client participant service instance with some initial variable values that can be subsequently used within the execution of the choreography. If an invalid test data file name is provided, that does not exist or is not XML, then the 'ok' button is disabled.

The format of the test data file is a root element 'serviceTestData' which contains zero or more 'serviceInstance' elements. Each 'serviceInstance' node represents a single execution of the choreography. The 'serviceInstance' element can then contain zero or more 'variable' elements, with a name and optional type attribute (XML schema type). This 'variable' node should contain only a single child node, representing either text or an XML fragment. For example, 


<serviceTestData>
    <serviceInstance>
        <variable name="var1" >
            <mydoc>
                <mynode attr="hello world" />
            </mydoc>
        </variable>
        <variable name="var2" >This is the value</variable>
    </serviceInstance>
    <serviceInstance>
        <variable name="var1" >Second id</variable>
    </serviceInstance>
</serviceTestData>

If a test data file is not specified, then it is the responsibility of the client participant to fabricate its own test information. This may be adequate in situations where the client participant is not used in the production environment, alternatively a test data file needs to be provided.

The choreography is initiated by identifying the participant within the choreography description that is only assuming the role of a client (i.e. it does not provide the implementation of any service itself). If a choreography does not have such a participant, or it has more than one, then it cannot be tested using this mechanism.

In pi4soa version 1.6, there will be support for participant types to share role types. In the current WS-CDL specification this is not permitted, and as a result, restricts how interactions are modelled when dealing with separate parties that actually do behave in the same way. This has led to work being undertaken on features that will be submitted for WS-CDL version 2.

In WS-CDL 2, it will be possible to define more than one behavior associated with a participant type. Currently, each participant type only has a single behavior. This means that the service associated with a participant type may be differently under different circumstances. Each of these behaviors is associated with a participant 'instance'. Therefore, from a testing perspective, we may need to indicate which participant 'instance' (out of potentially many) should be used to initiate the test.

This is achieved by specifying the 'instantiateParticipant' attribute on the 'serviceInstance' element, within the service test data. The value of this attribute must match the name of a 'Participant' declared within the choreography.

The other change that is required is related to internal tests. Currently because each role type can only belong to a single participant type, the routing of internal messages between service containers is based on the service type (which is associated with the role type). However, in pi4soa 1.6, it will not be possible to identify the participant (or service) if the same role type is shared between many participant types.

Therefore, in these situations it will be necessary to create a 'registry' element under the 'serviceInstance' element with the following attributes:

This is only used for internal testing. In a distributed runtime environment, the decision about which actual service (out of many that can implement the serviceType) will be made by the service registry, based on supplied information.