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