/* Copyright (C) 2006-2008 Board of Regents of the University of Wisconsin System (Univ. of Wisconsin-Madison, Trace R&D Center). This piece of the software package, developed by the Trace Center - University of Wisconsin is released to the public domain with only the following restrictions: 1) That the following acknowledgement be included in the source code and documentation for the program or package that use this code: "Parts of this program were based on software developed by the Trace Center, University of Wisconsin-Madison under funding from NIDRR / US Dept of Education.” 2) That this program not be modified unless it is plainly marked as modified from the original distributed by Trace. NOTE: This license agreement does not cover third-party components bundled with this software, which have their own license agreement with them. A list of included third-party components with references to their license files is provided with this distribution. This software was developed under funding from NIDRR / US Dept of Education under grant # H133E030012. THIS SOFTWARE IS EXPERIMENTAL/DEMONSTRATION IN NATURE. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. Note: This file is based on the UCH 1.0 specification of the URC Consortium, http://myurc.org/TR/uch1.0/. */ package org.myurc.uch; import java.util.List; import java.util.Map; import java.util.Set; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; /** * TA (Target Adapter) is the link inbetween 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. * * @author Parikshit Thakur & Team, Trace R&D Center * @version $Revision: 1.1 $ */ public interface ITA { /** * 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. * * @param taListener an Object of ITAListener * @param taProps a Map<String, String> of ITA Properties * @param uchProps a Map<String, String> of UCH Properties * @throws TAFatalException */ public void init(ITAListener taListener, Map taProps, Map uchProps) throws TAFatalException; /** * This method is called by UCH before Un-installing or Unloading the TA. * */ public void finalize(); /** * Get Target Adapter Properties Map. * * @return an object of Map<String, String> of Target Adapter Properties */ public Map getTAProps(); /** * Register Target Adapter with specified targetId. * * @param targetId a String value of targetId * @param targetProps Map<String, Object> * @throws TAException * @throws TAFatalException */ public void registerTarget(String targetId, Map targetProps) throws TAException, TAFatalException; /** * Called when target has been disappeared from the network. * * @param targetId a String value of targetId * @throws TAFatalException */ public void unregisterTarget(String targetId)throws TAFatalException; /** * Get the target identifiers that the TA is currently representing. * * @return List<String> * @throws TAFatalException */ public List getRegisteredTargetIds()throws TAFatalException; /** * Get the TargetName specified by targetId. * * @param targetId a String value of targetId * @return a String value of targetName * @throws TAFatalException */ public String getTargetName(String targetId)throws TAFatalException; /** * Get the URI for retrieving the Target Description. * * @param targetName a String value of targetName * @return a String value of Target Description URI * @throws TAFatalException */ public String getTargetDescriptionUri(String targetName)throws TAFatalException; /** * Get the Target's Properties for specified targetId. * * @param targetId a String value of targetId * @return a Map<String, Object> value of Target Properties * @throws TAFatalException */ public Map getTargetProps(String targetId)throws TAFatalException; /** * Get the List of SocketName for specified targetName. * * @param targetName a String value of targetName * @return List<String> of SocketName * @throws TAFatalException */ public List getSocketNames(String targetName)throws TAFatalException; /** * Get the SocketName for the specified sessionId. * * @param sessionId a String value of sessionId * @return a String of SocketName * @throws TAFatalException */ public String getSocketName(String sessionId)throws TAFatalException; /** * Get the Socket Friendly Name for the specified socketName and targetId. * * @param targetId a String value of targetId * @param socketName a String value of socketName * @return a String value of Socket Friendly Name */ public String getSocketFriendlyName(String targetId, String socketName); /** * Get the Session Identifiers for specified targetId and socketName. * * @param targetId a String value of targetId * @param socketName a String value of socketName * @return List<String> of sessionId * @throws TAFatalException */ public List getSessionIds(String targetId, String socketName)throws TAFatalException; /** * * Get the URI for retrieving the Socket Description for specified targetName and socketName. * * @param targetName a String value of targetName * @param socketName a String value of socketName * @return a String representing Socket Description URI * @throws TAFatalException */ public String getSocketDescriptionUri(String targetName, String socketName)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. * * @param targetId a String value of targetId * @param socketName a String value of socketName * @param clientProps Map<String, String> * @return Map<String, String> * @throws TAFatalException */ public Map openSessionRequest(String targetId, String socketName, Map 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. * * @param targetId a String value of targetId * @param sessionId a String value of sessionId * @param socketName a String value of socketName * @param clientProps Map<String, String> * @throws TAFatalException */ public void sessionOpened(String targetId, String sessionId, String socketName, Map clientProps)throws TAFatalException; /** * Closes the Session for specified sessionId and do the necessary clean-up for the target. * * @param sessionId a String value of sessionId * @throws TAFatalException */ public void sessionClosed(String sessionId)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. * * @param sessionId a String value of sessionId * @param paths List<String> a List of elementPaths * @param operations List<String> a List of operations (allowed operations are "S", "A", "R", "I" or "K" ) * @param reqValues List<String> a List of Requested Values * @return Map<String, List<String>> of set Values * @throws TAFatalException */ public Map> setValuesRequest(String sessionId, boolean isValidated, List paths, List operations, List reqValues)throws TAFatalException; /** * Get Indices available on specific level of dimension of dimensional Element. * * @param sessionId a String value of sessionId * @param eltIds a List<String> of elementIds * @param indexNos a List<Integer> of indexNo * @return a List<Set<Integer> of indices */ public List> getIndices(String sessionId, List eltIds, List indexNos); /** * Returns a value/state of the specified socket elements. * * @param sessionId a String value of sessionId * @param paths a List<String> of elementPath * @return a Map<String, String> of values * @throws TAFatalException */ public Map getValues(String sessionId, List paths)throws TAFatalException; /** * Get the Dynamic Resources from the TA. * The UCH shall specify the properties of the requested resource as many as possible. * * @param sessionId a String value of sessionId * @param resProps a List<Map<String, String>> value of Resource Properties * @return a List<Object> of resources * @throws TAFatalException */ public List> getDynRes( String sessionId, List> resProps )throws TAFatalException; /** * Checks whether a given socketElement is available in specified Socket of specified Target or not. * * @param targetId a String value of targetId * @param socketName a String value of socketName * @param eltId a String value of eltId * @return boolean whether specified socketElement is exists or not * @throws TAFatalException */ public boolean isElementAvailable(String targetId, String socketName, String eltId) throws TAFatalException; /** * Checks whether specified function is implemented by the TA or not. * * @param functionName a String value of functionName * @return boolean whether specified function is implemented by the TA or not. */ public boolean isImplemented(String functionName); /** * 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. * * @param request a HttpServletRequest Object * @param response a HttpServletResponse Object * @throws TAFatalException * @see HttpServletRequest * @see HttpServletResponse */ public void targetRequest( HttpServletRequest request, HttpServletResponse response )throws TAFatalException; /** * Invoke the specified locator function on a target. * This requires a prior call to registerTarget on this target. * * @param targetId a String value of targetId * @param locatorId a String value of locaterId * @throws TAException * @throws TAFatalException */ public void invokeLocator(String targetId, String locatorId) throws TAException, TAFatalException; /** * Get a map of locators containing locatorId and locatorType for a specific target. * * @param targetName a String value of targetName * @return a Map<string, String> of LocatorID V/S Locator Type */ public Map getLocators(String targetName); //------------------------------Optional Methods------------------------------- /** * The UCH asks for permission to suspend a session. If TA does not support this function then throw TANotImplementedException. * * @param sessionId a String value of sessionId * @return whether permission for session suspend is granted or not * @throws TAFatalException * @throws TANotImplementedException */ public boolean suspendSessionRequest(String sessionId) throws 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(). * * @param sessionId a String value of sessionId * @param suggestedTimeout a long value of suggestedTimeout * @return whether permission is granted or not * @throws TAException * @throws TAFatalException * @throws TANotImplementedException */ public long sessionSuspended(String sessionId, long suggestedTimeout) throws TAException, TAFatalException, TANotImplementedException; /** * The UCH asks for permission to resume a session. * If TA does not support this function then throw TANotImplementedException. * * @param sessionId a String value of sessionId * @return a a Long value of timeOut * @throws TAFatalException * @throws TANotImplementedException */ public boolean resumeSessionRequest(String sessionId) throws 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. * * @param sessionId a string value of sessionId * @throws TAException * @throws TAFatalException * @throws TANotImplementedException */ public void sessionResumed(String sessionId) throws TAException, TAFatalException, TANotImplementedException; }