UDP 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 datagram 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 OSGi 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 datagram scheme.

The datagram scheme provides UDP-based connections using the standard Java platform API for UDP sockets (contained in the java.net package: DatagramSocket, DatagramPacket, etc.). It supports connections for sending and/or for receiving.

Each created connection implements two interfaces: javax.microedition.io.DatagramConnection, which is a subinterface of Connection, and ConnectionNotifier, which registers listeners for sending connections. A connection also extends java.util.Dictionary. The Dictionary is used to store connection-related properties (described later).

It is not obligatory for both parties communicating over UDP to use the UDP Connection Factory Service. As the UDP Connection Factory Service implementation simply cares to open standard UDP sockets, connection-requester applications can communicate with any UDP socket opened on the specified host. If the connection factory is unregistered, all created connections are closed.

Registering Bundle

The service is registered by OSGi UDP Connector Bundle – com.prosyst.mbs.osgi.connector.udp. The bundle wraps a connection factory implementing the datagram scheme. This scheme provides UDP based connection that can serve as an underlying layer for various protocols. It can be used by bundles which need communication with the local or remote OSGi framework.

Datagram Uniform Resource Identifiers (URIs)

All URIs processed by the UDP connection factory must start with "datagram://". There are two types of URIs: for sending and for receiving.

• sending URIs – this type of URI specifies a default destination host and port for sending datagram packets. It has the following syntax:

  datagram://<dest_host>:<port>[;<param>=<value>;<param>=<value>...]

  where <dest_host> stands for the default destination host for sending the datagram packets. <port> stands for the port on which the UDP server receiving the datagrams is listening. Note that the local port for sending the datagrams is not specified in the sending type of URI. The [..] brackets show an optional part, they are not part of the URI itself. They show that the datagram URI can optionally have one or more parameters separated by semi-colon. <param> is the name of the parameter, <value> is its value. Parameters are listed in the table below.

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

  datagram://remote.psb:3333

  Or the same URI with parameters:

  datagram://remote.psb:3333;maxLength=1024;timeout=30000

• receiving URIs – this type of URI specifies the local port through which datagrams are sent. It does not specify destination host and port.

  The syntax of a receiving URI is as follows:

  datagram://:<local_port>[;<param>=<value>;<param>=<value>...]

  <local_port> indicates the local port for receiving packets. The optional parameters that can be passed to this URI are the same as the parameters for receiving connections. See the table below:

  Parameter	Description
  maxLenght	Defines the maximum allowed length of datagrams sent/received.
  nomLenght	Defines the nominal length of datagram sent/received.
  timeout	The timeout in milliseconds for receiving.

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

Connection Properties

The Dictionary created by each connection contains the following list of properties:

The UDP connection factory keeps all opened connections in a Dictionary. If the service gets unregistered, all connections are closed.

Using the Service

If you want to use the UDP 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 datagram URI to its open method. For more information refer to the OSGi Connector Bundle description. You can manage the created connections using the methods of the DatagramConnection and ConnectionNotifier sub-interfaces of javax.microedition.io.Connection, and their connection properties using the values stored in the connection Dictionary.