javax.microedition.io

MID Profile includes networking support based on the Generic Connection framework from the Connected, Limited Device Configuration.

HTTP Networking

In addition to the javax.microedition.io classes specified in the Connected Limited Device Configuration the Mobile Information Device Profile includes the following interface for the HTTP access. An HttpConnection is returned from Connector.open() when an "http://" connection string is accessed.

• javax.microedition.io.HttpConnection

The MIDP extends the connectivity support provided by the Connected, Limited Device Configuration (CLDC) with specific functionality for the GenericConnection framework. The MIDP supports a subset of the HTTP protocol, which can be implemented using both IP protocols such as TCP/IP and non-IP protocols such as WAP and i-Mode, utilizing a gateway to provide access to HTTP servers on the Internet.

The GenericConnection framework is used to support client-server and datagram networks. Using only the protocols specified by the MIDP will allow the application to be portable to all MIDs. MIDP implementations MUST provide support for accessing HTTP 1.1 servers and services.

There are wide variations in wireless networks. It is the joint responsibility of the device and the wireless network to provide the application service. It may require a gateway that can bridge between the wireless transports specific to the network and the wired Internet. The client application and the Internet server MUST NOT need to be required to know either that non-IP networks are being used or the characteristics of those networks. While the client and server MAY both take advantage of such knowledge to optimize their transmissions, they MUST NOT be required to do so.

For example, a MID MAY have no in-device support for the Internet Protocol (IP). In this case, it would utilize a gateway to access the Internet, and the gateway would be responsible for some services, such as DNS name resolution for Internet URLs. The device and network may define and implement security and network access policies that restrict access.

HTTP Network Connection

The GenericConnection framework from the CLDC provides the base stream and content interfaces. The interface HttpConnection provides the additional functionality needed to set request headers, parse response headers, and perform other HTTP specific functions.

The interface MUST support:

HTTP 1.1

Each device implementing the MIDP MUST support opening connections using the following URL schemes (RFC2396 Uniform Resource Identifiers (URI): Generic Syntax)

"http" as defined by RFC2616 Hypertext Transfer Protocol -- HTTP/1.1

Each device implementing the MIDP MUST support the full specification of RFC2616
HEAD, GET and POST requests. The implementation MUST also support the absolute forms of URIs.

The implementation MUST pass all request headers supplied by the application and response headers as supplied by the network server. The ordering of request and response headers MAY be changed. While the headers may be transformed in transit, they MUST be reconstructed as equivalent headers on the device and server. Any transformations MUST be transparent to the application and origin server. The HTTP implementation does not automatically include any headers. The application itself is responsible for setting any request headers that it needs.

Connections may be implemented with any suitable protocol providing the ability to reliably transport the HTTP headers and data.(RFC2616 takes great care to not to mandate TCP streams as the only required transport mechanism.)

HTTP Request Headers

The HTTP 1.1 specification provides a rich set of request and response headers that allow the application to negotiate the form, format, language, and other attributes of the content retrieved. In the MIDP, the application is responsible for selection and processing of request and response headers. Only the User-Agent header is described in detail. Any other header that is mutually agreed upon with the server may be used.

User-Agent and Accept-Language Request Headers

For the MIDP, a simple User-Agent field may be used to identify the current device. As specified by RFC2616, the field contains blank separated features where the feature contains a name and optional version number.

The application is responsible for formatting and requesting that the User-Agent field be included in HTTP requests via the setRequestProperty method in the interface javax.microedition.io.HttpConnection. It can supply any application-specific features that are appropriate, in addition to any of the profile-specific request header values listed below.

Applications are not required to be loaded onto the device using HTTP. But if they are, then the User-Agent request header should be included in requests to load an application descriptor or application JAR file onto the device. This will allow the server to provide the most appropriate application for the device.

The user-agent and accept-language fields SHOULD contain the following features as defined by system properties using java.lang.System.getProperty. If multiple values are present they will need to be reformatted into individual fields in the request header.

System Properties Used for User-Agent and Accept-Language Request Headers

HTTP Request Header Example

User-Agent: Profile/MIDP-2.1 Configuration/CLDC-1.0
Accept-Language: en-US

StreamConnection Behavior

All MIDP StreamConnections have one underlying InputStream and one OutputStream. Opening a DataInputStream counts as opening an InputStream and opening a DataOutputStream counts as opening an OutputStream. Trying to open another InputStream or another OutputStream from a StreamConnections causes an IOException. Trying to open InputStream or OutputStream after they have been closed causes an IOException.

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

The methods of StreamConnections are not synchronized. The only stream method that can be called safely in another thread is close. When close 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 streams have been closed, and when the StreamConnections is closed, any pending I/O operations MUST be interrupted in a timely manner.

Secure Networking

Since the MIDP release additional interfaces are available for secure communication with WWW network services. Secure interfaces are provided by HTTPS and SSL/TLS protocol access over the IP network. Refer to the package documentation of javax.microedition.pki for the details of certificate profile that applies to secure connections. An HttpsConnection is returned from Connector.open() when an "https://" connection string is accessed. A SecureConnection is returned from Connector.open() when an "ssl://" connection string is accessed.

• javax.microedition.io.HttpsConnection
• javax.microedition.io.SecureConnection
• javax.microedition.io.SecurityInfo
• javax.microedition.pki.Certificate
• javax.microedition.pki.CertificateException

Low Level IP Networking

Since the MIDP release, the MIDP specification also includes optional networking support for TCP/IP sockets and UDP/IP datagrams. For each of the following schemes, a host is specified for an outbound connection and the host is omitted for an inbound connection. The host can be a host name, a literal IPv4 address or a literal IPv6 address (according to RFC2732 square bracket characters '[' ']' may be used to designate an IPv6 address in URL strings). Implementations MUST be able to parse the URL string and recognize the address format used, but are not required to support all address formats and associated protocols.

When the host and port number are both omitted from the socket or datagram connection, the system will allocate an available port. The host and port numbers allocated in this fashion can be discovered using the getLocalAddress and getLocalPort methods. The colon (:) may be omitted when the connection string does not include the port parameter.

A SocketConnection is returned from Connector.open() when a "socket://host:port" connection string is accessed. A ServerSocketConnection is returned from Connector.open() when a "socket://:port" connection string is accessed. A UDPDatagramConnection is returned from Connector.open() when a "datagram://host:port" connection string is accessed.

• javax.microedition.io.SocketConnection
• javax.microedition.io.ServerSocketConnection
• javax.microedition.io.DatagramConnection
• javax.microedition.io.Datagram
• javax.microedition.io.UDPDatagramConnection

Push Applications

A PushRegistry is available in the MIDP release which provides a MIDlet with a means of registering for network connection events, which may be delivered when the application is not currently running.

• javax.microedition.io.PushRegistry

Serial Port Communications

A CommConnection is available in the MIDP release which provides a MIDlet with a means of registering for network accessing a local serial port as a stream connection.

• javax.microedition.io.CommConnection

Security of Networking Functions

The security model is found in the package javax.microedition.midlet and provides a framework that allows APIs and functions to be restricted to MIDlet suites that have been granted permissions either by signing or explicitly by the user. (See Security for MIDlet suites for details about granting specific permissions to a MIDlet suite.)

The risks associated with a MIDlet suite's use of the network are related the potential for network abuse and to costs to the device owner since network use may result in charges. MIDP provides a security framework in which network functions can be protected and allowed only to those applications that have requested and been granted appropriate permissions.

Each protocol is accessed by invoking javax.microedition.io.Connector.open with a URI including the protocol and arguments. The permissions below allow access to be granted individually to protocols. The functionality of the protocols is specified by subclasses of Connection interface that defines the syntax of the URI and any protocol specific methods. Devices are NOT REQUIRED to implement every protocol. If a protocol is implemented, the security framework specifies the naming of permissions according to the package and class name of the APIs used to access the protocol extended with the protocol name. The API providing access is javax.microedition.io.Connector.open. The table below defines the corresponding permissions for the protocols defined within this specification.

Security of PushRegistry

The PushRegistry is protected using the security framework and permissions. The MIDlet suite must have the javax.microedition.io.PushRegistry permission to register an alarm based launch, to register dynamically using the PushRegistry, to make a static registration in the application descriptor and to determine if the user needs to be prompted prior to invoking MIDlet suite in response to a Push connection event or alarm. The protection domain defines the general behavior for user permissions with the interaction modes of "oneshot", "session", and "blanket". For the PushRegistry and the AMS, launching behavior is specialized:

• Oneshot: The user is prompted before the MIDlet suite is invoked to handle a push event or alarm and for each PushRegistry request; for example to register an alarm or a connection.
• Session: The user is prompted before the MIDlet suite is invoked to handle a push event or alarm, or before the first PushRegistry request; for example to register an alarm or a connection. Subsequently, when a MIDlet uses the PushRegistry the user is not prompted.
• Blanket: The user is prompted only once during installation, before the first time the MIDlet suite is invoked to handle a push event or alarm, or uses the PushRegistry.

The push mechanism uses protocols in which the device is acting as the server and connections can be accepted from other elements of the network. To use the push mechanisms the MIDlet suite will need the permission to use the server connection. For example, to register a chat program that can be started via push might use the following attributes in the manifest:

MIDlet-Push-1: socket://:79, com.sun.example.SampleChat, *
MIDlet-Permissions: javax.microedition.io.PushRegistry, javax.microedition.io.Connector.serversocket
     

The creation of Connections is performed dynamically by looking up a protocol implementation class whose name is formed from the platform name (read from a system property) and the protocol name of the requested connection (extracted from the parameter string supplied by the application programmer.) The parameter string that describes the target should conform to the URL format as described in RFC 2396. This takes the general form:

{scheme}:[{target}][{params}]

where {scheme} is the name of a protocol such as http}.

The {target} is normally some kind of network address.

Any {params} are formed as a series of equates of the form ";x=y".

Since this is an interface class, the internal structure of the datagram packets is not defined here.

Reminder: Since the CLDC Specification does not define any actual network protocol implementations, the syntax for datagram addressing is not defined in the CLDC Specification. Rather, syntax definition takes place at the level of J2ME profiles such as MIDP.

In the sample implementation that is provided as part of the CLDC implementation, the following addressing scheme is used:

The parameter string describing the target of a connection in the CLDC implementation takes the following form:

 {protocol}://[{host}]:[{port}]
 

HTTP is a request-response protocol in which the parameters of request must be set before the request is sent. The connection exists in one of three states:

• Setup, in which the request parameters can be set
• Connected, in which request parameters have been sent and the response is expected
• Closed, the final state, in which the HTTP connection as been terminated

• setRequestMethod
• setRequestProperty

A secure connection MUST be implemented by one or more of the following specifications:

• HTTP over TLS as documented in RFC 2818 and TLS Protocol Version 1.0 as specified in RFC 2246.
• SSL V3 as specified in The SSL Protocol Version 3.0
• WTLS as specified in WAP Forum Specifications June 2000 (WAP 1.2.1) conformance release - Wireless Transport Layer Security document WAP-199.
• WAP(TM) TLS Profile and Tunneling Specification as specified in WAP-219-TLS-20010411-a

HTTPS is the secure version of HTTP (IETF RFC2616), a request-response protocol in which the parameters of the request must be set before the request is sent.

In addition to the normal IOExceptions that may occur during invocation of the various methods that cause a transition to the Connected state, CertificateException (a subtype of IOException) may be thrown to indicate various failures related to establishing the secure link.

A secure socket is accessed using a generic connection string with an explicit host and port number.

It provides the certificate, protocol, version, and cipher suite, etc.

A server socket is accessed using a generic connection string with the host omitted.

A socket is accessed using a generic connection string with an explicit host and port number.

In a typical implementation of this interface (for instance in MIDP), all StreamConnections have one underlying InputStream and one OutputStream. Opening a DataInputStream counts as opening an InputStream and opening a DataOutputStream counts as opening an OutputStream.