Socket Connection Factory Service

Represents a connection factory for the OSGi communication model (described in the OSGi IO Connector Service Specification) for creating connections over the socket scheme.

Overview

This service publishes the org.osgi.service.io.ConnectionFactory interface and represents a connection factory for the OSGi communication model, described in the OSGi IO Connector Service Specification. It is used by the IO Connector Service (exported by the OSGi Connector Bundle or by the System Bundle, depending on the version of the framework) for creating connections over the socket scheme.

The Socket Connection Factory supports two types of connection: server side and client side.

Server side connections – If the bundle initiator wants a server side connection waiting for client connections, the Socket Connection Factory will create a server TCP/IP socket (a java.net.ServerSocket object) to wait for client connections on the specified port. The created connection implements two interfaces: org.mbs.services.io.ConnectionNotifier and javax.microedition.io.StreamConnectionNotifier, which extends javax.microedition.io.Connection. The connection also extends java.util.Dictionary, which is used to hold specific connection properties (described in the Connection Properties part).

Creating a server side connection requires passing a server socket URI to the IO Connector Service.

Client side connections – In this case the Socket Connection Factory opens a client TCP/IP socket (java.net.Socket object) to initiate sending and/or receiving data with the server. This means that there should be a server side connection already open on the desired host (and on the desired port). The client connection implements two interfaces: org.mbs.services.io.ConnectionNotifier and javax.microedition.io.StreamConnection. The connection also extends java.util.Dictionary, used to hold specific connection properties (described later in this document).

Creating a client side connection requires passing a client socket URI to the IO Connector Service.

It is not obligatory for both parties of the TCP/IP communication channel to use the Socket Connection Factory Service. As the Socket Connection Factory Service implementation simply cares to open client- or server-side sockets, the connection-requester applications can communicate with any server or client socket opened on the specified host. For example, if a requests client connection through the URI: socket://remote.test:888 (see Client-Side URIs), a connection will be established to the specified host on port 888, no matter if the port has been opened through the Socket Connection Factory Service or not. If the connection factory is unregistered, all created connections are closed.

Registering Bundle

The service is registered by OSGi Socket Connection Bundle.

Socket Uniform Resource Identifiers (URIs)

The URIs passed to client and server side connections slightly differ. The URI needed for a client socket connection must contain the address on which the server socket is opened.

All URIs processed by the Socket Connection Factory must start with "socket://".

Server-Side Socket URIs

A server-side URI is passed when we need to open a server socket listening on the specified port. The format of a server-side URI is:

socket://:<port>[;time-out=<millis>]

Where <port> stands for the occupied port number. The timeout=<millis> part is optional. If timeout is set, IOException will be thrown when the timeout expires.

If zero is passed as a port value to a server side URI, the server socket will be bound to an arbitrary free port.

For example, a valid server URI may look like this:

socket://:3333

Or, if we want to specify the connection timeout:

socket://:3333;timeout=50000

Client-Side Socket URIs

A client-side URI is passed when we need to establish connection with a server socket listening on some port. It requires the following syntax:

socket://<host>:<port>[;timeout=<millis>]

where <host> stands for the IP address or DNS name of the server you need to contact. <port> stands for the server port on which the server is listening for connections. The timeout=<millis> part is optional. If it is included, it will indicate a timeout in milliseconds for the connections. For example, a valid socket URI may look like this:

socket://test:333

Some parts of the URI are case sensitive! For details, refer to RFC 2396.

Connection Properties

The Dictionary used by both client and server connections contains the following list of properties related to the connection:

Property	Client Connection	Server Connection	Description
local_address	available	available	The local address to which the socket is bound.
local_port	available	available	The local port to which this socket is bound.
address	available	not available	The address to which the socket is connected.
port	available	not available	The remote port to which this socket is connected.
timeout	optional	optional	The timeout in milliseconds. The timeout must be > 0. A timeout of zero is interpreted as an infinite timeout.

Using the Service

If you want to use the Socket Connection Factory Service as an underlying transport implementation for your connections, you must invoke the OSGi Connector Service, exported by the Connector Service Bundle, and pass a socket URI to its open method. For more information refer to the Connector Bundle description. You can manage the created connections using the methods of the respective sub-interfaces of javax.microedition.io.Connection, and their connection properties using the values stored in the connection Dictionary. Refer to "Client-Side Socket URIs" and "Server-Side Socket URIs" sections above for details.