public class Connector
extends java.lang.Object
The parameter string that describes the target should conform to the URI format as described in RFC 3986. This takes the general form:
{scheme}:[{hier-part}][?{query}][#{fragment}]
where
{scheme}
is the name of a protocol such as http.
{hier-part}
contains the target of the requested
connection and any necessary parameters in the form ";x=y".
Example URIs used with GCF include:
http://www.example.com:80/over/there?name=ferret#nose
socket://www.sun.com:8080
datagram://[2001:db8::7]:4567
datagram://:50000
multicast://224.0.12.34:50000
comm:port1;baudrate=300
An optional second parameter may be specified to the open function. This is a mode flag that indicates to the protocol handler the intentions of the calling code. The options here specify if the connection is going to be read (READ), written (WRITE), or both (READ_WRITE). The use of these flag settings is protocol dependent. For instance, a connection for a printer would not allow read access, and would throw an IllegalArgumentException. If the mode parameter is not specified, READ_WRITE is used by default. Each Connection specifies for its protocol how the mode is used. Unless specified by the Connection, the mode is unused and does not change the behavior of the Connection or Connector methods that return Connections.
An optional third parameter is a boolean flag that indicates
if the calling code can handle timeout exceptions. If this
flag is true
, the protocol implementation may throw an
InterruptedIOException when it detects a timeout condition.
This flag is only a hint to the protocol handler, and it
does not guarantee that such exceptions will actually be thrown.
If this parameter is false
or not supplied, no timeout exceptions will be
thrown.
ConnectionOption
are protocol-specific and allow
specifying a variable number of additional connection settings used
by the protocol implementation. For example, to supply a timeout value
or to select an AccessPoint
for the network connection.
The set of connection options, that are available to a protocol,
are inherited from the super interfaces of the protocol.
Refer to each protocol for other applicable ConnectionOption
s.
Failures to open a connection are either reported with exceptions
that are derived from IOException or with ConnectionNotFoundException
.
If the address of the remote host cannot be determined, ConnectionNotFoundException
is linked to a java.net.UnknownHostException
, which can be queried with
ConnectionNotFoundException.getCause()
.
If the underlying platform cannot determine the reason for ConnectionNotFoundException
or if the protocol is not supported,
ConnectionNotFoundException.getCause()
returns NULL
.
The exceptions that are reported by Connector.open via exceptions derived
from IOException
are typically defined by the underlying protocol.
For example on socket based protocols the exceptions that can be thrown by
Connector.open
include:
java.net.BindException
- Signals that an error occurred while attempting
to bind a socket to a local address and port.
java.net.ConnectException
- Signals that an error occurred while attempting
to connect a socket to a remote address and port.
java.net.NoRouteToHostException
- Signals that an error occurred while
attempting to connect a socket to a remote address and port.
java.net.PortUnreachable
- Signals that an ICMP Port Unreachable message
has been received on a connected datagram.
AccessPoint
class and provides equivalent functionality.
The creation of a new Connection object is subject to a security check to verify that the caller has the security Permission associated with the requested protocol scheme. If the caller lacks the necessary permission, the invoked Connector method throws SecurityException.
Any attempt to open a Connection to a target, which can only be used exclusively, will result in an IOException. This applies to socket-based connections on the same local port and may apply to other connection types too.
Because connections are frequently opened just to gain access
to a specific input or output stream, four convenience
functions are provided for this purpose.
The behavior is the same as if Connector.open(name)
is
followed getting the input or output stream from the Connection.
See also: DatagramConnection
for information relating to addressing datagrams individually.
Modifier and Type | Field and Description |
---|---|
static int |
READ
Access mode READ.
|
static int |
READ_WRITE
Access mode READ_WRITE.
|
static int |
WRITE
Access mode WRITE.
|
Modifier and Type | Method and Description |
---|---|
static long |
getBytesRead(Connection connection)
Returns the number of bytes, that were received using this connection.
|
static long |
getBytesWritten(Connection connection)
Returns the number of bytes, that were sent using this connection.
|
static boolean |
isProtocolSupported(java.lang.String name,
boolean server)
Returns the supported status of a protocol.
|
static Connection |
open(java.lang.String name)
Create and open a Connection.
|
static Connection |
open(java.lang.String name,
ConnectionOption<?>... settings)
Create and open a Connection.
|
static Connection |
open(java.lang.String name,
int mode)
Create and open a Connection.
|
static Connection |
open(java.lang.String name,
int mode,
boolean timeouts)
Create and open a Connection.
|
static Connection |
open(java.lang.String name,
int mode,
boolean timeouts,
ConnectionOption<?>... settings)
Create and open a Connection.
|
static Connection |
open(java.lang.String name,
int mode,
ConnectionOption<?>... settings)
Create and open a Connection.
|
static java.io.DataInputStream |
openDataInputStream(java.lang.String name)
Create and open a connection input stream.
|
static java.io.DataOutputStream |
openDataOutputStream(java.lang.String name)
Create and open a connection output stream.
|
static java.io.InputStream |
openInputStream(java.lang.String name)
Create and open a connection input stream.
|
static java.io.OutputStream |
openOutputStream(java.lang.String name)
Create and open a connection output stream.
|
public static final int READ
public static final int READ_WRITE
public static final int WRITE
public static long getBytesRead(Connection connection) throws java.io.IOException
connection
- a Connection
java.io.IOException
- If an I/O error occurs or the operation is not supported for this connection.java.lang.NullPointerException
- if Connection
is null
.public static long getBytesWritten(Connection connection) throws java.io.IOException
connection
- a Connection
java.io.IOException
- If an I/O error occurs or the operation is not supported for this connection.java.lang.NullPointerException
- if Connection
is null
.public static boolean isProtocolSupported(java.lang.String name, boolean server)
true
value indicates the device contains an
implementation of the protocol scheme. The individual
Connection interfaces describe the features of the connection.
The name can be a simple protocol name or a URL.
The name is truncated before the first protocol delimiter ":",
if any; the truncated string is the protocol.
For network protocols, the client and server may be queried
separately using the server
parameter. Note that in
the case of most protocols, server support implies client support.
For non-network protocols such as "file"
or "comm"
the server
parameter is ignored.
The return value must be consistent with the behavior of Connector.open
methods with respect to throwing or not throwing ConnectionNotFoundException
.
name
- a protocol or URLserver
- false
to query client support;
true
to query server supporttrue
if the protocol is supported for client or server
as requested; false
otherwise, including if the name is emptyjava.lang.NullPointerException
- if name
is null
public static Connection open(java.lang.String name) throws java.io.IOException
file
protocol,
the file gets overwritten.name
- The URL for the connection.java.lang.IllegalArgumentException
- If a parameter is invalid.ConnectionNotFoundException
- If the target of the
name cannot be found, or if the requested protocol type
is not supported.java.io.IOException
- If some other kind of I/O error occurs,
for example, a timeout establishing the connection.java.lang.SecurityException
- If access to the
protocol handler is prohibited.public static Connection open(java.lang.String name, ConnectionOption<?>... settings) throws java.io.IOException
file
protocol,
the file gets overwritten.name
- The URL for the connection.settings
- An optional list of ConnectionOption
instances.java.lang.IllegalArgumentException
- If a parameter is invalid.ConnectionNotFoundException
- If the target of the
name cannot be found, or if the requested protocol type
is not supported.java.io.IOException
- If some other kind of I/O error occurs,
for example, a timeout establishing the connection.java.lang.SecurityException
- If access to the
protocol handler is prohibited.public static Connection open(java.lang.String name, int mode) throws java.io.IOException
file
protocol,
the file gets overwritten for mode WRITE or READ_WRITE.name
- The URL for the connection.mode
- The access mode.java.lang.IllegalArgumentException
- If a parameter is invalid.ConnectionNotFoundException
- If the target of the
name cannot be found, or if the requested protocol type
is not supported.java.io.IOException
- If some other kind of I/O error occurs,
for example, a timeout establishing the connection.java.lang.SecurityException
- If access to the
protocol handler is prohibited.public static Connection open(java.lang.String name, int mode, boolean timeouts) throws java.io.IOException
file
protocol,
the file gets overwritten for mode WRITE or READ_WRITE.name
- The URL for the connectionmode
- The access modetimeouts
- A flag to indicate that the caller
wants timeout exceptionsjava.lang.IllegalArgumentException
- If a parameter is invalid.ConnectionNotFoundException
- If the target of the
name cannot be found, or if the requested protocol type
is not supported.java.io.IOException
- If some other kind of I/O error occurs,
for example, a timeout establishing the connection.java.lang.SecurityException
- If access to the
protocol handler is prohibited.public static Connection open(java.lang.String name, int mode, boolean timeouts, ConnectionOption<?>... settings) throws java.io.IOException
file
protocol,
the file gets overwritten for mode WRITE or READ_WRITE.name
- The URL for the connectionmode
- The access modetimeouts
- A flag to indicate that the caller
wants timeout exceptionssettings
- An optional list of ConnectionOption
instances.java.lang.IllegalArgumentException
- If a parameter is invalid.ConnectionNotFoundException
- If the target of the
name cannot be found, or if the requested protocol type
is not supported.java.io.IOException
- If some other kind of I/O error occurs,
for example, a timeout establishing the connection.java.lang.SecurityException
- If access to the
protocol handler is prohibited.public static Connection open(java.lang.String name, int mode, ConnectionOption<?>... settings) throws java.io.IOException
file
protocol,
the file gets overwritten for mode WRITE or READ_WRITE.name
- The URL for the connection.mode
- The access mode.settings
- An optional list of ConnectionOption
instances.java.lang.IllegalArgumentException
- If a parameter is invalid.ConnectionNotFoundException
- If the target of the
name cannot be found, or if the requested protocol type
is not supported.java.io.IOException
- If some other kind of I/O error occurs,
for example, a timeout establishing the connection.java.lang.SecurityException
- If access to the
protocol handler is prohibited.public static java.io.DataInputStream openDataInputStream(java.lang.String name) throws java.io.IOException
(InputConnection)Connector.open(name, READ)
followed by InputConnection.getDataInputStream
.
The InputConnection is closed and the stream is returned.name
- The URL for the connection. Some possible URL
prefixes that can be used include: "file:", "comm:",
"http:", "socket:", and "ssl:" when available
by the implementation and following the
respective connection specification.java.lang.IllegalArgumentException
- If a parameter is invalid or
the Connection
returned from Connector.open
is not an InputConnection
.ConnectionNotFoundException
- If the target of the
name cannot be found, or if the requested protocol type
is not supported.java.io.IOException
- If some other kind of I/O error occurs.java.lang.SecurityException
- If access to the
protocol handler is prohibited.public static java.io.DataOutputStream openDataOutputStream(java.lang.String name) throws java.io.IOException
(OutputConnection)Connector.open(name, WRITE)
followed by OutputConnection.getDataOutputStream
.
The OutputConnection is closed and the stream is returned.
In case of file
protocol,
the file gets overwritten.name
- The URL for the connection. Some possible URL
prefixes that can be used include: "file:", "comm:",
"http:", "socket:", and "ssl:" when available
by the implementation and following the
respective connection specification.java.lang.IllegalArgumentException
- If a parameter is invalid or
the Connection
returned from Connector.open
is not an OutputConnection
.ConnectionNotFoundException
- If the target of the
name cannot be found, or if the requested protocol type
is not supported.java.io.IOException
- If some other kind of I/O error occurs.java.lang.SecurityException
- If access to the
protocol handler is prohibited.public static java.io.InputStream openInputStream(java.lang.String name) throws java.io.IOException
(InputConnection)Connector.open(name, READ)
followed by InputConnection.getInputStream
. The InputConnection
is closed and the stream is returned.name
- The URL for the connection. Some possible URL
prefixes that can be used include: "file:", "comm:",
"http:", "socket:", and "ssl:" when available
by the implementation and following the
respective connection specification.java.lang.IllegalArgumentException
- If a parameter is invalid or
the Connection
returned from Connector.open
is not an InputConnection
.ConnectionNotFoundException
- If the target of the
name cannot be found, or if the requested protocol type
is not supported.java.io.IOException
- If some other kind of I/O error occurs.java.lang.SecurityException
- If access to the
protocol handler is prohibited.public static java.io.OutputStream openOutputStream(java.lang.String name) throws java.io.IOException
(OutputConnection)Connector.open(name, WRITE)
followed by OutputConnection.getOutputStream
.
The OutputConnection is closed and the stream is returned.
In case of file
protocol,
the file gets overwritten.name
- The URL for the connection. Some possible URL
prefixes that can be used include: "file:", "comm:",
"http:", "socket:", and "ssl:" when available
by the implementation and following the
respective connection specification.java.lang.IllegalArgumentException
- If a parameter is invalid or
the Connection
returned from Connector.open
is not an OutputConnection
.ConnectionNotFoundException
- If the target of the
name cannot be found, or if the requested protocol type
is not supported.java.io.IOException
- If some other kind of I/O error occurs.java.lang.SecurityException
- If access to the
protocol handler is prohibited.Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved. Use of this specification is subject to license terms.