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.
In order to 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 that will be 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.
In the example above, the gov.nih.nci.cabio.domain.Tissue Class will be serialized/deserialized to/from the
The behavior of the serializers/deserializers are controlled by the Castor Mappingruntime. 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 valid Castor Mappingfile. 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 as it will be non-deterministic which file will be loaded. If the "wrong" file is loaded, then Castor will try to "guess" how to handled a Class it doesn't know about. In these scenarios, you will need to either only have one xml-mapping.xml file on the Classpath, or specify non-default behavior (as detailed below).
To control what 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.
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 what 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) You next need to add a property to your WSDD files to point the framework at 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:
STEP 3.2) In the client-config.wsdd file, add a parameter to the globalConfiguration:
NOTE: Be sure to search for an existing castorMapping property before adding a new one, as 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:
STEP 4) Rebuild and redeploy your service.
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 (such as changes namespaces), based on the settings you selected when you created your service. If you wish to use this file, you should follow the instructions above and use this file as your "mapping file."
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 was 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 also, you need to have castor's mapping.dtd on your classpath. The caCORE SDK generated jars include this for you.|