Low-Level Multicast Java API
This documents is a proposal for a low-level multicast Java API. All multicast protocols have similarities, which may be generalised into a set of abstract classes, which depend upon subclassing to both integrate with the native code and implement the particularities of each protocol.
The content of the document focuses on the design of the API, providing necessary comments when deemed necessary. The current java.net package of SUN has been well designed but did not foresee the need of extension of some classes, while not providing a generic enough basis class, as is the case of the DatagramPacket. Therefore, there is a need for the inclusion within the java.net package of a more generic set of classes. Also presented in this document is the package relative to the Simple Multicast (SM) protocol.
This is a working document, thus much detail is missing, however it will promote discussion and exchange of ideas. Certain issues, such as exceptions, were not considered at this point.
These extensions are relevant to the set of generic classes that should be available to facilitate the development and integration of multicast protocols using the java language. Some assumptions are made to avoid redoing the base API again. It is important to stress that the motivation is to make the least disruption to the current package.
This class is necessary to hold the tuple that contains the address. In classical UDP and Multicast the tuple is just one element containing x.x.x.x, while in other proposals such as SM it will be a pair consisting of (C,M). See smTuple for further details.
public abstract Tuple extends Object implements Serializable {
//This might not be the best way of doing it, but it gives the main idea behind it.
private byte[][] m_elements;
//Basically calls the protected method buildTuple();
public Tuple();
//Various methods.
protected abstract void buildTuple();
public void addElement(int identifier, byte[] value);
public void removeElement(int identifier);
public byte[] getElement(int identifier);
private void writeObject(java.io.ObjectOutputStream out)
private void readObject(java.io.ObjectInputStream in)
//It is assumed (maybe wrongly) that the elements are of identical in number of bytes. This //approach allows to ease the identification of the tuple compliance with either Ipv4 or Ipv6 //merely by verifying the length of the Tuple.
public static int getLength();
}
This is an existing class of the java.net API, however the way the class is presented makes its adoption by other multicast protocols not originally foreseen as awkward. Also the fact that the class is final does not help very much either. There is no support for particular requirements such as the need to have tuples to discriminate the address space. Subclassing does not even solve simple issues such as the usage of IPv6 since all the methods of the class are Ipv4 oriented. An alternative approach is given as follows:
public abstract class InetAddress extends Object implements Serializable {
//unless there exists some mechanism to determine what are the numeric constants representing //each type of protocol, the best approach is to have a discriminative String id.
private String m_type;
//this contains the actual address. In classic multicast or UDP it will simply be x.x.x.x while in //SM and EXPRESS it will be (C,M) and (S,E) respectively.
private Tuple m_tuple;
//Constructor
public InetAddress();
public InetAddress(Tuple tuple);
//methods. Most are straightforward.
public Tuple getTuple ();
public void setTuple (Tuple tuple);
public String getType();
public boolean equals (Object obj);
//This may mostly correspond to the local IP address
public static InetAddress getLocalTuple();
}
Currently there is the assumption in the java.net package that datagram packets are either simple UDP or classic multicast, meaning that the only difference is the class of the address being used by the packets. However most alternative proposals are emerging, requiring more information in the header that simply is not available at this time. The solution is either to modify the DatagramPacket to handle differently each header or have a separate class named header that is different according to the particular protocol in use.
public abstract class Header extends Object implements Serializable {
private InetAddress m_address;
public abstract byte[] buildHeader();
public InetAddress getAddress();
public void setAddress(InetAddress address);
}
Current implementation of DatagramPacket is final making extending it impossible. But it is required to include the method to set and get the header of the packet.
public class DatagramPacket extends Object {
private byte[] m_data;
private smInetAddress m_address;
private int m_port
private Header m_header;
private int m_bufferSize;
//Cosntructors and methods
public DatagramPacket(byte [] buf, int length);
public DatagramPacket(byte [] buf, int length, Header header, int port);
public Header getHeader();
public void setHeader(Header header);
public InetAddress getAddress();
public byte[] getData();
public int getLength();
public int getPort();
public int getBufferSize();
public void setBufferSize(int size);
public void setAddress(smInetAddress address);
public void setData(byte[] data);
public void setLength(int length);
public void setPort(int port);
}
This package comprises the entire set of classes specific to the simple multicast (SM) protocol.
The SocketOptions provides the traditional set of available socket options, however it is not very useful when considering new protocols. Therefore, each multicast protocol must extend the base class just to include more options, since the two existing methods for set/get may be used. All options are public and final.
interface smSocketOptions extends SocketOptions
According the current SM draft, one option has been clearly identified:
Nevertheless many others may appear that are specific to the protocol, such as:
This class extends Tuple merely to provide it with the specific information to how the elements of the Tuple are named.
public class smTuple extends Tuple {
//Identifier fields for positioning the elements in the tuple.
public final int _CORE = 0;
public final int _ADDRESS = 1;
//Naturally this needs to be implemented.
protected void buildTuple();
//The current specification assumes that the class is compliant with Ipv4, so the returned value is //4.
public int getLenth();
}
Naturally this class will extend from the proposed InetAddress in this document. Basically the class specialises InetAddress to SM. However there is no real need considering that the information is contained within the smTuple. Nevertheless the class does know how to get extra information like translating IP addresses to logical names.
public class smInetAddress extends InetAddress {
private byte[] m_core;
private byte[] m_address;
private boolean m_nativeSupport;
public byte[] getCore ();
public byte[] getAddress();
public String getHostCore();
public String getHostAddress();
public String getHostName();
public boolean isNativeSM();
}
This is a particular class of SM since it does not exist in other multicast protocols (I think). It is of great importance, considering the possibilities it provides.
public class Mask extends Object {
private byte[] m_value;
public Mask(byte[] value);
public byte[] getValue();
}
The smHeader extends the Header previously defined, adding the particularities of the SM, such as the mask.
public class smHeader extends Header {
private Mask m_mask
public void setMask(Mask mask);
public Mask getMask();
}
This class is closely coupled with the native code that guarantees the functioning of the protocol. It provides in addition to the traditional blocking features the possibility of callback very similar to the delegation model of events in the JFC/AWT.
public abstract class smDatagramSocketImpl extends DatagramSocketImpl {
//The following two methods register the interest in receiving from a particular mask or range of //masks
protected abstract int registerMask(Mask mask);
protected abstract void deregisterMask(Mask mask);
protected abstract int registerMask(Mask[] mask);
protected abstract void deregisterMask(Mask[] mask);
//The following methods attach to each mask or range the appropriate listener that is interested //in handling the packets that arrive.
protected abstract void addListener(MaskListener listener, int maskID);
protected abstract void removeListener(MaskListner listner, int maskID);
//In addition to the traditional send this method determines which mask to be used. Naturally //this overrides the mask been previously set on the packer.
protected abstract void send(DatagramPacket packet, byte[] mask);
}
This class is basically the DatagramSocket but implementing with additional methods.
public class smDatagramSocket extends DatagramSocket {
public int registerMask(Mask mask);
public void deregisterMask(Mask mask);
public int registerMask(Mask[] mask);
public void deregisterMask(Mask[] mask);
public void addListener(MaskListener listener, int maskID);
public void removeListener(MaskListner listner, int maskID);
public void join(smInetAddress address);
public void leave(smInetAddress address);
}
This class is the one used in conjunction with the MaskEvent to enable the delegation mechanism to support callback.
public interface MaskListener {
public void handlePacket(MaskEvent event);
}
This interface may be more elaborated by adopting the usual Adapter paradigm available in the JFC/AWT API. The reason for the MaskListener to exist at this level is to bring the application into the network layer in a transparent way.
This class is the actual event that provides the information to what type of event it is and its corresponding value.
public abstract class MaskEvent extends Object {
public byte[] m_value;
public int m_type;
public Header m_source;
}
This class needs to be elaborated further, but the purpose is to make it extensible to implement whatever protocol the application wants. Therefore, the application defines subclasses of MaskEvent, which correspond to the data payload of the underlying network protocols.
IDEAS:
Apply the usage of filters at low level.
There is no approach to componentise a protocol in its basic elements: Filter, ActiveQueue, Dispatcher(what else is necessary?). I think this approach would provide the application complete flexibility to handle the network.