Programming Wireless Devices with the Java2 Platform

5.3 CLDC-Specific Classes

This section contains a description of the Generic Connection framework for supporting input/output and networking in a generalized, extensible fashion. The Generic Connection framework provides a coherent way to access and organize data in a resource-constrained environment.

5.3.1 Background and Motivation

The class libraries included in Java 2 Standard Edition and Java 2 Enterprise Edition provide a rich set of functionality for handling input and output access to storage and networking systems. For instance, in JDK 1.3.1, the package java.io contained 59 regular classes and interfaces, and 16 exception classes. The package java.net of JDK 1.3.1 consisted of 31 regular classes and interfaces, and 8 exception classes. It is difficult to make all this functionality fit in a small device with only a few hundred kilobytes of total memory budget. Furthermore, a significant part of the standard I/O and networking functionality is not directly applicable to today's small devices, which often do not have TCP/IP support, or which commonly need to support specific types of connections such as Infrared or Bluetooth.

In general, the requirements for the networking and storage libraries vary significantly from one resource-constrained device to another. For instance, device manufacturers who are dealing with packet-switched networks typically want datagram-based communication mechanisms, while those dealing with circuit-switched networks require stream-based connections. Due to strict memory limitations, manufacturers supporting certain kinds of networking capabilities generally do not want to support any other mechanisms. All this makes the design of the networking facilities for CLDC very challenging, especially since J2ME configurations are not allowed to define optional features. Also, the presence of multiple networking mechanisms and protocols is potentially very confusing to the application programmer, especially if the programmer has to deal with low-level protocol issues.

5.3.2 The Generic Connection Framework

The challenges presented above have led to the generalization of the J2SE networking and I/O classes. The high-level goal for this generalized design is to be a precise functional subset of J2SE classes, which can easily map to common low-level hardware or to any J2SE implementation, but with better extensibility, flexibility, and coherence in supporting new devices and protocols.

The general idea is illustrated below. Instead of using a collection of different kinds of abstractions for different forms of communication, a set of related abstractions are used at the application programming level.

General form

Connector.open("<protocol>:<address>;<parameters>");

HTTP

Connector.open("http://www.sun.com");

Sockets

Connector.open("socket://129.144.111.222:2800");

Communication ports

Connector.open("comm:com0;baudrate=9600");

Datagrams

Connector.open("datagram://129.144.111.222:2800");

All connections are created by calling the static method open of the class javax.microedition.io.Connector. If successful, this method will return an object that implements one of the javax.microedition.io.Connection interfaces shown in Figure 5.1. The Connector.open method takes a String parameter in the general form:

Connector.open("<protocol>:<address>;<parameters>");

The syntax of the Connector.open parameter strings should generally follow the Uniform Resource Indicator (URI) syntax as defined in the IETF standard RFC2396 (http://www.ietf.org/rfc/rfc2396.txt).

A central objective of this design is to isolate, as much as possible, the differences between the use of one protocol and another into a string characterizing the type of connection. This string is the parameter to the method Connector.open. A key benefit of this approach is that the bulk of the application code stays the same regardless of the kind of connection that is used. This is different from traditional implementations in which the abstractions and data types used in applications often change dramatically when changing from one form of communication to another.

The binding of protocols to a J2ME program is done at run time. At the implementation level, the string (up to the first occurrence of ':') that is provided as the parameter to the method Connector.open instructs the system to obtain the desired protocol implementation from a location where all the protocol implementations are stored. It is this late binding mechanism that permits a program to dynamically adapt to use different protocols at run time. Conceptually this is identical to the relationship between application programs and device drivers on a personal computer or workstation.

In order to read and write data to and from Generic Connections that have been opened using the Connector.open method, a number of input and output stream classes are provided. The input and output stream classes supported by CLDC are listed in Section 5.2.4, "Input/Output Classes." J2ME profiles may provide additional stream classes as necessary.

5.3.3 No Network Protocol Implementations Defined in CLDC

The Generic Connection framework included in CLDC does not specify the actual supported network protocols or mandate implementations of any specific networking protocols. The CLDC Specification provides an extensible framework that can be customized by J2ME profiles such as MIDP to support those protocols that specific device categories might need. The actual implementations and decisions regarding supported protocols must be made at the profile level. Refer to Chapter 15, "MIDP Networking and Serial Communications" and Chapter 16, "Secure Networking" for details on the MIDP networking libraries. Those chapters include a number of sample applications that illustrate the use of the Generic Connection framework.

5.3.4 Summary of the Generic Connection Interfaces

Connections to different types of devices will need to exhibit different forms of behavior. A file, for instance, can be renamed, but no similar operation exists for a TCP/IP socket. The Generic Connection framework reflects these different capabilities, ensuring that operations that are logically the same share the same API.

The Generic Connection framework is implemented using a hierarchy of Connection interfaces (located in package javax.microedition.io) that group together classes of protocols with the same semantics. This hierarchy consists of seven interfaces shown earlier in Figure 5.1. Additionally, there is the Connector class, one exception class (ConnectionNotFoundException), one other interface, and a number of data stream classes for reading and writing data. At the implementation level, a minimum of one class is needed for implementing each supported protocol. Often, each protocol implementation class contains simply a number of wrapper functions that call the native functions of the underlying host operating system.

There are six basic interface types that are addressed by the Generic Connection framework:

• A basic serial input device

• A basic serial output device

• A datagram-oriented communications device

• A circuit-oriented communications device

• A notification mechanism to inform a server of client-server connections

• A basic Web server connection

The collection of Connection interfaces forms a hierarchy that becomes progressively more capable as the hierarchy progresses from the root Connection interface. This arrangement allows J2ME profile designers or application programmers to choose the optimal level of cross-protocol portability for the libraries and applications they are designing.

The Connection interface hierarchy is illustrated in Figure 5.1. A brief summary of each interface class is provided below. For a definitive reference on the Connection interfaces, refer to the documentation that is provided as part of the CLDC reference implementation.

Interface Connection

This is the most basic connection type that can only be opened and closed. The open method is not included in the interface because connections are always opened using the static open method of the Connector class.

Methods:

public void close() throws IOException;

Interface InputConnection

This connection type represents a device from which data can be read. The openInputStream method of this interface will return an InputStream for the connection. The openDataInputStream method of this interface will return a DataInputStream for the connection.

Methods:

public InputStream openInputStream() throws IOException;
public DataInputStream openDataInputStream() throws IOException;

Interface OutputConnection

This connection type represents a device to which data can be written. The openOutputStream method of this interface will return an OutputStream for the connection. The openDataOutputStream method of this interface will return a DataOutputStream for the connection.

Methods:

public OutputStream openOutputStream() throws IOException;
public DataOutputStream openDataOutputStream() throws IOException;

Interface StreamConnection

This connection type combines the InputConnection and OutputConnection interfaces. It forms a logical starting point for classes that implement two-way communication interfaces.

Interface ContentConnection

This connection type is a sub-interface of StreamConnection. It provides access to some of the most basic metadata information provided by HTTP connections.

Methods:

public String getType();
public String getEncoding();
public long getLength();

Interface StreamConnectionNotifier

This connection type is used when waiting for a connection to be established. The acceptAndOpen method of this interface will block until a client program makes a connection. The method returns a StreamConnection on which a communications link has been established. Like all connections, the returned StreamConnection must be closed when it is no longer needed.

Methods:

public StreamConnection acceptAndOpen() throws IOException;

Interface DatagramConnection

This connection type represents a datagram endpoint. In common with the J2SE datagram interface, the address used for opening the connection is the endpoint at which datagrams are received. The destination for datagrams to be sent is placed in the datagram object itself. There is no address object in this API. Instead, a string is used that allows the addressing to be abstracted in a similar way as in the Connection interface design.

Methods:

public int getMaximumLength() throws IOException;
public int getNominalLength() throws IOException;
public void send(Datagram datagram) throws IOException;
public void receive(Datagram datagram) throws IOException;
public Datagram newDatagram(int size) throws IOException;
public Datagram newDatagram(int size, String addr)
       throws IOException;
public Datagram newDatagram(byte[] buf, int size)
       throws IOException;
public Datagram newDatagram(byte[] buf, int size, String addr)
       throws IOException;

This DatagramConnection interface requires a data type called Datagram that is used to contain the data buffer and the address associated with it. The Datagram interface contains a useful set of access methods with which data can be placed into or extracted from the datagram buffer. These access methods conform to the DataInput and DataOutput interfaces, meaning that the datagram object also behaves like a stream. A current position is maintained in the datagram. This is automatically reset to the start of the datagram buffer after a read operation is performed.

Refer to Chapter 15, "MIDP Networking and Serial Communications," and Chapter 16, "Secure Networking," for sample applications that illustrate the use of the Generic Connection framework and the interfaces listed above.