com.google.gwt.core.ext

## Class Linker

- java.lang.Object
- - com.google.gwt.core.ext.Linker

- Direct Known Subclasses:
    AbstractLinker, SoycReportLinker

      public abstract class Linker
      extends java.lang.Object

  Defines a linker for the GWT compiler. Each Linker must be annotated with a `LinkerOrder` annotation to determine the relative ordering of the Linkers. Exact order of Linker execution will be determined by the order of `add-linker` tags in the module configuration. Each Linker should also be annotated with `Shardable`; non-shardable linkers are deprecated and will eventually not be supported.

  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(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(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.

  When hosted mode starts for a module, it calls `link(TreeLogger, LinkerContext, ArtifactSet)` for non-shardable linkers and `link(TreeLogger, LinkerContext, ArtifactSet, boolean)` for shardable ones, passing `false` as the `onePermutation` argument. If any artifacts are subsequently generated during the course of running hosted mode, `relink(TreeLogger, LinkerContext, ArtifactSet)` will be called with the new artifacts.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Linker()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract java.lang.String` | `getDescription()` Returns a human-readable String describing the Linker.
    `boolean` | `isShardable()` Check whether this class is considered a shardable linker.
    `ArtifactSet` | `link(TreeLogger logger, LinkerContext context, ArtifactSet artifacts)` This method is invoked for linkers not annotated with `Shardable`.
    `ArtifactSet` | `link(TreeLogger logger, LinkerContext context, ArtifactSet artifacts, boolean onePermutation)` This method is invoked for linkers annotated with `Shardable`.
    `ArtifactSet` | `relink(TreeLogger logger, LinkerContext context, ArtifactSet newArtifacts)` Re-invoke the Linker with newly generated artifacts.
    `boolean` | `supportsDevModeInJunit(LinkerContext context)` Returns `true` if this linker supports DevMode.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### Linker

          public Linker()

  - ### Method Detail

    - #### getDescription

          public abstract java.lang.String getDescription()

      Returns a human-readable String describing the Linker.

    - #### isShardable

          public final boolean isShardable()

      Check whether this class is considered a shardable linker. A linker is shardable if it either implements the `Shardable` annotation or it has a field named `gwtIsShardable`. 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.

    - #### link

          public ArtifactSet link(TreeLogger logger,
                         LinkerContext context,
                         ArtifactSet artifacts)
                           throws UnableToCompleteException

      This method is invoked for linkers not annotated with `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 `Shardable`.
      Parameters:
        `logger` - the TreeLogger to record to
        `context` - provides access to the Linker's environment
        `artifacts` - an unmodifiable view of the artifacts to link
      Returns:
        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

    - #### link

          public ArtifactSet link(TreeLogger logger,
                         LinkerContext context,
                         ArtifactSet artifacts,
                         boolean onePermutation)
                           throws UnableToCompleteException

      This method is invoked for linkers annotated with `Shardable`. It is called at two points during compilation: after the compile of each permutation, and after all compilation has finished. The `onePermutation` is `true` for a per-permutation call and `false` for a global final-link call.

      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:

      1. All EmittedArtifacts have been converted to BinaryEmittedArtifacts
      2. All artifacts not marked as `Transferable` have been discarded.
      Parameters:
        `logger` - the TreeLogger to record to
        `context` - provides access to the Linker's environment
        `artifacts` - an unmodifiable view of the artifacts to link
        `onePermutation` - true for a one-permutation call
      Returns:
        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

    - #### relink

          public ArtifactSet relink(TreeLogger logger,
                           LinkerContext context,
                           ArtifactSet newArtifacts)
                             throws UnableToCompleteException

      Re-invoke the Linker with newly generated artifacts. Linkers that need to reference the original artifact set passed into `link(TreeLogger, LinkerContext, ArtifactSet)` should retain a copy of the original artifact set in an instance variable.
      Parameters:
        `logger` - the TreeLogger to record to
        `context` - provides access to the Linker's environment
        `newArtifacts` - an unmodifiable view of the newly generated artifacts
      Returns:
        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

    - #### supportsDevModeInJunit

          public boolean supportsDevModeInJunit(LinkerContext context)

      Returns `true` if this linker supports DevMode.
      Parameters:
        `context` - a LinkerContext