This tutorial walks you through using Symphony serialization when developing client applications and services. Symphony serialization allows clients and services written in different programming languages to communicate with each other. For example, you can use a C++ client with a Java service.
You should also use Symphony serialization if you are concerned with performance and memory usage.
In this tutorial, you build samples in C++, Java, and .NET, package and deploy the service in either language, and use the C++, Java, COM, and .NET clients to submit work to the service.
When you add an application through the DE PMC, you must use the Add Application wizard. This wizard defines a consumer location to associate with your application, deploys your service package, and registers your application. After completing the steps with the wizard, your application should be ready to use.
Client and service structures are the same in cross-language clients and services as those of same-language clients and services, except for serialization.
The Java and .NET APIs support two modes of serialization: native serialization and Symphony serialization. The same-language samples for both of these APIs demonstrate the use of native serialization. On the other hand, the C++ and cross-language samples implement Symphony serialization.
Symphony serialization allows communication between clients and services written in different languages. For example, Symphony serialization allows you to use a C++ client with a Java service.
Symphony serialization is achieved in all languages by deriving from the SOAM Message object and implementing the appropriate serialization handlers.
You also use Symphony serialization if you are concerned with performance and memory usage.
In Java and .NET, a character may consume 1-2 bytes of memory while in C++ a character consumes 1 byte of memory.
Since byte arrays are represented differently across the supported languages, you need to use a special method when serializing this data. To write a byte array in C++ and Java, use the writeByteArray() method on the OutputStream. To write a byte array in .NET, use the WriteByteArray() method on the OutputStream.
Note that the C++ “long” type and "unsigned long type" has been removed from the Compatibility Matrix for Symphony releases 3.1 and later due to portability issues across platforms and languages. While the C++ long type can still be serialized/de-serialized in the API, developers should consider using “int” for 32-bit values and “long long” for 64-bit values to maintain platform independence. Refer to the section on 64-bit Application Support for more information.
In the client, in CrossLanguageClient.java, when sending input to the service, session.sendTaskInput() takes in the message object instead of java.io.Serializable.
In MyMessage.java, implement the onSerialize() handler to write data to the provided OutputStream. Symphony calls this method when you send data.
In native serialization, the Java serialization mechanisms automatically serialize your data. For Symphony serialization, you need to specify the data you want to serialize.
In CrossLanguageService.java, create an instance of the message object and pass your own instance to populate the inMsg message object. The populateTaskInput() method fills in the object.
In MyMessage.java, implement the onDeSerialize() handler to read data from the provided InputStream. Symphony calls this method when you retrieve data.In native serialization, the Java serialization mechanisms automatically deserialize your data. For Symphony serialization, you need to specify the data to read from the stream.
In CrossLanguageService.java, pass the output message object to send output back to the client. Symphony invokes your onSerialize() handler to send the output back to the client.
In your client, in CrossLanguageClient.cs, when sending input to the service, session.SendTaskInput() takes a message object instead of a [serializable] object.
In MyMessage.cs, implement the OnSerialize() handler to write data to the provided OutputStream. Symphony calls this method when you send data.
In native serialization, .NET serialization mechanisms automatically serialize your data. For Symphony serialization, you need to specify the data you want to serialize.
In CrossLanguageService.cs, create an instance of the message object and pass your own instance to populate the inputMsg object. The PopulateTaskInput() method fills in the object.
In MyMessage.cs, implement the OnDeserialize() handler to read data from the provided InputStream. Symphony calls this method when you retrieve data.
In native serialization, .NET serialization mechanisms automatically deserialize your data. For Symphony serialization, you need to specify the data to read from the stream.
In CrossLanguageService.cs, pass the output message object to send output back to the client. Symphony invokes your OnSerialize() handler to send the output back to the client.
In your client, in CrossLanguageClient.cs, create an instance of the message object and pass your own instance to populate the outputMessage object. The PopulateTaskOutput() method fills in the object. Symphony invokes your OnDeSerialize() handler to retrieve the output.