Google Protocol Buffers
Overview
Google Protocol Buffers are a way of efficiently serializing structured data. They are language and platform neutral and have been designed to be easily extensible. The structure of your data is defined once, and then specific serialization and deserialization code is produced specifically to handle your data format efficiently.
For general details on using Google protocol buffers, see the section
Google Protocol Buffers in the
Concepts guide.
Using Google Protocol Buffers with Universal Messaging
To create an nProtobuf event, simply build your protocol buffer as normal and pass it into the nProtobuf constructor along with the message type used (see the programmatic example below).
Example.Builder example = Example.newBuilder();
example.setEmail("example@email.com");
example.setName("Name");
example.setAddress1("Norton Foldgate");
example.setHouseNumber(1);
byte[] buffer = example.build().toByteArray();
nProtobufEvent evt = new nProtobufEvent(buffer,"example");
myChannel.publish(evt);
nProtobuf events are received by subscribers in the normal way.
public void go(nConsumeEvent evt) {
if (evt instanceof nProtobufEvent) {
totalMsgs++;
// Get the data of the message
byte[] buffer = evt.getEventData();
if(((nProtobufEvent) evt).getTypeName().equals("BidOffer")){
BidOffer bid = null;
bid = BidOffer.parseFrom(buffer);
//......//
}
}
}
The Enterprise Manager can be used to view, edit and republish protocol buffer events, even if the Enterprise Manager is not running on the same machine as the server. The Enterprise Manager is able to parse the protocol buffer message and display the contents, rather than the binary data.
All descriptors will be automatically synced across the cluster if the channel is cluster-wide.
Programmatic example
//Create a realm node (this is standard administration API connection)
realm = new nRealmNode(new nSessionAttributes(testServer.getDefaultAdapter()));
realm.waitForEntireNameSpace();
//Create a channel with the descriptors.
Path path =Paths.get("../../changeManagement/test/protobuf/SAGTester.fds");
byte[] bytes = Files.readAllBytes(path);
byte[][] descriptors = new byte[1][bytes.length];
descriptors[0]=bytes;
myAttribs.setProtobufDescriptorSets(descriptors);
myChannel = nsession.createChannel(myAttribs);
Then we can publish using the protobuf serialized as usual, along with the "name" of the protobuf message type.
nProtobufEvent pbe = new nProtobufEvent(tester.toByteArray(), "SAGTester");
myChannel.publish(pbe);
You can then use Universal Messaging style message filters, as you would for normal events. e.g. "Name='test'".
Updating the Google Protocol Buffer
The protocol buffer definition files associated with a store (i.e. a channel or a queue) can be updated without requiring the store to be deleted and re-created. Once updated, all filtering will be done with the new protobuf definitions.
To update the protocol buffer definitions for a store programmatically, proceed as follows:
Stores have a method updateProtobufDescriptors(byte[][] descriptors). This takes an array of the descriptors to be applied to the channel. After calling this method, the new descriptors will be loaded and will be used for filtering on the channel from that point onwards. The code for performing this can be seen below.
nChannel myChannel = session.findChannel(channelAttributes);
myChannel.updateProtobufDefinitions(descriptors2);
This API is available via the client API. The Admin API is not required in order to perform these operations.
Instructions for updating the protocol buffer definitions using the Enterprise Manager are available in the section of the Administration Guide.