/*
 * Copyright (c)  2017, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */
package jdk.incubator.sql2;

import java.util.concurrent.CompletionStage;

/**
 * The result of submitting an {@link Operation}. The {@link cancel} method of a
 * {@link CompletionStage} does not cancel the {@link Operation}. This is part
 * of the contract of {@link CompletionStage}. This type provides a method to
 * cancel the {@link Operation}. Canceling an {@link Operation} only makes sense
 * after the {@link Operation} is submitted so this type is the result of
 * submitting an {@link Operation}.
 * 
 * ISSUE: Should Operation.submit return a CompletionStage with the requirement
 * that cancel attempts to cancel the database action? Conceptually this is fine.
 * The concern is that it requires the implementor to implement their own
 * CompletionStage or at the least subclass CompletableFuture to override
 * cancel. Neither of these is trivial.
 *
 * @param <T> The type of the result of the {@link Operation} that created this
 * {@link Submission}
 */
public interface Submission<T> {

  /**
   * Request that the {@link Operation} not be executed or that its execution be
   * aborted if already begun. This is a best effort action and may not succeed
   * in preventing or aborting the execution. This method does not block.
   * 
   * If execution is prevented the Operation is completed exceptionally with
   * SkippedSqlException. If the Operation is aborted it is completed
   * exceptionally with SqlException.
   *
   * @return a {@link java.util.concurrent.CompletionStage} that has the value
   * true if the {@link Operation} is canceled.
   */
  public CompletionStage<Boolean> cancel();

  /**
   * Returns a {@link CompletionStage} which value is the result of the
   * {@link Operation}. Any actions on the returned {@link CompletionStage},
   * eg {@code completeExceptionally} or {@code cancel}, have no impact on this
   * {@link Operation}. If this {@link Operation} is already completed the
   * returned {@link CompletionStage} will be completed. 
   * 
   * The returned {@link CompletionStage} is completed after the Operation
   * is completed. It may be completed by the same thread that completed the
   * Operation or a different one. The Operation following the one that created
   * this Submission begins execution when the Operation that created this 
   * Submission is completed. It is not required to wait for the returned
   * CompletionStage to complete. [Note: this is necessary because the app can
   * call this method after the Operation completes.]
   *
   * Each call of this method for a given {@link Operation} returns the same
   * {@link CompletionStage}.
   *
   * @return the {@link java.util.concurrent.CompletionStage} for the result of this
   * {@link Operation}. Retained.
   */
  public CompletionStage<T> getCompletionStage();

}