GigaSpaces XAP 9.0 API

com.sun.jini.discovery
Class Discovery

java.lang.Object
  extended by com.sun.jini.discovery.Discovery

public abstract class Discovery
extends Object

Class providing methods for participating in versions 1 and 2 of the discovery protocol.

Logging

This implementation uses the Loggers named com.sun.jini.discovery.DiscoveryV1 and com.sun.jini.discovery.DiscoveryV2 to log information at the following logging levels:

com.sun.jini.discovery.DiscoveryV1
Level Description
FINEST Encoding and decoding of discovery protocol version 1 multicast requests, multicast announcements, and unicast responses

com.sun.jini.discovery.DiscoveryV2
Level Description
WARNING Truncation of unicast request format ID list due to length; discovery format providers that are unusable or have conflicting discovery format IDs
HANDLED Constraint check failures encountered during the unicast discovery handshake when determining a suitable discovery format to use
FINEST Encoding and decoding of discovery protocol version 2 multicast requests, multicast announcements, and unicast responses; also, access of Discovery instances implementing protocol version 2

Since:
2.0
Author:
Sun Microsystems, Inc.

Field Summary
static int PROTOCOL_VERSION_1
          The version number for discovery protocol version 1.
static int PROTOCOL_VERSION_2
          The version number for discovery protocol version 2.
 
Constructor Summary
Discovery()
           
 
Method Summary
abstract  MulticastAnnouncement decodeMulticastAnnouncement(DatagramPacket packet, InvocationConstraints constraints)
          Decodes the multicast announcement data contained in the given datagram in a manner that satisfies the specified constraints, returning a MulticastAnnouncement instance that contains the decoded data.
 MulticastAnnouncement decodeMulticastAnnouncement(DatagramPacket packet, InvocationConstraints constraints, boolean delayConstraintCheck)
          Decodes the multicast announcement data contained in the given datagram in a manner that satisfies the specified constraints, returning a MulticastAnnouncement instance that contains the decoded data, with constraint checking optionally delayed.
abstract  MulticastRequest decodeMulticastRequest(DatagramPacket packet, InvocationConstraints constraints, ClientSubjectChecker checker)
          Decodes the multicast request data contained in the given datagram in a manner that satisfies the specified constraints and client subject checker (if any), returning a MulticastRequest instance that contains the decoded data.
 MulticastRequest decodeMulticastRequest(DatagramPacket packet, InvocationConstraints constraints, ClientSubjectChecker checker, boolean delayConstraintCheck)
          Decodes the multicast request data contained in the given datagram in a manner that satisfies the specified constraints and client subject checker (if any), returning a MulticastRequest instance that contains the decoded data, with constraint checking optionally delayed.
abstract  UnicastResponse doUnicastDiscovery(Socket socket, InvocationConstraints constraints, ClassLoader defaultLoader, ClassLoader verifierLoader, Collection context)
          Performs the client side of unicast discovery, obtaining the returned response data over the provided socket using the given default and codebase verifier class loaders and collection of object stream context objects in a manner that satisfies the specified constraints.
abstract  EncodeIterator encodeMulticastAnnouncement(MulticastAnnouncement announcement, int maxPacketSize, InvocationConstraints constraints)
          Returns an iterator which can be used to encode the given multicast announcement data into sets of DatagramPackets, each bounded in length by the specified maximum packet size, in a manner that satisfies the given constraints.
abstract  EncodeIterator encodeMulticastRequest(MulticastRequest request, int maxPacketSize, InvocationConstraints constraints)
          Returns an iterator which can be used to encode the given multicast request data into sets of DatagramPackets, each bounded in length by the specified maximum packet size, in a manner that satisfies the given constraints.
static Discovery getProtocol1()
          Returns an instance implementing protocol version 1.
static Discovery getProtocol2(ClassLoader loader)
          Returns an instance implementing protocol version 2 which uses providers loaded from the given class loader, or the current context class loader if the given loader is null.
static Discovery getProtocol2(MulticastRequestEncoder[] mre, MulticastRequestDecoder[] mrd, MulticastAnnouncementEncoder[] mae, MulticastAnnouncementDecoder[] mad, UnicastDiscoveryClient[] udc, UnicastDiscoveryServer[] uds)
          Returns an instance implementing protocol version 2 which uses the given providers.
abstract  void handleUnicastDiscovery(UnicastResponse response, Socket socket, InvocationConstraints constraints, ClientSubjectChecker checker, Collection context)
          Handles the server side of unicast discovery, transmitting the given response data over the provided socket using the given collection of object stream context objects in a manner that satisfies the specified constraints and client subject checker (if any).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

PROTOCOL_VERSION_1

public static final int PROTOCOL_VERSION_1
The version number for discovery protocol version 1.

See Also:
Constant Field Values

PROTOCOL_VERSION_2

public static final int PROTOCOL_VERSION_2
The version number for discovery protocol version 2.

See Also:
Constant Field Values
Constructor Detail

Discovery

public Discovery()
Method Detail

getProtocol1

public static Discovery getProtocol1()
Returns an instance implementing protocol version 1.

Returns:
an instance implementing protocol version 1

getProtocol2

public static Discovery getProtocol2(ClassLoader loader)
Returns an instance implementing protocol version 2 which uses providers loaded from the given class loader, or the current context class loader if the given loader is null. Available providers are determined by interpreting any resources of the indicated class loader named "META-INF/services/com.sun.jini.discovery.DiscoveryFormatProvider" as files containing names of provider classes, with one name per line.

Parameters:
loader - class loader from which to load providers, or null to indicate the current context class loader
Returns:
an instance implementing protocol version 2

getProtocol2

public static Discovery getProtocol2(MulticastRequestEncoder[] mre,
                                     MulticastRequestDecoder[] mrd,
                                     MulticastAnnouncementEncoder[] mae,
                                     MulticastAnnouncementDecoder[] mad,
                                     UnicastDiscoveryClient[] udc,
                                     UnicastDiscoveryServer[] uds)
Returns an instance implementing protocol version 2 which uses the given providers. Contents of arrays are copied; null array values are equivalent to empty arrays.

Parameters:
mre - providers for encoding multicast requests
mrd - providers for decoding multicast requests
mae - providers for encoding multicast announcements
mad - providers for decoding multicast announcements
udc - providers for performing the client side of unicast discovery
uds - providers for performing the server side of unicast discovery
Returns:
an instance implementing protocol version 2

encodeMulticastRequest

public abstract EncodeIterator encodeMulticastRequest(MulticastRequest request,
                                                      int maxPacketSize,
                                                      InvocationConstraints constraints)
Returns an iterator which can be used to encode the given multicast request data into sets of DatagramPackets, each bounded in length by the specified maximum packet size, in a manner that satisfies the given constraints. null constraints are considered equivalent to empty constraints. The destination of each DatagramPacket produced by the returned iterator is set to the address returned by Constants.getRequestAddress(), with the value of Constants.discoveryPort used as the destination port.

Parameters:
request - the request data to encode
maxPacketSize - the maximum size of packets to produce
constraints - the constraints to apply when encoding the data, or null
Returns:
an iterator to use for encoding the data
Throws:
NullPointerException - if request is null

decodeMulticastRequest

public abstract MulticastRequest decodeMulticastRequest(DatagramPacket packet,
                                                        InvocationConstraints constraints,
                                                        ClientSubjectChecker checker)
                                                 throws IOException
Decodes the multicast request data contained in the given datagram in a manner that satisfies the specified constraints and client subject checker (if any), returning a MulticastRequest instance that contains the decoded data. null constraints are considered equivalent to empty constraints. All the specified constraints are checked before this method returns.

Parameters:
packet - the packet to decode
constraints - the constraints to apply when decoding the packet, or null
checker - the object to use to check the client subject, or null
Returns:
the decoded multicast request data
Throws:
IOException - if an error occurs in interpreting the data
UnsupportedConstraintException - if unable to satisfy the specified constraints
SecurityException - if the given constraints cannot be satisfied due to insufficient caller permissions, or if the client subject check fails
NullPointerException - if packet is null

decodeMulticastRequest

public MulticastRequest decodeMulticastRequest(DatagramPacket packet,
                                               InvocationConstraints constraints,
                                               ClientSubjectChecker checker,
                                               boolean delayConstraintCheck)
                                        throws IOException
Decodes the multicast request data contained in the given datagram in a manner that satisfies the specified constraints and client subject checker (if any), returning a MulticastRequest instance that contains the decoded data, with constraint checking optionally delayed. null constraints are considered equivalent to empty constraints.

The delayConstraintCheck flag is used to control delayed constraint checking. Delayed constraint checking is useful for potentially delaying the expense of complete constraint checking, until other checks have been made on the returned MulticastRequest for preliminary validation. Implementations may ignore the flag, in which case, the behavior is equivalent to that of decodeMulticastRequest.

If delayConstraintCheck is true, the method behaves as follows:

If delayConstraintCheck is false, all the specified constraints are checked before this method returns.

Discovery implements this method to simply invoke decodeMulticastRequest, and thus checks all the specified constraints before returning.

Parameters:
packet - the packet to decode
constraints - the constraints to apply when decoding the packet, or null
checker - the object to use to check the client subject, or null
delayConstraintCheck - flag to control delayed constraint checking
Returns:
the decoded multicast request data.
Throws:
IOException - if an error occurs in interpreting the data
SecurityException - if the given constraints cannot be satisfied due to insufficient caller permissions, or if the client subject check fails
NullPointerException - if packet is null
Since:
2.1

encodeMulticastAnnouncement

public abstract EncodeIterator encodeMulticastAnnouncement(MulticastAnnouncement announcement,
                                                           int maxPacketSize,
                                                           InvocationConstraints constraints)
Returns an iterator which can be used to encode the given multicast announcement data into sets of DatagramPackets, each bounded in length by the specified maximum packet size, in a manner that satisfies the given constraints. null constraints are considered equivalent to empty constraints. The destination of each DatagramPacket produced by the returned iterator is set to the address returned by Constants.getAnnouncementAddress(), with the value of Constants.discoveryPort used as the destination port.

Parameters:
announcement - the announcement data to encode
maxPacketSize - the maximum size of packets to produce
constraints - the constraints to apply when encoding the data, or null
Returns:
an iterator to use for encoding the data
Throws:
NullPointerException - if announcement is null

decodeMulticastAnnouncement

public abstract MulticastAnnouncement decodeMulticastAnnouncement(DatagramPacket packet,
                                                                  InvocationConstraints constraints)
                                                           throws IOException
Decodes the multicast announcement data contained in the given datagram in a manner that satisfies the specified constraints, returning a MulticastAnnouncement instance that contains the decoded data. null constraints are considered equivalent to empty constraints. All the specified constraints are checked before this method returns.

Parameters:
packet - the packet to decode
constraints - the constraints to apply when decoding the packet, or null
Returns:
the decoded multicast announcement data
Throws:
IOException - if an error occurs in interpreting the data
UnsupportedConstraintException - if unable to satisfy the specified constraints
SecurityException - if the given constraints cannot be satisfied due to insufficient caller permissions
NullPointerException - if packet is null

decodeMulticastAnnouncement

public MulticastAnnouncement decodeMulticastAnnouncement(DatagramPacket packet,
                                                         InvocationConstraints constraints,
                                                         boolean delayConstraintCheck)
                                                  throws IOException
Decodes the multicast announcement data contained in the given datagram in a manner that satisfies the specified constraints, returning a MulticastAnnouncement instance that contains the decoded data, with constraint checking optionally delayed. null constraints are considered equivalent to empty constraints.

The delayConstraintCheck flag is used to control delayed constraint checking. Delayed constraint checking is useful for potentially delaying the expense of complete constraint checking, until other checks have been made on the returned MulticastAnnouncement for preliminary validation. Implementations may ignore the flag, in which case, the behavior is equivalent to that of decodeMulticastAnnouncement.

If delayConstraintCheck is true, the method behaves as follows:

If delayConstraintCheck is false, all the specified constraints are checked before this method returns.

Discovery implements this method to simply invoke decodeMulticastAnnouncement, and thus checks all the specified constraints before returning.

Parameters:
packet - the packet to decode
constraints - the constraints to apply when decoding the packet, or null
delayConstraintCheck - flag to control delayed constraint checking
Returns:
the decoded multicast announcement data.
Throws:
IOException - if an error occurs in interpreting the data
UnsupportedConstraintException - if unable to satisfy the specified constraints
SecurityException - if the given constraints cannot be satisfied due to insufficient caller permissions.
NullPointerException - if packet is null
Since:
2.1

doUnicastDiscovery

public abstract UnicastResponse doUnicastDiscovery(Socket socket,
                                                   InvocationConstraints constraints,
                                                   ClassLoader defaultLoader,
                                                   ClassLoader verifierLoader,
                                                   Collection context)
                                            throws IOException,
                                                   ClassNotFoundException
Performs the client side of unicast discovery, obtaining the returned response data over the provided socket using the given default and codebase verifier class loaders and collection of object stream context objects in a manner that satisfies the specified constraints. null constraints are considered equivalent to empty constraints.

Parameters:
socket - the socket on which to perform unicast discovery
constraints - the constraints to apply to unicast discovery, or null
defaultLoader - the class loader value (possibly null) to be passed as the defaultLoader argument to RMIClassLoader methods when unmarshalling the registrar proxy
verifierLoader - the class loader value (possibly null) to pass to Security.verifyCodebaseIntegrity, if codebase integrity verification is used when unmarshalling the registrar proxy
context - the collection of context information objects (possibly null) to use when unmarshalling the registrar proxy
Returns:
the received unicast response data
Throws:
IOException - if an error occurs in interpreting received data or in formatting data to send
UnsupportedConstraintException - if unable to satisfy the specified constraints
SecurityException - if the given constraints cannot be satisfied due to insufficient caller permissions
ClassNotFoundException - if the class of the discovered registrar cannot be resolved
NullPointerException - if socket is null

handleUnicastDiscovery

public abstract void handleUnicastDiscovery(UnicastResponse response,
                                            Socket socket,
                                            InvocationConstraints constraints,
                                            ClientSubjectChecker checker,
                                            Collection context)
                                     throws IOException
Handles the server side of unicast discovery, transmitting the given response data over the provided socket using the given collection of object stream context objects in a manner that satisfies the specified constraints and client subject checker (if any). This method assumes that the protocol version number has already been consumed from the socket, but that no further processing of the connection has occurred. null constraints are considered equivalent to empty constraints.

Parameters:
response - the unicast response data to transmit
socket - the socket on which to handle unicast discovery
constraints - the constraints to apply to unicast discovery, or null
checker - the object to use to check the client subject, or null
context - the collection of context information objects to use when marshalling the registrar proxy
Throws:
IOException - if the protocol handshake fails, or if an error occurs in interpreting received data or in formatting data to send
UnsupportedConstraintException - if unable to satisfy the specified constraints
SecurityException - if the given constraints cannot be satisfied due to insufficient caller permissions, or if the client subject check fails
NullPointerException - if response, socket, or context is null

GigaSpaces XAP 9.0 API

Copyright © GigaSpaces.