/*******************************************************************************
 * Copyright 2017 Graz University of Technology
 * EAAF-Core Components has been developed in a cooperation between EGIZ,  
 * A-SIT+, A-SIT, and Graz University of Technology.
 *
 * Licensed under the EUPL, Version 1.2 or - as soon they will be approved by
 * the European Commission - subsequent versions of the EUPL (the "Licence");
 * You may not use this work except in compliance with the Licence.
 * You may obtain a copy of the Licence at:
 * https://joinup.ec.europa.eu/news/understanding-eupl-v12
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the Licence is distributed on an "AS IS" basis,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the Licence for the specific language governing permissions and
 * limitations under the Licence.
 *
 * This product combines work with different licenses. See the "NOTICE" text
 * file for details on the various modules and licenses.
 * The "NOTICE" text file is part of the distribution. Any derivative works
 * that you distribute must include a readable copy of the "NOTICE" text file.
 *******************************************************************************/
/*******************************************************************************
 *******************************************************************************/
/*******************************************************************************
 *******************************************************************************/
/*******************************************************************************
*
 * Licensed under the EUPL, Version 1.1 or - as soon they will be approved by
 * the European Commission - subsequent versions of the EUPL (the "Licence");
 * You may not use this work except in compliance with the Licence.
 * You may obtain a copy of the Licence at:
 * http://www.osor.eu/eupl/
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the Licence is distributed on an "AS IS" basis,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the Licence for the specific language governing permissions and
 * limitations under the Licence.
 *
 * This product combines work with different licenses. See the "NOTICE" text
 * file for details on the various modules and licenses.
 * The "NOTICE" text file is part of the distribution. Any derivative works
 * that you distribute must include a readable copy of the "NOTICE" text file.
 *******************************************************************************/
package at.gv.egiz.eaaf.core.api;

import java.util.Map;

import at.gv.egiz.eaaf.core.api.idp.ISPConfiguration;
import at.gv.egiz.eaaf.core.exceptions.EAAFStorageException;

public interface IRequest {
		
	/**
	 * Indicates the module, which implements this authentication protocol.
	 * The class, which is referenced, had to implement the 'IModulInfo' interface.
	 * 
	 * @return Full-qualified name of the class which implements this protocol
	 */
	public String requestedModule();
	
	/**
	 * Indicates the protocol specific action, which should executed if the request is processed. 
	 * The class, which is referenced, had to implement the 'IAction' interface.
	 * 
	 * @return Full-qualified name of the class which implements the action  
	 */
	public String requestedAction();
	
	/**
	 * Unique identifier, which indicates the service provider. 
	 * 
	 * @return Unique identifier for the service provider
	 */
	public String getSPEntityId();
	
	/**
	 * Indicates the passive flag in authentication requests.
	 * If the passive flag is set, the identification and authentication process 
	 * failed if no active SSO session is found. 
	 * 
	 * @return true, if the is passive flag is set in authentication request, otherwise false
	 */
	public boolean isPassiv();
	
	/**
	 * Indicates the force authentication flag in authentication request
	 * If this flag is set, a new identification and authentication process
	 * is carried out in any case.
	 * 
	 * @return true, if the force authentication flag is set, otherwise false
	 */
	public boolean forceAuth();
	
	
	/**
	 * Returns a generic request-data object with is stored with a specific identifier 
	 * 
	 * @param key The specific identifier of the request-data object
	 * @return The request-data object or null if no data is found with this key
	 */
	public Object getGenericData(String key);
	
	/**
	 * Returns a generic request-data object with is stored with a specific identifier 
	 * 
	 * @param key The specific identifier of the request-data object
	 * @param clazz The class type which is stored with this key
	 * @return The request-data object or null if no data is found with this key
	 */
	public <T> T getGenericData(String key, final Class<T> clazz);
	
	/** 
	 * Store a generic data-object into pending request with a specific identifier
	 * 
	 * @param key Identifier for this data-object
	 * @param object Generic data-object which should be stored. This data-object had to be implement the 'java.io.Serializable' interface
	 * @throws SessionDataStorageException Error message if the data-object can not stored to generic request-data storage
	 */
	public void setGenericDataToSession(String key, Object object) throws EAAFStorageException;

	/** 
	 * Store generic data-objects into pending request with specific identifiers
	 * 
	 * @param map Map with Identifiers and values
	 * @throws SessionDataStorageException Error message if the data-object can not stored to generic request-data storage
	 */
	public void setGenericDataToSession(Map<String, Object> map) throws EAAFStorageException;
	
	
	
	/**
	 * Get the internal dataStorage map
	 * 
	 * @return read-only map of data stored to this pending request
	 */
	public Map<String, Object> genericFullDataStorage();
	
	/**
	 * Hold the identifier of this request object. 
	 * This identifier can be used to load the request from request storage 
	 * 
	 * @return Request identifier
	 */
	public String getPendingRequestId();
	

	/**
	 * Hold the identifier of the SSO-Session which is associated with this request
	 * 
	 * @return SSO session-identifier if a associated session exists, otherwise null
	 */
	public String getInternalSSOSessionIdentifier();

	/**
	 * Set the in SSO session identifier, if an active SSO session exists
	 * 
	 * @param internalSSOSessionId
	 */
	public void setInternalSSOSessionIdentifier(String internalSSOSessionId);
	
	/**
	 * Holds a unique transaction identifier, which could be used for looging
	 * This transaction identifier is unique for a single identification and authentication process
	 * 
	 * @return Unique transaction identifier. 
	 */
	public String getUniqueTransactionIdentifier();
	
	/**
	 * Holds a unique session identifier, which could be used for logging 
	 * This session identifier is unique for the full Single Sign-On session time
	 * 
	 * @return Unique session identifier
	 */
	public String getUniqueSessionIdentifier();
	
	
	/**
	 * Hold the identifier if the process instance, which is associated with this request 
	 * 
	 * @return ProcessInstanceID if this request is associated with a authentication process, otherwise null
	 */
	public String getProcessInstanceId();
	
	
	/**
	 * get the IDP URL PreFix, which was used for authentication request
	 * 
	 * @return IDP URL PreFix <String>. The URL prefix always ends without /
	 */
	public String getAuthURL();
	public String getAuthURLWithOutSlash();
	
	/**
	 * Indicates if this pending request needs authentication
	 * 
	 * @return true if this request needs authentication, otherwise false
	 */
	public boolean isNeedAuthentication();
	
	/**
	 * Indicates, if this pending request needs Single Sign-On (SSO) functionality 
	 * 
	 * @return true if this request needs SSO, otherwise false
	 */
	public boolean needSingleSignOnFunctionality();
	public void setNeedSingleSignOnFunctionality(boolean needSSO);
	
	
	/**
	 * Indicates, if this pending request needs an additional user consent 
	 * 
	 * @return true if this request needs additional user consent, otherwise false
	 */
	public boolean isNeedUserConsent();
	public void setNeedUserConsent(boolean needConsent);
	
	/**
	 * Indicates, if this pending request is already authenticated
	 * 
	 * @return true if this request is already authenticated, otherwise false
	 */
	public boolean isAuthenticated();
	public void setAuthenticated(boolean isAuthenticated);
	
	/**
	 * Get get Service-Provider configuration which is associated with this request.
	 * 
	 * @return Service-Provider configuration
	 */
	public ISPConfiguration getServiceProviderConfiguration();

	
	/**
	 * Get get Service-Provider configuration which is associated with this request.
	 * 
	 * @return Service-Provider configuration as object
	 */
	public <T> T getServiceProviderConfiguration(final Class<T> decorator);
	
		
	/**
	 * Indicates, if this pending-request is aborted by the user
	 * 
	 * @return true, if it is aborted, otherwise false
	 */
	public boolean isAbortedByUser();

	/**
	 * Set the 'isAboredByUser' flag of this pending-request
	 * 
	 * @param b true, if the user has abort the authentication process, otherwise false
	 */
	public void setAbortedByUser(boolean isAborted);
	
}