Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.sun.jini.discovery
Class Discovery

    java.lang.Object
      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 `Logger`s 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

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.
`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.
`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 `DatagramPacket`s, 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 `DatagramPacket`s, 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 `DatagramPacket`s, 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.

  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`

### 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 `DatagramPacket`s, 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.

  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`

### 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`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2004 Sun Microsystems, Inc. All rights reserved