12. Utilities¶
The AMPS C# client includes a set of utilities and helper classes to make working with AMPS easier.
Composite Message Types¶
The client provides a pair of classes for creating and parsing composite message types.
CompositeMessageBuilder
allows you to assemble the parts of a composite message and then serialize them in a format suitable for AMPS.CompositeMessageParser
extracts the individual parts of a composite message type .
For more information regarding composite message types, refer to Chapter 4.3.
Building Composite Messages¶
To build a composite message, create an instance of
CompositeMessageBuilder
, and populate the parts. The
CompositeMessageBuilder
copies the parts provided, in order, to the
underlying message. The builder simply writes to an internal buffer with
the appropriate formatting, and does not allow you to update or change
the individual parts of a message once they’ve been added to the
builder.
The snippet below shows how to build a composite message that includes a
JSON part, constructed as a string, and a binary part consisting of the
bytes from a List
.
StringBuilder sb = new StringBuilder();
sb.append("{\"data\":\"sample\"}");
List<Double> theData = new List<Double>();
// populate theData
...
// Create a byte array from the data: this is
// what the program will send.
byte[] outBytes = null;
using (MemoryStream stream = new MemoryStream())
{
BinaryFormatter format = new BinaryFormatter();
format.Serialize(stream,theData);
outBytes = stream.ToArray();
}
// Create the payload for the composite message.
CompositeMessageBuilder builder;
// Construct the composite
CompositeMessageBuilder builder = new CompositeMessageBuilder();
builder.append(sb.ToString());
builder.append(outBytes, 0, outBytes.Length);
// send the message
Field outMessage = new Field();
builder.setField(outMessage);
topic = "messages";
byte[] topicBytes = System.Text.Encoding.UTF8.GetBytes(topic.ToCharArray());
client.publish(topicBytes, 0, topicBytes.Length, outMessage.buffer, 0, outMessage.length);
Parsing Composite Messages¶
To parse a composite message, create an instance of
CompositeMessageParser
, then use the parse()
method to parse the
message provided by the AMPS client. The CompositeMessageParser
gives you access to each part of the message as a sequence of bytes.
For example, the following snippet parses and prints messages that contain a JSON part and a binary part that contains an array of doubles.
foreach(Message message in client.subscribe("messages"))
{
int parts = parser.parse(message);
string json = parser.getString(0);
Field binary = new Field();
parser.getField(1, binary);
List<double> theData = new List<double>();
using (MemoryStream stream = new MemoryStream())
{
BinaryFormatter format = new BinaryFormatter();
stream.Write(binary.buffer, binary.position, binary.length);
stream.Seek(0, SeekOrigin.Begin);
theData = (List<double>)format.Deserialize(stream);
}
System.Console.WriteLine("Received message with " + parts + " parts");
System.Console.WriteLine(json);
foreach (double d in theData)
{
System.Console.Write(d + " ");
}
System.Console.WriteLine();
}
Notice that the receiving application is written with explicit knowledge of the structure and content of the composite message type.
NVFIX Messages¶
The client provides a pair of classes for creating and parsing NVFIX messages.
NVFIXBuilder
allows you to assemble a NVFIX message and then serialize it in a format suitable for AMPS.NVFIXShredder
extracts the individual fields of a NVFIX message type.
Building NVFIX Messages¶
To build a NVFIX message, create an instance of NVFIXBuilder
, then
add the fields of the message using append()
. NVFIXBuilder
copies the fields provided, in order, to the underlying message. The
builder simply writes to an internal buffer with the appropriate
formatting, and does not allow you to update or change the individual
fields of a message once they’ve been added to the builder.
The snippet below shows how to build a NVFIX message and publish it to the AMPS client.
// create a builder with 1024 bytes of initial capacity
// using the default 0x01 delimiter
NVFIXBuilder builder = new NVFIXBuilder(1024, (byte)1);
// add fields to the builder
builder.append("test", "data");
builder.append("more", "test data");
// create a byte array for the topic
byte[] topic = Encoding.ASCII.GetBytes("messages");
// publish the message to the "messages" topic
client.publish(topic, 0,topic.Length,
builder.getBytes(),0, builder.getSize());
Parsing NVFIX Messages¶
To parse a NVFIX message, create an instance of NVFIXShredder
, then
use the toNVMap()
method to parse the message provided by the AMPS
client. The NVFIXShredder
gives you access to the message data in a
map.
The snippet below shows how to parse and print a NVFIX message.
try
{
// create a shredder -- since this just returns
// the Map, we can reuse the same shredder.
NVFIXShredder shredder = new NVFIXShredder((byte)1);
// iterate through each message and write data to console
foreach (Message msg in ms)
{
System.Console.Write("Got a message");
// shred the message to a dictionary
Dictionary<string, string> fields = shredder.toMap(msg.getData());
// iterate over the keys in the map and display the key and data
foreach (KeyValuePair<string,string> key in fields)
{
System.Console.Write(" " + key + " " + key.Value);
}
}
}
finally // close the message stream to release the subscription
{ ms.close(); }
FIX Messages¶
The client provides a pair of classes for creating and parsing FIX messages.
FIXBuilder
allows you to assemble a FIX message and then serialize it in a format suitable for AMPS.FIXShredder
extracts the individual fields of a FIX message.
Building FIX Messages¶
To build a FIX message, create an instance of FIXBuilder
, then add
the fields of the message using append()
. FIXBuilder
copies the
fields provided, in order, to the underlying message. The builder simply
writes to an internal buffer with the appropriate formatting, and does
not allow you to update or change the individual fields of a message
once they’ve been added to the builder.
The snippet below shows how to build a FIX message and publish it to the AMPS client.
// create a builder with 1024 bytes of initial capacity
// using the default 0x01 delimiter
FIXBuilder builder = new FIXBuilder(1024, (byte)1);
// add fields to the builder
builder.append(0, "data");
builder.append(1, "more data");
// create a string for the topic
string topic = "messages";
// publish the message to the "messages" topic
client.publish(topic.getBytes(), 0, topic.length(), builder.getBytes(), 0, builder.getSize());
Parsing FIX Messages¶
To parse a FIX message, create an instance of FIXShredder
, then use
the toMap()
method to parse the message provided by the AMPS client.
The FIXShredder
gives you access to the message data in a map.
The snippet below shows how to parse and print a FIX message.
try
{
// create a shredder -- since this just returns
// the Map, we can reuse the same shredder.
FIXShredder shredder = new FIXShredder((byte)1);
// iterate through each message and write data to console
foreach (Message msg in ms)
{
System.Console.Write("Got a message");
// shred the message to a map
Dictionary<int, string> fields = shredder.toMap(msg.getData());
// iterate over the keys in the map and display the key and data
foreach (KeyValuePair<int, string> key in fields)
{
System.Console.Write(" " + key + " " + key.Value);
}
}
}
finally // close the message stream to release the subscription
{ ms.close(); }