/*
 * 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.
 *
 * 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.
*/

package at.gv.egiz.eaaf.core.api.idp.process;

import java.io.Serializable;
import java.util.Set;

/**
 * Encapsulates data needed for or provided by task execution.
 *
 * @author tknall
 *
 */
public interface ExecutionContext extends Serializable {

  /**
   * Flag that indicates that a Task canceled the current
   * {@link ExecutionContext}.
   *
   * @return true if the process-flow was marked as canceled, otherwise false
   */
  boolean isProcessCancelled();

  /**
   * Mark this {@link ExecutionContext} as cancelled.
   *
   * <p>
   * The process-flow engine will stop execution when the task that sets this flag
   * is finished
   * </p>
   */
  void setCanceleProcessFlag();

  /**
   * Returns the identifier of underlying process instance.
   *
   * @return The identifier of the process instance.
   */
  String getProcessInstanceId();

  /**
   * Sets the identifier of underlying process instance.
   *
   * @param processInstanceId The identifier of the process instance.
   */
  void setProcessInstanceId(String processInstanceId);

  /**
   * Stores a serializable object using {@code key}.
   *
   * @param key    The key under that the {@code object} should be stored.
   * @param object The object to be stored.
   */
  void put(String key, Serializable object);

  /**
   * Returns an serializable object stored within this process context using
   * {@code key}.
   *
   * @param key The key that has been used to store the serializable object (may
   *            be {@code null}).
   * @return The object or {@code null} in case the key does not relate to a
   *         stored object or the stored object itself was {@code null}.
   */
  Serializable get(String key);

  /**
   * Removes the object stored using {@code key}.
   *
   * @param key The key that has been used to store the serializable object (may
   *            be {@code null}).
   * @return The object that has been removed or {@code null} there was no object
   *         stored using {@code key}.
   */
  Serializable remove(String key);

  /**
   * Returns an unmodifiable set containing the stored keys.
   *
   * @return The keyset (never {@code null}).
   */
  Set<String> keySet();

}