GCF 8 (JSR360 Final Release)

Package javax.microedition.io

The Generic Connection Framework provides a simplified I/O mechanism.

See: Description

Package javax.microedition.io Description

The Generic Connection Framework provides a simplified I/O mechanism. I/O is performed by means of Connections obtained through the Connector factory class. Connections are dynamically created based on URIs conforming to RFC 3986, which take the general form:

{scheme}:[{hier-part}][?{query}][#{fragment}].

Please see the Connector class for more information. For each protocol scheme implemented the respective GCF security checks MUST be implemented.

GCF defines a set of protocols, which can be included by a Configuration or Profile. Each of these protocols is optional, unless otherwise specified. Implementations may define additional proprietary protocol schemes to offer additional protocols.

In general these protocol schemes are independent from each other and they can be implemented separately. The following exception to this rule apply:

Protocol Support

Each protocol scheme, if required by the Configuration or Profile, must be implemented as follows:

The exact syntax of the protocol schemes is defined in the individual protocol class.

For the protocols above, the {host} parameter can be a host name, such as "www.jcp.org", or a string representing its IPV4 or IPV6 literal address, such as "206.26.48.100" or "[1080:0:0:0:8:800:200C:4171]".

A literal IPv4 address is specified by the IPv4address rule of RFC 3986.
A literal IPv6 address is an IP-literal as defined by RFC 3986, which requires to surround the IPv6Address with square brackets ('[', ']').
IPvFuture addresses from RFC 3986 are not supported.

Generic Connection Framework Security Checks

Access to each protocol via the methods of javax.microedition.io.Connector is controlled by per protocol subclasses of GCFPermission and by host and port security checks in java.lang.SecurityManager or java.security.AccessController as appropriate for the platform.

Access is permitted if the check succeeds for either the per protocol permission or check succeeds for the host and port. If either check succeeds then the other check does not need to be performed.

Operating system access controls that prevent access to resources SHOULD be reported by throwing java.io.IOException with an informative message and MUST NOT throw java.lang.SecurityException.

Per Protocol Permissions

For a given protocol scheme, a corresponding security permission, {Scheme}ProtocolPermission, must be checked either by java.lang.SecurityManager or java.security.AccessController. The table below provides the permission corresponding to the original URL request.

Protocol/Function URI Form and Function AccessController.checkPermission
TCP/IP Client Socket socket://{host}:{port} SocketProtocolPermission("socket://{host}:{port}")
TCP/IP Server Socket socket://:{port} (open)

socket://{host}:{port} (acceptAndOpen)		 SocketProtocolPermission("socket://:{port}")

SocketProtocolPermission("socket://{host}:{port}")
HTTP 1.1 http://{host}[{path}]

http://{host}:{port}[{path}]		 HttpProtocolPermission("http://{host}[{path}]")

HttpProtocolPermission("http://{host}:{port}[{path}]")
HTTPS https://{host}[{path}]

http://{host}:{port}[{path}]		 HttpsProtocolPermission("https://{host}[{path}"]

HttpsProtocolPermission("https://{host}:{port}[{path}]")
Secure Socket ssl://{host}:{port} SSLProtocolPermission("ssl://{host}:{port}")
Secure Server Socket ssl://:{port} SSLProtocolPermission("ssl://:{port}")
File I/O file://[{host}]{abs_path} (mode READ)

file://[{host}]{abs_path} (mode WRITE)

file://[{host}]{abs_path} (mode READ_WRITE)		 FileProtocolPermission("file://[{host}]{abs_path}", "READ")

FileProtocolPermission("file://[{host}]{abs_path}", "WRITE")

FileProtocolPermission("file://[{host}]{abs_path}", "READ,WRITE")
Datagram Socket datagram://:{port} (open)

datagram://{host}:{port} (open)

datagram://{host}:{port} (send and receive)		 DatagramProtocolPermission("datagram://:{port}")

DatagramProtocolPermission("datagram://:0")

DatagramProtocolPermission("datagram://{host}:{port}")
Secure Datagram Socket dtls://{host}:{port} (open)

dtls://{host}:{port} (send and receive)		 DTLSProtocolPermission("dtls://{host}:{port}")
Multicast Datagram Socket multicast://:{port} (open)

multicast://{host}:{port} (open)

multicast://{host}:{port} (send and receive, join and leave)		 MulticastProtocolPermission("multicast://:{port}")

MulticastProtocolPermission("multicast://:0")

MulticastProtocolPermission("multicast://{host}:{port}")
NetworkUtilities N/A SocketProtocolPermission("socket://{host}:*")
Serial Ports comm://{portid}[{params}] CommProtocolPermission("comm://{portid}[{params}]")

Resource Based Access Control

Access to network hosts and ports and files can be permitted via the resource based checks of the SecurityManager. For each protocol the following SecurityManager checks permit access:

Protocol/Function URI Form and Function SecurityManager Check
TCP/IP Client Socket socket://{host}:{port} checkConnect({host}, {port})
TCP/IP Server Socket socket://:{port} (open)

Check the incoming host and port before returning from acceptAndOpen		 checkListen({port})

checkAccept({host}, {port})
HTTP 1.1 http://{host}[{path}]

http://{host}:{port}[{path}]		 checkConnect({host}, 80)

checkConnect({host}, {port})
HTTPS https://{host}[{path}]

https://{host}:{port}[{path}]		 checkConnect({host}, 443)

checkConnect({host}, {port})
Secure Socket ssl://{host}:{port} checkConnect({host}, {port})
Secure Server Socket ssl://:{port} (open)

Check the incoming host and port before returning from acceptAndOpen		 checkListen({port})

checkAccept({host}, {port})
File I/O file://{abs_path} (mode READ)

file://{abs_path} (mode WRITE)

file://{abs_path} (mode READ_WRITE)		 checkRead({abs_path})

checkWrite({abs_path})

checkRead({abs_path}) and checkWrite({abs_path})
Datagram Socket datagram://{host}:{port} (open)

datagram://:{port} (open)

datagram://{host}:{port} (send)

datagram://{host}:{port} (receive)		 checkListen(0)

checkListen({port})

checkConnect({host}, {port})

checkAccept({host}, {port})
Secure Datagram Socket dtls://{host}:{port} (open)

dtls://{host}:{port} (send)

dtls://{host}:{port} (receive)		 checkListen(0)

checkConnect({host}, {port})

checkAccept({host}, {port})
Multicast Datagram Socket multicast://{host}:{port} (open)

multicast://:{port} (open)

multicast://{host}:{port} (send)

multicast://{host}:{port} (receive)

multicast://{host}:{port} (join)

multicast://{host}:{port} (leave)

 checkListen(0)

checkListen({port})

checkConnect({host}, {port})

checkAccept({host}, {port})

checkAccept({host}, {port})

checkAccept({host}, {port})
Network Utilities N/A checkConnect({host}, -1)
Serial Ports N/A The only SecurityManager check applicable to the comm protocol is SecurityManager.checkPermission(CommProtocolPermission).

Extension of Per Protocol Permissions

The Generic Connection Framework may be extended through the definition of additional protocol schemes. A specification that extends the Generic Connection Framework should define both the connection type and GCFPermission subclass associated with the new protocol in a package unique to the specification.

Stream Handling Constraints

Each StreamConnection has one underlying InputStream and one OutputStream. Also each InputConnection and OutputConnection has only one underlying stream instance.

Opening a DataInputStream counts as opening the InputStream and opening a DataOutputStream counts as opening the OutputStream. Each stream may be opened multiple times using the methods of InputConnection, OutputConnection and StreamConnection. The stream returned from each call MUST either be the same OR share the same data buffer and read and/or write pointer (those of the single underlying stream instance.) Trying to open an InputStream from an InputConnection or an OutputStream from an OutputConnection again MUST NOT cause any exception.

Applications should match each call to open a stream with a call to close the stream in order to free resources used by the stream. Once all open streams of the same type (either input or output) are closed, an attempt to open another stream of the same type MUST cause an IOException.

The methods of StreamConnection and any of its streams are not synchronized. The only stream method that can be called safely in another thread is close. When the close method is invoked on a stream that is executing in another thread, any pending I/O method MUST throw an InterruptedIOException. In the above case implementations SHOULD try to throw the exception in a timely manner. When all open input streams or all output streams have been closed, any pending I/O operations on those streams MUST be interrupted in a timely manner.

After calling the Connection.close method, regardless of open streams, further method calls to the connection will result in an IOException for those methods that are declared to throw IOException. For the methods that do not throw exceptions, unknown results may be returned.

References

GCF 8 (JSR360 Final Release)
4-April-2014 03:30

Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved. Use of this specification is subject to license terms.