This document describes how to write the merge specification for the concast service. You can get the best idea of the behavior of concast daemons and merge specification by reading the concast Internet draft [1]. This document describes details of the current java implementation of the Merged, specified in [1] and helps to write new merge specifications.
A Merge Specification consists of three java classes. The first class implements 5 methods: getTag, merge, done, buildMsg, and checkAndDecrypt. The second class should contain the definition of the Datagram Equivalence Class (DEC) state that the spec can keep. The third class should implement the encryption method. The first class has to subclass concast.base.SpecBase, the second class should subclass concast.base.MergeState, and the third class should subclass concast.base.EncryptionSpecBase.
In general, all classes that are important to the code developer are in the concast.base package. (Note: The only other class required to compile merge spec is concast.merged.UNL)
First, let's look at data structures used by merge specs. ConcastPacket contains the byte array which holds the concast packet.
Note: In the current implementation, merge spec receives incoming data packet with all packet headers starting with a transport header. That is, if an application uses UDP packets to transmit concast data, then merge spec receives packets starting witha UDP header and then application data. When merge spec builds new packets, it also has to build transport headers.
Now, let's look at 5 methods that code developers must implement in the merge spec class.
int getTag(ConcastPacket msg)
Implementation of this method has to calculate the DEC number by given ConcastPacket. If there is only one DEC per concast application, this method can just always return a constant value.
void merge(MergeState state, ConcastPacket msg)
This method has to merge new incoming packet with the merge state. Note: if it is the first time that merge method is called for the given tag value, then merged will supply new empty merge state as parameter.
Note: merge() method can modify the state, Merged will save all changes that this method makes.
boolean done(MergeState state)
This method should return true if the merged framework should build and send the message and return false if this operation has to be postponed.
Code developer can schedule the second part of processing (call of done() and buildMsg()) by setting up the timer using userAPI.setTimer() call.
Note: argument to setTimer() is absolute time in milliseconds. getTimer() method is available to retrieve the current value of the scheduled timer.
PacketAndState buildMsg(MergeState state)
This method has to return both concast packet and the state. If code developer wants to remove state associated with a current DEC, s/he can return null as the new merge state.
boolean checkAndDecrypt(ConcastPacket msg)
This method should return true if the concast message was successfully decrypted. If the code developer is not using encryption, s/he can just return true without altering the concast packet.
Note: Concast packet has to contain all headers stating with a transport header (all headers, except an IP header).
Now, let's look at the encryption method that code developers must implement in the merge spec class.
ConcastPacket Encrypt(ConcastPacket msg)
This method returns the encrypted concast packet. If the code developer does not want to use encryption, s/he can just return the concast packet unchanged.
Please look at example applications located at MERGEd/Java/concast/apps/
References
[1] draft-calvert-concast-svc-02.txt (local copy)