marshal
Product: xTier™/LWC 2.3 Whitepaper:  Technical Whitepaper	support@fitechlabs.com  Download  Buy
Depends: log  Related: grid  cache  cluster
xTier™ Navigator: cache cluster config email i18n ioc info jmx jndi security log marshal objpool os fs tx uidgen workflow jobs db startup jms grid

Description
The xTier™ 'marshal' service enables high-performance Java-based data exchange. It is important to note that 'marshal' service is network protocol, component model and generally system architecture agnostic and it only concerns itself with transforming native data presentation to and from certain format. For instance, it can be used to generate payloads for SOAP envelopes, binary email attachments or to encode "Value Objects" in an EJB infrastructure. 'marshal' service supports 3 types of output/input "media" for marshalling and demarshalling:

• Byte arrays.
• Standard Java IO streams.
• Native IO byte buffer.

Each formatter provides two types of functionality: encoding/decoding and marshalling/demarshalling.

 Top

Encoding/Decoding
This type of functionality provides basic encoding decoding for primitive and reference types. That functionality can be used to develop custom marshalling and demarshalling protocol if the one provided by xTier™ is not suitable. These encoding and decoding methods provide all necessary basic type transformations right out-of-the-box.

Each of the 3 marshallers can encode and decode primitive types:

• signed 8-bit, 16-bit, 32-bit and 64-bit integer
• 16-bit character
• 32-bit and 64-bit real
• boolean

• String
• Date

 Top

Marshalling/Demarshalling
That functionality implements xTier™ specific marshalling and demarshalling protocol that can be used for high-performance object exchange. The fundamental goal of this protocol is to provide extremely high-performance marshalling and demarshalling infrastructure. Testing shows that 'marshal' service can achieve performance up to 25x times faster than native Java serialization. That translates, for example, into up to 1000x times faster than SOAP-based marshalling that ultimately enables the 'marshal' service to be used in near Real-Time (nRT) applications.

In order to be marshallable and demarshallable an object must implement a simple interface that specifies marshallable object as a map of properties and unique global ID (GUID). Keys and values in property map can be of any of the following types (note that all types are reference types; arrays can be primitive):

• java.lang.Byte
• java.lang.Short
• java.lang.Integer
• java.lang.Long
• java.lang.Float
• java.lang.Double
• java.lang.Character
• java.lang.Boolean
• java.lang.String
• java.util.Date
• java.util.Hashtable (keys and values should also be one of these types)
• java.util.ArrayList (values should also be one of these types)
• Reference to other marshallable object
• Java arrays (elements should also be one of these types or Java primitive types)

 Top

Configuration
'marshal' service is configured via pre-defined xtier_marshal.xml configuration file. Formal specification for this file can be found at ${XTIER_ROOT}/config/dtd/xtier_marshal.dtd file. This file follows standard xTier™ service configuration pattern. The only configurable property is marshallable factories:

1		<xtier-marshal>
2		<region name="examples">
3		<!-- Example factory. -->
4		<factory>
5		<ioc policy="new">
6		<java class="com.fitechlabs.xtier.examples.
7		services.marshal.MarshalFactory"/>
8		</ioc>
9		</factory>
10		</region>
11		</xtier-marshal>

Factories are specified as <factory> with nested IoC objects. See IocService for more details on IoC configuration. Note that if user only uses pre-defined marshallable containers MarshalObject and MarshalObjectEx he does not need to provide any factories (these two containers handled internally by default).

 Top

Examples
Usage of 'marshal' service follows the standard pattern of using xTier™ service: you need to obtain an instance of xTier™ kernel that serves as a service registry. Once you have xTier™ kernel you can get an instance of any service, in our case the marshal service. Once the service instance is obtained the service API can be used. Following example illustrates encoding/decoding functionality:

1		// Get the instance of xTier kernel.
2		XtierKernel xtier = XtierKernel.getInstance();
3
4		// Get the instance of 'marshal' service.
5		MarshalService marshal = xtier.marshal();
6
7		// Get the instance of IO marshaller.
8		IoMarshaller marshaller = marshal.getIoMarshaller();
9
10		// Get the destination stream.
11		OutputStream out = new BufferedOutputStream(
12		new FileOutputStream("test.out"));
13
14		// Encoding.
15		marshaller.encodeFloat64(123.456, out);
16		marshaller.encodeChar16('S', out);
17
18		// Closes stream.
19		out.close();
20
21		// Get the source stream.
22		InputStream in = new BufferedInputStream(
23		new FileInputStream("test.out"));
24
25		// Decoding.
26		System.out.println("Float64 decoding [" +
27		marshaller.decodeFloat64(in) + ']');
28		System.out.println("Char16 decoding [" +
29		marshaller.decodeChar16(in) + ']');

Following example demonstrates marshalling/demarshalling functionality:

1		// Get the instance of xTier kernel.
2		XtierKernel xtier = XtierKernel.getInstance();
3
4		// Get the instance of 'marshal' service.
5		MarshalService marshal = xtier.marshal();
6
7		// Get byte marshaller.
8		ByteMarshaller marshaller = marshal.getByteMarshaller();
9
10		// Creates destination byte array.
11		byte[] arr = new byte[10000];
12
13		// Create & populate user marshallable object
14		MarshalUserObject userObj = new MarshalUserObject();
15
16		// Marshalling.
17		marshaller.marshalObj(userObj, arr, 0);
18
19		// Demarshalling.
20		MarshalUserObject obj = (MarshalUserObject)marshaller.
21		demarshalObj(arr, 0).getObject();

 Top