com.sun.jdmk.discovery
Class DiscoveryResponder

java.lang.Object
  com.sun.jdmk.discovery.DiscoveryResponder

All Implemented Interfaces:

DiscoveryResponderMBean, Serializable, MBeanRegistration

public class DiscoveryResponder
extends Object
implements Serializable, DiscoveryResponderMBean, MBeanRegistration

Implements the MBean that responds to the discovery requests. Any agent that needs to be discovered must instantiate and register a DiscoveryResponder in its MBean server.

When the DiscoveryResponder start method is called, the MBean creates a multicast socket. The DiscoveryResponder then sends a join message to the multicast group. When a DiscoveryResponder is unregistered from the MBean server, or when stop method is called, the MBean sends a leave message to the multicast group. The format of these messages is not exposed. These messages allow DiscoveryMonitor objects to maintain a list of agents with DiscoveryResponder objects registered in their MBean server. When start method is called, and when a join message has been sent, the DiscoveryResponder starts to listen for discovery requests.

The multicast socket uses the group and port specified by the properties multicastGroup and multicastPort. The default values for the group and the port are 224.224.224.224 and 9000. These values can be changed using appropriate constructor. These values can be also changed using setMulticastGroup and setMulticastPort methods when the DiscoveryResponder is OFFLINE.

When join/leave message are sent to the multicast group, a default time-to-live (see java.net.MulticastSocket) value is used. The time-to-live value specifies how many "hops" that the packet is forwarded on the network before it expires. DiscoveryResponder objects use a time-to-live specified by the property ttl. The default time-to-live value is 1. It can be changed using setTimeToLive method when the DiscoveryResponder is OFFLINE.

See Also:

Serialized Form

Field Summary

static int	OFFLINE Marks the "state" property as stopped.
static int	ONLINE Marks the "state" property as running.
static int	STARTING Marks the "state" property as in-transition from OFFLINE to ONLINE.
static int	STOPPING Marks the "state" property as in-transition from ONLINE to OFFLINE.

Constructor Summary

DiscoveryResponder()
Constructs a DiscoveryResponder.

DiscoveryResponder(String multicastGroup, int multicastPort)
Constructs a DiscoveryResponder.

DiscoveryResponder(String multicastGroup, int multicastPort, InetAddress inf)
Constructs a DiscoveryResponder.

DiscoveryResponder(String multicastGroup, int multicastPort, InetAddress inf, String local)
Constructs a DiscoveryResponder.

Method Summary

String	getMulticastGroup() Returns the multicast group.
int	getMulticastPort() Returns the multicast port.
Integer	getState() Returns the state of this DiscoveryResponder.
String	getStateString() Returns the state of this DiscoveryResponder in string form.
int	getTimeToLive() Returns the time-to-live value.
byte[]	getUserData() Returns a byte[] containing the additional information that the user added in the DiscoveryResponse.
boolean	isActive() Tests if the DiscoveryResponder is active.
void	postDeregister() Allows the MBean to perform any operations needed after having been unregistered in the MBean server.
void	postRegister(Boolean registrationDone) Allows the MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.
void	preDeregister() Allows the MBean to perform any operations it needs before being unregistered by the MBean server.
ObjectName	preRegister(MBeanServer server, ObjectName name) Allows the MBean to perform any operations it needs before being registered in the MBean server.
void	setMulticastGroup(String multicastGroup) Sets the multicast group name.
void	setMulticastPort(int multicastPort) Sets the multicast port.
void	setTimeToLive(int ttl) Sets the default Time to Live to be used to send join and leave message to the Multicast group.
void	setUserData(byte[] data) Allows the user to specify additional information in the DiscoveryResponse message.
void	start() Create a multicast socket and join the multicast group.
void	stop() Sends a leave message to the multicast group and leaves it.
boolean	waitState(int state, long timeout) Waits until either the State attribute of this MBean equals the specified state parameter, or the specified timeout has elapsed.

Methods inherited from class java.lang.Object

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

Field Detail

ONLINE

public static final int ONLINE

Marks the "state" property as running.

See Also:

Constant Field Values

OFFLINE

public static final int OFFLINE

Marks the "state" property as stopped.

See Also:

Constant Field Values

STOPPING

public static final int STOPPING

Marks the "state" property as in-transition from ONLINE to OFFLINE.

See Also:

Constant Field Values

STARTING

public static final int STARTING

Marks the "state" property as in-transition from OFFLINE to ONLINE.

See Also:

Constant Field Values

Constructor Detail

DiscoveryResponder

public DiscoveryResponder()

Constructs a DiscoveryResponder.

Creates a discovery responder using the default multicast group (224.224.224.224) and the default multicast port (9000). No check is done on the default values: check will be performed by the start method. The multicast group and port values can be overwritten using setter the properties multicastGroup and multicastPort.

DiscoveryResponder

public DiscoveryResponder(String multicastGroup,
                          int multicastPort)

Constructs a DiscoveryResponder.

Creates a discovery responder using the specified multicast group and the specified multicast port. The multicast group and port values can be overwritten using setter the properties multicastGroup and multicastPort. No check is done on the parameter values: check will be performed by the start method.

Parameters:

multicastGroup - The multicast group name.

multicastPort - The multicast port number.

DiscoveryResponder

public DiscoveryResponder(String multicastGroup,
                          int multicastPort,
                          InetAddress inf)

Constructs a DiscoveryResponder.

This constructor initialize multicast group and a multicast port. No check is done on the parameter values. Check will be performed by the start method.

Parameters:

multicastGroup - The multicast group name.

multicastPort - The multicast port number.

inf - the interface used by a MulticastSocket.

DiscoveryResponder

public DiscoveryResponder(String multicastGroup,
                          int multicastPort,
                          InetAddress inf,
                          String local)

Constructs a DiscoveryResponder.

This constructor initialize multicast group and a multicast port. No check is done on the parameter values. Check will be performed by the start method.

Parameters:

multicastGroup - The multicast group name.

multicastPort - The multicast port number.

inf - the interface used by a MulticastSocket.

local - the local host address used to answer a request.

Method Detail

preRegister

public ObjectName preRegister(MBeanServer server,
                              ObjectName name)
                       throws Exception

Allows the MBean to perform any operations it needs before being registered in the MBean server. If the name of the MBean is not specified, the MBean can provide a name for its registration. If any exception is raised, the MBean will not be registered in the MBean server.

Specified by:

preRegister in interface MBeanRegistration

Parameters:

server - The MBean server in which the MBean will be registered.

name - The object name of the MBean.

Returns:

The name of the MBean registered.

Throws:

Exception - This exception should be caught by the MBean server and re-thrown as an MBeanRegistrationException.

postRegister

public void postRegister(Boolean registrationDone)

Allows the MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.

Specified by:

postRegister in interface MBeanRegistration

Parameters:

registrationDone - Indicates whether or not the MBean has been successfully registered in the MBean server. The value false means that the registration phase has failed.

preDeregister

public void preDeregister()
                   throws Exception

Allows the MBean to perform any operations it needs before being unregistered by the MBean server.

Specified by:

preDeregister in interface MBeanRegistration

Throws:

java.langException - This exception should be caught by the MBean server and re-thrown as an MBeanRegistrationException.

Exception

postDeregister

public void postDeregister()

Allows the MBean to perform any operations needed after having been unregistered in the MBean server.

Specified by:

postDeregister in interface MBeanRegistration

start

public void start()
           throws IOException

Create a multicast socket and join the multicast group. This method creates a multicast socket that is used to broadcast The DiscoveryResponder will then join the multicast group and send a join message. This method has no effect if the DiscoveryResponder is ONLINE or STOPPING or STARTING.

Specified by:

start in interface DiscoveryResponderMBean

Throws:

IOException - The creation of the Multicast socket failed.

stop

public void stop()

Sends a leave message to the multicast group and leaves it. The DiscoveryResponder leaves its multicast group. This method has no effect if the DiscoveryResponder is OFFLINE or STOPPING or STARTING.

Specified by:

stop in interface DiscoveryResponderMBean

isActive

public boolean isActive()

Tests if the DiscoveryResponder is active. True is returned if the DiscoveryResponder is started (DiscoveryResponder has join the multicast group).

Specified by:

isActive in interface DiscoveryResponderMBean

waitState

public boolean waitState(int state,
                         long timeout)

Waits until either the State attribute of this MBean equals the specified state parameter, or the specified timeout has elapsed. The method waitState returns with a boolean value indicating whether the specified state parameter equals the value of this MBean's State attribute at the time the method terminates.

Two special cases for the timeout parameter value are:

• if timeout is negative then waitState returns immediately (i.e. does not wait at all),
• if timeout equals zero then waitState waits until the value of this MBean's State attribute is the same as the state parameter (i.e. will wait indefinitely if this condition is never met).

Specified by:

waitState in interface DiscoveryResponderMBean

Parameters:

state - The value of this MBean's State attribute to wait for. state can be one of: DiscoveryResponder.OFFLINE, DiscoveryResponder.ONLINE, DiscoveryResponder.STARTING, DiscoveryResponder.STOPPING.

timeout - The maximum time to wait for, in milliseconds, if positive. Infinite time out if 0, or no waiting at all if negative.

Returns:

true if the value of this MBean's State attribute is the same as the state parameter; false otherwise.

getMulticastGroup

public String getMulticastGroup()

Returns the multicast group. A multicast group is specified by a class D IP address, those in the range 224.0.0.1 to 239.255.255.255.

Specified by:

getMulticastGroup in interface DiscoveryResponderMBean

Returns:

A string containing the multicast group name.

setMulticastGroup

public void setMulticastGroup(String multicastGroup)
                       throws IllegalStateException

Sets the multicast group name. A multicast group is specified by a class D IP address, those in the range 224.0.0.1 to 239.255.255.255.

Only available if state in OFFLINE

Specified by:

setMulticastGroup in interface DiscoveryResponderMBean

Parameters:

multicastGroup - The multicast group name.

Throws:

IllegalStateException - This method has been invoked while the DiscoveryResponder was ONLINE or STARTING.

getMulticastPort

public int getMulticastPort()

Returns the multicast port. It can be any standard UDP port number.

Specified by:

getMulticastPort in interface DiscoveryResponderMBean

Returns:

The multicast port number.

setMulticastPort

public void setMulticastPort(int multicastPort)
                      throws IllegalStateException

Sets the multicast port. It can be any standard UDP port number.

Only available if state in OFFLINE

Specified by:

setMulticastPort in interface DiscoveryResponderMBean

Parameters:

multicastPort - The multicast port.

Throws:

IllegalStateException - This method has been invoked while the DiscoveryResponder was ONLINE or STARTING.

getTimeToLive

public int getTimeToLive()

Returns the time-to-live value.

Specified by:

getTimeToLive in interface DiscoveryResponderMBean

Returns:

The time-to-live value.

setTimeToLive

public void setTimeToLive(int ttl)
                   throws IllegalStateException

Sets the default Time to Live to be used to send join and leave message to the Multicast group.

Time to Live should an integer verifying the following condition: 0 < ttl <= 255 Only available if state in OFFLINE

Specified by:

setTimeToLive in interface DiscoveryResponderMBean

Parameters:

ttl - The Time to live value.

Throws:

IllegalArgumentException - The input ttl value is not in the 1 to 255 range.

IllegalStateException - This method has been invoked while the DiscoveryResponder was ONLINE or STARTING.

getState

public Integer getState()

Returns the state of this DiscoveryResponder.

Specified by:

getState in interface DiscoveryResponderMBean

Returns:

ONLINE, OFFLINE or STOPPING or STARTING .

getStateString

public String getStateString()

Returns the state of this DiscoveryResponder in string form.

Specified by:

getStateString in interface DiscoveryResponderMBean

Returns:

One of the strings "ONLINE", "OFFLINE" or "STOPPING" or "STARTING".

setUserData

public void setUserData(byte[] data)

Allows the user to specify additional information in the DiscoveryResponse message. The following limitation applies to the length of the byte array parameter: The length of a UDP packet is maximum 64 Kbytes. In addition to the specified user data, the discovery response UDP packet contains the following :

• All string attributes of the MBean server delegate MBean (in the following order: the MBeanServerId; the specification name, vendor and version; and the implementation name, vendor and version).
• The ObjectName and the ConnectorAddresses for each of the connectors/adaptors registered in the MBean server.

The user should take into consideration this content whose size is dependent upon the delegate's string attributes and the number of connectors/adaptors registered in an MBean server. The provided byte array should not exceed the space remaining up to the UDP packet's 64 Kbyte limit. Otherwise, the packet is truncated and information will be lost. For example, if you wish to allow enough space to include up to 100 connectors/adaptors in the discovery response message, the data byte array should not exceed 40 KBytes, approximately.

Specified by:

setUserData in interface DiscoveryResponderMBean

getUserData

public byte[] getUserData()

Returns a byte[] containing the additional information that the user added in the DiscoveryResponse. If no additional information has been added, this method returns null.

Specified by:

getUserData in interface DiscoveryResponderMBean