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