| /* |
| * 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.resources.ext; |
| |
| import com.google.gwt.core.ext.TreeLogger; |
| import com.google.gwt.core.ext.UnableToCompleteException; |
| import com.google.gwt.core.ext.typeinfo.JMethod; |
| |
| /** |
| * Encapsulates per-type resource generation logic. This type is used only by |
| * developers who wish to add additional resource types to the resource |
| * generation system. Implementations are paired with one or more interfaces |
| * derived from ResourcePrototype that have been annotated with an |
| * {@link ResourceGeneratorType} annotation. Instances of ResourceGenerator must |
| * support default-instantiation (i.e. via {@link Class#newInstance()}). |
| * <p> |
| * The methods on an instance of ResourceGenerator will be called in the |
| * following order by the resource generation system: |
| * <ol> |
| * <li>{@link #init}</li> |
| * <li> |
| * {@link #prepare} once for each method</li> |
| * <li>Based on the requirements specified by the ResourceGenerator, the |
| * framework may decide that no further action is required. If this is the case, |
| * the framework will immediately invoke {@link #finish}.</li> |
| * <li>{@link #createFields}</li> |
| * <li>{@link #createAssignment} once for each method</li> |
| * <li>{@link #finish}</li> |
| * </ol> |
| * <p> |
| * The methods {@link #prepare} and {@link #createAssignment} will be called |
| * only with those methods whose ResourcePrototype-derived type specifies the |
| * particular type of ResourceGenerator as the implementor. The relative order |
| * in which ResourceGenerators are invoked and the specific order in which the |
| * bundle's methods are presented is undefined. |
| * <p> |
| * Direct access to the contents of the generated bundle implementation is |
| * intentionally limited to prevent unrelated ResourceGenerators from |
| * potentially creating namespace conflicts or generating invalid Java source. |
| * |
| * @see ResourceGeneratorUtil |
| */ |
| public interface ResourceGenerator { |
| |
| /** |
| * Produce the right-hand-side of a Java assignment expression to provide the |
| * singleton instance object for a particular resource. |
| * <p> |
| * Example: |
| * |
| * <pre> |
| * new MySampleResource() { public Foo getFoo() { ... } } |
| * </pre> |
| */ |
| String createAssignment(TreeLogger logger, ResourceContext context, |
| JMethod method) throws UnableToCompleteException; |
| |
| /** |
| * The ResourceGenerator can create fields within the implementation of the |
| * bundle type. The Fields object passed into this method is used to declare, |
| * and possibly initialize, Java fields within the final implementation of the |
| * resource bundle type. |
| * <p> |
| * The Fields instance should not be retained beyond the lifetime of this |
| * method as operation on this object is not defined after the implementation |
| * of this method returns. |
| */ |
| void createFields(TreeLogger logger, ResourceContext context, |
| ClientBundleFields fields) throws UnableToCompleteException; |
| |
| /** |
| * Called at the end of the resource generation phase and can be used to |
| * perform cleanup. |
| */ |
| void finish(TreeLogger logger, ResourceContext context) |
| throws UnableToCompleteException; |
| |
| /** |
| * Initialize the ResourceGenerator with the generation context that will |
| * remain valid for the duration of the resource-generation phase. The logger |
| * instance should not be retained; use the per-method loggers instead. |
| */ |
| void init(TreeLogger logger, ResourceContext context) |
| throws UnableToCompleteException; |
| |
| /** |
| * Called once for each method the ResourceGenerator is expected to handle. |
| * This allows cross-resource state to be accumulated, such as for data |
| * aggregation. |
| */ |
| void prepare(TreeLogger logger, ResourceContext context, |
| ClientBundleRequirements requirements, JMethod method) |
| throws UnableToCompleteException; |
| } |