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

How to Write a Target Adapter (TA)

---

Page Content:

---

Understand the UCH Architecture

Please refer to the UCH specification.

Write Your TA

Your TA must implement the ITA interface, and may use any method of the ITAListener interface.

ITA has the following methods:

• void init(ITAListener taListener, Map taProps, Map uchProps) throws TAFatalException
  • init() is called only once by the UCH prior to any other method of TA when any target is discovered in the network. UCH decides to instantiate this TA for communicating with that particular Device (for which this TA is implemented).
  • UCH has a Resource Manager, which searches for appropriate TA, for Targets discovered by the Target Discovery Manager (TDM). At present the UCH uses Resource Manager for searching the proper TA class, using the Target properties provided the TDM.
  • Store the reference to 'taListener' for sending updates/events to UCH which are further forwarded to Client through the appropriate UIPM (selected by the Client).
  • One of the uchProps keys - 'docRoot' points to the [TOMCAT_HOME]/webapps/UCH/. This key is assigned by UCH itself on startup. In UCH offline mode, please add the TD, UIS and RSHEET's for this TA as a UCH offline resource.
• void registerTarget(string targetId, Map targetProps, Map[] contexts) throws TAException, TAFatalException
  • It is called when target is registered in UCH. 'targetProps' Map has the Device properties that are parsed by the TDM and forwarded to the UCH.
  • TA should parse Target Description File(.td) and its Socket Description Files(.uis) and get the Elements which are used to save state/value of the Device discovered from network.
  • If TA has to subscribe to services of the Device, then TA should subscribe to all such services, for sending updates to Controllers.
  • Map[] contexts - specifies a list of contexts, and every context contains one userProfile and one controllerProfile that provides properties of User and Controller respectively. 'null' value of contexts specifies target is available for all users and controllers. Store the contexts for further usage. If TA doesn't want to restrict session based on userProfile and controllerProfile then no need to do any implementation regarding contexts.
  • Note that if same type of Device is discovered in network then UCH does not create new instance of TA. Instead UCH just invokes registerTarget() of already instantiated TA. So TA must have capability to handle multiple Devices of the same type.
• void targetContextsAdded(string targetId, Map[] Contexts) throws TAFatalException
  • It is called when new contexts are added for specified target.
  • TA should add these contexts to the stored context's.
  • If TA doesn't want to restrict session based on userProfile and controllerProfile then no need to implement this method.
• void targetContextsRemoved(string targetId, Map[] Contexts) throws TAFatalException
  • It is called when new contexts are removed for specified target.
  • TA should remove thease contexts from stored context's.
  • If TA doesn't want to restrict session based on userProfile and controllerProfile then no need to implement this method.
• Map openSessionRequest(string targetId, string socketName, Map sessionProps, Map context) throws TAFatalException
  • The UCH asks for permission to open a session with a specified client on a specified socket. Note that this function asks for permission only, and is not supposed to actually open a session.
  • TA should check targetId, socketName and clientProps whether they are appropriate and valid to open a session with this target.
  • TA can also check userProfile and controllerProfile got from context. If TA don't want to restrict session based on userProfile and controllerProfile then don't need to do any implementation regarding to contexts.
  • If requirements are fulfilled then TA should return below mentioned key/value pair in return Map.
    • "result", "A".
  • If requirements are not fulfilled, but TA knows of any other TA that can open session with this client then TA should return below mentioned key/value pair in return Map.
    • "result", "F".
    • "targetName", "[Name of Target]".
    • "socketName", "[Name of Socket]".
    • "authorizationCode", "[AuthorizationCode]".
  • Otherwise TA should reject the request and return below mentioned key/value pair in return Map.
    • "result", "R".
• void sessionOpened(string targetId, string sessionId, string socketName, Map sessionProps, Map context) throws TAFatalException
  • If the TA had accepted an open session request (see above), and if the UCH succeeded in the necessary steps to open a session with the client, the UCH will call sessionOpened and provide the sessionId pertaining to the new session.
  • Now TA should open a new session for the client and possibly maintain a new copy of the elements of that socket for this new session. If TA programmer wants, he/she can avoid maintaining a copy of elements and instead always go to actual Device for latest values/updates.
  • TA should save the value of context locally for further usage. If TA doesn't want to make further decisions based on userProfile and controllerProfile then no need to do any implementation regarding contexts.
  • In future, when any request comes to TA for this session then it will process the request with the locally stored elements of this new session or directly go to the actual Device for latest updated values.
• Map<String, String> getValues(String sessionId, List<String> paths, List<String> includeSets)
  • TA decides whether it gets the values from Device or return the value stored within the element of that session.
  • includeSets is used to decide whether values of the elements of the Set should be returned when the path points to a Set.
  • TA should return Map of elemetPath v/s value.
• Map<String, List<String>>setValuesRequest(String sessionId, boolean isValidated, List<String> paths, List<String> operations, List<String> reqValues)
  • TA should change the value/state of Device as per the new value requested for the given 'path'. If caching is done locally then cache should be updated accordingly.
  • If caching is done then TA is responsible to make changes to all sessions of this target.
  • If device sends updates of its value/state change then TA should send updates to the UCH and if caching then update the values of all sessions.
  • SetValue, InvokeCommand, AddDimension, RemoveDimension and Notify Acknowledgement all are handled within this method.
• void sessionClosed(String sessionId)
  • TA should clean up all the information regarding to the session specified by 'sessionId', and update the actual Device if necessary.
  • Note that if all sessions are closed with one particular target and if TA had subscribed to any of the services of the actual Device then it should unsubscribe to all the services.
• unregisterTarget(String targetId)
  • When any target is discarded/removed from the network then UCH invokes this method.
  • TA should clean up all the information regarding to the target specified by 'targetId'.
  • It should close all the sessions with this target as well as invoke abortSession() of ITAListener.
  • Note that if TA has subscribed for any services of the actual Device then it should unsubscribe to all the services at this point.
• NOTE: If TA has subscribed for any services of the actual Device then it has to handle all updates from the Device, as well as it has to make sure that all session's elements are up to date and also invoke the ITAListener's method updateValues()

Configure UCHj to use your TA

Please refer to How to Add Local Resource.

---

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