ConstrainableLookupLocator (Apache River v3.0.0 API Documentation)

java.lang.Object
- net.jini.core.discovery.LookupLocator
- - net.jini.discovery.ConstrainableLookupLocator

All Implemented Interfaces:

Serializable, RemoteMethodControl
```
public final class ConstrainableLookupLocator
extends LookupLocator
implements RemoteMethodControl
```
LookupLocator subclass which supports constraint operations through the RemoteMethodControl interface. The constraints of a ConstrainableLookupLocator instance control how it performs unicast discovery, and apply only to its getRegistrar() and getRegistrar(int) methods. The constraints may also be used by other utilities, such as LookupLocatorDiscovery, to determine how unicast discovery should be performed on behalf of a given ConstrainableLookupLocator instance. Untrusted ConstrainableLookupLocator instances can be verified using the ConstrainableLookupLocatorTrustVerifier trust verifier.
Since:

2.0

Author:

Sun Microsystems, Inc.

See Also:

Serialized Form

Implementation Specifics:
This class supports use of the following constraint types to control unicast discovery behavior:
- DiscoveryProtocolVersion: this constraint can be used to control which version of the unicast discovery protocol is used.
- UnicastSocketTimeout: this constraint can be used to control the read timeout set on sockets over which unicast discovery is performed.
- ConnectionRelativeTime: this constraint can be used to control the relative connection timeout set on sockets over which unicast discovery is performed.
- ConnectionAbsoluteTime: this constraint can be used to control the absolute connection timeout set on sockets over which unicast discovery is performed.
In addition, the MulticastMaxPacketSize and MulticastTimeToLive constraint types are trivially supported, but do not have any effect on unicast discovery operations. Constraints other than those mentioned above are passed on to the underlying implementations of versions 1 and 2 of the discovery protocols.
An example of using constraints with ConstrainableLookupLocator is:
```
 new ConstrainableLookupLocator("target_host", 4160, new BasicMethodConstraints(
     new InvocationConstraints(
         DiscoveryProtocolVersion.TWO, new UnicastSocketTimeout(120000))));
 
```
The resulting ConstrainableLookupLocator instance would (when used) perform unicast discovery to the host target_host on port 4160 using discovery protocol version 2, with a socket read timeout of 120000 milliseconds unless one was explicitly specified using the getRegistrar(int) method.

Field Summary
- Fields inherited from class net.jini.core.discovery.LookupLocator
  host, port

Constructor Summary

Constructors
Constructor and Description
`ConstrainableLookupLocator(String host, int port, MethodConstraints constraints)` Constructs a new `ConstrainableLookupLocator` instance which can be used to perform unicast discovery to the given host and port with the provided constraints applied.
`ConstrainableLookupLocator(String url, MethodConstraints constraints)` Constructs a new `ConstrainableLookupLocator` instance which can be used to perform unicast discovery to the host and port named by the given URL with the provided constraints applied.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`equals(Object o)` Two locators are equal if they have the same `host` and `port` fields.
`MethodConstraints`	`getConstraints()` Returns the client constraints placed on this proxy.
`ServiceRegistrar`	`getRegistrar()` Performs unicast discovery as specified by `LookupLocator.getRegistrar()` with the following differences.
`ServiceRegistrar`	`getRegistrar(int timeout)` Performs unicast discovery as specified by `LookupLocator.getRegistrar(int)`, additionally applying the supplied discovery constraints.
`int`	`hashCode()` Returns a hash code value calculated from the `host` and `port` field values.
`RemoteMethodControl`	`setConstraints(MethodConstraints constraints)` Returns a new copy of this proxy with the client constraints set to the specified constraints.
`String`	`toString()` Returns a string representation of this object.

Methods inherited from class net.jini.core.discovery.LookupLocator
getHost, getPort, getRegistrar

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - ConstrainableLookupLocator
```
public ConstrainableLookupLocator(String url,
                                  MethodConstraints constraints)
                           throws MalformedURLException
```
    Constructs a new ConstrainableLookupLocator instance which can be used to perform unicast discovery to the host and port named by the given URL with the provided constraints applied. This constructor invokes its superclass LookupLocator.LookupLocator(String) constructor. Any exceptions thrown by the superclass constructor are rethrown.
    The url must be a valid URL of scheme "jini" as described in LookupLocator(String). A null constraints value is interpreted as mapping both getRegistrar methods to empty constraints.
    
    Parameters:
    
    url - the URL to use
    
    constraints - the constraints to apply to unicast discovery, or null
    
    Throws:
    
    MalformedURLException - if url cannot be parsed
    
    NullPointerException - if url is null
  - ConstrainableLookupLocator
```
public ConstrainableLookupLocator(String host,
                                  int port,
                                  MethodConstraints constraints)
```
    Constructs a new ConstrainableLookupLocator instance which can be used to perform unicast discovery to the given host and port with the provided constraints applied. This constructor invokes its superclass LookupLocator.LookupLocator(String, int) constructor. Any exceptions thrown by the superclass constructor are rethrown.
    A null constraints value is interpreted as mapping both getRegistrar methods to empty constraints. The host and port must satisfy the requirements of the LookupLocator(String, int) constructor.
    
    Parameters:
    
    host - the name of the host to contact
    
    port - the number of the port to connect to
    
    constraints - the constraints to apply to unicast discovery, or null
    
    Throws:
    
    NullPointerException - if host is null
    
    IllegalArgumentException - if the port and host do not meet the requirements of LookupLocator(String, int).
- Method Detail
  - hashCode
```
public int hashCode()
```
    Description copied from class: LookupLocator
    
    Returns a hash code value calculated from the host and port field values.
    
    Overrides:
    
    hashCode in class LookupLocator
  - equals
```
public boolean equals(Object o)
```
    Description copied from class: LookupLocator
    
    Two locators are equal if they have the same host and port fields. The case of the host is ignored. Alternative forms of the same IPv6 addresses for the host value are treated as being unequal.
    
    Overrides:
    
    equals in class LookupLocator
  - getRegistrar
```
public ServiceRegistrar getRegistrar()
                              throws IOException,
                                     ClassNotFoundException
```
    Performs unicast discovery as specified by LookupLocator.getRegistrar() with the following differences.
    - It applies the supplied constraints (if any) for this method.
    - It does not invoke the getRegistrar(int) method.
    - If no timeout constraints are specified, this method assumes a default timeout of 60 seconds. A non default timeout can only be specified through the supplied constraints, the net.jini.discovery.timeout system property is ignored.
    ConstrainableLookupLocator implements this method to use the values of the host and port field in determining the host and port to connect to.
    Overrides:
    
    getRegistrar in class LookupLocator
    
    Returns:
    
    lookup service proxy
    
    Throws:
    
    UnsupportedConstraintException - if the discovery-related constraints contain conflicts, or otherwise cannot be processed
    
    ClassNotFoundException
    
    IOException - an error occurred during discovery
  - getRegistrar
```
public ServiceRegistrar getRegistrar(int timeout)
                              throws IOException,
                                     ClassNotFoundException
```
    Performs unicast discovery as specified by LookupLocator.getRegistrar(int), additionally applying the supplied discovery constraints. The timeout is considered a requirement with respect to other constraints specified for this instance.
    
    Overrides:
    
    getRegistrar in class LookupLocator
    
    Parameters:
    
    timeout - the maximum time to wait for a response, in milliseconds. A value of 0 specifies an infinite timeout.
    
    Returns:
    
    lookup service proxy
    
    Throws:
    
    UnsupportedConstraintException - if the discovery-related constraints contain conflicts, or otherwise cannot be processed
    
    ClassNotFoundException
    
    IOException - an error occurred during discovery
  - toString
```
public String toString()
```
    Returns a string representation of this object.
    
    Overrides:
    
    toString in class LookupLocator
    
    Returns:
    
    the string representation
  - setConstraints
```
public RemoteMethodControl setConstraints(MethodConstraints constraints)
```
    Description copied from interface: RemoteMethodControl
    
    Returns a new copy of this proxy with the client constraints set to the specified constraints. These constraints completely replace (in the copy) any client constraints previously placed on this proxy; calling the getConstraints method of the copy returns the identical constraints instance. The original proxy is not modified. A null value is interpreted as mapping all methods to empty constraints (one that has no requirements and no preferences). For any given remote call, the specific client requirements and preferences to be satisfied are given by the return value of invoking the getConstraints method of the specified MethodConstraints instance with a Method object representing the remote method.
    Client constraints placed on a proxy are included in the serialized state of the proxy. This allows third-party services to be transparent to the client's needs. For example, if remote object s1 obtains a proxy for remote object s2, and passes that proxy to remote object s3, expecting s3 to invoke a remote method on s2, then s1 can control that call by placing its constraints directly on the proxy before passing it to s3. If s3 does not wish to be transparent in this way, then it should explicitly replace the client constraints on received proxies with whatever constraints are appropriate to implement its own policy.
    
    Specified by:
    
    setConstraints in interface RemoteMethodControl
    
    Parameters:
    
    constraints - client constraints, or null
    
    Returns:
    
    a new copy of this proxy with the client constraints set to the specified constraints
    
    See Also:
    
    RemoteMethodControl.getConstraints()
  - getConstraints
```
public MethodConstraints getConstraints()
```
    Description copied from interface: RemoteMethodControl
    
    Returns the client constraints placed on this proxy. The return value can be null, which is interpreted as mapping all methods to empty constraints (one that has no requirements and no preferences).
    
    Specified by:
    
    getConstraints in interface RemoteMethodControl
    
    Returns:
    
    the client constraints, or null
    
    See Also:
    
    RemoteMethodControl.setConstraints(net.jini.core.constraint.MethodConstraints)

Class ConstrainableLookupLocator

Field Summary

Fields inherited from class net.jini.core.discovery.LookupLocator

Constructor Summary

Method Summary

Methods inherited from class net.jini.core.discovery.LookupLocator

Methods inherited from class java.lang.Object

Constructor Detail

ConstrainableLookupLocator

ConstrainableLookupLocator

Method Detail

hashCode

equals

getRegistrar

getRegistrar

toString

setConstraints

getConstraints