public interface SocketConnection extends StreamConnection
A socket is accessed using a generic connection string with an explicit host
and port number.
The mode
parameter of Connector.open
is not used.
The host may be specified as a fully qualified host name or
IP address.
e.g. socket://host.com:79
defines a target socket on the
host.com
system at
port 79
.
Note that RFC1900 recommends the use of names rather than IP numbers for best results in the event of IP number reassignment.
Every StreamConnection
provides a Connection
object as well as an InputStream
and OutputStream
to handle the I/O associated with the connection. Each of these interfaces
has its own close()
method. For systems that support
duplex communication over the socket connection, closing of the
input or output stream SHOULD shutdown just that side of the
connection. e.g. closing the InputStream
will permit the
OutputStream
to continue sending data.
Once the input or output stream has been closed, it can only be reopened
with a call to Connector.open()
. The application will receive
an IOException
if an attempt is made to reopen the stream.
The SocketConnection
supports additional settings during Connector.open
to
specify non-standard behavior of the connection.
The following connection settings are supported on all platforms.
ConnectionOption | Type | Sample Value |
---|---|---|
Timeout | Integer | 2000 |
AccessPoint | AccessPoint | See AccessPoint.getAccessPoints |
EnableRoaming | Boolean | true or false |
IPVersion | String | ipv6 |
The ConnectionOption Timeout
can be used to specify a timeout in milliseconds on blocking
read or write operations on this connection.
The behavior is equivalent to calling setSocketOption(TIMEOUT, n)
.
With this option set to a non-zero timeout, a read() call on the InputStream
associated with this connection will block for only this amount of time.
If the timeout expires and the timeouts
flag on connector.open
is true,
a java.io.InterruptedIOException
is thrown.
If no timeouts
flag was used or timeouts
is false
,
the read operation returns the number of bytes available and no exception is thrown.
The timeout value must be greater than or equal to 0.
A timeout value of zero is interpreted as an infinite timeout.
If a platform does not support timeouts, the Timeout
setting is silently ignored
and the read/write operations behave as if it was set to 0.
The ConnectionOption AccessPoint
is used to supply a specific AccessPoint
instance that must be used for the connection.
The connect
method of the AccessPoint will be
called to connect the AccessPoint.
If the access point is not valid or can not be connected, Connector.Open
throws a ConnectionNotFoundException
.
ConnectionOption values are validated during Connector.open
and any exceptions reported.
In the case an AccessPoint is not present in the parameters to
Connector.open, Connector.open must use one of the AccessPoints
already connected that supports the requested ConnectionOptions.
If no AccessPoint is available the implementation may initialize a
network connection and create an AccessPoint for it.
Otherwise, a ConnectionNotFoundException is thrown.
The AccessPoint for a connection is available from getAccessPoint
.
The ConnectionOption EnableRoaming
with a value of true
is used to enable making connections via a NetworkInterface that returns
true
from isRoaming
.
The value false
disables creating connections via a roaming
NetworkInterface. A ConnectionNotFoundException
is
thrown if a roaming enabled connection was requested but cannot be found.
If the ConnectionOption is not present, it is implementation specific, whether
the use of roaming connections is permitted.
The ConnectionOption IPVersion
may be used on dual stack IPv4/IPv6 platforms
and AccessPoints,
for setting the preferred protocol stack (IPv4 or IPv6) as well as the preferred
address family types (inet4 or inet6) for the connection. Possible values are either
"ipv4" or "ipv6".
The host name to IP address lookup mechanism also uses IPVersion
.
If an IP Address of the requested address type is not available, whether via DNS
or other hostname translation service a java.net.UnknownHostException
is thrown.
If the exception occurs in Connector.open a
ConnectionNotFoundException
is thrown with the UnknownHostException
as the cause.
In case of a conflict between the IPVersion
ConnectionOption and
a literal host address in the URL string or another ConnectionOption
Connector.Open
throws a ConnectionNotFoundException
.
If the platform or AccessPoint does not support the selected IP version,
Connector.Open
throws a ConnectionNotFoundException
.
The URI must conform to the BNF syntax specified below. If the URI
does not conform to this syntax, an IllegalArgumentException
is thrown.
<socket_connection_string> | ::= "socket://"<hostport> |
<hostport> | ::= host ":" port |
<host> | ::= host name or IP address (omitted for inbound connections, See ServerSocketConnection) |
<port> | ::= numeric port number (omitted for system assigned port in inbound connection) |
The following examples show how a SocketConnection
would be used to access a sample loopback connection.
SocketConnection sc = (SocketConnection) Connector.open("socket://host.com:79"); sc.setSocketOption(SocketConnection.LINGER, 5); InputStream is = sc.openInputStream(); OutputStream os = sc.openOutputStream(); os.write("\r\n".getBytes()); int ch = 0; while(ch != -1) { ch = is.read(); } is.close(); os.close(); sc.close();
Modifier and Type | Field and Description |
---|---|
static byte |
DELAY
Socket option for the small buffer writing delay (0).
|
static byte |
KEEPALIVE
Socket option for the keep alive feature (2).
|
static byte |
LINGER
Socket option for the linger time to wait in seconds
before closing a connection with
pending data output (1).
|
static byte |
RCVBUF
Socket option for the size of the receiving buffer (3).
|
static byte |
SNDBUF
Socket option for the size of the sending buffer (4).
|
static byte |
TIMEOUT
Socket option for a timeout on a blocking read or write operation.
|
Modifier and Type | Method and Description |
---|---|
AccessPoint |
getAccessPoint()
Gets the AccessPoint for this connection.
|
java.lang.String |
getAddress()
Gets the remote address to which the socket is bound.
|
java.lang.String |
getLocalAddress()
Gets the local address to which the socket is bound.
|
int |
getLocalPort()
Returns the local port to which this socket is bound.
|
int |
getPort()
Returns the remote port to which this socket is bound.
|
int |
getSocketOption(byte option)
Get a socket option for the connection.
|
void |
setSocketOption(byte option,
int value)
Set a socket option for the connection.
|
openDataInputStream, openInputStream
openDataOutputStream, openOutputStream
close
static final byte DELAY
static final byte KEEPALIVE
static final byte LINGER
static final byte RCVBUF
static final byte SNDBUF
static final byte TIMEOUT
AccessPoint getAccessPoint()
java.lang.String getAddress() throws java.io.IOException
java.io.IOException
- if the connection was closed.java.lang.String getLocalAddress() throws java.io.IOException
The host address is returned as a numeric IP address. For IPV6, the string MUST be formatted as in a URL according to RFC 2732 so it contains the '[' and ']'. Since IP addresses may be dynamically assigned, a remote application will need to be robust in the face of IP number reassignment.
The local hostname (if available) can be accessed from
System.getProperty("microedition.hostname")
java.io.IOException
- if the connection was closed.ServerSocketConnection
int getLocalPort() throws java.io.IOException
java.io.IOException
- if the connection was closed.ServerSocketConnection
int getPort() throws java.io.IOException
java.io.IOException
- if the connection was closed.int getSocketOption(byte option) throws java.lang.IllegalArgumentException, java.io.IOException
option
- socket option identifier (KEEPALIVE, LINGER,
SNDBUF, RCVBUF, DELAY or TIMEOUT)java.lang.IllegalArgumentException
- if the option identifier is
not validjava.io.IOException
- if the connection was closedsetSocketOption(byte, int)
void setSocketOption(byte option, int value) throws java.lang.IllegalArgumentException, java.io.IOException
Options inform the low level networking code about intended usage patterns that the application will use in dealing with the socket connection.
Calling setSocketOption
to assign buffer sizes
is a hint to the platform of the sizes to set the underlying
network I/O buffers.
Calling getSocketOption
can be used to see what
sizes the system is using.
The system MAY adjust the buffer sizes to account for
better throughput available from Maximum Transmission Unit
(MTU) and Maximum Segment Size (MSS) data available
from current network information.
option
- socket option identifier (KEEPALIVE, LINGER,
SNDBUF, RCVBUF, DELAY or TIMEOUT)value
- numeric value for specified optionjava.lang.IllegalArgumentException
- if the value is not
valid (e.g. negative value) or if the option
identifier is not validjava.io.IOException
- if the connection was closedgetSocketOption(byte)
Copyright (c) 2014, Oracle and/or its affiliates. All Rights Reserved. Use of this specification is subject to license terms.