/*
 * Copyright © 2015 Cask Data, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */

package co.cask.cdap.api.data;

import co.cask.cdap.api.dataset.Dataset;

import java.util.Map;

/**
 * This interface provides methods to instantiate and dismiss instances of Datasets
 * during the runtime of a program.
 */
public interface DatasetProvider extends DatasetContext {

  /**
   * Calling this means that the dataset is not used by the caller any more,
   * and the DatasetProvider is free to dismiss or reuse it. The dataset must
   * have been acquired through this provider using {@link #getDataset(String)}
   * or {@link #getDataset(String, Map)}. It is up to the implementation of the
   * provider whether this dataset is discarded, or whether it is reused as the
   * result for subsequent {@link #getDataset} calls with the same arguments.
   *
   * @param dataset The dataset to be released.
   */
  void releaseDataset(Dataset dataset);

  /**
   * Calling this means that the dataset is not used by the caller any more,
   * and the DatasetProvider must close and discard it. The dataset must
   * have been acquired through this provider using {@link #getDataset(String)}
   * or {@link #getDataset(String, Map)}. It is guaranteed that no subsequent
   * invocation of {@link #getDataset} will return the same object.
   *
   * @param dataset The dataset to be dismissed.
   */
  void discardDataset(Dataset dataset);
}

@@ -1354,16 +1354,237 @@
 uments.%0A
+   * This may be influenced by resource constraints, expiration policy, or%0A   * advanced configuration.%0A   * %3Cp%3E%0A   * Note: In the current implementation, this is equivalent to %7B@link #discardDataset(Dataset)%7D.%0A   * %3C/p%3E%0A
    *%0A   
@@ -1812,17 +1812,42 @@
 scard it
-.
+ as soon as possible.%0A   *
  The dat
@@ -1847,37 +1847,32 @@
 The dataset must
-%0A   *
  have been acqui
@@ -1894,32 +1894,37 @@
 s provider using
+%0A   *
  %7B@link #getData
@@ -1927,37 +1927,32 @@
 Dataset(String)%7D
-%0A   *
  or %7B@link #getD
@@ -1968,24 +1968,38 @@
 ring, Map)%7D.
+%0A   * %3Cp%3E%0A   *
  It is guara
@@ -2090,16 +2090,530 @@
  object.
+ The only%0A   * exception is if getDataset() is called again before the dataset could be%0A   * effectively discarded. For example, if the dataset participates in a%0A   * transaction, then the system can only discard it after that transaction%0A   * has completed. If getDataset() is called again during the same transaction,%0A   * then the DatasetProvider will return the same object, and this effectively%0A   * cancels the discardDataset(), because the dataset was reacquired before it%0A   * could be discarded.%0A   * %3C/p%3E
 %0A   *%0A  

clarify difference between discard and release