com.sun.jaw.impl.agent.services.jawdiscovery
Class DiscoveryClient

java.lang.Object
  |
  +--com.sun.jaw.impl.agent.services.jawdiscovery.DiscoveryClient

public class DiscoveryClient
extends java.lang.Object
implements java.io.Serializable, ActivatableIf

The DiscoveryClient class provides methods to discover agents. An agent can only discovered if it has a DiscoveryResponder registered in its framework. A discovery operation is executed in two steps:

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 performFindHosts method or the performFindAdaptors method on a DiscoveryClient object. These methods represent the discovery result by a Vector of DiscoveryResponse. A DiscoveryResponse is included for each discovered agent, it provides the host of the agent and optionally the list of adaptors available in the agent.

A DiscoveryResponder can send back responses using two modes:

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

See Also:
DiscoveryResponder, Serialized Form

Field Summary
static int OFFLINE
          Marks the "state" property as stopped.
static int ONLINE
          Marks the "state" property as runnig.
protected  int state
          Reflects the current state of the discovery client.
static int STOPPING
          Marks the "state" property as in-transition from ONLINE to OFFLINE.
 
Constructor Summary
DiscoveryClient()
          Constructs a DiscoveryClient.
 
Method Summary
 void deleteCmf()
          Invoked by the framework when it is requested to delete the DiscoveryClient.
 java.lang.String getClassVersion()
          Returns the version of this class.
 java.lang.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.
 java.lang.Integer getState()
          Returns the state of this DiscoveryClient.
 java.lang.String getStateString()
          Returns the state of this DiscoveryClient in string form.
 int getTimeOut()
          Returns the time to wait for discovery responses in milliseconds.
 byte getTimeToLiveByte()
          Returns the time-to-live as a byte value.
 int getTimeToLiveInt()
          Returns the time-to-live as a int value.
 void initCmf(Framework cmf, ObjectName name, boolean db, ModificationList list)
          Invoked by the framework when it is requested to register the DiscoveryClient.
 boolean isActive()
          Tests if the DiscoveryClient is active.
 java.util.Vector performFindAdaptors()
          Discovers all agents and associated adaptors.
 java.util.Vector performFindAdaptors(java.lang.String SelectedHost)
          Discovers all agents and associated adaptors present on an host.
 java.util.Vector performFindHosts()
          Discovers all agents.
 java.util.Vector performFindHosts(java.lang.String SelectedHost)
          Discovers whether a Java DMK agent with a DiscoveryResponder registered in its framework is on a host.
 void performStart()
          Connects this DiscoveryClient, the socket joins its multicast group.
 void performStop()
          Disconnects this DiscoveryClient, the socket leaves its multicast group.
 void setMulticastGroup(java.lang.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 setTimeToLiveByte(byte ttl)
          Sets the default time-to-live expressed as a byte value.
 void setTimeToLiveInt(int ttl)
          Sets the default time-to-live for this DiscoveryClient.
 
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 runnig.

OFFLINE

public static final int OFFLINE
Marks the "state" property as stopped.

STOPPING

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

state

protected transient int state
Reflects the current state of the discovery client.
Constructor Detail

DiscoveryClient

public DiscoveryClient()
                throws java.io.IOException
Constructs a DiscoveryClient.

This constructor creates a multicast socket that is used to broadcast the discovery request using the default group (224.224.224.224) and port (9000).

Throws:
java.io.IOException - The creation of the socket failed.
Method Detail

initCmf

public void initCmf(Framework cmf,
                    ObjectName name,
                    boolean db,
                    ModificationList list)
             throws InstanceAlreadyExistException
Invoked by the framework when it is requested to register the DiscoveryClient.

For Java DMK internal use only.

Parameters:
cmf - The core management framework to register the service with.
name - Object name containing configuration information.
db - Indicates if persistent storage is required.
list - The modification list to use for setting up parameters.
Throws:
InstanceAlreadyExistException - The m-bean is already registered in the repository.

deleteCmf

public void deleteCmf()
Invoked by the framework when it is requested to delete the DiscoveryClient.

For Java DMK internal use only.


performStart

public void performStart()
Connects this DiscoveryClient, the socket joins its multicast group.
Specified by:
performStart in interface ActivatableIf

performStop

public void performStop()
Disconnects this DiscoveryClient, the socket leaves its multicast group.
Specified by:
performStop in interface ActivatableIf

isActive

public boolean isActive()
Tests if the DiscoveryClient is active.
Specified by:
isActive in interface ActivatableIf

performFindHosts

public java.util.Vector performFindHosts()
                                  throws CommunicationException
Discovers all agents.

Each DiscoveryResponse contains the host names of all agents that were discovered.

Returns:
A vector of DiscoveryResponse.
Throws:
CommunicationException - An error occurred during the discovery.
See Also:
DiscoveryResponse

performFindHosts

public java.util.Vector performFindHosts(java.lang.String SelectedHost)
                                  throws CommunicationException
Discovers whether a Java DMK agent with a DiscoveryResponder registered in its framework is on a host.

The DiscoveryResponse only contains the host name.

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.
See Also:
DiscoveryResponse

performFindAdaptors

public java.util.Vector performFindAdaptors()
                                     throws CommunicationException
Discovers all agents and associated adaptors.
Returns:
A vector of DiscoveryResponse.
Throws:
CommunicationException - An error occurred during the discovery.
See Also:
DiscoveryResponse

performFindAdaptors

public java.util.Vector performFindAdaptors(java.lang.String SelectedHost)
                                     throws CommunicationException
Discovers all agents and associated adaptors present on an host.
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.

getClassVersion

public java.lang.String getClassVersion()
Returns the version of this class.

getMulticastGroup

public java.lang.String getMulticastGroup()
Returns the multicast group.

setMulticastGroup

public void setMulticastGroup(java.lang.String multicastGroup)
Sets the multicast group name.

Only available if the state is OFFLINE

Parameters:
multicastGroup - The multicast group name.

getMulticastPort

public int getMulticastPort()
Returns the multicast port.

setMulticastPort

public void setMulticastPort(int multicastPort)
Sets the multicast port.

Only available if the state is OFFLINE

Parameters:
multicastPort - The multicast port.

setTimeOut

public void setTimeOut(int timeOut)
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 performFindHosts and performFindAdaptors block until this time elapsed.

Parameters:
timeOut - The timeOut in milliseconds.
See Also:
getTimeOut()

getTimeOut

public int getTimeOut()
Returns the time to wait for discovery responses in milliseconds.
Returns:
The timeOut in milliseconds.
See Also:
setTimeOut(int)

setTimeToLiveInt

public void setTimeToLiveInt(int ttl)
                      throws java.io.IOException
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:
java.io.IOException - If the socket rejected the specified value.

setTimeToLiveByte

public void setTimeToLiveByte(byte ttl)
                       throws java.io.IOException
Sets the default time-to-live expressed as a byte value.
Parameters:
ttl - A byte value.
Throws:
java.io.IOException - If the socket rejected the specified value.

getTimeToLiveByte

public byte getTimeToLiveByte()
Returns the time-to-live as a byte value.
Returns:
The time-to-live as a byte value.

getTimeToLiveInt

public int getTimeToLiveInt()
Returns the time-to-live as a int value.
Returns:
The time-to-live as a int value.

getPointToPointResponse

public 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

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.

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

getState

public java.lang.Integer getState()
Returns the state of this DiscoveryClient.
Returns:
ONLINE, OFFLINE or STOPPING.

getStateString

public java.lang.String getStateString()
Returns the state of this DiscoveryClient in string form.
Returns:
One of the strings "ONLINE", "OFFLINE" or "STOPPING".