com.sun.jdmk.discovery
Class DiscoveryClient

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

All Implemented Interfaces:

DiscoveryClientMBean, Serializable, MBeanRegistration

public class DiscoveryClient
extends Object
implements Serializable, DiscoveryClientMBean, MBeanRegistration

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

See Also:

Serialized Form

Field Summary

static int	OFFLINE Marks the "state" property as stopped.
static int	ONLINE Marks the "state" property as running.
protected int	state Reflects the current state of the discovery client.

Fields inherited from interface com.sun.jdmk.discovery.DiscoveryClientMBean

STOPPING

Constructor Summary

DiscoveryClient()
Constructs a DiscoveryClient.

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

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

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

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

state

protected transient volatile int state

Reflects the current state of the discovery client.

Constructor Detail

DiscoveryClient

public DiscoveryClient()

Constructs a DiscoveryClient.

This constructor initializes multicast group and a multicast port to the default values (224.224.224.224 and 9000). No check is done on the default values. Check will be performed by the start method.

DiscoveryClient

public DiscoveryClient(String multicastGroup,
                       int multicastPort)

Constructs a DiscoveryClient.

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.

DiscoveryClient

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

Constructs a DiscoveryClient.

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.

Since:

Java DMK 5.0

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

Specified by:

start in interface DiscoveryClientMBean

Throws:

IOException - The creation of the Multicast socket failed.

stop

public void stop()

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

Specified by:

stop in interface DiscoveryClientMBean

isActive

public boolean isActive()

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

Specified by:

isActive in interface DiscoveryClientMBean

findMBeanServers

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

Specified by:

findMBeanServers in interface DiscoveryClientMBean

Returns:

A vector of DiscoveryResponse.

Throws:

CommunicationException - An error occurred during the discovery.

findMBeanServers

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

Specified by:

findMBeanServers in interface DiscoveryClientMBean

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

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

Specified by:

findCommunicators in interface DiscoveryClientMBean

Returns:

A vector of DiscoveryResponse.

Throws:

CommunicationException - An error occurred during the discovery.

findCommunicators

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

Specified by:

findCommunicators in interface DiscoveryClientMBean

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

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 DiscoveryClientMBean

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

Specified by:

setMulticastGroup in interface DiscoveryClientMBean

Parameters:

multicastGroup - The multicast group name.

Throws:

IllegalStateException - This method has been invoked while the DiscoveryClient 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 DiscoveryClientMBean

setMulticastPort

public 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

Specified by:

setMulticastPort in interface DiscoveryClientMBean

Parameters:

multicastPort - The multicast port.

Throws:

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

setTimeOut

public 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 the default value.

The methods findMBeanServers and findCommunicators block until this time elapsed.

Specified by:

setTimeOut in interface DiscoveryClientMBean

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

public int getTimeOut()

Returns the time to wait for discovery responses in milliseconds.

Specified by:

getTimeOut in interface DiscoveryClientMBean

Returns:

The timeOut in milliseconds.

setTimeToLive

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

Specified by:

setTimeToLive in interface DiscoveryClientMBean

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

getTimeToLive

public int getTimeToLive()

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

Specified by:

getTimeToLive in interface DiscoveryClientMBean

getPointToPointResponse

public boolean getPointToPointResponse()

Get the unicast datagram socket mode for the Java DMK agent response. The default value is true.

Specified by:

getPointToPointResponse in interface DiscoveryClientMBean

Returns:

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

setPointToPointResponse

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

Specified by:

setPointToPointResponse in interface DiscoveryClientMBean

Parameters:

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

getState

public Integer getState()

Returns the state of this DiscoveryClient.

Specified by:

getState in interface DiscoveryClientMBean

Returns:

ONLINE, OFFLINE.

getStateString

public String getStateString()

Returns the state of this DiscoveryClient in string form.

Specified by:

getStateString in interface DiscoveryClientMBean

Returns:

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