TcpEndpoint (Apache River v3.0.0 Specification-only API Documentation)

java.lang.Object
- net.jini.jeri.tcp.TcpEndpoint

All Implemented Interfaces:

Serializable, Endpoint, TrustEquivalence
```
public final class TcpEndpoint
extends Object
implements Endpoint, TrustEquivalence, Serializable
```
An implementation of the Endpoint abstraction that uses TCP sockets (instances of Socket) for the underlying communication mechanism.
TcpEndpoint instances contain a host name and a TCP port number, as well as an optional SocketFactory for customizing the type of Socket to use. The host name and port number are used as the remote address to connect to when making socket connections.
TcpEndpoint uses the Jini extensible remote invocation (Jini ERI) multiplexing protocol to map outgoing requests to socket connections.
A SocketFactory used with a TcpEndpoint should be serializable and must implement Object.equals to obey the guidelines that are specified for equals methods of Endpoint instances.

Since:

2.0

See Also:

TcpServerEndpoint, Serialized Form

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`checkTrustEquivalence(Object obj)` Returns `true` if the specified object (which is not yet known to be trusted) is equivalent in trust, content, and function to this known trusted object, and `false` otherwise.
`boolean`	`equals(Object obj)` Compares the specified object with this `TcpEndpoint` for equality.
`String`	`getHost()` Returns the host that this `TcpEndpoint` connects to.
`static TcpEndpoint`	`getInstance(String host, int port)` Returns a `TcpEndpoint` instance for the given host name and TCP port number.
`static TcpEndpoint`	`getInstance(String host, int port, SocketFactory sf)` Returns a `TcpEndpoint` instance for the given host name and TCP port number that contains the given `SocketFactory`.
`int`	`getPort()` Returns the TCP port that this `TcpEndpoint` connects to.
`SocketFactory`	`getSocketFactory()` Returns the `SocketFactory` that this endpoint uses to create `Socket` objects.
`int`	`hashCode()` Returns the hash code value for this `TcpEndpoint`.
`OutboundRequestIterator`	`newRequest(InvocationConstraints constraints)` Returns an `OutboundRequestIterator` to use to send a new request to this remote endpoint using the specified constraints.
`String`	`toString()` Returns a string representation of this `TcpEndpoint`.

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

- Method Detail
  - getInstance
```
public static TcpEndpoint getInstance(String host,
                                      int port)
```
    Returns a TcpEndpoint instance for the given host name and TCP port number.
    The SocketFactory contained in the returned TcpEndpoint will be null, indicating that this endpoint will create Socket objects directly.
    
    Parameters:
    
    host - the host for the endpoint to connect to
    
    port - the TCP port on the given host for the endpoint to connect to
    
    Returns:
    
    a TcpEndpoint instance
    
    Throws:
    
    IllegalArgumentException - if the port number is out of the range 1 to 65535 (inclusive)
    
    NullPointerException - if host is null
  - getInstance
```
public static TcpEndpoint getInstance(String host,
                                      int port,
                                      SocketFactory sf)
```
    Returns a TcpEndpoint instance for the given host name and TCP port number that contains the given SocketFactory.
    If the socket factory argument is null, then this endpoint will create Socket objects directly.
    
    Parameters:
    
    host - the host for the endpoint to connect to
    
    port - the TCP port on the given host for the endpoint to connect to
    
    sf - the SocketFactory to use for this TcpEndpoint, or null
    
    Returns:
    
    a TcpEndpoint instance
    
    Throws:
    
    IllegalArgumentException - if the port number is out of the range 1 to 65535 (inclusive)
    
    NullPointerException - if host is null
  - getHost
```
public String getHost()
```
    Returns the host that this TcpEndpoint connects to.
    
    Returns:
    
    the host that this endpoint connects to
  - getPort
```
public int getPort()
```
    Returns the TCP port that this TcpEndpoint connects to.
    
    Returns:
    
    the TCP port that this endpoint connects to
  - getSocketFactory
```
public SocketFactory getSocketFactory()
```
    Returns the SocketFactory that this endpoint uses to create Socket objects.
    
    Returns:
    
    the socket factory that this endpoint uses to create sockets, or null if no factory is used
  - newRequest
```
public OutboundRequestIterator newRequest(InvocationConstraints constraints)
```
    Returns an OutboundRequestIterator to use to send a new request to this remote endpoint using the specified constraints.
    The constraints must be the complete, absolute constraints for the request.
    The returned OutboundRequestIterator's next method behaves as follows:
    Initiates an attempt to communicate the request to this remote endpoint.
    When the implementation of this method needs to create a new Socket, it will do so by invoking one of the createSocket methods on the SocketFactory of this TcpEndpoint (which produced this iterator) if non-null, or it will create a Socket directly otherwise.
    When the implementation needs to connect a Socket, if the host name to connect to (this TcpEndpoint's host name) resolves to multiple addresses (according to InetAddress.getAllByName), it attempts to connect to the first resolved address; if that attempt fails with an IOException or a SecurityException, it then attempts to connect to the next address; and this iteration continues as long as there is another resolved address and the attempt to connect to the previous address fails with an IOException or a SecurityException. If the host name resolves to just one address, the implementation makes one attempt to connect to that address. If the host name does not resolve to any addresses (InetAddress.getAllByName would throw an UnknownHostException), the implementation still makes an attempt to connect the Socket to that host name, which could result in an UnknownHostException. If the final connection attempt fails with an IOException or a SecurityException, then if any connection attempt failed with an IOException, this method throws an IOException, and otherwise (if all connection attempts failed with a SecurityException), this method throws a SecurityException.
    If there is a security manager:
    
    If a new connection is to be created, the security manager's checkConnect method is invoked with this TcpEndpoint's host and -1 for the port; if this results in a SecurityException, this method throws that exception. checkConnect is also invoked for each connection attempt, with the remote IP address (or the host name, if it could not be resolved) and port to connect to; this could result in a SecurityException for that attempt. (Note that the implementation may carry out these security checks indirectly, such as through invocations of InetAddress.getAllByName or Socket's constructors or connect method.)
    In order to reuse an existing connection for the communication, the current security context must have all of the permissions that would be necessary if the connection were being created. Specifically, it must be possible to invoke checkConnect in the current security context with this TcpEndpoint's host and -1 for the port without resulting in a SecurityException, and it also must be possible to invoke checkConnect with the remote IP address and port of the Socket without resulting in a SecurityException (if the remote socket address is unresolved, its host name is used instead). If no existing connection satisfies these requirements, then this method must behave as if there are no existing connections.
    
    Throws NoSuchElementException if this iterator does not support making another attempt to communicate the request (that is, if hasNext would return false).
    Throws IOException if an I/O exception occurs while performing this operation, such as if a connection attempt timed out or was refused.
    Throws SecurityException if there is a security manager and an invocation of its checkConnect method fails.
    Specified by:
    
    newRequest in interface Endpoint
    
    Parameters:
    
    constraints - the complete, absolute constraints
    
    Returns:
    
    an OutboundRequestIterator to use to send a new request to this remote endpoint
    
    Throws:
    
    NullPointerException - if constraints is null
  - hashCode
```
public int hashCode()
```
    Returns the hash code value for this TcpEndpoint.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    the hash code value for this TcpEndpoint
  - equals
```
public boolean equals(Object obj)
```
    Compares the specified object with this TcpEndpoint for equality.
    This method returns true if and only if
    - the specified object is also a TcpEndpoint,
    - the host and port in the specified object are equal to the host and port in this object, and
    - either this object and the specified object both have no SocketFactory or the SocketFactory in the specified object has the same class and is equal to the one in this object.
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    obj - the object to compare with
    
    Returns:
    
    true if obj is equivalent to this object; false otherwise
  - checkTrustEquivalence
```
public boolean checkTrustEquivalence(Object obj)
```
    Returns true if the specified object (which is not yet known to be trusted) is equivalent in trust, content, and function to this known trusted object, and false otherwise.
    This method returns true if and only if
    - the specified object is also a TcpEndpoint,
    - the host and port in the specified object are equal to the host and port in this object, and
    - either this object and the specified object both have no SocketFactory or the SocketFactory in the specified object has the same class and is equal to the one in this object.
    Specified by:
    
    checkTrustEquivalence in interface TrustEquivalence
    
    Parameters:
    
    obj - object to check that is not yet known to be trusted
    
    Returns:
    
    true if the specified object (that is not yet known to be trusted) is equivalent in trust, content, and function to this known trusted object, and returns false otherwise
  - toString
```
public String toString()
```
    Returns a string representation of this TcpEndpoint.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    a string representation of this TcpEndpoint

Class TcpEndpoint

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getInstance

getInstance

getHost

getPort

getSocketFactory

newRequest

hashCode

equals

checkTrustEquivalence

toString