| /* |
| * Copyright 2007 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.core.ext.linker.Artifact; |
| import com.google.gwt.core.ext.linker.GeneratedResource; |
| import com.google.gwt.core.ext.typeinfo.TypeOracle; |
| import com.google.gwt.dev.resource.ResourceOracle; |
| |
| import java.io.OutputStream; |
| import java.io.PrintWriter; |
| |
| /** |
| * Provides metadata to deferred binding generators. |
| */ |
| public interface GeneratorContext { |
| |
| /** |
| * Checks whether a rebind rule is available for a given sourceTypeName, such |
| * as can appear in a replace-with or generate-with rule. |
| * |
| * @param sourceTypeName the name of a type to check for rebind rule |
| * availability. |
| * @return true if a rebind rule is available |
| */ |
| boolean checkRebindRuleAvailable(String sourceTypeName); |
| |
| /** |
| * Commits source generation begun with |
| * {@link #tryCreate(TreeLogger, String, String)}. |
| */ |
| void commit(TreeLogger logger, PrintWriter pw); |
| |
| /** |
| * Add an Artifact to the {@link com.google.gwt.core.ext.linker.ArtifactSet} |
| * that will be presented to the {@link Linker} chain at the end of the |
| * compilation cycle. Custom sub-classes of Artifact can be used to write |
| * cooperating Generator and Linker combinations. This method is semantically |
| * equivalent to calling |
| * {@link com.google.gwt.core.ext.linker.ArtifactSet#replace(Artifact)} if an |
| * equivalent Artifact had previously been committed. |
| * |
| * @param logger a logger; normally the logger passed into the currently |
| * invoked generator or a branch thereof |
| * @param artifact the Artifact to provide to the Linker chain. |
| */ |
| void commitArtifact(TreeLogger logger, Artifact<?> artifact) throws UnableToCompleteException; |
| |
| /** |
| * Commits resource generation begun with |
| * {@link #tryCreateResource(TreeLogger, String)}. |
| * |
| * @return the GeneratedResource that was created as a result of committing |
| * the OutputStream. |
| * @throws UnableToCompleteException if the resource cannot be written to |
| * disk, if the specified stream is unknown, or if the stream has |
| * already been committed |
| */ |
| GeneratedResource commitResource(TreeLogger logger, OutputStream os) |
| throws UnableToCompleteException; |
| |
| /** |
| * Get the cached rebind result that has been provided to the context, if |
| * available. The provided result will be the most recent previously generated |
| * result for the currently active rebind rule and requested type name. |
| * |
| * @return A {@link CachedGeneratorResult} object, if one has been provided to |
| * the context. Null is returned if there is no previous result |
| * available. |
| */ |
| CachedGeneratorResult getCachedGeneratorResult(); |
| |
| /** |
| * Gets the property oracle for the current generator context. Generators can |
| * use the property oracle to query deferred binding properties. |
| */ |
| PropertyOracle getPropertyOracle(); |
| |
| /** |
| * Returns a resource oracle containing all resources that are mapped into the |
| * module's source (or super-source) paths. Conceptually, this resource oracle |
| * exposes resources which are "siblings" to GWT-compatible Java classes. For |
| * example, if the module includes <code>com.google.gwt.core.client</code> as |
| * a source package, then a resource at |
| * <code>com/google/gwt/core/client/Foo.properties</code> would be exposed by |
| * this resource oracle. |
| */ |
| ResourceOracle getResourcesOracle(); |
| |
| /** |
| * Gets the type oracle for the current generator context. Generators can use |
| * the type oracle to ask questions about the entire translatable code base. |
| * |
| * @return a TypeOracle over all the relevant translatable compilation units |
| * in the source path |
| */ |
| TypeOracle getTypeOracle(); |
| |
| /** |
| * Check whether generator result caching is currently enabled. |
| */ |
| boolean isGeneratorResultCachingEnabled(); |
| |
| /** |
| * Returns true if generators are being run to produce code for a production |
| * compile. Returns false for dev mode. Generators can use this information to |
| * produce code optimized for the target. |
| */ |
| boolean isProdMode(); |
| |
| /** |
| * Attempts to get a <code>PrintWriter</code> so that the caller can generate |
| * the source code for the named type. If the named types already exists, |
| * <code>null</code> is returned to indicate that no work needs to be done. |
| * The file is not committed until {@link #commit(TreeLogger, PrintWriter)} is |
| * called. |
| * |
| * @param logger a logger; normally the logger passed into the currently |
| * invoked generator, or a branch thereof |
| * @param packageName the name of the package to which the create type belongs |
| * @param simpleName the unqualified source name of the type being generated |
| * @return <code>null</code> if the package and class already exists, |
| * otherwise a <code>PrintWriter</code> is returned. |
| */ |
| PrintWriter tryCreate(TreeLogger logger, String packageName, String simpleName); |
| |
| /** |
| * Attempts to get an <code>OutputStream</code> so that the caller can write |
| * file contents into the named file underneath the compilation output |
| * directory. The file is not committed until |
| * {@link #commitResource(TreeLogger, OutputStream)} is called. |
| * |
| * @param logger a logger; normally the logger passed into the currently |
| * invoked generator, or a branch thereof |
| * @param partialPath the name of the file whose contents are to be written; |
| * the name can include subdirectories separated by forward slashes |
| * ('/') |
| * @return an <code>OutputStream</code> into which file contents can be |
| * written, or <code>null</code> if a resource by that name is already |
| * pending or already exists |
| * @throws UnableToCompleteException if the resource could not be initialized |
| * for some reason, such as if the specified partial path is invalid |
| */ |
| OutputStream tryCreateResource(TreeLogger logger, String partialPath) |
| throws UnableToCompleteException; |
| |
| /** |
| * Mark a type to be reused from the generator result cache, if available. |
| * Calling this method with a successful response indicates that the calling |
| * generator will not re-generate this type. A cached version of this type |
| * will be added to the context once the calling generator returns from |
| * {@link IncrementalGenerator#generateIncrementally}, with a result |
| * containing {@link RebindMode#USE_PARTIAL_CACHED}. |
| * |
| * @param typeName the fully qualified source name of a type. |
| * @return true if the requested type is available from the generator result |
| * cache, false otherwise. |
| */ |
| boolean tryReuseTypeFromCache(String typeName); |
| } |