/*
* 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.GeneratorContext;
import com.google.gwt.core.ext.UnableToCompleteException;
import com.google.gwt.core.ext.typeinfo.JClassType;
import java.net.URL;
/**
* Context object for ResourceGenerators. An instance of this type will be
* provided by the resource generation framework to implementations of
* ResourceGenerator via {@link ResourceGenerator#init}. Because this interface
* is not intended to be implemented by end-users, the API provided by this
* interface may be extended in the future.
* <p>
* Depending on the optimizations made by the implementation of {@link #deploy},
* the resulting URL may or may not be compatible with standard
* {@link com.google.gwt.http.client.RequestBuilder} / XMLHttpRequest security
* semantics. If the resource is intended to be used with XHR, or if there are
* other reasons why embedding the resource is undesirable such as known
* incompatibilities, the <code>forceExternal</code> parameter should be set to
* <code>true</code> when invoking {@link #deploy}.
* </p>
*/
public interface ResourceContext {
/**
* Cause a specific collection of bytes to be available in the program's
* compiled output. The return value of this method is a Java expression which
* will evaluate to the location of the resource at runtime. The exact format
* should not be depended upon.
*
* @param suggestedFileName an unobfuscated filename to possibly use for the
* resource
* @param mimeType the MIME type of the data being provided
* @param data the bytes to add to the output
* @param forceExternal prevents embedding of the resource, e.g. in case of
* known incompatibilities or for example to enforce compatibility
* with security restrictions if the resource is intended to be
* accessed via an XMLHttpRequest
* @return a Java expression which will evaluate to the location of the
* provided resource at runtime
*/
String deploy(String suggestedFileName, String mimeType, byte[] data,
boolean forceExternal) throws UnableToCompleteException;
/**
* Cause a specific collection of bytes to be available in the program's
* compiled output. The return value of this method is a Java expression which
* will evaluate to the location of the resource at runtime. The exact format
* should not be depended upon.
*
* @param resource the resource to add to the compiled output
* @param forceExternal prevents embedding of the resource, e.g. in case of
* known incompatibilities or for example to enforce compatibility
* with security restrictions if the resource is intended to be
* accessed via an XMLHttpRequest
* @return a Java expression which will evaluate to the location of the
* provided resource at runtime
* @deprecated use {@link #deploy(URL, String, boolean)} instead
*/
@Deprecated
String deploy(URL resource, boolean forceExternal)
throws UnableToCompleteException;
/**
* Cause a specific collection of bytes to be available in the program's
* compiled output. The return value of this method is a Java expression which
* will evaluate to the location of the resource at runtime. The exact format
* should not be depended upon.
*
* @param resource the resource to add to the compiled output
* @param mimeType optional MIME Type to be used for an embedded resource
* @param forceExternal prevents embedding of the resource, e.g. in case of
* known incompatibilities or for example to enforce compatibility
* with security restrictions if the resource is intended to be
* accessed via an XMLHttpRequest
* @return a Java expression which will evaluate to the location of the
* provided resource at runtime
*/
String deploy(URL resource, String mimeType, boolean forceExternal)
throws UnableToCompleteException;
/**
* Retrieve data from the ResourceContext.
*
* @param <T> the type of data to retrieve
* @param key the key value passed to {@link #getCachedData}
* @param clazz the type to which the cached value must be assignable
* @return the value previously passed to {@link #putCachedData} or
* <code>null</code> if the data was not found
* @throws ClassCastException if the cached data is not assignable to the
* specified type
*/
<T> T getCachedData(String key, Class<T> clazz);
/**
* Return the interface type of the resource bundle being generated.
*/
JClassType getClientBundleType();
/**
* Return the GeneratorContext in which the overall resource generation
* framework is being run. Implementations of ResourceGenerator should prefer
* {@link #deploy} over {@link GeneratorContext#tryCreateResource} in order to
* take advantage of serving optimizations that can be performed by the bundle
* architecture.
*/
GeneratorContext getGeneratorContext();
/**
* Returns the simple source name of the implementation of the bundle being
* generated. This can be used during code-generation to refer to the instance
* of the bundle (e.g. via <code>SimpleSourceName.this</code>).
*
* @throws IllegalStateException if this method is called during
* {@link ResourceGenerator#init} or
* {@link ResourceGenerator#prepare} methods.
*/
String getImplementationSimpleSourceName() throws IllegalStateException;
/**
* Returns a {@link ClientBundleRequirements} object, which can be used to
* track deferred-binding and configuration properties that are relevant to a
* resource context.
*/
ClientBundleRequirements getRequirements();
/**
* Store data in the ResourceContext. ResourceGenerators may reduce the amount
* of recomputation performed by caching data the ResourceContext. This cache
* will be invalidated when the compiler's TypeOracle is refreshed or
* replaced. Each ResourceGenerator has an isolated view of the cache.
*
* @param <T> the type of data being stored
* @param key a string key to locate the data
* @param value the value to store
* @return <code>true</code> if the cache did not previously contain the
* key-value pair
*/
<T> boolean putCachedData(String key, T value);
/**
* Indicates if the runtime context supports data: urls. When data URLs are
* supported by the context, aggregation of resource data into larger payloads
* is discouraged, as it offers reduced benefit to the application at runtime.
*/
boolean supportsDataUrls();
}