You are here: MyURC.org > Tools & Prototypes > UCHj > tutorial > How to write a UIPM

How to Write a User Interface Protocol Module (UIPM)

---

Page Content:

---

Understand the UCH Architecture

You should be familiar with the URC framework and the UCH architecture.

Here are some useful documents:

• URC Technical Primer
• Universal Control Hub specification

Write Your UIPM

Your UIPM must implement the IUIPM interface, and may use any method of the IUIPMListener interface.

IUIPM has the following methods:

• init(IUIPMListener uipmListener, Map<String, String> uipmProps, Map<String,String> uchProps)

  • When the UIPM is installed and loaded, the UCH calls init() prior to any other UIPM function. This allows the UIPM to initialize itself.

  • UIPM programmer needs to list down the Sockets that are supported by the UIPM. Once decided, the uch.config file needs to be updated, so that UCH can decide to instantiate or assign a UIPM when a related Target (one with Socket Names that this UIPM supports) is discovered in the Network. For this to work properly, a UIPM implementor needs to modify the uch.config.

  • If UIPM fails to instantiate itself (because of uipmListener is null or uipmProps are invalid/in-sufficient or because of any other problem) then UIPM should throw UIPMFatalException().

  • UIPM should Store the reference of 'uipmListener' for invoking methods of IUIPMListener.

  • UIPM should start URI services for the URI's which are independent of any Target Control, by invoking startUriService() of IUIPMListener.

• void targetDiscovered( String targetId )

  • This function is called when a new target has been discovered after initialization of the UIPM.

  • UIPM should collect information(like targetName, Target Description URI, Socket Names, Socket Friendly Names, Socket Description URIs) for preparing a URI which the UIPM will service. It can call IUIPMListener's startUriService() to forward all requests on that URI to this UIPM. After that is done, it needs to call IUIPMListener's addCompatibleUI() for the registering to the UCH, so that UCH can show to the controllers, which Compatible UIs are available to control.

  • UIPM can get baseUri(http://myurc.org/ns/res#httpBaseUrl) from 'uipmProps' which is used for startUriService() for discovered Target.

  • UIPM should maintain information about all the URI's for which service is started, so that it can call IUIPMListener's stopServiceURI() when the target is discarded.

  • Read more in UCH Specification.

• void controllerRequest(HttpServletRequest request, HttpServletResponse response)

  • When UCH receives a request on a particular URI, which was registered by this UIPM, then it calls this method to forward the Request.

  • UIPM should parse the 'request' and invoke relative method of IUIPMListener. And make changes to the 'response' according to the return of the invoked IUIPMListener's method.

  • UIPM needs to call any one of the openSession(), getValues(), setValueRequest(),getResource() or closeSession() of the IUIPMListener according to the queryString and requestBody of 'request', or as defined by the UIPM protocol.

• void updateValues(List<String>sessionIds, List<String>paths, List<String>operations, List<String>values, List<Boolean>hasDynRes)

  • Called From IUIPMListener when value/state of target is changed.

  • UIPM has two ways to handle this:

    1. Store the updates locally, so that when a Get Updates request comes from the controller then it can send those updates.

    2. If UIPM supports some custom Update Channel with the Controller, then it can straight away push the updates to that Channel, in the format of its protocol.

• void sessionAborted(String sessionId)

  • Called from IUIPMListener when target encounter a problem that can not be fixed or target is discarded from network before calling targetDiscarded(), if session is existing with that target.

  • UIPM should clean up information about that session. It should also close any Update Channel, if exists, with the controller or any such session specific functionality provided by the UIPM.

• void targetDiscarded(String targetId)

  • Called from IUIPMListener when target encountered a problem that can not be fixed or target is discarded from the network.

  • UIPM should clean up all information about that target and also invoke stopServiceUri() and removeCompatibleUIs() of IUIPMListener for the URIs related to that target.

Configure the UCHj to Use Your UIPM

Please refer to How to Modify the UCHj Configuration.

---

Last update: Parikshit Thakur & Team, 2008-11-04