com.google.gwt.core.ext.IncrementalGenerator.java Source code

Introduction

Here is the source code for com.google.gwt.core.ext.IncrementalGenerator.java

Source

/*
 * Copyright 2011 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;

/**
 * An extension to the {@link Generator} class which supports incremental
 * generation. It adds a {@link #generateIncrementally} method.
 */
public abstract class IncrementalGenerator extends Generator {

    /**
     * A static helper method to wrap a non-incremental generator's result. It
     * calls the generator's {@link Generator#generate} method, and synthesizes a
     * {@link RebindResult} instance to be returned.
     *
     * @param logger A TreeLogger
     * @param generator A non-incremental generator
     * @param context The generator context
     * @param typeName The type for which a subclass will be generated
     * @return a RebindResult
     * @throws UnableToCompleteException
     */
    public static RebindResult generateNonIncrementally(TreeLogger logger, Generator generator,
            GeneratorContext context, String typeName) throws UnableToCompleteException {

        RebindMode mode;
        String resultTypeName = generator.generate(logger, context, typeName);
        if (resultTypeName == null) {
            mode = RebindMode.USE_EXISTING;
            resultTypeName = typeName;
        } else {
            mode = RebindMode.USE_ALL_NEW_WITH_NO_CACHING;
        }

        return new RebindResult(mode, resultTypeName);
    }

    /**
     * This method overrides {@link Generator#generate}, and is included only for
     * backwards compatibility. It wraps a call to {@link #generateIncrementally}.
     * This method won't normally be called by the gwt rebind process, and it is
     * declared final and can't be overridden. It is provided in support of
     * existing applications and other generators which call this method directly,
     * outside of the gwt framework.
     * <p>
     * The passed in context is wrapped with an instance of
     * {@link NonIncrementalGeneratorContext}, to ensure that no generator result
     * caching is attempted, since the cached result will be ignored by callers of
     * this method anyway.
     *
     * @see Generator#generate
     *
     * @param logger A TreeLogger
     * @param context The generator context
     * @param typeName The type for which a subclass will be generated
     * @return the name of a subclass to substitute for the requested class, or
     *         return <code>null</code> to cause the requested type itself to be
     *         used
     * @throws UnableToCompleteException
     */
    @Override
    public final String generate(TreeLogger logger, GeneratorContext context, String typeName)
            throws UnableToCompleteException {
        /*
         * Since no generator result caching should happen if this method is called,
         * we wrap the context, to ensure that the check for {@link
         * GeneratorContext.isGeneratorResultCachingEnabled()} will return false.
         */
        GeneratorContext wrappedContext = NonIncrementalGeneratorContext.newInstance(context);
        RebindResult result = generateIncrementally(logger, wrappedContext, typeName);
        return result.getResultTypeName();
    }

    /**
     * Incrementally generate a default constructible subclass of the requested
     * type. The generator can use information from the context to make decisions
     * on whether to incrementally reuse cached output from previous invocations.
     * <p>
     * It returns a {@link RebindResult}, which contains a {@link RebindMode}
     * field, which indicates whether to use previously cached output, newly
     * generated output, or a partial mixture of both cached and newly generated
     * output.
     * <p>
     * The result also includes a field for the name of the subclass to substitute
     * for the requested class. It may also contain extra client data added by
     * specific generator implementations.
     * <p>
     * This method throws an <code>UnableToCompleteException</code> if for any
     * reason it cannot complete successfully.
     *
     * @see RebindResult
     * @see RebindMode
     *
     * @param logger A TreeLogger
     * @param context The generator context
     * @param typeName The type for which a subclass will be generated
     * @return a RebindResult
     * @throws UnableToCompleteException
     */
    public abstract RebindResult generateIncrementally(TreeLogger logger, GeneratorContext context, String typeName)
            throws UnableToCompleteException;

    /**
     * Returns a version id for an IncrementalGenerator. It is used by the system
     * to invalidate {@link CachedGeneratorResult}'s that were generated by a
     * different version of this generator. This is useful when new versions of a
     * generator are developed, which might alter the structure of generated
     * output, or alter semantics for cache reusability checking.
     * <p>
     * It is the responsibility of the developer to maintain this version id
     * consistently.
     *
     * @return a version id
     */
    public abstract long getVersionId();
}