com.sun.jdmk.discovery
Interface DiscoveryResponderMBean

All Known Implementing Classes:

DiscoveryResponder

public interface DiscoveryResponderMBean

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.

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	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.

Method Detail

start

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.

Throws:

IOException - The creation of the Multicast socket failed.

stop

void stop()

Sends a leave message to the multicast group and leaves it. The DiscoveryResponder leaves its multicast group.

isActive

boolean isActive()

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

waitState

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).

Parameters:

state - The value of this MBean's State attribute to wait for. state can be one of: CommunicatorServer.OFFLINE, CommunicatorServer.ONLINE, CommunicatorServer.STARTING, CommunicatorServer.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

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.

Returns:

A string containing the multicast group name.

setMulticastGroup

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

Parameters:

multicastGroup - The multicast group name.

Throws:

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

getMulticastPort

int getMulticastPort()

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

Returns:

The multicast port number.

setMulticastPort

void setMulticastPort(int multicastPort)
                      throws IllegalStateException

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

Only available if state in OFFLINE

Parameters:

multicastPort - The multicast port.

Throws:

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

getTimeToLive

int getTimeToLive()

Returns the time-to-live value.

Returns:

The time-to-live value.

setTimeToLive

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

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

Integer getState()

Returns the state of this DiscoveryResponder.

Returns:

ONLINE, OFFLINE or STOPPING.

getStateString

String getStateString()

Returns the state of this DiscoveryResponder in string form.

Returns:

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

setUserData

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.

getUserData

byte[] getUserData()

Returns a byte[] containing the additional information that the user added in the DiscoveryResponse.