/*
 * 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();
}