org.myurc.uch
Interface ITA

All Known Implementing Classes:

GenericTAFacade, UpnpAvTAFacade, UpnpSatelliteBoxTAFacade

public interface ITA

TA (Target Adapter) is the link in between UCH and final proprietory Target. It converts URC protocol to Target proprietory protocol and vice-versa. A Target Adapter (TA) represents one or multiple targets to the UCH. It is installed and loaded upon the discovery of a first target that it can represent. The UCH will register new targets with the TA as they are discovered by the TDM; and unregister after they have disappeared from the network. After having opened a session on a target’s socket, the TA is responsible for managing the values of the pertaining socket instance.

Version:

$Revision: 1.4 $

Author:

Parikshit Thakur & Team, Trace R&D Center

Method Summary

void	finalize() This method is called by UCH before Un-installing or Unloading the TA.
List<Map<String,Object>>	getDynRes(String sessionId, List<Map<String,String>> resProps) Get the Dynamic Resources from the TA.
List<Set<String>>	getIndices(String sessionId, List<String> eltIds, List<Integer> indexNos) Get Indices available on specific level of dimension of dimensional Element.
Map<String,String>	getLocators(String targetName) Get a map of locators containing locatorId and locatorType for a specific target.
List<String>	getRegisteredTargetIds() Get the target identifiers that the TA is currently representing.
List<String>	getSessionIds(String targetId, String socketName) Get the Session Identifiers for specified targetId and socketName.
String	getSocketDescriptionUri(String targetName, String socketName) Get the URI for retrieving the Socket Description for specified targetName and socketName.
String	getSocketFriendlyName(String targetId, String socketName) Get the Socket Friendly Name for the specified socketName and targetId.
String	getSocketName(String sessionId) Get the SocketName for the specified sessionId.
List<String>	getSocketNames(String targetName) Get the List of SocketName for specified targetName.
Map<String,String>	getTAProps() Get Target Adapter Properties Map.
String	getTargetDescriptionUri(String targetName) Get the URI for retrieving the Target Description.
String	getTargetName(String targetId) Get the targetName for specified targetId.
Map<String,Object>	getTargetProps(String targetId) Get the Target's Properties for specified targetId.
Map<String,String>	getValues(String sessionId, List<String> paths, List<Boolean> includeSets) Returns a value/state of the specified socket elements.
void	init(ITAListener taListener, Map<String,String> taProps, Map<String,String> uchProps) When the TA is installed and loaded, this method is called by UCH prior to any other TA function.
void	invokeLocator(String targetId, String locatorId) Invoke the specified locator function on a target.
boolean	isElementAvailable(String targetId, String socketName, String eltId) Checks whether a given socketElement is available in specified Socket of specified Target or not.
boolean	isImplemented(String functionName) Checks whether specified function is implemented by the TA or not.
Map<String,String>	openSessionRequest(String targetId, String socketName, Map<String,String> clientProps, Map<String,IProfile> context) The UCH asks for permission to open a session with a specified client on a specified socket.
void	registerTarget(String targetId, Map<String,Object> targetProps, List<Map<String,IProfile>> contexts) Register Target Adapter with specified targetId.
boolean	resumeSessionRequest(String sessionId) The UCH asks for permission to resume a session.
void	sessionClosed(String sessionId) Closes the Session for specified sessionId and do the necessary clean-up for the target.
void	sessionOpened(String targetId, String sessionId, String socketName, Map<String,String> clientProps, Map<String,IProfile> context) If the TA has accepted an open session request, 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.
void	sessionResumed(String sessionId) The UCH signals the TA that the session has resumed.
long	sessionSuspended(String sessionId, long suggestedTimeout) The UCH signals the TA that the client has suspended a session with one of the TA’s targets.
Map<String,List<String>>	setValuesRequest(String sessionId, boolean isValidated, List<String> paths, List<String> operations, List<String> reqValues) The client requests to change the target state in one or more operations on specified socket elements.
boolean	suspendSessionRequest(String sessionId) The UCH asks for permission to suspend a session.
void	targetContextsAdded(String targetId, List<Map<String,IProfile>> contexts) Called when one or more contexts got added to an existing target.
void	targetContextsRemoved(String targetId, List<Map<String,IProfile>> contexts) Called when one or more contexts got removed to an existing target.
void	targetRequest(HttpServletRequest request, HttpServletResponse response, Map<String,IProfile> context) The UCH calls this function if it has received a request from a target to a URI that the TA has claimed for itself by a previous call to startUriService().It modify the response object according to request object.
void	unregisterTarget(String targetId) Called when target has been disappeared from the network.

Method Detail

init

void init(ITAListener taListener,
          Map<String,String> taProps,
          Map<String,String> uchProps)
          throws TAFatalException

When the TA is installed and loaded, this method is called by UCH prior to any other TA function. Within this method the TA initializes itself.

Parameters:

taListener - an Object of ITAListener

taProps - a Map<String, String> of ITA Properties

uchProps - a Map<String, String> of UCH Properties

Throws:

TAFatalException - an Object of TAFatalException

finalize

void finalize()

This method is called by UCH before Un-installing or Unloading the TA.

getTAProps

Map<String,String> getTAProps()

Get Target Adapter Properties Map.

Returns:

an object of Map<String, String> of Target Adapter Properties

registerTarget

void registerTarget(String targetId,
                    Map<String,Object> targetProps,
                    List<Map<String,IProfile>> contexts)
                    throws TAException,
                           TAFatalException

Register Target Adapter with specified targetId.

Parameters:

targetId - a String value of targetId

targetProps - Map<String, Object>

contexts - a List<Map<String, IProfile>> of user and controller profile map

Throws:

TAException - an Object of TAException

TAFatalException - an Object of TAFatalException

targetContextsAdded

void targetContextsAdded(String targetId,
                         List<Map<String,IProfile>> contexts)
                         throws TAFatalException

Called when one or more contexts got added to an existing target.

Parameters:

targetId - a String value of targetId

contexts - a List<Map<String, IProfile>> of user and controller profile map

Throws:

TAFatalException - an Object of TAFatalException

targetContextsRemoved

void targetContextsRemoved(String targetId,
                           List<Map<String,IProfile>> contexts)
                           throws TAFatalException

Called when one or more contexts got removed to an existing target.

Parameters:

targetId - a String value of targetId

contexts - a List<Map<String, IProfile>> of user and controller profile map

Throws:

TAFatalException - an Object of TAFatalException

unregisterTarget

void unregisterTarget(String targetId)
                      throws TAFatalException

Called when target has been disappeared from the network.

Parameters:

targetId - a String value of targetId

Throws:

TAFatalException - an Object of TAFatalException

getRegisteredTargetIds

List<String> getRegisteredTargetIds()
                                    throws TAFatalException

Get the target identifiers that the TA is currently representing.

Returns:

List<String>

Throws:

TAFatalException - an Object of TAFatalException

getLocators

Map<String,String> getLocators(String targetName)

Get a map of locators containing locatorId and locatorType for a specific target.

Parameters:

targetName - a String value of targetName

Returns:

a Map<string, String> of LocatorID V/S Locator Type

invokeLocator

void invokeLocator(String targetId,
                   String locatorId)
                   throws TAException,
                          TAFatalException

Invoke the specified locator function on a target. This requires a prior call to registerTarget on this target.

Parameters:

targetId - a String value of targetId

locatorId - a String value of locaterId

Throws:

TAException - an Object of TAException

TAFatalException - an Object of TAFatalException

getTargetName

String getTargetName(String targetId)
                     throws TAFatalException

Get the targetName for specified targetId.

Parameters:

targetId - a String value of targetId

Returns:

a String value of targetName

Throws:

TAFatalException - an Object of TAFatalException

getTargetDescriptionUri

String getTargetDescriptionUri(String targetName)
                               throws TAFatalException

Get the URI for retrieving the Target Description.

Parameters:

targetName - a String value of targetName

Returns:

a String value of Target Description URI

Throws:

TAFatalException - an Object of TAFatalException

getTargetProps

Map<String,Object> getTargetProps(String targetId)
                                  throws TAFatalException

Get the Target's Properties for specified targetId.

Parameters:

targetId - a String value of targetId

Returns:

a Map<String, Object> value of Target Properties

Throws:

TAFatalException - an Object of TAFatalException

getSocketNames

List<String> getSocketNames(String targetName)
                            throws TAFatalException

Get the List of SocketName for specified targetName.

Parameters:

targetName - a String value of targetName

Returns:

List<String> of SocketName

Throws:

TAFatalException - an Object of TAFatalException

getSocketName

String getSocketName(String sessionId)
                     throws TAFatalException

Get the SocketName for the specified sessionId.

Parameters:

sessionId - a String value of sessionId

Returns:

a String of SocketName

Throws:

TAFatalException - an Object of TAFatalException

getSocketFriendlyName

String getSocketFriendlyName(String targetId,
                             String socketName)

Get the Socket Friendly Name for the specified socketName and targetId.

Parameters:

targetId - a String value of targetId

socketName - a String value of socketName

Returns:

a String value of Socket Friendly Name

getSessionIds

List<String> getSessionIds(String targetId,
                           String socketName)
                           throws TAFatalException

Get the Session Identifiers for specified targetId and socketName.

Parameters:

targetId - a String value of targetId

socketName - a String value of socketName

Returns:

List<String> of sessionId

Throws:

TAFatalException - an Object of TAFatalException

getSocketDescriptionUri

String getSocketDescriptionUri(String targetName,
                               String socketName)
                               throws TAFatalException

Get the URI for retrieving the Socket Description for specified targetName and socketName.

Parameters:

targetName - a String value of targetName

socketName - a String value of socketName

Returns:

a String representing Socket Description URI

Throws:

TAFatalException - an Object of TAFatalException

openSessionRequest

Map<String,String> openSessionRequest(String targetId,
                                      String socketName,
                                      Map<String,String> clientProps,
                                      Map<String,IProfile> context)
                                      throws TAFatalException

The UCH asks for permission to open a session with a specified client on a specified socket. If it is permitted then a map returns a keyValue pair {"Result", "A"} i.e. Accept Else it returns a keyValue pair {"Result", "R"} i.e. rejection.

Parameters:

targetId - a String value of targetId

socketName - a String value of socketName

clientProps - Map<String, String>

context - a Map<String, IProfile> of user and controller profile

Returns:

Map<String, String>

Throws:

TAFatalException - an Object of TAFatalException

sessionOpened

void sessionOpened(String targetId,
                   String sessionId,
                   String socketName,
                   Map<String,String> clientProps,
                   Map<String,IProfile> context)
                   throws TAFatalException

If the TA has accepted an open session request, 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. It opens a new Session for specified socketName with the targetId mentioned.

Parameters:

targetId - a String value of targetId

sessionId - a String value of sessionId

socketName - a String value of socketName

clientProps - Map<String, String>

context - a Map<String, IProfile> of user and controller profile

Throws:

TAFatalException - an Object of TAFatalException

sessionClosed

void sessionClosed(String sessionId)
                   throws TAFatalException

Closes the Session for specified sessionId and do the necessary clean-up for the target.

Parameters:

sessionId - a String value of sessionId

Throws:

TAFatalException - an Object of TAFatalException

setValuesRequest

Map<String,List<String>> setValuesRequest(String sessionId,
                                          boolean isValidated,
                                          List<String> paths,
                                          List<String> operations,
                                          List<String> reqValues)
                                          throws TAFatalException

The client requests to change the target state in one or more operations on specified socket elements. The requested operations are coded as cross-indexed arrays of paths, operations, identifiers and requested new values.

Parameters:

sessionId - a String value of sessionId

paths - List<String> a List of elementPaths

operations - List<String> a List of operations (allowed operations are "S", "A", "R", "I" or "K" )

reqValues - List<String> a List of Requested Values

Returns:

Map<String, List<String>> of set Values

Throws:

TAFatalException - an Object of TAFatalException

getValues

Map<String,String> getValues(String sessionId,
                             List<String> paths,
                             List<Boolean> includeSets)
                             throws TAFatalException

Returns a value/state of the specified socket elements.

Parameters:

sessionId - a String value of sessionId

paths - a List<String> of elementPath

includeSets - a List<Boolean> of includeSets

Returns:

a Map<String, String> of values

Throws:

TAFatalException - an Object of TAFatalException

getIndices

List<Set<String>> getIndices(String sessionId,
                             List<String> eltIds,
                             List<Integer> indexNos)

Get Indices available on specific level of dimension of dimensional Element.

Parameters:

sessionId - a String value of sessionId

eltIds - a List<String> of elementIds

indexNos - a List<Integer> of indexNo

Returns:

a List<Set<Integer> of indices

getDynRes

List<Map<String,Object>> getDynRes(String sessionId,
                                   List<Map<String,String>> resProps)
                                   throws TAFatalException

Get the Dynamic Resources from the TA. The UCH shall specify the properties of the requested resource as many as possible.

Parameters:

sessionId - a String value of sessionId

resProps - a List<Map<String, String>> value of Resource Properties

Returns:

a List<Object> of resources

Throws:

TAFatalException - an Object of TAFatalException

isElementAvailable

boolean isElementAvailable(String targetId,
                           String socketName,
                           String eltId)
                           throws TAFatalException

Checks whether a given socketElement is available in specified Socket of specified Target or not.

Parameters:

targetId - a String value of targetId

socketName - a String value of socketName

eltId - a String value of eltId

Returns:

boolean whether specified socketElement is exists or not

Throws:

TAFatalException - an Object of TAFatalException

isImplemented

boolean isImplemented(String functionName)

Checks whether specified function is implemented by the TA or not.

Parameters:

functionName - a String value of functionName

Returns:

boolean whether specified function is implemented by the TA or not.

suspendSessionRequest

boolean suspendSessionRequest(String sessionId)
                              throws TAFatalException,
                                     TANotImplementedException

The UCH asks for permission to suspend a session. If TA does not support this function then throw TANotImplementedException.

Parameters:

sessionId - a String value of sessionId

Returns:

whether permission for session suspend is granted or not

Throws:

TAFatalException - an Object of TAFatalException

TANotImplementedException - an Object of TANotImplementedException

sessionSuspended

long sessionSuspended(String sessionId,
                      long suggestedTimeout)
                      throws TAException,
                             TAFatalException,
                             TANotImplementedException

The UCH signals the TA that the client has suspended a session with one of the TA’s targets. The TA do the necessary actions internally and with the target. The session is now suspended until a subsequent call to resumeSessionRequest(), or until the TA terminates the session for timing out or other reasons, in which case the TA shall call sessionAborted().

Parameters:

sessionId - a String value of sessionId

suggestedTimeout - a long value of suggestedTimeout

Returns:

whether permission is granted or not

Throws:

TAException - an Object of TAException

TAFatalException - an Object of TAFatalException

TANotImplementedException - an Object of TANotImplementedException

resumeSessionRequest

boolean resumeSessionRequest(String sessionId)
                             throws TAFatalException,
                                    TANotImplementedException

The UCH asks for permission to resume a session. If TA does not support this function then throw TANotImplementedException.

Parameters:

sessionId - a String value of sessionId

Returns:

a a Long value of timeOut

Throws:

TAFatalException - an Object of TAFatalException

TANotImplementedException - an Object of TANotImplementedException

sessionResumed

void sessionResumed(String sessionId)
                    throws TAException,
                           TAFatalException,
                           TANotImplementedException

The UCH signals the TA that the session has resumed. A call to this function shall only occur after a resume session request has been granted by the TA.

Parameters:

sessionId - a string value of sessionId

Throws:

TAException - an Object of TAException

TAFatalException - an Object of TAFatalException

TANotImplementedException - an Object of TANotImplementedException

targetRequest

void targetRequest(HttpServletRequest request,
                   HttpServletResponse response,
                   Map<String,IProfile> context)
                   throws TAFatalException

The UCH calls this function if it has received a request from a target to a URI that the TA has claimed for itself by a previous call to startUriService().It modify the response object according to request object.

Parameters:

request - a HttpServletRequest Object

response - a HttpServletResponse Object

context - a Map<String, IProfile> of user and controller profile

Throws:

TAFatalException - an Object of TAFatalException

See Also:

HttpServletRequest, HttpServletResponse