com.sun.jdmk.discovery
Interface DiscoveryClientMBean

All Known Implementing Classes:

DiscoveryClient

public interface DiscoveryClientMBean

Provides methods to discover Java DMK agents. A Java DMK agent can only discovered if it has a DiscoveryResponder registered in its MBean server. A discovery operation is executed in two steps:

• a DiscoveryClient broadcasts a discovery request on a multicast group
• Registered DiscoveryResponder MBeans listening on the multicast group catch the request. Each DiscoveryResponder sends a discovery response to the DiscoveryClient

A DiscoveryClient can only reach the DiscoveryResponder objects that listen on the same multicast group and port. The default group is 224.224.224.224 and the default port is 9000. Other values can be used by configuring the multicastGroup and multicastPort properties on the DiscoveryClient and DiscoveryResponder objects.

The scope of the discovery depends on the time-to-live used by the MulticastSocket. By default, the time-to-live is 1. It can be changed by setting the property timeToLive on the DiscoveryClient.

After it has sent its discovery request, a DiscoveryClient waits a finite time for responses. The default is 1 second. This can be customized by setting the timeOut property on the DiscoveryClient.

An application triggers a discovery operation by invoking either the findMBeanServers method or the findCommunicators method on a DiscoveryClient object. These methods represent the discovery result by a Vector of DiscoveryResponse. A DiscoveryResponse is included for each discovered Java DMK agent. It provides the host name and the MBean server information of the agent ( see MBeanServerDelegate and DiscoveryResponse) and optionally the list of communicator (Adaptor and connector) available in the agent.

A DiscoveryResponder can send back responses using two modes:

• Unicast mode. A datagram socket is sent from the DiscoveryResponder to the DiscoveryClient. The response is NOT multicasted to the group. The default datagram socket port is 9001. The datagram socket Inet address is defined by the local host name. It cannot be customized. To enable unicast mode, set the pointToPointResponse property to true. (Unicast mode is enabled by default.)
• Multicast mode. A multicast socket is used between the DiscoveryResponder and the DiscoveryClient. The response is multicasted to the group. This behavior allows DiscoveryMonitor objects to be aware of changes. To enable multicast mode, set the pointToPointResponse property to false.

It is possible to instantiate multiple DiscoveryClient objects with different groups and ports for multicast responses and datagram sockets for unicast responses.

Field Summary

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

Method Summary

Vector	findCommunicators() Discovers all Java DMK agents and associated communicators (adaptors or connectors).
Vector	findCommunicators(String SelectedHost) Discovers all Java DMK agents and associated communicators (adaptors or connectors) present on an host.
Vector	findMBeanServers() Discovers all Java DMK agents.
Vector	findMBeanServers(String SelectedHost) Discovers whether Java DMK agents with a DiscoveryResponder registered in any MBean server is on a host.
String	getMulticastGroup() Returns the multicast group.
int	getMulticastPort() Returns the multicast port.
boolean	getPointToPointResponse() Get the unicast datagram socket mode for the Java DMK agent response.
Integer	getState() Returns the state of this DiscoveryClient.
String	getStateString() Returns the state of this DiscoveryClient in string form.
int	getTimeOut() Returns the time to wait for discovery responses in milliseconds.
int	getTimeToLive() Get the time-to-live.
boolean	isActive() Tests if the DiscoveryClient is active.
void	setMulticastGroup(String multicastGroup) Sets the multicast group name.
void	setMulticastPort(int multicastPort) Sets the multicast port.
void	setPointToPointResponse(boolean pointToPointResponse) Set unicast datagram socket mode for the Java DMK agent response.
void	setTimeOut(int timeOut) Sets the time during which the DiscoveryClient waits for discovery responses.
void	setTimeToLive(int ttl) Sets the default time-to-live for this DiscoveryClient.
void	start() Create a multicast socket and join the multicast group.
void	stop() Leaves the multicast group.

Field Detail

ONLINE

static final int ONLINE

Marks the "state" property as running.

See Also:

Constant Field Values

OFFLINE

static final int OFFLINE

Marks the "state" property as stopped.

See Also:

Constant Field Values

STOPPING

static final int STOPPING

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

See Also:

Constant Field Values

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 DiscoveryClient will then join the multicast group.

Throws:

IOException - The creation of the Multicast socket failed.

stop

void stop()

Leaves the multicast group. The DiscoveryClient leaves its multicast group, and the multicast socket is released.

isActive

boolean isActive()

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

findMBeanServers

Vector findMBeanServers()
                        throws CommunicationException

Discovers all Java DMK agents.

Returns a vector of DiscoveryResponse, one element for each discovered Java DMK agent. Each DiscoveryResponse contains the host name and the MBean server information of the discovered agent ( see MBeanServerDelegate and DiscoveryResponse). The communicators list is not relevant: it is set to null.

Returns:

A vector of DiscoveryResponse.

Throws:

CommunicationException - An error occurred during the discovery.

findMBeanServers

Vector findMBeanServers(String SelectedHost)
                        throws CommunicationException

Discovers whether Java DMK agents with a DiscoveryResponder registered in any MBean server is on a host.

Returns a vector of DiscoveryResponse, one element for each discovered Java DMK agent on the specified host. Each DiscoveryResponse only contains the host name and the MBean server information of the discovered agent ( see MBeanServerDelegate and DiscoveryResponse) of the specified host. The communicators list is not relevant: it is set to null.

Parameters:

SelectedHost - The host on which the discovery is to be performed.

Returns:

A vector of DiscoveryResponse.

Throws:

CommunicationException - An error occurred during the discovery.

findCommunicators

Vector findCommunicators()
                         throws CommunicationException

Discovers all Java DMK agents and associated communicators (adaptors or connectors).

Returns a vector of DiscoveryResponse, one element for each discovered Java DMK agent. Each DiscoveryResponse contains the host name, the MBean server information of the discovered agent ( see MBeanServerDelegate and DiscoveryResponse) and the communicators list.

Returns:

A vector of DiscoveryResponse.

Throws:

CommunicationException - An error occurred during the discovery.

findCommunicators

Vector findCommunicators(String SelectedHost)
                         throws CommunicationException

Discovers all Java DMK agents and associated communicators (adaptors or connectors) present on an host.

Returns a vector of DiscoveryResponse, one element for each discovered Java DMK agent. Each DiscoveryResponse contains the host name, the MBean server information of the discovered agent ( see MBeanServerDelegate and DiscoveryResponse) and the communicators list.

Parameters:

SelectedHost - The host on which the discovery is to be performed.

Returns:

A vector of DiscoveryResponse.

Throws:

CommunicationException - An error occurred during the discovery.

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.

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 the state is OFFLINE

Parameters:

multicastGroup - The multicast group name.

Throws:

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

getMulticastPort

int getMulticastPort()

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

setMulticastPort

void setMulticastPort(int multicastPort)
                      throws IllegalStateException

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

Only available if the state is OFFLINE

Parameters:

multicastPort - The multicast port.

Throws:

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

setTimeOut

void setTimeOut(int timeOut)
                throws IOException

Sets the time during which the DiscoveryClient waits for discovery responses.

This time is expressed in milliseconds. The default value is 1000. If the specified argument is negative or zero, the timeOut is reset to 1000.

The methods findMBeanServers and findCommunicators block until this time elapsed.

Parameters:

timeOut - The timeOut in milliseconds.

Throws:

IOException - If the socket rejected the specified value (See java.net.MulticastSocket). This exception can be thrown only if the state in ONLINE: the actual java.net.MulticastSocket setting is done when the DiscoveryClient is ONLINE.

getTimeOut

int getTimeOut()

Returns the time to wait for discovery responses in milliseconds.

Returns:

The timeOut in milliseconds.

setTimeToLive

void setTimeToLive(int ttl)
                   throws IOException,
                          IllegalArgumentException

Sets the default time-to-live for this DiscoveryClient.

The time-to-live is the number of 'hops' that the multicast packet is forwarded on the network.

Parameters:

ttl - A number between 1 and 255.

Throws:

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

IOException - If the socket rejected the specified value. This means the the state in ONLINE.

getTimeToLive

int getTimeToLive()

Get the time-to-live. The default value is returned if the TimeToLive has not been set.

getPointToPointResponse

boolean getPointToPointResponse()

Get the unicast datagram socket mode for the Java DMK agent response.

Returns:

True indicates that unicast datagram socket is being used. false indicates that the multicast response mode is being used.

setPointToPointResponse

void setPointToPointResponse(boolean pointToPointResponse)

Set unicast datagram socket mode for the Java DMK agent response.

The client sends a request for a unicast response in each discovery request. The multicast group Inet address is used for the unicast response.

Parameters:

pointToPointResponse - The datagram socket mode. false value unsets the use of unicast socket for the response, multicast is used instead.

getState

Integer getState()

Returns the state of this DiscoveryClient.

Returns:

ONLINE, OFFLINE or STOPPING.

getStateString

String getStateString()

Returns the state of this DiscoveryClient in string form.

Returns:

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