16.3. Protocol Interoperability
Red Hat JBoss Data Grid protocol interoperability allows data in the form of raw bytes to be read/write accessed by different protocols, such as REST, Memcached, library, and Hot Rod, that are written in various programming languages, such as C++ or Java.
By default, each protocol stores data in the most efficient format for that protocol, ensuring transformations are not required when retrieving entries. When this data is required to be accessed from multiple protocols, compatibility mode must be enabled on caches that are being shared.
Enable Compatibility Mode declaratively in Client-Server mode
The compatibility element's enabled parameter is set to true or false to determine whether compatibility mode is in use.
Example 16.1. Compatibility Mode Enabled
<cache-container name="local" default-cache="default" statistics="true">
<local-cache name="default" start="EAGER" statistics="true">
<compatibility enabled="true"/>
</local-cache>
</cache-container>Enable Compatibility Mode programmatically in Library mode
Use a configurationBuilder with the compatibility mode enabled as follows:
ConfigurationBuilder builder = ... builder.compatibility().enable();
Enable Compatibility Mode declaratively in Library mode
The compatibility element's enabled parameter is set to true or false to determine whether compatibility mode is in use.
<namedCache name="compatcache"> <compatibility enabled="true"/> </namedCache>
16.3.1. Use Cases and Requirements
The following table outlines typical use cases for data interoperability in Red Hat JBoss Data Grid.
| Use Case | Client A (Reader or Writer) | Client B (Write/Read Counterpart of Client A) |
|---|---|---|
| 1 | Memcached | Hot Rod Java |
| 2 | REST | Hot Rod Java |
| 3 | Memcached | REST |
| 4 | Hot Rod Java | Hot Rod C++ |
| 5 | Embedded | Hot Rod Java |
| 6 | REST | Hot Rod C++ |
| 7 | Memcached | Hot Rod C++ |
In the provided use cases, marshalling is entirely up to the user. JBoss Data Grid stores a byte[], while the user marshalls or unmarshalls this into meaningful data.
For example, in Use Case 1, interoperability is between a Memcached client (A), and a Hot Rod Java client (B). If Client A wishes to serialize an application-specific Object, such as a
Person instance, it would use a String as a key.
The following steps apply to all use cases:
Client A Side
- A uses a third-party marshaller, such as Protobuf or Avro, to serialize the
Personvalue into a byte[]. A UTF-8 encoded string must be used as the key (according to Memcached protocol requirements). - A writes a key-value pair to the server (key as UTF-8 string, the value as byte arrays).
Client B Side
- B must read a
Personfor a specific key (String). - B serializes the same UTF-8 key into the corresponding byte[].
- B invokes
get(byte[]) - B obtains a byte[] representing the serialized object.
- B uses the same marshaller as A to unmarshall the byte[] into the corresponding
Personobject.
Note
- In Use Case 4, the Protostream Marshaller, which is included with the Hot Rod Java client, is recommended. For the Hot Rod C++ client, the Protobuf Marshaller from Google (https://developers.google.com/protocol-buffers/docs/overview) is recommended.
- In Use Case 5, the default Hot Rod marshaller can be used.
16.3.2. Protocol Interoperability Over REST
When data is stored via the REST interface the values are interpreted by embedded, Hot Rod or Memcached clients as a sequence of bytes. Meaning is given to this byte-sequence using the MIME type specified via the "Content-Type" HTTP header, but the content type information is only available to REST clients. No specific interoperability configuration is required for this to occur.
When retrieving data via REST, primitive types stored are read in their primitive format. If a UTF-8 String has been stored via Hot Rod, Embedded, or Memcached, it will be retrieved as String from REST. If custom objects have been serialized and stored via the embedded or remote cache, these can be retrieved as
application/x-java-serialized-object, application/xml, or application/json. Any other byte arrays are treated as application/octet-stream.
