There is a problem when using Internet Explorer to access image bundle files
over HTTPS, when the image bundle files have a security constraint set by the
web application. The problem seems to occur when the web application server is
Tomcat or Glassfish. It stems from the way in which Internet Explorer renders
the composite image, and the caching headers that are set by Tomcat and
Glassfish when the HTTPS protocol is used to request a resource protected by a
security constraint.
Tomcat and Glassfish set HTTP response headers indicating that the file should
not be cached. Internet Explorer requires that all content viewed via a plugin
must be cached. We are using AlphaImageLoader to display png files, which
qualifies as a plugin. The result is that the images which rely on the image
bundle image are not displayed.
After doing some research, I discovered a few ways to get around this problem.
Since this problem is not really GWT specific, the best that I could do is
document the problem and the workarounds in the ImageBundle javadoc. I have also
added a "Tip" to the ImageBundle section of the developer guide to point users
to the ImageBundle javadoc if they plan on using HTTPS with ImageBundles.
I also added another section to the ImageBundle javadoc about caching image
bundle files. This section was already in the Developer Guide, but it is good
have it in both places, as not everybody reads the Developer Guide.
Finally, I made a couple minor corrections to the existing javadoc.
Patch by: rdayal
Review by: jgw
Issue: 1172
git-svn-id: https://google-web-toolkit.googlecode.com/svn/trunk@1200 8db76d5a-ed1c-0410-87a9-c151d255dfc7
diff --git a/doc/src/com/google/gwt/doc/DeveloperGuide.java b/doc/src/com/google/gwt/doc/DeveloperGuide.java
index e662eb4..7231823 100644
--- a/doc/src/com/google/gwt/doc/DeveloperGuide.java
+++ b/doc/src/com/google/gwt/doc/DeveloperGuide.java
@@ -1592,6 +1592,11 @@
* specification</a> recommends specifying date of approximately one
* year in the future for the <code>Expires</code> header to indicate
* that the resource is permanently cacheable.
+ * @tip If your image bundle files are going to be accessed via the HTTPS
+ * protocol, see the section entitled "Image Bundles and the HTTPS Protocol"
+ * in the {@link com.google.gwt.user.client.ui.ImageBundle ImageBundle documentation}.
+ * To support Internet Explorer, some changes to your web application
+ * configuration may be required.
*/
public static class ImageBundles {
diff --git a/user/src/com/google/gwt/user/client/ui/ImageBundle.java b/user/src/com/google/gwt/user/client/ui/ImageBundle.java
index b7877ca..4687aa1 100644
--- a/user/src/com/google/gwt/user/client/ui/ImageBundle.java
+++ b/user/src/com/google/gwt/user/client/ui/ImageBundle.java
@@ -35,12 +35,15 @@
* <code>png</code>, <code>gif</code>, or <code>jpg</code>. If the
* image name contains '/' characters, it is assumed to be the name of a
* resource on the classpath, formatted as would be expected by
- * <code>ClassLoader.getResource(String)</code>. Otherwise, the image must be
- * located in the same package as the user-defined image bundle.
+ * <code>
+ * <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/ClassLoader.html#getResource(java.lang.String)">ClassLoader.getResource(String)</a>.
+ * </code>
+ * Otherwise, the image must be located in the same package as the user-defined
+ * image bundle.
* </p>
*
* <p>
- * The easiest way to create image bundle is to omit the
+ * The easiest way to create an image bundle is to omit the
* <code>gwt.resource</code> metadata tag, and name the method the same as the
* image name, excluding the extension. When the image name is inferred in this
* manner, the image name's extension is assumed to be either <code>png</code>,
@@ -125,7 +128,93 @@
* </pre>
*
* </p>
- *
+ *
+ * <h3>Caching Recommendations for Image Bundle Files</h3>
+ * Since the filename for the image bundle's composite image is based on a hash
+ * of the file's contents, the server can tell the browser to cache the file
+ * permanently.
+ *
+ * <p>
+ * To make all image bundle files permanently cacheable, set up a rule in your
+ * web server to emit the <code>Expires</code> response header for any files
+ * ending with <code>".cache.*"</code>. Such a rule would automatically match
+ * generated image bundle filenames
+ * (e.g. <code>320ADF600D31858000C612E939F0AD1A.cache.png</code>).
+ * The HTTP/1.1 specification recommends specifying date of approximately one
+ * year in the future for the <code>Expires</code> header to indicate that the
+ * resource is permanently cacheable.
+ * </p>
+ *
+ * <h3>Image Bundles and the HTTPS Protocol</h3>
+ * There is an issue with displaying image bundle images in Internet Explorer
+ * when:
+ *
+ * <ul>
+ * <li>The image bundle's composite image is requested using the HTTPS protocol, and</li>
+ * <li>The web application has a security constraint set for the composite image</li>
+ * </ul>
+ *
+ * This issue is known to occur with the web application servers Tomcat and
+ * Glassfish. It stems from the way in which Internet Explorer renders
+ * the composite image, and the caching headers that are set by Tomcat and
+ * Glassfish when the HTTPS protocol is used to request a resource protected
+ * by a security constraint.
+ *
+ * <p>
+ * The native format for the composite image is <code>png</code>, and
+ * versions of Internet Explorer prior to 7 cannot render <code>png</code>
+ * transparerency. To get around this problem, we make use of a plugin built
+ * into the operating system.
+ * </p>
+ *
+ * <p>
+ * Internet Explorer specifies that files which require a plugin for viewing
+ * must be cached by the brower. That way, the plugin can read the cached file
+ * from the disk. Whenever the composite image has a security constraint specified
+ * by the web application's configuration and is requested using the HTTPS protocol,
+ * both Tomcat and Glassfish automatically append the HTTP headers
+ * <code>Pragma: No-cache</code> and <code>Cache-Control: no-cache</code>
+ * to the response.
+ * </p>
+ *
+ * <p>
+ * When the browser recieves the response, it does not cache the composite image.
+ * Since the composite image is not stored on disk, the plugin is unable to render
+ * it, and all of the images in the application which rely on the composite image
+ * will not be displayed.
+ * </p>
+ *
+ * <p>
+ *
+ * There are several ways to work around this issue:
+ *
+ * <ol>
+ * <li>
+ * Add a servlet filter which overrides the <code>Pragma</code> and
+ * <code>Cache-Control</code> headers for <code>png</code> files. These
+ * headers should either be removed, or set in such a way that the file will
+ * be cached by the browser.
+ * </li>
+ * <li>
+ * Use the <code>securePagesWithPragma</code> (works in Glassfish and Tomcat)
+ * or <code>disableProxyCaching</code> settings (works in Tomcat) in your
+ * web application configuration file. Refer to your web application
+ * server's documentation for specific instructions.
+ * </li>
+ * <li>
+ * Exclude the image bundle's composite image from the web application's
+ * security constraint.
+ * </li>
+ * <li>
+ * If there is sensitive data in any of the images in the image bundle,
+ * exclude that image from the bundle and include it in the web application's
+ * security constraint. Then, rebuild the image bundle, and exclude the updated
+ * bundle's composite image from the security constraint.
+ * </li>
+ * </ol>
+ *
+ * </p>
+ *
* <h3>For More Information</h3>
* See the GWT Developer Guide for an introduction to image bundles.
* @see com.google.gwt.user.client.ui.AbstractImagePrototype
