org.apache.river.discovery

Class Discovery

java.lang.Object

org.apache.river.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 org.apache.river.discovery.DiscoveryV1 and org.apache.river.discovery.DiscoveryV2 to log information at the following logging levels:

org.apache.river.discovery.DiscoveryV1

Level	Description
FINEST	Encoding and decoding of discovery protocol version 1 multicast requests, multicast announcements, and unicast responses

org.apache.river.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

Fields

Modifier and Type	Field and Description
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

Constructors

Constructor and Description
Discovery()

Method Summary

Modifier and Type	Method and Description
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.
static Discovery	getUnicastHttps(ClassLoader loader) Returns an instance implementing the unicast https protocol which uses providers loaded from the given class loader, or the context class loader if the given loader is null.
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/org.apache.river.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

getUnicastHttps

public static Discovery getUnicastHttps(ClassLoader loader)

Returns an instance implementing the unicast https protocol which uses providers loaded from the given class loader, or the 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/org.apache.river.discovery.Discovery" with a toString() method that returns the string "UnicastHTTPS". TODO: provide a mechanism to allow more flexible mechanism for selection of loader.

Parameters:

loader - class loader from which to load providers, or null to indicate the current context class loader

Returns:

an instance implementing the unicast https protocol

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:

• Some of the specified constraints may not be checked before this method returns; the returned MulticastRequest's checkConstraints method must be invoked to complete checking of all the constraints.
• Constraints which must be checked before accessor methods of the returned MulticastRequest can be invoked are always checked before this method returns.

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:

• Some of the specified constraints may not be checked before this method returns; the returned MulticastAnnouncement's checkConstraints method must be invoked to complete checking of all the constraints.
• Constraints which must be checked before accessor methods of the returned MulticastAnnouncement can be invoked are always checked before this method returns.

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