Creating a Connection—The Connector Class

In the GCF, connections are established using the class Connector. By passing a URL describing the protocol to the open method of the Connector class, a connection is established. For example, the following line opens a Hypertext Transfer Protocol (HTTP) connection to the address http://java.sun.com:

try {
   Connection connection = Connector.open ("http://java.sun.com");
}
catch (IOException e) {
    // an error occurred while opening the connection.
}

In the case of an error, an IOException is thrown. Most of the GCF methods can throw an IOException in order to report I/O errors to the application.

If the connection is established successfully, an instance of a class implementing the Connection interfaces is returned. Other special interfaces derived from Connection are available for different connection types like datagram or stream connections. Figure 6.1 gives an overview of the corresponding GCF interfaces.

The general Connection interface itself does not implement much functionality. It only defines the close() method that is needed to terminate a connection that was opened using the open() method of the Connector class. The functionality for reading and writing data is added in InputConnection and OutputConnection. The InputConnection defines two methods for reading data from the connection: openInputStream() returns an InputStream, and openDataInputStream() returns a DataInputStream. Analogously, the OutputConnection provides two methods, openOutputStream() and openDataOutputStream(), returning the corresponding streams for writing data.

Probably the most important connection interface is the StreamConnection, combining the InputConnection and OutputConnection in one interface. It is used directly or as base interface for most connection types. It is the base interface for the ContentConnection, which adds functionality for accessing the meta-information available for HTTP connections. For datagram connections, the GCF provides the DatagramConnection interface, representing an endpoint for datagrams. Finally, the GCF supports the interface StreamConnectionNotifier that corresponds to J2SE ServerSockets. This interface consists of only one acceptAndOpen() method. This method returns a StreamConnection when a client has successfully established a connection.

For filesystem and serial port connectivity, the PDAP provides the FileConnection and CommConnection interfaces. These connections are optional to a PDAP implementation depending on the underlying hardware and operating system.

We have already shown the simple open() method of the Connector class, taking a URI string as input and returning an instance of a class implementing the Connection interface. However, this is not the only open() method available; the Connector class provides two additional open() methods. The second variant of open() takes an additional mode integer constant that determines whether the connection is read-only, write-only, or a read-write connection. The corresponding constants are listed in Table 6.2. The last variant of the open() method takes a third parameter, indicating that the protocol may throw an InterruptedIOException in the case of a device-specific timeout. Without using additional parameters, the behavior of the open() method is to open a connection in READ_WRITE mode, without throwing timeout exceptions.

The optional parameters depend on the protocol to which they are passed. For instance, the connection mode WRITE might result in an IllegalArgumentException if it is used to open a protocol for accessing a bar code scanner allowing read-only access.

We already mentioned that a concrete instance of a class implementing the Connection interface is returned when a connection is established successfully. In order to access the functionality of the concrete type of connection, the returned Connection needs to be typecast to the corresponding sub-interface. For example, when opening an HTTP connection, it usually makes sense to cast the returned object to the more specific HttpConnection interface:

HttpConnection httpConnection =
    (HttpConnection) Connector.open ("http://java.sun.com");

In the following section, we will take a closer look at the different connection types that are listed in the CLDC specification.