SocketConnection

SocketConnection

The SocketConnection interface extends interface javax.microedition.io.StreamConnection to define the API to TCP/IP or similar socket streams. (Refer to the documentation of interface StreamConnection on page 69.)

Applications that need to accept connections from other applications must use ServerSocketConnection instead. See Section 15.6, "ServerSocketConnection" for more information.

An application opens a socket on a target host by calling the Connector.open method. The application must provide a URI string that starts with 'socket://' and is followed by a host name and port number separated by a colon. For example, 'socket://host.com:79' has the correct syntax to open a socket connection on the host.com system at port 79.

In the string the MIDlet can specify the host as a fully qualified host name or IPv4 number. Note that RFC1900 [reference 2] recommends the use of host names rather than IP numbers. Using the host name means the MIDlet can still make the connection, even if the host's IP number is reassigned. For example, 'socket://host.com:79' is preferred to 'socket://183.206.241.133:79'. If the connection string uses incorrect syntax, Connector.open throws an IllegalArgumentException exception.

The Connector.open method returns a SocketConnection instance. It has methods that enable the MIDlet to get the local and remote addresses and the local and remote port numbers, and to control socket options.

1 Getting the Local Address and Port Number

An application can get the local host address and port number for an open connection. (This information is needed primarily by applications that use a ServerSocketConnection to allow clients to make inbound connections to a system-assigned port. See Section 15.6, "ServerSocketConnection" for more information.) The getLocalAddress method returns the local IP number to which the socket is bound. Calling System.getProperty("microedition.hostname") returns the host name of the device, if it is available. The getLocalPort method returns the local port to which this socket is bound.

If an application sends address and port information to a remote application so that it can connect to the device, the application should try to send the host name of the device. IP addresses can be dynamically assigned, so a remote application with only an IP address will not be able to make contact if the device IP number changes. If a host name is available, sending it would help the remote application be more robust.

2 Getting the Remote Host Address and Port

An application can get the remote host address and port number for an open connection. The getAddress method returns the remote host (as either a host name or an IP address) to which the socket is bound. The getPort method returns the remote port to which this socket is bound. The methods get their return values from the string passed to Connector.open.

3 Getting and Setting Socket Options

An application can control some low-level socket options to optimize interactions with the network. The socket options inform the low-level networking code about the application's intended usage patterns. The options are listed in Figure.

The setSocketOption method sets the value for a socket option for the connection. The getSocketOption method returns the value for a socket option for the connection or –1 if the value is not available. Both methods throw an IllegalArgumentException if the value is not valid (for example, if the value is negative) or the option identifier is not valid.

For example, if a MIDlet calls the setSocketOption method to assign buffer sizes, the device can use this as a hint about the sizes to set the underlying network I/O buffers. The system might adjust the buffer sizes to account for better throughput available from Maximum Transmission Unit (MTU) and Maximum Segment Size (MSS) data available from current network information.

4 Closing Streams

Every stream connection has an associated Connection object, InputStream and OutputStream. These objects have their own close methods and, on systems that support duplex communication over the socket connection, closing the input or output stream shuts down only that side of the connection. For example, closing the InputStream does not stop the OutputStream from sending data.

Both the input and output stream must be closed before the connection is completely closed. Conversely, the application will receive an IOException if it tries to use a closed input stream, output streams, or socket connection.

5 Security of SocketConnection

Access to a socket connection is restricted to prevent unauthorized transmission or reception of data. MIDlet suites needing to use sockets must request the javax.microedition.io.Connector.socket permission for Trusted MIDlet suites as described in Section 18.3, "Trusted MIDlet Suite Security Model."

The device may try to authorize the MIDlet when the MIDlet calls the Connector.open method with a valid socket connection string. If the authorization fails and the MIDlet is not allowed to use the socket API, the Connector.open method throws a java.lang.SecurityException. The device might also check the MIDlet's permission when the MIDlet calls the openInputStream, openDataInputStream, openOutputStream, or openDataOutputStream methods.

6 Example

The following example shows the use of a SocketConnection to send and receive text from the echo port of a remote host. Refer to previous examples for the complete handling of exceptions and closing of streams and the connection.

// Open the socket and its associated streams. Set the linger time
SocketConnection sc =
    (SocketConnection)Connector.open("socket://host.com:7");
sc.setSocketOption(SocketConnection.LINGER, 5);
DataInputStream is  = sc.openDataInputStream();
DataOutputStream os = sc.openDataOutputStream();

// Write to and read from the remote echo port
os.writeUTF("Hello World\n");
os.flush();
String result = is.readUTF();
// Close the connection and its streams
is.close();
os.close();
sc.close();