// Copyright 2014 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.analysis;

import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableSet;
import com.google.devtools.build.lib.actions.Action;
import com.google.devtools.build.lib.actions.ActionAnalysisMetadata;
import com.google.devtools.build.lib.actions.ActionRegistry;
import com.google.devtools.build.lib.actions.Artifact;
import com.google.devtools.build.lib.actions.MiddlemanFactory;
import com.google.devtools.build.lib.actions.Root;
import com.google.devtools.build.lib.analysis.buildinfo.BuildInfoFactory.BuildInfoKey;
import com.google.devtools.build.lib.analysis.config.BuildConfiguration;
import com.google.devtools.build.lib.events.ExtendedEventHandler;
import com.google.devtools.build.lib.vfs.PathFragment;
import com.google.devtools.build.skyframe.SkyFunction;

/**
 * The set of services that are provided to {@link ConfiguredTarget} objects
 * during initialization.
 *
 * <p>These objects should not outlast the analysis phase. Do not pass them to {@link Action}
 * objects or other persistent objects. There are internal tests to ensure that AnalysisEnvironment
 * objects are not persisted that check the name of this class, so update those tests you change the
 * names of any implementation of this class.
 */
public interface AnalysisEnvironment extends ActionRegistry {
  /** Returns a callback to be used in this build for reporting analysis errors. */
  ExtendedEventHandler getEventHandler();

  /**
   * Returns whether any errors were reported to this instance.
   */
  boolean hasErrors();

  /**
   * Returns the artifact for the derived file {@code rootRelativePath}.
   *
   * <p><b>DO NOT USE</b> in rule implementations. Use
   * {@link RuleContext#getPackageRelativeArtifact(PathFragment, Root)} or
   * {@link RuleContext#getUniqueDirectoryArtifact(String, PathFragment, Root)}, or, if there is
   * really no other way, {@link RuleContext#getShareableArtifact(PathFragment, Root)} instead.
   *
   * <p>Creates the artifact if necessary and sets the root of that artifact to {@code root}.
   *
   * <p>This method can create artifacts anywhere in the output tree, thus making it possible for
   * artifacts generated by two different rules to clash. To avoid this, use the artifact creation
   * method on {@link RuleContext} mentioned above.
   */
  Artifact getDerivedArtifact(PathFragment rootRelativePath, Root root);

  /**
   * Returns an artifact for the derived file {@code rootRelativePath} whose changes do not cause
   * a rebuild.
   *
   * <p>Creates the artifact if necessary and sets the root of that artifact to {@code root}.
   *
   * <p>This is useful for files that store data that changes very frequently (e.g. current time)
   * but does not substantially affect the result of the build.
   */
  Artifact getConstantMetadataArtifact(PathFragment rootRelativePath,
      Root root);

  /**
   * Returns the artifact for the derived TreeArtifact with directory {@code rootRelativePath},
   * creating it if necessary, and setting the root of that artifact to
   * {@code root}. The artifact will be a TreeArtifact.
   */
  Artifact getTreeArtifact(PathFragment rootRelativePath, Root root);

  /**
   * Returns the artifact for the derived file {@code rootRelativePath},
   * creating it if necessary, and setting the root of that artifact to
   * {@code root}. The artifact will represent the output directory of a {@code Fileset}.
   */
  Artifact getFilesetArtifact(PathFragment rootRelativePath, Root root);

  /**
   * Returns the middleman factory associated with the build.
   */
  // TODO(bazel-team): remove this method and replace it with delegate methods.
  MiddlemanFactory getMiddlemanFactory();

  /**
   * Returns the generating action for the given local artifact.
   *
   * If the artifact was created in another analysis environment (e.g. by a different configured
   * target instance) or the artifact is a source artifact, it returns null.
   */
  ActionAnalysisMetadata getLocalGeneratingAction(Artifact artifact);

  /**
   * Returns the actions that were registered so far with this analysis environment, that is, all
   * the actions that were created by the current target being analyzed.
   */
  Iterable<ActionAnalysisMetadata> getRegisteredActions();

  /**
   * Returns the Skyframe SkyFunction.Environment if available. Otherwise, null.
   *
   * <p>If you need to use this for something other than genquery, please think long and hard
   * about that.
   */
  SkyFunction.Environment getSkyframeEnv();

  /**
   * Returns the Artifact that is used to hold the non-volatile workspace status for the current
   * build request.
   */
  Artifact getStableWorkspaceStatusArtifact() throws InterruptedException;

  /**
   * Returns the Artifact that is used to hold the volatile workspace status (e.g. build changelist)
   * for the current build request.
   */
  Artifact getVolatileWorkspaceStatusArtifact() throws InterruptedException;

  /**
   * Returns the Artifacts that contain the workspace status for the current build request.
   *
   * @param ruleContext the rule to use for error reporting.
   * @param config the current build configuration.
   */
  ImmutableList<Artifact> getBuildInfo(
      RuleContext ruleContext, BuildInfoKey key, BuildConfiguration config)
      throws InterruptedException;

  /**
   * Returns the set of orphan Artifacts (i.e. Artifacts without generating action). Should only be
   * called after the ConfiguredTarget is created.
   */
  ImmutableSet<Artifact> getOrphanArtifacts();
}