/*
 * Copyright 2008 Google 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 com.google.gwt.core.ext;

import com.google.gwt.core.ext.linker.ArtifactSet;
import com.google.gwt.core.ext.linker.Shardable;

/**
 * Defines a linker for the GWT compiler. Each Linker must be annotated with a
 * {@link com.google.gwt.core.ext.linker.LinkerOrder} annotation to determine
 * the relative ordering of the Linkers. Exact order of Linker execution will be
 * determined by the order of <code>add-linker</code> tags in the module
 * configuration. Each Linker should also be annotated with {@link Shardable};
 * non-shardable linkers are deprecated and will eventually not be supported.
 * 
 * <p>
 * A new instance of a linker is created each time a module is compiled or
 * during hosted mode when a module first loads (or is refreshed). During a
 * compile, {@link #link(TreeLogger, LinkerContext, ArtifactSet)} is called
 * exactly once on each non-shardable linker, and the artifact set will contain
 * any and all generated artifacts. For shardable linkers,
 * {@link #link(TreeLogger, LinkerContext, ArtifactSet, boolean)} is called once
 * for each compiled permutation and once after all compiles are finished. The
 * precise artifacts supplied differ with each call and are described in the
 * method's documentation.
 * 
 * <p>
 * When hosted mode starts for a module, it calls
 * {@link #link(TreeLogger, LinkerContext, ArtifactSet)} for non-shardable
 * linkers and {@link #link(TreeLogger, LinkerContext, ArtifactSet, boolean)}
 * for shardable ones, passing <code>false</code> as the
 * <code>onePermutation</code> argument. If any artifacts are subsequently
 * generated during the course of running hosted mode,
 * {@link #relink(TreeLogger, LinkerContext, ArtifactSet)} will be called with
 * the new artifacts.
 * </p>
 */
public abstract class Linker {
  /**
   * Returns a human-readable String describing the Linker.
   */
  public abstract String getDescription();

  /**
   * Check whether this class is considered a shardable linker. A linker is
   * shardable if it either implements the {@link Shardable} annotation or it
   * has a field named <code>gwtIsShardable</code>. If such a field is present,
   * it doesn't matter what value the field holds. The latter mechanism is only
   * intended to support linkers that must compile against older versions of
   * GWT.
   */
  public final boolean isShardable() {
    if (getClass().isAnnotationPresent(Shardable.class)) {
      return true;
    }

    try {
      getClass().getDeclaredField("gwtIsShardable");
      return true;
    } catch (NoSuchFieldException e) {
      // The field does not exist; fall through
    }

    return false;
  }
  
  /**
   * This method is invoked for linkers not annotated with {@link Shardable}. It
   * sees all artifacts across the whole compile and can modify them
   * arbitrarily. This method is only called if the linker is not annotated with
   * {@link Shardable}.
   * 
   * @param logger the TreeLogger to record to
   * @param context provides access to the Linker's environment
   * @param artifacts an unmodifiable view of the artifacts to link
   * @return the artifacts that should be propagated through the linker chain
   * @throws UnableToCompleteException if compilation violates assumptions made
   *           by the Linker or for errors encountered by the Linker
   */
  public ArtifactSet link(TreeLogger logger, LinkerContext context,
      ArtifactSet artifacts) throws UnableToCompleteException {
    assert !isShardable();
    return artifacts;
  }

  /**
   * <p>
   * This method is invoked for linkers annotated with {@link Shardable}. It is
   * called at two points during compilation: after the compile of each
   * permutation, and after all compilation has finished. The
   * <code>onePermutation</code> is <code>true</code> for a per-permutation call
   * and <code>false</code> for a global final-link call.
   * 
   * <p>
   * For one-permutation calls, this method is passed all artifacts generated
   * for just the one permutation. For the global call at the end of
   * compilation, this method sees artifacts for the whole compilation, but with
   * two modifications intended to support builds on computer clusters:
   * <ol>
   * <li>All EmittedArtifacts have been converted to BinaryEmittedArtifacts
   * <li>All artifacts not marked as
   * {@link com.google.gwt.core.ext.linker.Transferable} have been discarded.
   * </ol>
   * 
   * @param logger the TreeLogger to record to
   * @param context provides access to the Linker's environment
   * @param artifacts an unmodifiable view of the artifacts to link
   * @param onePermutation true for a one-permutation call
   * @return the artifacts that should be propagated through the linker chain
   * @throws UnableToCompleteException if compilation violates assumptions made
   *           by the Linker or for errors encountered by the Linker
   */
  public ArtifactSet link(TreeLogger logger, LinkerContext context,
      ArtifactSet artifacts, boolean onePermutation)
      throws UnableToCompleteException {
    assert isShardable();
    return artifacts;
  }

  /**
   * Re-invoke the Linker with newly generated artifacts. Linkers that need to
   * reference the original artifact set passed into
   * {@link #link(TreeLogger, LinkerContext, ArtifactSet)} should retain a copy
   * of the original artifact set in an instance variable.
   * 
   * @param logger the TreeLogger to record to
   * @param context provides access to the Linker's environment
   * @param newArtifacts an unmodifiable view of the newly generated artifacts
   * @return the new artifacts that should be propagated through the linker
   *         chain; it is not necessary to return any artifacts from the
   *         original link (or previous calls to relink) that have not been
   *         modified
   * @throws UnableToCompleteException if compilation violates assumptions made
   *           by the Linker or for errors encountered by the Linker
   */
  public ArtifactSet relink(TreeLogger logger, LinkerContext context,
      ArtifactSet newArtifacts) throws UnableToCompleteException {
    return newArtifacts;
  }

  /**
   * Does this linker support DevMode?
   */
  public boolean supportsDevMode() {
    // By default, linkers do not support Dev Mode
    return false;
  }
}