edu.wisc.trace.uch
Interface ITA

All Known Implementing Classes:

GenericTAFacade, UpnpAvTAFacade, UpnpSatelliteBoxTAFacade

public interface ITA

A Target Adapter (TA) represents one or multiple targets to the UCH. It is being 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. 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.11 $

Author:

Parikshit Thakur & Team, Trace R&D Center

Method Summary

void	finalize() The UCH should call finalize() before it Un-installs or Unloads the TA.
List<Map<String,Object>>	getDynRes(String sessionId, List<Map<String,String>> resProps) Get the Dynamic atomic Resources from the TA.
List<Set<String>>	getIndices(String sessionId, List<String> eltIds, List<Integer> indexNos) Get IndexNames available on specific level of dimension of dimensional Element.
Map<String,String>	getLocators(String targetName) Get a map with Locator Ids and locator types for a specific target type.
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 SocketName.
String	getSocketDescriptionUri(String targetName, String socketName) Get the URI for retrieving the Socket Description of specified targetName and socketName.
String	getSocketFriendlyName(String targetId, String socketName) Get Friendly Name for the Socket specified by the 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 specified by targetId.
Map<String,Object>	getTargetProps(String targetId) Get the Target's Properties for specified targetId.
Map<String,String>	getValues(String sessionId, List<String> paths) 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, the UCH calls this method 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) 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) 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 with specific sessionId and do the necessary clean-up for the target.
void	sessionOpened(String targetId, String sessionId, String socketName, Map<String,String> clientProps) 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	targetRequest(HttpServletRequest request, HttpServletResponse response) 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, the UCH calls this method prior to any other TA function. Within this method the TA should initialize 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

finalize

void finalize()

The UCH should call finalize() before it Un-installs or Unloads 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)
                    throws TAException,
                           TAFatalException

Register Target Adapter with specified targetId.

Parameters:

targetId - a String value of targetId

targetProps - Map<String, Object>

Throws:

TAException

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

getRegisteredTargetIds

List<String> getRegisteredTargetIds()
                                    throws TAFatalException

Get the target identifiers that the TA is currently representing.

Returns:

List<String>

Throws:

TAFatalException

getTargetName

String getTargetName(String targetId)
                     throws TAFatalException

Get the TargetName specified by targetId.

Parameters:

targetId - a String value of targetId

Returns:

a String value of targetName

Throws:

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

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

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

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

getSocketFriendlyName

String getSocketFriendlyName(String targetId,
                             String socketName)

Get Friendly Name for the Socket specified by the 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 SocketName.

Parameters:

targetId - a String value of targetId

socketName - a String value of socketName

Returns:

List<String> of sessionId

Throws:

TAFatalException

getSocketDescriptionUri

String getSocketDescriptionUri(String targetName,
                               String socketName)
                               throws TAFatalException

Get the URI for retrieving the Socket Description of 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

openSessionRequest

Map<String,String> openSessionRequest(String targetId,
                                      String socketName,
                                      Map<String,String> clientProps)
                                      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>

Returns:

Map<String, String>

Throws:

TAFatalException

sessionOpened

void sessionOpened(String targetId,
                   String sessionId,
                   String socketName,
                   Map<String,String> clientProps)
                   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>

Throws:

TAFatalException

sessionClosed

void sessionClosed(String sessionId)
                   throws TAFatalException

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

Parameters:

sessionId -

Throws:

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>> a Map of set Values

Throws:

TAFatalException

getIndices

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

Get IndexNames 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

getValues

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

Returns a value/state of the specified socket elements.

Parameters:

sessionId - a String value of sessionId

paths - a List<String> of elementPath

Returns:

a Map<String, String> of values

Throws:

TAFatalException

getDynRes

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

Get the Dynamic atomic 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:

List<Object>

Throws:

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

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.

targetRequest

void targetRequest(HttpServletRequest request,
                   HttpServletResponse response)
                   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

Throws:

TAFatalException

See Also:

HttpServletRequest, HttpServletResponse

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

TAFatalException

getLocators

Map<String,String> getLocators(String targetName)

Get a map with Locator Ids and locator types for a specific target type.

Parameters:

targetName - a String value of targetName

Returns:

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

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

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

TAFatalException

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

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

TAFatalException

TANotImplementedException