Java tutorial
/* * 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; } /** * Returns {@code true} if this linker supports DevMode. * * @param context a LinkerContext */ public boolean supportsDevModeInJunit(LinkerContext context) { // By default, linkers do not support Dev Mode return false; } }