Package 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 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
FINE 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 Details

    • PROTOCOL_VERSION_1

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

    • PROTOCOL_VERSION_2

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

  • Constructor Details

    • Discovery

      public Discovery()

  • Method Details

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