Overview   Package  Class  Use  Tree  Deprecated  Index  Help 
MIDP3.0
 PREV PACKAGE   NEXT PACKAGE FRAMES    NO FRAMES    

Package javax.microedition.io

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

See:
          Description

Interface Summary
CommConnection This interface defines a logical serial port connection.
HttpConnection This interface defines the necessary methods and constants for an HTTP connection.
HttpsConnection This interface defines the necessary methods and constants to establish a secure network connection.
IMCConnection This interface defines a low-level asynchronous bi-directional stream connection for the Inter-MIDlet Communication protocol (IMC).
IMCServerConnection This interface defines a server connection for the Inter-MIDlet Communication (IMC) protocol.
SecureConnection This interface defines the secure socket stream connection.
SecurityInfo This interface defines methods to access information about a secure network connection.
ServerSocketConnection This interface defines the server socket stream connection.
SocketConnection This interface defines the socket stream connection.
UDPDatagramConnection This interface defines a datagram connection which knows it's local end point address.
 

Class Summary
PushRegistry The PushRegistry maintains a list of inbound connections.
PushRegistryPermission The PushRegistryPermission class is used to check the static and dynamic registration of push connections and for registration of an alarm.
 

Package javax.microedition.io Description

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

Unless otherwise noted, passing a null argument to a constructor or method in any class or interface in this package MUST cause a NullPointerException to be thrown.

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.

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 IP protocol in this chapter covers both IPv4 and IPv6 addressing.

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

Figure 11-1 : HTTP Network Connection Over Various Stacks

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 ([RFC3986] , 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, POST, PUT and DELETE requests. The implementation MUST also support the absolute forms of URIs. Support for PUT and DELETE requests was added to version 3.0 of the MIDP specification.

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 for applications in other than Unidentified Third Party Protection Domains. The application itself is responsible for setting any request headers that it needs. For the MIDlets in the Unidentified Third Party Protection Domain, the HttpConnection and HttpsConnection MUST include in the User-Agent header the Product-Token "UNTRUSTED/1.0". User-Agent headers supplied by the application MUST NOT be deleted. This behavior for the Unidentified domain applications is specified in the Mobile Service Architecture (JSR 248) specification.

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 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

Table 11-1 : System Properties Used for User-Agent and Accept-Language Request Headers

System Property

Description

microedition.profiles

A blank (Unicode U+0020) separated list of the Java ME profiles that this device supports. For MIDP 3.0 implementations, this property MUST contain at least "MIDP-3.0".

microedition.configuration

The Java ME configuration supported by this device.

For example, "CLDC-1.1."

microedition.locale

The name of the current locale on this device.

For example, "en-US."

HTTP Request Header Example

User-Agent: Profile/MIDP-2.0 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 2.0 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.

Low Level IP Networking

Since the MIDP 2.0 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 '[' ']' MUST 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.

Push Applications

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

Serial Port Communications

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

IP Version Support

When a MIDlet executes on a device that has support for the Internet Protocol (IP), it MAY specify which version of IP to use, version 4, version 6 or either version. The specification of IP version MUST be done at installation time in the manifest and JAD. The attribute MIDlet-Required-IP-Version = value (ipv4|ipv6|any) specifies the IP version all MIDlets in a suite MUST use, or whether both are allowed. If the attribute is not given in the manifest, it means that the MIDlet is able to handle any type of IP addresses. If the implementation can not support the requested version, the MIDlet suite MUST fail to install and return Status Code 905 (Attribute Mismatch) to report the problem.

The attribute MIDlet-Required-IP-Version also has a runtime meaning. It means that the implementation MUST use the specified IP version in all the network connections used by the MIDlet. The implementation MUST NOT allow a MIDlet to make connections to ports that have been dedicated to different IP version usage than what the MIDlet is requiring. If the implementation cannot provide the MIDlet with the required IP version at runtime, an IOException MUST be thrown.

Inter-MIDlet Communications (IMC)

The MIDP Inter-MIDlet Communication protocol defines a low-level, asynchronous, bi-directional stream connection to support direct communication links between MIDlets. Very similar to the socket protocol, the IMC protocol provides for both client and server connection. When an IMC client makes a connection to a server, the IMC server is identified by MIDlet UID, and the IMC server name and version. The MIDlet UID is the unique identifier of a MIDlet suite, composed of the combination of the MIDlet's name, vendor, and version. The MIDlet UID is omitted in the connection URL strings when opening an IMC server connection. More information about the MIDlet UIDs can be found in Chapter 16.

The Inter-MIDlet Communication protocol MUST be supported by all implementations.

LIBlets enable MIDlet suites to share software components; however, a MIDlet suite and the LIBlets it depends upon are statically bound at installation into a single isolated runtime execution environment. Further, code belonging to a single LIBlet and bound to multiple MIDlet suites' execution environments cannot easily exchange data at runtime.

With the introduction of Inter-MIDlet communication, a MIDlet will be able to access a shareable component running inside another execution environment through thin client APIs, and thus make possible component-based programming for MIDP applications. The shareable component runs inside another MIDlet execution environment and handles requests from other MIDlets.

An example use case for Inter-MIDlet communication is a media decoder. In this use case, a media player MIDlet invokes a GUI-less decoder MIDlet through an IMC connection to decode a media stream with a content type not supported by the device. These decoder MIDlets are executed as if they were LIBlets bound to the player MIDlet, but can be individually installed or deleted and run inside isolated execution environments.

The following interfaces are defined for Inter-MIDlet communication:

An IMC server has the ability to restrict the set of clients that are allowed to connect to it. This is achieved by specifying the need for access authorization when a server connection is created. Only clients that match a server MIDlet's access authorization requirements are allowed to connect to the server; see Application Level Access Authorization for more details.

A MIDlet starting an IMC server can be launched in the background when the device is powered on, or at client request. Unlike LIBlet code static sharing, a MIDlets IMC server can be independently shut down and unloaded from memory if it is no longer serving client requests. An IMC server can either display screens to the user to gather inputs upon receiving a request from a client, or do the processing in the background silently without any GUI, as if it were part of the original MIDlet's execution to the user's experience.

Security of Networking Functions

The MIDP security model 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 MIDP Applications for details about granting specific permissions to a MIDlet suite.

The risks associated with a MIDlet suite's use of the network are related to the potential for network abuse and to costs to the device owner since network usage 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.

Connections made using the Generic Connection Framework Connector.open to local addresses on the device do not cause chargeable events and as such SHOULD NOT result in a prompt to the user. This includes access to hostname "localhost", the IP address 127.0.0.1, and other local IP addresses.

Each protocol is accessed by invoking javax.microedition.io.Connector.open with a URI including the protocol and arguments. CLDC 1.1.1 defines the permissions that protect access to protocols accessed via Connector.open. Devices are NOT REQUIRED to implement every protocol.

Security of PushRegistry

The PushRegistry is protected using the security framework and permissions. The MIDlet suite must have the javax.microedition.io.PushRegistryPermission to register an alarm based launch, to register dynamically using the PushRegistry and to make a static registration in the application descriptor. PushRegistryPermission also determines if the user needs to be prompted prior to invoking a MIDlet in response to a Push connection event or an alarm. When user is prompted on the event of an alarm or push registration, the implementation SHOULD allow for user to select whether to be prompted or not for application auto-launch.

The interaction modes control when the user is prompted to access the protected PushRegistry functionality. Depending on the policy, they user MAY be prompted only once or each time restricted function is called, including the automatic launch of the application. If the user is prompted at installation time to allow static push registration and the user does not accept the prompt, the installation of the MIDlet suite SHOULD fail with status code 910.

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-Permission-1: javax.microedition.io.PushRegistryPermission "socket:" "static,dynamic"
MIDlet-Permission-2: javax.microedition.io.SocketProtocolPermission "socket://"

Since:
MIDP 1.0
Overview   Package  Class  Use  Tree  Deprecated  Index  Help 
MIDP3.0
 PREV PACKAGE   NEXT PACKAGE FRAMES    NO FRAMES    
Send a comment or suggestionVersion 3.0 of Mobile Information Device Profile Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-2009 Motorola Inc. Portions copyright 1993-2002 Sun Microsystems, Inc. and Motorola, Inc. All Rights Reserved.