gnu.cajo.utils

Class Multicast

java.lang.Object

gnu.cajo.utils.Multicast

All Implemented Interfaces:

Runnable

public final class Multicast
extends Object
implements Runnable

This class can listen for UDP multicasts over the network, as well as to send out UDP announcements. The mechanism is rigged to send a reference to a remote object as a zipped MarshalledObject (zedmob). It also allows a listening object to receive announced object referencess via a callback mechanism. A single VM can use as many Multicast objects as it wishes.

Note: this class requires that the network routers be configured to pass IP multicast packets, at least for the multicast address used. If not, the packets will will only exist within the subnet of origination.

Version:

1.0, 01-Nov-99 Initial release

Author:

John Catherino

Field Summary

Fields

Modifier and Type	Field and Description
String	address A reference to the address on which this object is operating.
InetAddress	host The network interface on which this multicast object is listening
InetAddress	iaddr A reference to the address of the calling VM, when the object is listening.
RemoteInvoke	item A reference to a received remote object reference, when the object is listening.
int	port A reference to the port on which this object is operating.

Constructor Summary

Constructors

Constructor and Description
Multicast() The default constructor sets the internal fields to default values which should be sufficient for most purposes.
Multicast(String address, int port) This constructor allows creation of Multicast objects on any appropriate multicast address, and port number.
Multicast(String host, String address, int port) The full constructor allows creation of Multicast objects on any appropriate address, and port number.

Method Summary

Methods

Modifier and Type	Method and Description
void	announce(Object item, int ttl) This method is used to make UDP announcements on the network.
void	announce(Object item, int ttl, Object proxy) This method is used to make UDP announcements on the network.
void	listen(Object callback) This method starts a thead to listen on the construction address and port.
static void	main(String[] args) The application method loads a zipped marshalled object (zedmob) to a proxy from a URL, or a file, and allows it run in this virtual machine.
void	run() The monitor thread, it listens for multicasts.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

host

public final InetAddress host

The network interface on which this multicast object is listening

address

public final String address

A reference to the address on which this object is operating. It is referenced by the called listener, and is valid for the duration of the object's existence.

port

public final int port

A reference to the port on which this object is operating. It is referenced by the called listener, and is valid for the duration of the object's existence.

iaddr

public InetAddress iaddr

A reference to the address of the calling VM, when the object is listening. It is referenced by the called listener, and should be considered valid for the duration of the invocation only.

item

public RemoteInvoke item

A reference to a received remote object reference, when the object is listening. It is referenced by the called listener, and should be considered valid for the duration of the invocation only.

Constructor Detail

Multicast

public Multicast()
          throws UnknownHostException

The default constructor sets the internal fields to default values which should be sufficient for most purposes. The multicast socket address will be set to 244.0.23.162, which is officially registered with IANA for cajo object reference announcements. The UDP port number on which this object will announce and listen is set to 1198, which is is also assigned by the IANA, for cajo object reference acquisition. The object will listen on the same network interface being used for the server's RMI communication. It sends and listens on the machine's default network interface

Throws:

UnknownHostException - If the default network interface could not be resolved, not very likely.

Multicast

public Multicast(String address,
         int port)
          throws UnknownHostException

This constructor allows creation of Multicast objects on any appropriate multicast address, and port number. It uses the default network interface. being used for the server's RMI communication.

Parameters:

address - The multicast socket domain name, or address, on which this object will listen. It can be any address in the range 224.0.0.1 through 239.255.255.255.

port - The UDP port number on which this object will announce and listen, its value can be 0 - 65535. It is completely independent of all TCP port numbers. Application specific meaning could be assigned to port numbers, to identify broadcast types.

Throws:

UnknownHostException - If the specified host address could not be resolved, or is invalid.

Multicast

public Multicast(String host,
         String address,
         int port)
          throws UnknownHostException

The full constructor allows creation of Multicast objects on any appropriate address, and port number. It uses the same network interface being used for the server's RMI communication.

Parameters:

host - The network interface on which to send or receive multicasts, specified when a machine has more than one, otherwise use "0.0.0.0" to send and receive on all of them

address - The multicast socket domain name, or address, on which this object will listen. It can be any address in the range 224.0.0.1 through 239.255.255.255.

port - The UDP port number on which this object will announce and listen, its value can be 0 - 65535. It is completely independent of all TCP port numbers. Application specific meaning could be assigned to port numbers, to identify broadcast types.

Throws:

UnknownHostException - If the specified host address could not be resolved, or is invalid.

Method Detail

announce

public void announce(Object item,
            int ttl)
              throws IOException

This method is used to make UDP announcements on the network. The provided object will first have its startThread method invoked with a null argument, to signal it to start its main processing thread (if it has one). Next it will have its setProxy method invoked remote reference to itself, with which it can share with remote VMs, in an application specific manner (again if it has one).

Parameters:

item - The object reference to be sent in the announcement packet, if it is not already remoted, it will be, automatically.

ttl - The time-to-live of the broadcast packet. This roughly specifies how many multicast enabled routers will pass this packet before automatically discarding it. For example 16, should cover a medium sized LAN. The maximum value is 255, which could theoretically cover the globe, that is, in 1999. A value of 1 confines the packet to its immediate subnet.

Throws:

IOException - If a datagram socket could not be created, or the packet could not be sent.

announce

public void announce(Object item,
            int ttl,
            Object proxy)
              throws IOException

This method is used to make UDP announcements on the network. The provided object will first have its startThread method invoked with a null argument, to signal it to start its main processing thread (if it has one). If the proxy has a setItem method, it will be called with a remote reference to the serving object. If the item implements a setProxy method it will be called with a MarshalledObject containing the proxy object.

Parameters:

item - The object reference to be sent in the announcement packet, if it is not already remoted, it will be, automatically.

ttl - The time-to-live of the broadcast packet. This roughly specifies how many multicast enabled routers will pass this packet before automatically discarding it. For example 16, should cover a medium sized LAN. The maximum value is 255, which could theoretically cover the globe, that is, in 1999. A value of 1 confines the packet to its immediate subnet.

proxy - The proxy object to be sent to requesting clients.

Throws:

IOException - If a datagram socket could not be created, or the packet could not be sent.

listen

public void listen(Object callback)

This method starts a thead to listen on the construction address and port. The listening object will be called on its public multicast method, with a reference to the calling Multicast object. This is to allow the possibility for a single listener, to monitor multiple multicast objects. If a listener is used to monitor multiple multicast objects, it may be invoked reentrantly, otherwise it cannot. Listening will continue until the callback object's multicast method retruns a non-null value. If it does, this method would havt to be called again to restart listening.

Parameters:

callback - An object, presumably local to this VM, which is to receive notifications about announcements.

Throws:

IllegalArgumentException - If the object is actively listening, at the time of the invocation.

run

public void run()

The monitor thread, it listens for multicasts. It will sleep until the arrival of a message. The packet will be reconstituted into a remote object reference, from its zedmob encapsulation. The object reference will be saved into the public item member variable, also the calling VM's address will be extracted into the public address member variable. The listener's multicast method will be called next with a reference to this object. The multicast reference is used to access its public member variables; the remote announcer's reference and IP address, as well as the multicast address and port on which it was received. The second two members are of interest in the case where the same object is listening on multiple multicast objects. If the method returns null, the multicast listening will continue, otherwise it will be stopped. Once stopped it can be restarted by the application as necessary, by invoking the listen method again.

Specified by:

run in interface Runnable

main

public static void main(String[] args)
                 throws Exception

The application method loads a zipped marshalled object (zedmob) to a proxy from a URL, or a file, and allows it run in this virtual machine. It will load an RMISecurityManager to protect the hosting machine from potentially or accidentally dangerous proxies, if not prohibited by the user at startup. It uses the getitem method of the Remote class to load the object. Following loading, it will also create an rmiregistry, and bind a remote reference to it under the name "main". This can allow remote clients to connect to, and interact with, the object. It will announce its startup on a default Multicast object, and then begin listening on it for further announcements, which will be passed to the loaded proxy object. It can be configured using the following arguments, all arguments subsequent to the ones specified in the command line can be omitted:

• args[0] The optional URL where to get the object: file:// http:// ftp:// ..., /path/name , path/name , or alternatively; //[host][:port]/[name], where the object will be requested from a remote rmiregistry and the returned reference cast to the Lookup interface and invoked with a null reference, to return its proxy object. If no arguments are provided, the URL will be assumed to be //localhost:1099/main.
• args[1] The optional external client host name, if using NAT.
• args[2] The optional external client port number, if using NAT.
• args[3] The optional internal client host name, if multi home/NIC.
• args[4] The optional internal client port number, if using NAT.
• args[5] The optional URL where to get a proxy object: file:// http:// ftp:// ..., //host:port/name (rmiregistry), /path/name (serialized), or path/name (class). It will be passed into the loaded object as the sole argument to a setItem method.

Throws:

Exception