2 files changed, 98 insertions, 10 deletions
diff --git a/src/main/java/com/google/devtools/build/lib/actions/ActionLookupValue.java b/src/main/java/com/google/devtools/build/lib/actions/ActionLookupValue.java
index 000f359315..33555a20c7 100644
--- a/src/main/java/com/google/devtools/build/lib/actions/ActionLookupValue.java
+++ b/src/main/java/com/google/devtools/build/lib/actions/ActionLookupValue.java
@@ -122,18 +122,19 @@ public class ActionLookupValue implements SkyValue {
     return Preconditions.checkNotNull(actions.get(index), "null action: %s %s", index, this);
   }
 
+  public ActionTemplate<?> getActionTemplate(int index) {
+    ActionAnalysisMetadata result = getActionAnalysisMetadata(index);
+    Preconditions.checkState(
+        result instanceof ActionTemplate, "Not action template: %s %s %s", result, index, this);
+    return (ActionTemplate<?>) result;
+  }
+
   /**
-   * Returns the {@link ActionAnalysisMetadata} at index {@code index} if it is present and
-   * <i>not</i> an {@link Action}. Tree artifacts need their {@code ActionTemplate}s in order to
-   * generate the correct actions, but in general most actions are not needed after they are
-   * executed and may not even be available.
+   * Returns if the action at {@code index} is an {@link ActionTemplate} so that tree artifacts can
+   * take the proper action.
    */
-  public ActionAnalysisMetadata getIfPresentAndNotAction(int index) {
-    ActionAnalysisMetadata actionAnalysisMetadata = actions.get(index);
-    if (!(actionAnalysisMetadata instanceof Action)) {
-      return actionAnalysisMetadata;
-    }
-    return null;
+  public boolean isActionTemplate(int index) {
+    return actions.get(index) instanceof ActionTemplate;
   }
 
   /** To be used only when checking consistency of the action graph -- not by other values. */
diff --git a/src/main/java/com/google/devtools/build/lib/actions/ActionTemplate.java b/src/main/java/com/google/devtools/build/lib/actions/ActionTemplate.java
new file mode 100644
index 0000000000..2a68628e75
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/lib/actions/ActionTemplate.java
@@ -0,0 +1,87 @@
+// Copyright 2017 The Bazel Authors. All rights reserved.
+//
+// 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 com.google.devtools.build.lib.actions;
+
+import com.google.devtools.build.lib.actions.Artifact.TreeFileArtifact;
+
+/**
+ * A placeholder action that, at execution time, expands into a list of {@link Action}s to be
+ * executed.
+ *
+ * <p>ActionTemplate is for users who want to dynamically register Actions operating on individual
+ * {@link TreeFileArtifact} inside input and output TreeArtifacts at execution time.
+ *
+ * <p>It takes in one TreeArtifact and generates one TreeArtifact. The following happens at
+ * execution time for ActionTemplate:
+ *
+ * <ol>
+ *   <li>Input TreeArtifact is resolved.
+ *   <li>For each individual {@link TreeFileArtifact} inside input TreeArtifact, generate an output
+ *       {@link TreeFileArtifact} inside output TreeArtifact.
+ *   <li>For each pair of input and output {@link TreeFileArtifact}s, generate an associated {@link
+ *       Action}.
+ *   <li>All expanded {@link Action}s are executed and their output {@link TreeFileArtifact}s
+ *       collected.
+ *   <li>Output TreeArtifact is resolved.
+ * </ol>
+ *
+ * <p>Implementations of ActionTemplate must follow the contract of this interface and also make
+ * sure:
+ *
+ * <ol>
+ *   <li>ActionTemplate instances should be immutable and side-effect free.
+ *   <li>ActionTemplate inputs and outputs are supersets of the inputs and outputs of expanded
+ *       actions, excluding inputs discovered at execution time. This ensures the ActionTemplate can
+ *       properly represent the expanded actions at analysis time, and the action graph at analysis
+ *       time is correct. This is important because the action graph is walked in a lot of places
+ *       for correctness checks and build analysis.
+ *   <li>The outputs of expanded actions must be under the output TreeArtifact and must not have
+ *       artifact or artifact path prefix conflicts.
+ * </ol>
+ */
+public interface ActionTemplate<T extends Action> extends ActionAnalysisMetadata {
+
+  /** An exception signalling that the template expansion failed during execution phase */
+  class ActionTemplateExpansionException extends Exception {
+
+    public ActionTemplateExpansionException(String cause) {
+      super(cause);
+    }
+
+    public ActionTemplateExpansionException(Throwable cause) {
+      super(cause);
+    }
+  }
+
+  /**
+   * Given a list of input TreeFileArtifacts resolved at execution time, returns a list of expanded
+   * SpawnActions to be executed.
+   *
+   * @param inputTreeFileArtifacts the list of {@link TreeFileArtifact}s inside input TreeArtifact
+   *     resolved at execution time
+   * @param artifactOwner the {@link ArtifactOwner} of the generated output {@link
+   *     TreeFileArtifact}s
+   * @return a list of expanded {@link Action}s to execute, one for each input {@link
+   *     TreeFileArtifact}
+   */
+  Iterable<T> generateActionForInputArtifacts(
+      Iterable<TreeFileArtifact> inputTreeFileArtifacts, ArtifactOwner artifactOwner)
+      throws ActionTemplateExpansionException;
+
+  /** Returns the input TreeArtifact. */
+  Artifact getInputTreeArtifact();
+
+  /** Returns the output TreeArtifact. */
+  Artifact getOutputTreeArtifact();
+}