Serialization becomes a concern within SwitchYard with regards to clustering and execution from a client invoker (introduced in 0.6.0.Beta2). In those cases, objects that represent the content of a SwitchYard Message or objects that are placed within a SwitchYard Exchange's Context become candidates for serialization/deserialization.
Application-Defined Objects
Custom (application-defined) objects that are stored as the content of the message or property of the exchange context are not required to implement java.io.Serializable. This is because SwitchYard does not use the JDK's default object serialization mechanism. Rather, it traverses the object graph, extracting the properties along the way, and stores the values in it's own graph representation, which by default is serialized to/from the JSON format. This is what ends up going over the wire. For this to work, custom objects must follow one of the following two rules:
-
Adhere to the JavaBeans specification. This means a public, no arg constructor, and public getter/setter pairs for every property you want serialized. If you go this (suggested) route, your custom objects will not require any compilation dependencies on SwitchYard.
-
Use SwitchYard annotations to define your serialization strategy (see below).
Annotations
The following annotations, enums, interface and class exist in the org.switchyard.serial.graph package:
-
@Strategy - Here you can define the serialization strategy, including access type, coverage type, and factory (all optional) for your class.
-
access=AccessType - BEAN (default) for getter/setter property access, FIELD for member variable access.
-
coverage=CoverageType - INCLUSIVE (default) for serializing all properties, EXCLUSIVE for ignoring all properties. (See @Include and @Exclude below for overrides.)
-
factory=Factory - Interface for how the class gets instantiated.
-
@Include - Placed on individual getter methods or fields to override CoverageType.EXCLUSIVE.
-
@Exclude - Placed on individual getter methods or fields to override CoverageType.INCLUSIVE.
Level API Usage
As an application developer, you should not have to use SwitchYard's serialization API directly. However, documentation is still presented here.
Serialization is done using Serializers, obtained from the SerializerFactory. For example:
// See SerializerFactory for overloaded "create" methods.
Serializer ser = SerializerFactory.create(FormatType.JSON, CompressionType.GZIP, true);
// to and from a byte array
Foo fooBefore = new Foo();
byte[] bytes = ser.serialize(fooBefore, Foo.class);
Foo fooAfter = ser.deserialize(bytes, Foo.class);
// to and from output/input streams
Bar barBefore = new Bar();
OutputStream out = ...
ser.serialize(barBefore, Bar.class, out);
InputStream in = ...
Bar barAfter = ser.deserialize(in, Bar.class);
Out of the box, the available FormatTypes are SER_OBJECT, XML_BEAN and JSON, and the available CompressionTypes are GZIP, ZIP, or null (for no compression).
In the example Serializer.create invocation above, the 3rd (boolean) argument means that the object graph will be walked via reflection, as per the description in "Application-Defined Objects" above.