/* 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; /** * IUIPMListener receives calls from UIPM. UCH implements this interface. * * @author Parikshit Thakur & Team, Trace R&D Center * @version $Revision: 1.1 $ */ public interface IUIPMListener { /** * Get the identifiers of the available targets. * * @return List<String> */ public List getAvailableTargetIds(); /** * Get the name of a target for the specified targetId. * * @param targetId a String value of targetId * @return a String */ public String getTargetName(String targetId); /** * Get the target Properties for the specified targetId. * * @param targetId a String value of targetId * @return Map<String, Object> */ public Map getTargetProps(String targetId); /** * Get the URI for retrieving the Target Description for the specified targetName. * * @param targetName a String value of targetName * @return a Target Description URI String */ public String getTargetDescriptionUri(String targetName); /** * Get specified document through HTTP GET or POST. * * @param uri a String value of URI * @param postData a String value of postData * @return a String value of requested Document * @throws UCHException */ public String getDocument(String uri, String postData)throws UCHException; /** * Returns List of socket Names for the specified Target Name. * * @param targetName a String value of targetName * @return List<String> */ public List getSocketNames(String targetName); /** * Get the URI for retrieving the Socket Description of the 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); /** * 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); /** * Get Friendly Name of the Socket 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); /** * Checks whether a given socketElement is available in the 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); /** * Returns the matching Resource with the Resource Properties specified by 'resProps'. * * @param sessionId a String value of SessionId * @param resProps List<Map<String, String>> of Resource Properties * @return an List<Map<String,Object>> representing Resources */ public List> getResources(String sessionId, List> resProps); /** * Request for opening a session with the specified target and socket. * * @param targetId a String value of targetId * @param socketName a String value of socketName * @param clientProps Map<String,String> * @return Map<String,String> */ public Map openSessionRequest(IUIPM uipm, String targetId, String socketName, Map clientProps); /** * Closes a Session for the specified sessionId. * * @param sessionId a String value of sessionId */ public void closeSession(String sessionId); /** * 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); /** * The UIPM 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, operation 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>> a Map of set Values */ public Map> setValuesRequest(String sessionId, List paths, List operations, List reqValues); /** * Tell the UCH to add a user interface item (advertised by the UIPM) to its UIList which is exposed to controllers on request. * * @param targetId a String value of targetId * @param socketNames a List<String> value of socketNames * @param protocolShortName a String value of protocolShortName * @param uris a List<String> value of uris * @param protocolInfo a Map<String, String> of protocol Information * * @return whether CompatibleUI is added or not. * @throws UCHException */ public boolean addCompatibleUI(String targetId, List socketNames, String protocolShortName, List uris, Map protocolInfo) throws UCHException; /** * Tells the UCH to remove user interface URIs from the UIList that were previously added by addCompatibleUI(). * * @param uris a List<String> of URIs * @throws UCHException */ public void removeCompatibleUIs(List uris)throws UCHException; /** * Get the Local UCH Store. * * @return an Object of IUCHStore */ public IUCHStore getLocalUCHStore(); /** * Checks whether specified function is implemented or not. * * @param functionName a String value of function Name * @return whether the function is implemented or not */ public boolean isImplemented(String functionName); /** * Get the IP address of the UCH. * * @return return a string value */ public String getIpAddress(); /** * The UIPM requests the UCH to start servicing a URI which is made up of a given scheme, port, and base path. * If successful, the UCH will forward all messages that have this URI as its base, to controllerRequest(). * * @param uipm an IUIPM object * @param scheme a String value of schema * @param port a port no * @param portIsFlexible a boolean value * @param basePath a String value of basePath * @param basePathIsFlexible a boolean value * @return a String value of URI * @throws UCHException */ public String startUriService(IUIPM uipm, String scheme, int port, boolean portIsFlexible, String basePath, boolean basePathIsFlexible) throws UCHException; /** * The UIPM requests the UCH to stop servicing a URI that was requested to be serviced in a previous call to startUriService(). * * @param uri a String value of URI * @throws UCHException */ public void stopUriService(String uri) throws UCHException; /** * Get a map of locatores containing locatorId and locatorType for a specified target Name. * * @param targetName a String value of targetName * @return a Map<string, String> of LocatorID V/S Locator Type */ public Map getLocators(String targetName); /** * Invoke the specified locator function of the specified targetId. * * @param targetId a String value of TargetId * @param locatorId a String value of LocatorId */ public void invokeLocator(String targetId, String locatorId); /** * Get a Map of UCH Properties. * * @return an object of Map<String, String> or UCH Properties */ public Map getUCHProps(); //------------------------------Optional Methods---------------------------------------// /** * Checks whether value is valid or not. * If IUIPMListener does not support this functionality then UCHNotImplementedException is thrown by this function. * * @param sessionId a String value of sessionId * @param path a String value of path * @param value a String value * @return whether the value is valid or not. * @throws UCHNotImplementedException */ public boolean validateValue(String sessionId, String path, String value) throws UCHNotImplementedException; /** * Get the actual value of a dependency. * If IUIPMListener does not support this functionality then UCHNotImplementedException is thrown by this function. * * @param sessionId a String value of sessionId * @param path a String value of path * @param dependency a String value of dependency * @return whether the dependency is true or false. * @throws UCHNotImplementedException */ public boolean getDependencyValue(String sessionId, String path, String dependency) throws UCHNotImplementedException; /** * Get the elementRef URI that points to a particular socket element/set. * If IUIPMListener does not support this functionality then UCHNotImplementedException is thrown by this function. * * @param sessionId a String value of sessionId * @param path a String value of path * @return a String value of elementRef * @throws UCHNotImplementedException */ public String getElementRef(String sessionId, String path) throws UCHNotImplementedException; /** * Check whether the given session can be suspended. * If IUIPMListener does not support this functionality then UCHNotImplementedException is thrown by this function. * * @param sessionId a String value of sessionId * @return whether the given session can be suspended or not * @throws UCHNotImplementedException */ public boolean isSessionSuspendable(String sessionId) throws UCHNotImplementedException; /** * The target is requested to suspend the given session with a suggested timeout value. * If IUIPMListener does not support this functionality then UCHNotImplementedException is thrown by this function. * * @param sessionId a String value of sessionId * @param suggestedTimeout a long value * @return a long value of timeOut * @throws UCHNotImplementedException */ public long suspendSession(String sessionId, long suggestedTimeout) throws UCHNotImplementedException; /** * Checks whether the given session can be resumed. * If IUIPMListener does not support this functionality then UCHNotImplementedException is thrown by this function. * * @param sessionId a String value of sessionId * @return whether the given session can be resumed or not * @throws UCHNotImplementedException */ public boolean isSessionResumable(String sessionId) throws UCHNotImplementedException; /** * The target is requested to resume the given session. * If IUIPMListener does not support this functionality then UCHNotImplementedException is thrown by this function. * * @param sessionId a String value of sessionId * @return whether request for resume session is granted or not. * @throws UCHNotImplementedException */ public boolean resumeSession(String sessionId) throws UCHNotImplementedException; /** * Removes the specified uipm from the UCH. * * @param uipm an Object of IUIPM */ public void removeUIPM(IUIPM uipm); }