How to write a URC TUN in Java

The abbreviation TUN stands for 'Target-URC-Network'. The TUN Link manages Network specific functions to Discover/Communicate Devices in the Network. It abstracts the underlying Network specific jargon for a Target/Client implementor. The TUN Link may act as a translator between already existing Networking Architectures (e.g. UPnP, Jini, HAVi) and a URC Architecture.

Select your Networking Architecture using which Devices can Discover/Communicate with each other. You can either implement the URC-Architecture directly on an existing Physical Network Layer Architecture(WLAN, LAN, Bluetooth, etc.) or select from several Networking Architectures popular in the Industry: Jini, UPnP, HAVi, etc, which also work on popular Physical Networks Layers. We will consider the example of UPnP Networking Architecture. This tutorial will explain how our TUN will translate UPnP Network specific functionality to URC-architecture specific functionality.

We have a sample ClientTunManager, which manages Client's and TUN's. Please see: Client - Binding to and configuring a TUN

When a Client binds to a TUN, then this process triggers the method:

IClientTun.configureForClient(IClient client, Map<String, Object> parameterMap)

The TUN implementor can do the necessary things as regards to the Networking Architecture being implemented. For example: in Upnp2sClientTun, the above method creates a New UPnP Device on the fly using the information from the 'parameterMap'. This Device can be discovered/communicated with, in the UPnP network.

When a Client unbinds from a TUN, then it triggers the method:

IClientTun.unbindClient(IClient client)

The TUN implementor can do the necessary things as regards to the Networking Architecture being implemented. For example: in Upnp2sClientTun, the above method stops the UPnP Device which was created on the fly.

A Listener has to be set for Listening to the events received from the TUN. Using the following method for setting Listener to Target/Client:

IClientTun.setListener(IClientTunListener clientTunListener)

In present UrcSdk, ClientTunManager, is an IClientTunListener.

When a Client discovers a Target Device in the Network, using the Networking Architecture of choice, then the TUN has the responsibility of finding the Target Description XML file for that Target Device and create a new edu.wisc.trace.urcsdk.client.TargetMirror using it.

For example in the UPnP Architecture, a ControlPoint is used for Device Discovery. So this ControlPoint discovers the TargetDevice and posts the details to the TUN and the TUN inturn finds out the appropriate Target Description document from the Resource Server or from the Target details.

After creating the TargetMirror, the TUN posts this event to the Listener, as following:

IClientTunListener.targetDiscovered(IClient client, TargetMirror targetMirror)

When the Target stops or gets removed from the Network, then TUN removes all references for that particular Target and posts a message to the IClientTunListener:

IClientTunListener.targetDiscarded(TargetMirror targetMirror)

After discovering a Target Device in the Network, a Client tries to open a Session using a particular Socket. Finally the following method in the Client TUN is called:

IClientTun.openSessionRequest(IClient client, TargetMirror target, UISocketMirror socket)

The above method has to be implemented according to Network Specific functions for sending the message to the Target and getting a SessionId in return. For example: the Upnp2sClientTun invokes the UPnP Action on the Target Device of choice.

For the Client to invoke a Command on the Target, or set the Value of a Variable, please refer: Client - InvokeCommand/SetValue The above method finally calls either of the following methods in the Client TUN:

IClientTun.invokeCommandRequest(IUISocketElement socketElement) or
IClientTun.setElementStateRequest(IUISocketElement socketElement)

The above methods have to be implemented according to Network Specific functions for sending the message to the Target. For example: the Upnp2sClientTun invokes the UPnP Action on the Target Device.

On the Client-side, when the updateElementState message is received from the Network, then the IClientTun's following method should be called:

IClientTun.updateElementState(String sessionId, String elementId, String elementValue)

The above method should inturn call:

IClientTunListener.updateElementState(String sessionId, String elementId, String elementValue)

The Client receives the update and accordingly updates the User Interface.

A 'Close Session' message is sent from a Client to the Target. The message flows as follows:

IClientTun.closeSession(String sessionId) through Network, to
ITargetTun.closeSession(String sessionId) to
ITargetTunListener.closeSession(String sessionId)

The Target further takes care of closing the session properly.