/*

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;

/**
 * ITAListener receives calls from TA. UCH implements this interface.
 * The Listener receives calls from TA and forwards them to the UIPM and thereby to the client.
 * 
 * @author Parikshit Thakur & Team, Trace R&D Center
 * @version $Revision: 1.1 $
 */
public interface ITAListener {
	
	/**
	 * The TA requests the client to open a session with different socket.
	 * 
	 * @param sessionId a String value of sessionId
	 * @param forwardInfo Map<String, String>
	 */
	public void sessionForwardRequest(String sessionId, Map<String, String> forwardInfo);
	
	/**
	 * The TA has terminated a session, when the TA will have no knowledge about that session.
	 * 
	 * @param sessionId a String value of sessionId
	 */
	public void abortSession(String sessionId);
	
	
	/** 
	 * The TA signals a change in the target’s status, affecting one or more sessions.  
	 * 
	 * @param sessionIds a List&lt;String&gt; of sessionIds
	 * @param paths a List&lt;String&gt; of paths
	 * @param operations a List&lt;String&gt; of operations
	 * @param values a List&lt;String&gt; of values
	 * @param hasDynRes a List&lt;Boolean&gt; of hasDynRes
	 */
	
	public void updateValues(List<String> sessionIds, List<String> paths, List<String> operations, List<String> values, List<Boolean> hasDynRes);

	/**
	 * Signals that the set of resources pertaining to a specific socket element has been changed.
	 * 
	 * @param sessionIds a List&lt;String&gt; of sessionIds
	 * @param eltIds a List&lt;String&gt; of elementIds
	 */
	public void updateDynRes(List<String> sessionIds, List<String> eltIds);
	
	
	/**
	 * Check whether to do validation for the TA or not.
	 * 
	 * @param ta an Object of ITA
	 * @param activate a boolean value of activate
	 * @return boolean whether to do validation for the TA or not
	 */
	public boolean setValidation(ITA ta, boolean activate);
	 
	/**
	 * Gets an Object of LocalUCHStore.
	 * 
	 * @return an Object of IUCHStore
	 */
	public IUCHStore getLocalUCHStore();
	
	/**
	 * The ITA 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 ta an ITA 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(ITA ta, String scheme, int port, boolean portIsFlexible, String basePath, boolean basePathIsFlexible) throws UCHException;
	
	/**
	 * The ITA 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 the IP address of the UCH. 
	 * 
	 * @return return a string value
	 */
	public String getIpAddress();
	
	/**
	 * Get resource from the UCH specified by Resource Properties.
	 * 
	 * @param sessionId a String value of sessionId
	 * @param resProps a List&lt;Map&lt;String, String&gt;&gt; of Resource Properties
	 * @return a List&lt;Map&lt;String, Object&gt;&gt; value
	 */
	public List<Map<String, Object>> getResources(String sessionId, List<Map<String, String>> resProps);
	
	/**
	 * 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;
	
	/**
	 * Get a Map of UCH Properties.
	 * 
	 * @return an object of Map&lt;String, String&gt; or UCH Properties
	 */
    public Map<String, String> getUCHProps();
    
    /**
     * Returns 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);
	
}