WorkflowToken.java

/*
 * Copyright © 2015-2016 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.workflow;

import co.cask.cdap.api.annotation.Beta;

import java.util.List;
import java.util.Map;
import javax.annotation.Nullable;

/**
 * Interface to represent the data that is transferred from one node to the next nodes in the {@link Workflow}.
 */
@Beta
public interface WorkflowToken {

  /**
   * Keys in the {@link WorkflowToken} can be added by user, using the
   * {@link WorkflowToken#put} method. These keys are added under the {@link Scope#USER} scope.
   * CDAP also adds some keys to the {@link WorkflowToken}. for e.g. MapReduce counters.
   * The keys added by CDAP are added under the {@link Scope#SYSTEM} scope.
   */
  enum Scope {
    USER,
    SYSTEM
  }

  /**
   * Put the specified key and value into the {@link WorkflowToken}.
   * The token may store additional information about the context in which
   * this key is being set. For example, the context information stored by the
   * token may be the workflow node that is performing the operation, or the name
   * of the workflow if the operation is performed in {@link AbstractWorkflow#initialize}
   * or {@link AbstractWorkflow#destroy} method.
   * @param key the key representing the entry
   * @param value the value for the key
   * @throws UnsupportedOperationException if called in a context where the token may not be modified.
   */
  void put(String key, String value);

  /**
   * Put the specified key and {@link Value} into the {@link WorkflowToken}.
   * The token may store additional information about the context in which
   * this key is being set. For example, the context information stored by the
   * token may be the workflow node that is performing the operation, or the name
   * of the workflow if the operation is performed in {@link AbstractWorkflow#initialize}
   * or {@link AbstractWorkflow#destroy} method.
   * @param key the key representing entry
   * @param value the {@link Value} for the key
   * @throws UnsupportedOperationException if called in a context where the token may not be modified.
   */
  void put(String key, Value value);

  /**
   * Get the most recent value added for the specified key for a {@link Scope#USER} scope.
   * @param key the key to be searched
   * @return the {@link Value} for the key or <code>null</code> if the key does not
   * exist in the {@link Scope#USER} scope
   */
  @Nullable
  Value get(String key);

  /**
   * Get the most recent value for the specified key for a given scope.
   * @param key the key to be searched
   * @param scope the {@link WorkflowToken.Scope} for the key
   * @return the {@link Value} for the key from the specified scope or <code>null</code> if the key
   * does not exist in the given scope
   */
  @Nullable
  Value get(String key, Scope scope);

  /**
   * Get the value set for the specified key by the specified node for a {@link Scope#USER} scope.
   * To get the token values set from {@link AbstractWorkflow#initialize} or
   * {@link AbstractWorkflow#destroy} methods, provide the name of the Workflow as nodeName.
   * @param key the key to be searched
   * @param nodeName the name of the node
   * @return the {@link Value} set for the key by nodeName or <code>null</code> if the key is not
   * added by the nodeName in the {@link Scope#USER} scope
   */
  @Nullable
  Value get(String key, String nodeName);

  /**
   * Get the value set for the specified key by the specified node for a given scope.
   * To get the token values set from {@link AbstractWorkflow#initialize} or
   * {@link AbstractWorkflow#destroy} methods, provide the name of the Workflow as nodeName.
   * @param key the key to be searched
   * @param nodeName the name of the node
   * @param scope the {@link WorkflowToken.Scope} for the key
   * @return the {@link Value} set for the key by nodeName for a given scope or <code>null</code>
   * if the key is not added by the nodeName in the given scope
   */
  @Nullable
  Value get(String key, String nodeName, Scope scope);

  /**
   * Same key can be added to the {@link WorkflowToken} by multiple nodes.
   * This method returns the {@link List} of {@link NodeValue}, where
   * each entry represents the unique node name and the {@link Value} that it set
   * for the specified key for a {@link Scope#USER} scope.
   * <p>
   * The list maintains the order in which the values were
   * inserted in the WorkflowToken for a specific key except in the case of fork
   * and join. In case of fork in the Workflow, copies of the WorkflowToken are made
   * and passed along each branch. At the join, all copies of the
   * WorkflowToken are merged together. While merging, the order in which the values were
   * inserted for a specific key is guaranteed within the same branch, but not across
   * different branches.
   * @param key the key to be searched
   * @return the list of {@link NodeValue} from node name to the value that node
   * added for the input key
   */
  List<NodeValue> getAll(String key);

  /**
   * Same key can be added to the WorkflowToken by multiple nodes.
   * This method returns the {@link List} of {@link NodeValue}, where
   * each entry represents the unique node name and the {@link Value} that it set
   * for the specified key for a given scope.
   * <p>
   * The list maintains the order in which the values were
   * inserted in the WorkflowToken for a specific key except in the case of fork
   * and join. In case of fork in the Workflow, copies of the WorkflowToken are made
   * and passed along each branch. At the join, all copies of the
   * WorkflowToken are merged together. While merging, the order in which the values were
   * inserted for a specific key is guaranteed within the same branch, but not across
   * different branches.
   * @param key the key to be searched
   * @param scope the {@link WorkflowToken.Scope} for the key
   * @return the list of {@link NodeValue} from node name to the value that node
   * added for the input key for a given scope
   */
  List<NodeValue> getAll(String key, Scope scope);

  /**
   * Get the {@link Map} of key to {@link Value}s that were added to the {@link WorkflowToken}
   * by specific node for a {@link Scope#USER} scope. To get the token values set from
   * {@link AbstractWorkflow#initialize} or {@link AbstractWorkflow#destroy} methods, provide
   * the name of the Workflow as nodeName.
   * @param nodeName the unique name of the node
   * @return the map of key to values that were added by the specified node
   */
  Map<String, Value> getAllFromNode(String nodeName);

  /**
   * Get the {@link Map} of key to {@link Value}s that were added to the {@link WorkflowToken}
   * by specific node for a given scope. To get the token values set from
   * {@link AbstractWorkflow#initialize} or {@link AbstractWorkflow#destroy} methods, provide
   * the name of the Workflow as nodeName.
   * @param nodeName the unique name of the node
   * @param scope the {@link WorkflowToken.Scope} for the key
   * @return the map of key to values that were added by the specified node for a given scope
   */
  Map<String, Value> getAllFromNode(String nodeName, Scope scope);

  /**
   * Same key can be added to the WorkflowToken by multiple nodes.
   * This method returns the key to {@link List} of {@link NodeValue}
   * added in the {@link Scope#USER} scope.
   * @return the {@link Map} of key to {@link List} of {@link NodeValue} added for
   * the given scope
   */
  Map<String, List<NodeValue>> getAll();

  /**
   * Same key can be added to the WorkflowToken by multiple nodes.
   * This method returns the key to {@link List} of {@link NodeValue}
   * added in the {@link WorkflowToken.Scope} provided.
   * @param scope the scope for the key
   * @return the {@link Map} of key to {@link List} of {@link NodeValue} added for
   * the given scope
   */
  Map<String, List<NodeValue>> getAll(Scope scope);

  /**
   * @deprecated As of release 3.1, MapReduce counters are now stored
   * under the key counter group name, followed by ".", followed by the counter name.
   * <p/>
   * For example: to access the the number of input records to the map method of
   * the ``PurchaseHistoryBuilder`` MapReduce program:
   * <pre>
   * <code>
   * String counterGroupName = "org.apache.hadoop.mapreduce.TaskCounter";
   * String counterName = "MAP_INPUT_RECORDS";
   * String counterKey = counterGroupName + "." + counterName;
   * String counterValue = workflowToken.get(counterKey, "PurchaseHistoryBuilder", WorkflowToken.Scope.SYSTEM);
   * </code>
   * </pre>
   * <p/>
   * Get the Hadoop counters from the previous MapReduce program in the Workflow.
   * The method returns null if the counters are not set.
   * @return the Hadoop MapReduce counters set by the previous MapReduce program
   */
  @Deprecated
  @Nullable
  Map<String, Map<String, Long>> getMapReduceCounters();
}