Configure Castor Serialization

Overview

An overview of serialization and deserialization can be found in the caGrid Serialization page. This page details how to configure the serialization process for services and clients using the caGrid support for caCORE SDK Serialization. However, this process is not specific to SDK-created systems and will work for any service wishing to use Castor serialization.

Default Behavior

In order to enact this serialization and deserialization, the serializer and deserializer must be specified as gov.nih.nci.cagrid.encoding.SDKSerializerFactory and gov.nih.nci.cagrid.encoding.SDKDeserializerFactory, respectively, as shown below, for each Class sent over the grid. This needs to be done in both the client-config.wsdd and server-config.wsdd. Introduce automatically handles the editing of these files based on the serialization settings configured in Introduce. Furthermore, when using the Data Service wizard and selecting an SDK-created system, this is automatically done.

<ns3:typeMapping encodingStyle=""
 serializer="gov.nih.nci.cagrid.encoding.SDKSerializerFactory"
 deserializer="gov.nih.nci.cagrid.encoding.SDKDeserializerFactory"
 type="ns1:gov.nih.nci.cabio.domain.Tissue" qname="ns2:Tissue"
 xmlns:ns1="http://xml.apache.org/axis/wsdd/providers/java"
 xmlns:ns2="gme://caCORE.caCORE/3.1/gov.nih.nci.cabio.domain"
 xmlns:ns3="http://xml.apache.org/axis/wsdd/"/>

In the example above, the gov.nih.nci.cabio.domain.Tissue Class will be serialized/deserialized to/from the following element:

{gme://caCORE.caCORE/3.1/gov.nih.nci.cabio.domain}Tissue

The behavior of the serializers/deserializers are controlled by the Castor Mapping runtime. The default behavior is to attempt to load a resource from the Classpath called xml-mapping.xml. For an SDK-created system, this file will exist in the client.jar created by the SDK. This file/resource is expected to be a valid Castor Mapping file. If there is only one of these on the classpath, then the default behavior will be sufficient. However, if multiple SDK-created systems are on the classpath, or if the standard caCORE client.jar is there as well as your project-specific client.jar, then there will be a conflict because it will be indeterminable as to which file will be loaded. If the "wrong" file is loaded, then Castor will try to guess how to handle that Class. In these scenarios, you will need to either only have one xml-mapping.xml file on the Classpath or specify non-default behavior.

Non-Default Behavior

To control which mapping file is used, the framework allows you to specify a setting in the WSDD files. As the WSDD files control the behavior in a specific context (such as a service, or client), this allows fine grain control over the behavior in a specific context. In the event multiple mapping files need to exist in the same Classpath, you will need to rename or repackage them. Then specify which one to use by configuring the appropriate WSDD files.

Steps to Specifying a Specific Mapping File:

STEP 1) Locate the mapping file you are using. You can create your own or extract it from your client.jar if you used the caCORE SDK.

STEP 2) Place this file in your source code tree, somewhere that is uniquely package-qualified to your service, and optionally rename it if the package alone will not be unique. For example, if your service is in the gov.nih.nci.cagrid.tutorial package, you could place the mapping file in that folder/package. Files in your "service package" will be placed in your *-common.jar and deployed with your service.

STEP 3) Next you need to add a property to your WSDD files to point the framework to this new location. You will need to edit both the server-config.wsdd in the root directory of your service as well as the client-config.wsdd in your client package (gov.nih.nci.cagrid.tutorial.client).

STEP 3.1) In the server-config.wsdd file, add a parameter to the service section:

<?xml version="1.0" encoding="UTF-8"?>
<deployment xmlns="http://xml.apache.org/axis/wsdd/" ...>
  <service name="..." provider="Handler" use="literal" style="document">
    <parameter name="className" value="..." />
    <wsdlFile>...</wsdlFile>
    ...
    <parameter name="castorMapping" value="/gov/nih/nci/cagrid/tutorial/xml-mapping.xml" />       <------- ADD THIS HERE
  </service>
  ...
</deployment>

STEP 3.2) In the client-config.wsdd file, add a parameter to the globalConfiguration:

<deployment xmlns="http://xml.apache.org/axis/wsdd/" xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
 <globalConfiguration>
  <parameter name="adminPassword" value="admin" />
   ...
  <parameter name="castorMapping" value="/gov/nih/nci/cagrid/tutorial/xml-mapping.xml" />       <------- ADD THIS HERE
  <requestFlow>
  ...
</deployment>

NOTE: Be sure to search for an existing castorMapping property before adding a new one; the last property specified takes precedence. If you used the Data Service SDK wizard in Introduce in the caGrid 1.0 release, you likely have an existing property (specifying the default xml-mapping.xml file) right before the end of the globalConfiguration section:

</handler>
  </responseFlow>
 <parameter name="castorMapping" value="xml-mapping.xml" /></globalConfiguration>               <------- LOOK HERE
 <transport name="java" pivot="java:org.apache.axis.transport.java.JavaSender" />

STEP 4) Rebuild and redeploy your service.

Data Service Support

The SDK Data Service wizard will automatically extract your SDK-created mapping file from your client.jar and place it in the root directory of your service, modifying it appropriately (e.g., change namespaces) based on the settings selected at the creation of the service. If you wish to use this file, you should follow the instructions above and use it as your "mapping file."

Troubleshooting

The framework is fairly verbose when debug logging is turned on; it will indicate whether or not a castorMapping property is set, which mapping it is trying to load, and whether or not it is successful. You can follow the instructions here to turn on DEBUG level logging for the gov.nih.nci.cagrid.encoding package to see this information.

Note: you need to have castor's mapping.dtd on your classpath. The caCORE SDK-generated jars include this.

Knowledgebase