GEMSS Transport and Messaging Framework


Overview

The GEMSS Transport and Messaging framework is an invocation and messaging framework. It enables client applications to make invocations against message based services. Initially support exists for WSDL web services but the general framework can be extended to support other types of messaging too. The framework can be extended to support new types of application data, message encoding and transport protocols. For those familiar with Apache Axis, Transport and Messaging is a direct replacement for that invocation library. A comparison of Transport and Messaging and Axis is provided later.

Users of the framework can use it directly as an invocation library in a similar manner to Axis, this is described in Invoking WSDL Services. Developers can also extend the framework to enable new types of message encoding and processing, this is described in Extending the Framework.

The framework is also distributed as a server side module for Axis. The package is called Web Service Enforcer and is a lightweight version of the full framework that concentrates on policy enforcement and not serialisation. Information on how to deploy the Web Service Enforcer is provided in the section Deploying Web Service Enforcer

The framework is well suited to using the GEMSS Security Context Framework for handling security token, trust and cipher requirements. The Security Context Framework is included with the basic binary distribution because it is so important for message security.

You can access the framework API documentation here.


Configuration

There is a single configuration file for the transport and messaging library. It is called 'gemss.transport.messaging.properties'. At present this file only contains proxy setting details for HTTP and HTTPS but will likely include more settings as functionality increases. The file includes comments on how to set the different options.

The GEMSS security context library is included within the transport and messaging framework. It includes a configuration file that includes information concerning the users Java keystore. In particular information about the location of the keystore, aliases and passwords must be provided. The file includes comments on how to set the different options.

To use the library within your application you should include all the libraries in the folder 'lib' within your application classpath.


Running the Sample Client

There is a sample client included within the package. The sample requires that you have a valid GEMSS keystore and access to the ISS Test Server in Vienna. Since this is not possible for most users a batch script for running the sample client has been removed. A more general sample client is on its way!


Invoking WSDL Services

Invoking WSDL web services is very easy using the transport and messaging framework. It essentially comes down to providing information about the service to invoke and supply the input payload.

Firstly a client must provide an instance of the interface ServiceDescription. The instance must also provide access to instances of the interfaces ServiceInterface, ServicePolicy and ServiceEndpoint. The reference implementation supplied by IT Innovation includes concrete implementations of these interfaces that clients can use, they are called WSDL11InterfaceImp, ServicePolicyImp and WSDLEndpointImp. Alternatively clients can implement their own implementations of these interfaces.

In addition a client must supply an instance of the interface Payload that contains the input data for the service invocation. If the service invocation takes no input data then an empty Payload instance should be supplied. Again the IT Innovation reference implementation includes a concrete implementation of the Payload interface.

The following code snippet shows the basic mechanism for undertaking a service invocation using the transport and messaging framework.

//Create a configuration that points to the directory where configuration files are stored
TransportMessagingConfiguration config = new TransportMessagingConfiguration("/myConfigDir");

//Create an instance of the Transport and Messaging library, this constructor creates one without any configuration
//information.
TransportMessaging transportMessaging = new TransportMessaging(config);

//Create an instance of ServiceInterface for a WSDL1.1 service
WSDL11InterfaceImp wsdlIntf = 
	new WSDL11InterfaceImp("http://myhost.org/messageservice.wsdl","getMessage","getMessagePortType","getMessageSoapBinding");
//Create an instance of ServiceEndpoint for WSDL service binding
WSDLEndpointImp wsdlEndp = new WSDLEndpointImp("http://myhost.org/messageservice.wsdl","getMessageService","getMessagePort"); //Create an payload with single input that is the input message
Payload payload = new PayloadImpl(); DataItem[] dataItems = new DataItem[] {new DataItemImpl("in0",new XSDTypeDescription("inMsg",XSDTypeDescription.XSD_STRING),"messagedata"))};
//Use a policy of no security or extra processing. ServicePolicyImp policyContainer = new ServicePolicyImp();
policyContainer.addIncomingPolicy(new NoPolicyImp());
policyContainer.addOutgoingPolicy(new NoPolicyImp());
InvocationInput input = new InvocationInputImp(payload);
InvocationOutput output = transportMessaging.invokeService(new ServiceDescriptionImp(wsdlIntf,wsdlEndp,policyContainer),input); //output now contains the payload and data items that are the outputs of the invocation if any actually exist.

The JavaDoc API describes the classes and methods in more detail as well other ways to use the transport and messaging component. You can access the API documentation here.



Deploying Web Service Enforcer

The web service enforcer module implements message processing policies within an Axis web service container. It does this by intercepting request and response SOAP messages within an Axis SOAP Handler.

Rerequisites are:

1) Working Tomcat / Axis server installation
2) Make sure that you have copied the latest version of the Xalan jar to your Java 1.4 endorsed directory and $TOMCAT_HOME/common/endorsed directory. You may find it easier to use the xalan.jar file included within the 'lib' directory.

3) If you have 'java:samples.security.LogHandler' within your Axis configuration file 'server-config.wsdd' you should
remove it or comment it out e.g.

 <globalConfiguration> 
   <parameter name="attachments.Directory" value="D:\dev\jakarta-tomcat-4.1.18\webapps\axis\WEB-INF\attachments"/>
   <parameter name="sendXsiTypes" value="true"/>
   <parameter name="sendMultiRefs" value="true"/>
   <parameter name="attachments.implementation" value="org.apache.axis.attachments.AttachmentsImpl"/>
   <parameter name="sendXMLDeclaration" value="true"/>
   <requestFlow>
   <!-- <handler name="track" type="java:samples.security.LogHandler">
   <parameter name="filename" value="MyService.log"/>
   </handler> -->
   </requestFlow>
   </globalConfiguration>


First it is necessary to copy the required files to your Axis installation.

1)Copy all the files in the lib directory to directory 'axis/WEB-INF/lib'


3)Copy the following files in the conf directory to 'axis/WEB-INF/classes'

 	gemss.security.context.properties
   gemss.transport.messaging.properties
   message_codec_providers.xml
   message_processor_providers.xml
	message_enforcement.xml
   security_token_providers.xml
	security_trust_providers.xml
	securiyt_store_providers.xml

	logging.properties

4)If you have a previous phase I1 version of the web service enforcer then you must remove some jar libraries from your Axis installation The libraries conflict with the new version and include:

 	jaxm-api.jar
	jaxm-ri-srcbuild.jar
	dom4j.jar
	saaj-api.jar

	securityctxAPI.jar

	securityctxImpl.jar

	transportmsgAPI.jar

	transportmsgImpl.jar


You can ignore all these files except 'gemss.security.context.properties'. You should edit that file so that it includes
the correct keystore parameters for your server. The file contains information on each setting.

Security is added to your installation using Axis Handlers. This is not ideal but is sufficient for
early implementation.
To set up the handlers you can alter your webservice deployment descriptor (WSDD) file or edit the file
'webapps/axis/WEB-INF/server-config.wsdd' directly. The following procedure edits server-config.wsdd directly. It is a good idea to backup this file before editing it.

1)Find the request flow declaration for your service, create one if one does not exist. Add the GEMSSRequestHandler and GEMSSResponseHandler to it. You must also declare them within the file. Below is an example. You should change parameter values to match your configuration. The directory 'transport.config.dir' is the directory where you have put the file 'gemss.transport.messaging.properties'. The directory 'gemss.security.context.properties' is the directory where you have put the file 'gemss.security.context.properties'. The option 'message.enforcement.file' points to the policy file that defines what policies you want to apply to incoming and outgoing messages.

'gemss.transport.messaging.wsdl.uri' should be set to file location for service interface wsdl, it should be a valid URI since the WSDL will be read for validation purposes.

'gemss.transport.messaging.service.endpoint' should be set to service endpoint for the service

'gemss.transport.messaging.service.porttype' should be set to the portType name for the service, it should be valid since it is used for validation purposes.

'gemss.transport.messaging.service.binding' should be set to the binding name for the service, it should be valid since it is used for validation purposes.

<handler name="gemssrequest" type="java:uk.ac.soton.itinnovation.gemss.transportmessaging.proxies.axis.GEMSSRequestHandler">
   <parameter name="gemss.transport.messaging.config.dir" value="d:\dev\jakarta-tomcat-4.1.18\webapps\axis\WEB-INF\classes"/>
   <parameter name="gemss.security.context.config.dir" value="d:\dev\jakarta-tomcat-4.1.18\webapps\axis\WEB-INF\classes"/>
   <parameter name="gemss.transport.messaging.enforcement.file" value="d:\dev\jakarta-tomcat-4.1.18\webapps\axis\WEB-INF\classes\message_enforcement.xml"/>
	<parameter name="gemss.transport.messaging.wsdl.uri" value="file://d:\dev\jakarta-tomcat-4.1.18\webapps\axis\WEB-INF\classes\AppServer.wsdl"/>
	<parameter name="gemss.transport.messaging.service.endpoint" value="https://www.it-innovation.soton.ac.uk/appserver"/>
	<parameter name="gemss.transport.messaging.service.porttype" value="ApplicationExecuter"/>
	<parameter name="gemss.transport.messaging.service.binding" value="appexSoapBinding"/>

	</handler>
   <handler name="gemssresponse" type="java:uk.ac.soton.itinnovation.gemss.transportmessaging.proxies.axis.GEMSSResponseHandler">
   <parameter name="gemss.transport.messaging.config.dir" value="d:\dev\jakarta-tomcat-4.1.18\webapps\axis\WEB-INF\classes"/>
   <parameter name="gemss.security.context.config.dir" value="d:\dev\jakarta-tomcat-4.1.18\webapps\axis\WEB-INF\classes"/>
   <parameter name="gemss.transport.messaging.enforcement.file" value="d:\dev\jakarta-tomcat-4.1.18\webapps\axis\WEB-INF\classes\message_enforcement.xml"/>
	<parameter name="gemss.transport.messaging.wsdl.uri" value="d:\dev\jakarta-tomcat-4.1.18\webapps\axis\WEB-INF\classes\AppServer.wsdl"/>
	<parameter name="gemss.transport.messaging.service.endpoint" value="https://www.it-innovation.soton.ac.uk/appserver"/>
	<parameter name="gemss.transport.messaging.service.porttype" value="ApplicationExecuter"/>
	<parameter name="gemss.transport.messaging.service.binding" value="appexSoapBinding"/>	
</handler>
   
   ...
   <service name="ApplicationExecuterService" provider="java:RPC">
   <requestFlow>
   <handler type="gemssrequest"/>
   </requestFlow>
   <responseFlow>
   <handler type="gemssresponse"/>
   </responseFlow>
   <parameter name="allowedMethods" value="start, getStatus,    upload, download, getCId"/>
   <parameter name="scope" value="application"/>
   <parameter name="className" value="uk.ac.soton.itinnovation.gemss.dummyappserver.ApplicationExecuterImpl"/>
   </service>


You must reload the Axis webapp for the changes to take effect.

You should be complete. All SOAP invocations made against the protected service will be authenticated at a message level, plus all responses will be secured using the default security policy.


 

Extending the Framework

The transport and messaging framework is very flexible and can be extended in several ways.

Firstly clients to the framework can register a DOM Translator for serialising and deserialising application specific data types. Secondly new types of message encoding can be added to support particular types of service interface and finally a given message can be manipulated by custom message processors that can be plugged-in for particular service policies.

Adding Support for Application Datatypes

Applications can extend the transport and messaging framework so that it can serialise and deserialise application specific objects. To do this applications should create an instance of the interface DataItemDOMTranslator for each application specific object and register the relevent translator with the DataItem instance holding the object. They must also create a concrete instance of the interface TypeDescription that identifies their object to the framework. The following code snippet is an example for doing this

...

MyObject myObj = new MyObject();
DataItem dataItem = new DataItemImpl("MyObject Description",myTypeDescription,myObj);
dataItem.setDataItemDOMTranslator(new myObjectTranslator());
...

When the transport and messaging framework has to serialise a DataItem with type myTypeDescription it will call the translator myObjectTranslator.

Adding Support for New Message Encodings

New message encodings can be added to support new types of service interface. Support of WSDL SOAP encoding is provided with the reference implementation. If an application uses a proprietary message carrier encoding then they can provide concrete implementations of the interfaces MessageCoDecProvider and MessageCoDec that enable processing of a particular type of ServiceInterface. Obviously they must provide the concrete implementation of the interface ServiceInterface that identifies their message encoding to the system. Concrete implementations of the interface MessageCoDecProvider must have a constructor that has no arguments otherwise loading of the provider will fail.

The framework loads instances MessageCoDecProvider by reading the file 'message_codec_providers.xml'. This file is located in the 'conf ' directory of the transport and messaging distribution. The file is an XML document, the schema for the document is described in Provider Schema.

For each additional MessageCoDecProvider there should be single provider element. The element provider-name is a descriptive name for the provider that will be used for logging and client reporting while provider-classname is the full qualified class name for the provider class.

<TODO - extra code samples etc. >

Adding Support for New Message Processing

Once a message is encoded for a particular service interface then it is often necessary to further process the message in order to support policies that individual service providers might require e.g. for security. As an example the transport and messaging framework includes support for a policy of signing the SOAP body using WS-Security encoding.

To add new message processing it is necessary to provide concrete implementations of MessageProcessorProviderSpi and MessageProcessor. In addition you must provide a concrete implementation of the interface Policy so that the framework can select your message processor when an instance of the policy is presented. Concrete implementations of the interface MessageProcessorProvider must have a constructor that has no arguments otherwise loading of the provider will fail.

As with instances of MessageCoDecProvider, the framework loads instances of MessageProcessorProviderSpi by reading the file 'message_processor_providers.xml'. The schema for this file is the same as that used for MessageCoDecProvider loading, more information is available in Provider Schema.

The Web Service Enforcer distribution concentrates on message processing and is deployed within Apache Axis. Policies for the server are defined within the file 'message_enforcement.xml' located in the 'conf' directory of the Web Service Enforcer distribution. This file is an XML file and is described in Message Enforcement Schema.