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:

• void init(IUIPMListener uipmListener, Map uipmProps, Map uchProps, Map[] contexts) throws UIPMFatalException

  • 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 properties in ".ucf" (UCH configuration file) offline file or the Resource Server 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.

  • If UIPM fails to instantiate itself (because 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.

  • Map[] contexts specifies a list of context's, and every context contains one userProfile and one controllerProfile that provides properties of User and Controller respectively. 'null' value of contexts specifies availablility for all users and controllers. Store the contexts for further usage. If UIPM doesn't want to restrict any Targets and URI services based on userProfile and controllerProfile then no need to do any implementation regarding contexts.

• void targetDiscovered(string targetId, Map[] contexts) throws UIPMFatalException

  • 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.

  • Map[] contexts specifies a list of context's, and every context contains one userProfile and one controllerProfile that provides properties of User and Controller respectively. 'null' value of contexts specifies availablility for all users and controllers. Store the contexts for further usage. If UIPM doesn't want to restrict any Targets and URI services based on userProfile and controllerProfile then no need to do any implementation regarding contexts.

  • 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 and their contexts for which service is started, so that it can call IUIPMListener's stopServiceURI() when the target is discarded.

  • Read more in UCH Specification.

• void contextsOpened(Map[] Contexts) throws TDMFatalException

  • It is called when new contexts are added in UCH.

  • UIPM should add these contexts to stored context's.

  • UIPM should call the method IUIPMListener.addUriServiceContexts(string uri, Map[] Contexts). If UIPM doesn't want to restrict targets and URI services based on userProfile and controllerProfile then no need to do any implementation regarding contexts.

• void contextsClosed(Map[] Contexts) throws TDMFatalException

  • It is called when new contexts are removed for specified target.

  • UIPM should remove these contexts from stored context's.

  • UIPM should call the method IUIPMListener.removeUriServiceContexts(string uri, Map[] Contexts). If UIPM doesn't want to restrict targets and URI services based on userProfile and controllerProfile then no need to do any implementation regarding contexts.

• Map[] getUriServiceContexts(string uri) throws UIPMFatalException

  • It is called when UCH wants to get already bound context's with specific URI.

  • UIPM should get contexts for specific URI from local Map of URI and contexts which is maintained by the values received when calling IUIPMListener.startUriService(IUIPM uipm, string scheme, int port, boolean portIsFlexible, string basePath, boolean basePathIsFlexible, Map[] contexts) , IUIPMListener.addUriServiceContexts(string uri, Map[] contexts) and IUIPMListener.removeUriServiceContexts(string uri, Map[] Contexts). If UIPM has not maintained contexts then just return null.

• void controllerRequest(HttpServletRequest request, HttpServletResponse response,Map context)

  • 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 UCHj to use your UIPM

Please refer to How to Add Local Resources .

---

Last update: Parikshit Thakur & Team, 2010-04-13