inria.net.lrmp
Class Lrmp

java.lang.Object
  |
  +--inria.net.lrmp.Lrmp

public class Lrmp
extends java.lang.Object

an implementation of the Light-weight Reliable Multicast Protocol which provides point-to-multipoint reliable and ordered data delivery service. This object works in multicast mode if the provided network address is a multicast group address, or in unicast mode if it is a classical host IP address. The configuration is set using LrmpProfile by which a number of transmission and reception parameters can be adjusted. Not ordered but reliable packet delivery is currently not implemented.

For performance reason, an application must not modify the packets received from and sent to LRMP. These packets are kept in the cache for possible retransmissions. If necessary, an application should make a local copy before the modification.

An application should implement the LrmpEventHandler interface for processing data packets and events received from LRMP. This event handler interface is also configured through LrmpProfile.

An application should set the data rate to a tolerable range. Lrmp keeps the data rate between the minimum rate and the maximum rate while adapting to the available network resources. Correct rate setting is very important for both reliability and congestion control. It is advised not to use an aggressive data rate in a large scale.

Received data flows from different senders are distinguished by the sender's ID and the network address. Under normal network conditions, Lrmp guarantees that the data packets delivered to the application are in good order. If serious network troubles make this guarantee impossible, Lrmp will notify the application if there is a break in the data sequence through processEvent() of the event handler. Upon this notification, the application may need to drop the current incomplete object.

A LRMP session has a TTL value which is used to limit the scope of the session and should be between 0 and 255. More meaningfully,

For better performance, it is advised to use a TTL value corresponding to the scope of the session. A TTL value which is unnecessarily large may degrade the performance.

The following is a simple example of how to use this object:

 import inria.net.lrmp.*;
 public class Test implements LrmpEventHandler {
 private Lrmp lrmp;
 public Test(String group, int port, int ttl) {
 LrmpProfile profile = new LrmpProfile();
 profile.setEventHandler(this);
 profile.minRate = 8;
 profile.maxRate = 16;
 try {
 lrmp = new Lrmp(group, port, ttl, profile);
 } catch (LrmpException e) {
 System.exit(1);
 }
 lrmp.start();
 }
 public void quit() {
 lrmp.stopSession();
 }
 public void sendTestData() {
 LrmpPacket pack = new LrmpPacket();
 int maxLen = pack.getMaxDataLength();
 pack.setDataLength(maxLen);
 try {
 lrmp.send(pack);
 } catch (LrmpException e) {
 }
 }
 public void processData(LrmpPacket pack) {
 System.out.println("got packet from " + pack.getSourceID() + "@" +
 pack.getAddress());
 System.out.println("buffer " + pack.getDataBuffer() +
 " offset " + pack.getOffset() +
 " length " + pack.getDataLength());
 }
 public void processEvent(int event, Object obj) {
 switch (event) {
 case LrmpEventHandler.UNRECOVERABLE_SEQUENCE_ERROR:
 System.out.println("reception failure!");
 break;
 default:
 break;
 }
 }
 }
 


Field Summary
 java.lang.String Version
          the version of this LRMP implementation.
 
Constructor Summary
Lrmp(java.net.InetAddress addr, int port, int ttl, LrmpProfile prof)
          creates and joins an LRMP multicast session.
Lrmp(java.net.InetAddress addr, int port, LrmpProfile prof)
          creates and joins an LRMP unicast session.
Lrmp(java.lang.String group, int port, int ttl, LrmpProfile prof)
          creates and joins an LRMP multicast session.
Lrmp(java.lang.String addr, int port, LrmpProfile prof)
          creates and joins an LRMP unicast session.
 
Method Summary
 void flush()
          Flushes the output queue.
 java.net.InetAddress getAddress()
          Returns the destination address.
 LrmpDomainStats getDomainStats(int scope)
          Returns the recovery domain statistics.
 LrmpStats getLrmpStats()
          Returns the overall statistics.
 int getPort()
          Returns the port number.
 int getTTL()
          Returns the scope value.
 void send(LrmpPacket pack)
          Sends a data packet to the session.
 void setProfile(LrmpProfile prof)
          Sets the profile.
 void setTTL(int i)
          Sets the scope value.
 void start()
          Starts the session.
 void startSession()
          Deprecated. it is replaced by start().
 void stop()
          Stops the session.
 void stopSession()
          Deprecated. it is replaced by stop().
 LrmpEntity whoami()
          Returns the local user info.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

Version

public final java.lang.String Version
the version of this LRMP implementation.
Constructor Detail

Lrmp

public Lrmp(java.net.InetAddress addr,
            int port,
            int ttl,
            LrmpProfile prof)
     throws LrmpException
creates and joins an LRMP multicast session. The session will be carried on the specified group address and the transport port.
Parameters:
addr - the destination address.
port - the port to use.
ttl - the time-to-live value.
prof - the profile to use.
Throws:
LrmpException - is raised if there is an error in joining or bad profile.

Lrmp

public Lrmp(java.net.InetAddress addr,
            int port,
            LrmpProfile prof)
     throws LrmpException
creates and joins an LRMP unicast session.
Parameters:
addr - the destination address.
port - the port to use.
prof - profile to use.
Throws:
LrmpException - is raised if there is an error in creating socket or bad profile.

Lrmp

public Lrmp(java.lang.String group,
            int port,
            int ttl,
            LrmpProfile prof)
     throws LrmpException
creates and joins an LRMP multicast session.
Parameters:
group - the destination address.
port - the port to use.
ttl - the time-to-live value.
prof - profile to use.
Throws:
LrmpException - is raised if there is an error in joining or bad profile.

Lrmp

public Lrmp(java.lang.String addr,
            int port,
            LrmpProfile prof)
     throws LrmpException
creates and joins an LRMP unicast session.
Parameters:
addr - the destination address.
port - the port to use.
prof - profile to use.
Throws:
LrmpException - is raised if there is an error in creating socket or bad profile.
Method Detail

start

public void start()
Starts the session. After started, the application can send and receive data through this object.

stop

public void stop()
Stops the session. After stopped, the application should not send data to this object.

startSession

public void startSession()
Deprecated. it is replaced by start().

Starts the session.

stopSession

public void stopSession()
Deprecated. it is replaced by stop().

Stops the session.

setProfile

public void setProfile(LrmpProfile prof)
                throws LrmpException
Sets the profile. The configuration parameters will be reset using the new profile.
Parameters:
prof - the profile to use.
Throws:
LrmpException - is raised if this is a bad profile.

setTTL

public void setTTL(int i)
Sets the scope value.

getAddress

public java.net.InetAddress getAddress()
Returns the destination address.

getPort

public int getPort()
Returns the port number.

getTTL

public int getTTL()
Returns the scope value.

getLrmpStats

public LrmpStats getLrmpStats()
Returns the overall statistics.

getDomainStats

public LrmpDomainStats getDomainStats(int scope)
Returns the recovery domain statistics.
Parameters:
scope - the domain scope.

whoami

public LrmpEntity whoami()
Returns the local user info.

send

public void send(LrmpPacket pack)
          throws LrmpException
Sends a data packet to the session. This method will block if the output queue is full in Lrmp.
Parameters:
pack - the packet to send.
Throws:
LrmpException - is raised if the packet is too big.

flush

public void flush()
Flushes the output queue. This method returns only after all enqueued packets are sent to the underlying network.


JavaTM Reliable MulticastTM Service version 1.1
Copyright (c) 2001, Sun Microsystems Laboratories, All rights reserved.