A Quick Guide to writing JRMS applications

1. Introduction

2. Example application

2.1 Overview

We refer to steps 1-4 as the set-up phase, and step 6 as the tear-down phase.

There are considerable details and variations: for example, what is in the transport profile? Is the data sent as a stream, or in logical blocks? Is data sent continuously (file transfer) or with interleaving gaps (publish and subscribe)? When does the sender stop advertising? We will try to cover some of these below.

2.2 Classes used

        import com.sun.multicast.allocation.MulticastAddressManager;

	import com.sun.multicast.reliable.channel.ChannelManagerFinder;
	import com.sun.multicast.reliable.channel.PrimaryChannelManager;
	import com.sun.multicast.reliable.channel.Channel;

	import com.sun.multicast.reliable.transport.TransportProfile;
	import com.sun.multicast.reliable.transport.tram.TRAMTransportProfile;
	import com.sun.multicast.reliable.transport.RMPacketSocket;

	import java.net.InetAddress;
	import java.net.DatagramPacket;

2.3 JRMS Javadoc Guide

2.4 Creating a transport profile

	private TransportProfile tp;
	private InetAddress addr;
	private int port;
        private Scope scope;
	
	// first, allocate one multicast address


        MulticastAddressManager mam = MulticastAddressManager.getMulticastAddressManager();
        if (scope == null) {
            scope = mam.getScopeList(IPv4AddressType.getAddressType()).findScopeForTTL(ttl);
            if (scope == null)
		throw new IOException("No scope for requested TTL");
        }

        /* get an address with a long duration */
        Lease lease = mam.allocateAddresses(null, scope, (int) ttl,
                    1, startTime, startTime, duration, -1, null);
        InetAddress addr = ((IPv4Address) lease.getAddresses().
                    getFirstAddress()).toInetAddress();

        // create a TRAM transport profile
	// other transports, such as UM, LRMP, can be used instead of TRAM	
	tp = new TRAMTransportProfile(addr,port);

	// set multicast session scope	
	tp.setTTL(ttl);

	// enable ordered delivery
	tp.setOrdered(true);

        // set maximum rate of data transfer
	tp.setMaximumSpeed(speed);

	// and set any other transport-specific parameters
	...

2.5 Creating a channel

	// create a channel
	private PrimaryChannelManager pcm;
	private Channel channel;
	pcm = ChannelManagerFinder.getPrimaryChannelManager(null);
	channel = pcm.createChannel();
	channel.setChannelName(channelName);
	channel.setApplicationName(applicationName);
	channel.setTransportProfile(tp);
	channel.setAbstract(someBlurbAboutThisChannel);
	channel.setAdvertisingRequested(true);

	// plus any other channel parameters
	...

	// once enabled, configuration is complete and advertisement can start
	channel.setEnabled(true);

2.6 Receiver's set-up phase

	// find the channel of interest
	private PrimaryChannelManager pcm;
	private Channel channel;
	pcm = ChannelManagerFinder.getPrimaryChannelManager(null);
	
	// channel lookup is by channelName and applicationName
	// since more than one may match, need to determine the right one
	long channelids[] = pcm.getChannelList(channelName, applicationName);
	
	// loop through the following to find the channel of interest
	channel = pcm.getChannel(channelids[i]);

	// apply application-specific criteria
	checkInterest(channel);
	...

	// extract the transport profile from the advertised channel
	tp = channel.getTransportProfile();

2.7 Socket and data

	private RMPacketSocket ms;
	private DatagramPacket sendPacket;
	byte[]	senddata = new byte[PACKET_SIZE];
	
	// create socket
	ms = channel.createRMPacketSocket(tp, TransportProfile.SENDER);
	// or directly using tp
	// ms = tp.createRMPacketSocket(TransportProfile.SENDER);

	// data transmission
	// repeat the following according to application needs
	preparePacket(senddata);
	sendPacket = new DatagramPacket(senddata, senddata.length);
	ms.send(sendPacket);
	...

	// teardown phase
	ms.close();

	// stop advertising this channel
	// this can be done earlier, e.g. after data transmission starts
	channel.setAdvertisingRequested(false);

	private RMPacketSocket ms;
	private DatagramPacket recvPacket;

	// create socket
	ms = channel.createRMPacketSocket(tp, TransportProfile.RECEIVER);

	// data reception
	// loop through the following until end of transmission recognized
	try {
		recvPacket = ms.receive();
		// application-specific processing
		consumePacket(recvPacket);
	} catch ( SessionDoneException e ) {
		// teardown phase
		ms.close();
	} catch ( JRMSException e) {
		System.out.println("...");
	}

2.8 Stream socket interface

	// create stream socket
	ms = channel.createRMStreamSocket(tp, TransportProfile.SENDER);
	// or directly
	// ms = tp.createMRStreamSocket(TransportProfile.SENDER);
	OutputStream s = ms.getOutputStream();

	// data transmission
	// use whatever stream write method that's convenient, e.g.
	s.write("hello");
	...
	// send
	s.flush();

	// teardown phase
	ms.close();
	channel.setAdvertisingRequested(false);

	// create stream socket at receiver
	ms = channel.createRMStreamSocket(tp, TransportProfile.RECEIVER);
	// or directly
	// ms = tp.createMRStreamSocket(TransportProfile.RECEIVER);
	InputStream s = ms.getInputStream();

	// data reception
	// use whatever read method that's convenient
	byte message[] = new byte[SIZE];
	int len = s.read(message);
	...

	// teardown phase
	ms.close();

3. Operational Tips

This section explains various manual configuration tips when it is desirable/necessary to override autoconfiguration.

3.1 Storing channel parameters in a file

	// Get a LocalPCM
	LocalPCM m = 
          (LocalPCM) ChannelManagerFinder.getPrimaryChannelManager(null);
          
        // Create a serializable channel (LocalChannel) and fill in the
        // parameters, including the transport profile
	LocalChannel c = (LocalChannel) m.createChannel();
	c.setChannelName(channelName);
	c.setApplicationName(applicationName); 
	InetAddress mcastAddress = InetAddress.getByName(address);
	tp = new TRAMTransportProfile(mcastAddress, port);
	tp.setMaxDataRate(speed);
	tp.setTTL(ttl);
	tp.setOrdered(true);    
	c.setTransportProfile(tp);
	c.setEnabled(true);
	
	// Use the LocalPCM fileChannel method to store the channel in
	// a file.  Here, the ChannelName is used as the file name.
	m.fileChannel(c, channelName);

	LocalPCM m =
	  (LocalPCM) ChannelManagerFinder.getChannelManager(null);
	LocalChannel c = (LocalChannel) cm.readChannel(channelFileName);
        TransportProfile tp = c.getTransportProfile();

In the simple package, there is a SimpleChannel program that lets you create a simple channel with a few of the essential parameters that you can enter on the command line.

3.2 Static repair tree configuration

1. When you prepare the transport profile, add the following step:

     tp.setTreeFormationPreference(TRAMTRansportProfile.TREE_FORM_HAMTHA_STATIC_R) 

   This tells all the receivers that the session is using HAMTHA method for for tree formation, and reading a static file is allowed. (HAMTHA stands for "Head Advertisement before data starts and Member Triggered Head Advertisement after data started", which is the default method).

2. For each receiver that needs to have a specific repair head, create a file, named jrmstree.cfg (in the application's directory), that contains the following line:

     [head's ip address] [ttl from head]   

   The ip address is in the a.b.c.d form, and the ttl is the number of hops (in terms of multicast) the receiver is away from the head (e.g. equal to 1 if both hosts are on the same LAN). If you allow a number of possible repair heads, you can include a number of lines in the file.

3. For each receiver that must serve as a head, create a file, named jrmstree.cfg (in the application's directory), that contains the following line:

     [local host's ip address] 0  

   If this receiver must have a specific parent, then it must contain an additional line as described above.

4. Importing new transport protocols into JRMS

1. Select a package name for the transport protocol to be added. For example:

          com.mycompany.newprotocolName  

2. Implement a transport profile class for the new transport. Note that the transport profile class implements the interface specified in TransportProfile.java.
3. Depending on the protocol, implement any one or both of the following interfaces.
   • RMPacketSocket.java
   • RMStreamSocket.java
4. Implement an RMStatistics interface (optional).
5. Compile the package. Applications will have to import the new transport package to use it.

	Transport name and version
	Multicast Address
	Multicast Port
	Ordered Delivery Available
	MultiSender Support Available
	AuthenticationSecurity Specifications
	Maximum Data Rate

	private int mr = DEFAULT_MAX_RATE;
	public int getMaximumDataRate() { return mr; }
	public void setMaximumDataRate(int rate) { mr = rate; }