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

Introduction

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

Source

/*
 * Copyright 2010 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.dev.javac.rebind.RebindResult;

/**
 * EXPERIMENTAL and subject to change. Do not use this in production code.
 * <p>
 * Adds a new {@link #generateIncrementally} method.
 * <p> 
 * TODO(jbrosenberg): Merge this into {@link Generator} directly, once the api
 * has stabilized and we can remove the "experimental" moniker.
 */
public abstract class GeneratorExt extends Generator {

    /**
     * A default implementation of the abstract method defined in the base
     * {@link Generator} class.  This will wrap a call to
     * {@link #generateIncrementally}, and attempt no caching.  This supports
     * backwards compatibility for applications or other generators which call 
     * this generator directly, as outside of the normal internal rebind process.
     * <p>
     * It is recommended that {@link #generateIncrementally} be used instead.
     * 
     * @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
     */
    @Override
    public String generate(TreeLogger logger, GeneratorContext context, String typeName)
            throws UnableToCompleteException {

        // wrap the passed in context
        GeneratorContextExt contextExt = context instanceof GeneratorContextExt ? (GeneratorContextExt) context
                : GeneratorContextExtWrapper.newInstance(context);

        RebindResult result = generateIncrementally(logger, contextExt, typeName);
        return result.getReturnedTypeName();
    }

    /**
     * Incrementally generate a default constructible subclass of the requested 
     * type.  The generator can use information from the context to determine
     * whether it needs to regenerate everything, or whether it can selectively
     * regenerate a subset of its output, or whether it can return quickly to
     * allow reuse of all previously cached objects.  It will return a 
     * {@link RebindResult}, which contains a
     * {@link com.google.gwt.dev.javac.rebind.RebindStatus} field indicating
     * whether to use previously cached artifacts, newly generated ones, or a
     * partial mixture of both cached and newly generated objects.
     * <p>
     * The result also includes a field for the name of the subclass to 
     * substitute for the requested class.
     * <p>
     * The generator throws an <code>UnableToCompleteException</code> if for 
     * any reason it cannot complete successfully.
     * 
     * @return a RebindResult
     */
    public abstract RebindResult generateIncrementally(TreeLogger logger, GeneratorContextExt context,
            String typeName) throws UnableToCompleteException;
}