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)
  • 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 the file uch.config for searching the proper TA class, using the Target properties provided the TDM. For this work properly, a TA implementor needs to modify the uch.config file.
  • 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/. In UCH offline mode, please put the TD, UIS and RSHEET's for this TA in the docRoot. You can also create sub-folders in the docRoot for convenience. The reason to keep them in the 'docRoot' path, is because the TD and UIS are also served to clients from that path like: http://192.168.0.1/UCH/.../xxx.td and http://192.168.0.1/UCH/.../xxx.uis
• void registerTarget(String targetId, Map<String, Object> targetProps)
  • 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.
  • Note that if same type of Device is discovered in network then UCH does not cteate new instance of TA.Instead UCH just invokes registerTarget() of already intantiated TA. So TA must have capability to handle multiple Devices of the same type.
• Map<String, String> openSessionRequest(String targetId, String socketName, Map<String, String> clientProps)
  • 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.
  • 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<String, String> clientProps)
  • 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, they can escape maintaining a copy of elements and instead always go to actual Device for latest values/updates.
  • 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)
  • TA decides whether it get the values from Device or return the value stored with the element of that session.
  • 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 send updates if any of its value/state is changed 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 with 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 all session's element up to date and also invoke the ITAListener's method updateValues()

Configure the UCHj to Use Your TA

Please refer to How to Modify the UCHj Configuration File.

---

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