/*******************************************************************************
 * Copyright 2017 Graz University of Technology EAAF-Core Components has been developed in a
 * cooperation between EGIZ, A-SIT Plus, A-SIT, and Graz University of Technology.
 * <br>
 * 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
 * <br>
 * 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.
 * <br>
 * 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.io.Serializable;
import java.util.Map;

import javax.annotation.Nonnull;

import at.gv.egiz.eaaf.core.api.idp.ISpConfiguration;
import at.gv.egiz.eaaf.core.exceptions.EaafStorageException;

public interface IRequest extends Serializable {

  /**
   * 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
   */
  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
   */
  String requestedAction();

  /**
   * Unique identifier, which indicates the service provider.
   *
   * @return Unique identifier for the service provider
   */
  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
   */
  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
   */
  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
   */
  Object getRawData(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
   * @param <T> Response class type
   * @return The request-data object or null if no data is found with this key
   */
  <T> T getRawData(String key, 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
   */
  void setRawDataToTransaction(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
   */
  void setRawDataToTransaction(Map<String, Object> map) throws EaafStorageException;

  /**
   * Wrap the internal dataStorage map into a DAO.
   *
   * @param wrapper DOA to access SessionData
   * @param <T> Response class type
   * @return
   */
  @Nonnull
  <T> T getSessionData(@Nonnull Class<T> wrapper);

  /**
   * Hold the identifier of this request object. This identifier can be used to
   * load the request from request storage.
   *
   * @return Request identifier
   */
  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
   */
  String getInternalSsoSessionIdentifier();

  /**
   * Set the in SSO session identifier, if an active SSO session exists.
   *
   * @param internalSsoSessionId Internal SSO session id
   */
  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.
   */
  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
   */
  String getUniqueSessionIdentifier();


  /**
   * Holds a unique transaction identifier for PII related information,
   *     like DSGVO data.
   * <br>
   * <p><b>This transaction identifier SHALL NOT be used for technical log-correlation</b></p>
   * @return
   */
  String getUniquePiiTransactionIdentifier();

  /**
   * 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
   */
  String getProcessInstanceId();

  /**
   * get the IDP URL PreFix, which was used for authentication request.
   *
   * @return IDP URL PreFix. The URL prefix always ends without /
   */
  String getAuthUrl();

  /**
   * get the IDP URL PreFix, which was used for authentication request.
   *
   * @return IDP URL PreFix. The URL prefix always ends without /
   */
  String getAuthUrlWithOutSlash();

  /**
   * Indicates if this pending request needs authentication.
   *
   * @return true if this request needs authentication, otherwise false
   */
  boolean isNeedAuthentication();

  /**
   * Indicates, if this pending request needs Single Sign-On (SSO) functionality.
   *
   * @return true if this request needs SSO, otherwise false
   */
  boolean needSingleSignOnFunctionality();

  /**
   * Set flag that this requests needs SSO.
   *
   * @param needSso true if SSO is needed, otherwise false
   */
  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
   */
  boolean isNeedUserConsent();

  void setNeedUserConsent(boolean needConsent);

  /**
   * Indicates, if this pending request is already authenticated.
   *
   * @return true if this request is already authenticated, otherwise false
   */
  boolean isAuthenticated();

  void setAuthenticated(boolean isAuthenticated);

  /**
   * Get get Service-Provider configuration which is associated with this request.
   *
   * @return Service-Provider configuration
   */
  ISpConfiguration getServiceProviderConfiguration();

  /**
   * Get get Service-Provider configuration which is associated with this request.
   *
   * @param decorator Interface of the Service-Provider information DAO
   * @param <T> Response class type
   * @return Service-Provider configuration as object
   */
  <T> T getServiceProviderConfiguration(Class<T> decorator);

  /**
   * Indicates, if this pending-request is aborted by the user.
   *
   * @return true, if it is aborted, otherwise false
   */
  boolean isAbortedByUser();

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

}