Java tutorial
/* * 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.user.client.ui; import java.lang.annotation.Documented; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * A tag interface that is used in the generation of image bundles. An image * bundle is a composition of multiple images into a single large image, along * with an interface for accessing a specific image's * {@link com.google.gwt.user.client.ui.AbstractImagePrototype prototype} from * within the composition. Obtain an image bundle instance by calling * <code>GWT.create(<i>T</i>)</code>, where <code>T</code> is an * interface that directly or indirectly extends <code>ImageBundle</code>. * * <p> * To create and use an image bundle, extend the <code>ImageBundle</code> * interface, and add a method declaration for each image that is to be part of * the bundle. Each method must take no parameters and must have a return type * of * {@link com.google.gwt.user.client.ui.AbstractImagePrototype AbstractImagePrototype}. * The image name can optionally be specified using the {@link Resource} * annotation. (Note that the <code>gwt.resource</code> javadoc metadata tag * supporting in GWT 1.4 has been superceded by the <code>Resource</code> * annotation.) Valid image name extensions are <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> * <a href="http://download.oracle.com/javase/1.5.0/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 an image bundle is to omit the {@link Resource} * annotation, 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>, <code>gif</code>, * or <code>jpg</code>, and the image location must be in the same package as * the user-defined image bundle. In the event that there are multiple image * files that have the same name with different extensions, the order of * extension precedence is <code>png</code>, <code>gif</code>, * <code>jpg</code>. * * <h3>Example</h3> * * <pre class="code"> * public interface MyImageBundle extends ImageBundle { * * /** * * Notice that the Resource annotation is not present, * * so the method name itself is assumed to match the associated * * image filename. * * * * One of btn_submit_icon.png, btn_submit_icon.gif, or * * btn_submit_icon.jpg must be located in the same package * * as MyImageBundle. * */ * public AbstractImagePrototype btn_submit_icon(); * * // No doc comment is required if you want the default * // name-matching behavior. * public AbstractImagePrototype cancelButtonIcon(); * } * </pre> * * </p> * * <p> * An image bundle that uses the <code>Resource</code> annotation to specify * image names might look something like this: * * <pre class="code"> * public interface MyImageBundle extends ImageBundle { * * /** * * The resource annotation contains no '/' characters, so * * btn_submit_icon.gif must be located in the same * * package as MyImageBundle. * */ * {@code @Resource("btn_submit_icon.gif")} * public AbstractImagePrototype submitButtonIcon(); * * /** * * btn_cancel_icon.png must be located in the package * * com.mycompany.myapp.icons (which must be on the classpath). * */ * {@code @Resource("com/mycompany/myapp/icons/btn_cancel_icon.png")} * public AbstractImagePrototype cancelButtonIcon(); * } * </pre> * * </p> * * <p> * Here is how MyImageBundle might be used in an application: * * <pre class="code"> * ... * * // Create a new instance of MyImageBundle using GWT.create. * // This only needs to be done once - a reference to myImageBundle can * // be kept for use by other parts of the application. * MyImageBundle myImageBundle = GWT.create(MyImageBundle.class); * * // Retrieve the image prototypes from myImageBundle. * AbstractImagePrototype submitButtonImgPrototype = myImageBundle.btn_submit_icon(); * AbstractImagePrototype cancelButtonImgPrototype = myImageBundle.cancelButtonIcon(); * * // Add the images that are created based on the prototypes to the panel. * panel.add(submitButtonImgPrototype.createImage()); * panel.add(cancelButtonImgPrototype.createImage()); * * ... * </pre> * * </p> * * <h3>Security Warning: Image Bundle's use of the javax.image.imageio Classes</h3> * Certain versions of the JVM are susceptible to a vulnerability in the * javax.image.imageio classes, which are generally used to parse images. These * classes are used by image bundle's implementation to combine all of the * images into a single composite image. * * <p> * It is possible that the vulnerability could be exploited by using a specially * crafted image as part of an image bundle. To prevent this type of attack from * occurring, use a version of the JVM that includes a fix for this * vulnerability. See the following link for more information: * </p> * * <pre> * <a href="http://sunsolve.sun.com/search/document.do?assetkey=1-26-102934-1">http://sunsolve.sun.com/search/document.do?assetkey=1-26-102934-1</a> * </pre> * * <p> * Alternatively, if the images to be used in the bundle are trusted, then it is * not necessary to upgrade the JVM. * </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>Using Security Constraints to Protect Image Bundle Files</h3> * When a web application has a security constraint set for the composite image, * web application servers may change the image's HTTP response headers so that * web browsers will not cache it. For example, Tomcat and Glassfish set the * HTTP response headers <code>Pragma: No-cache</code>, * <code>Cache-Control: None</code>, and * <code>Expires: Thu, 1 Jan 1970 00:00:00</code> (or some other date in the * past). * * <p> * This can lead to performance problems when using image bundles, because the * large composite image will be re-requested unnecessarily. In addition, * <code>clear.cache.gif</code>, which is a blank image used by the image * bundle implementation, will be re-requested as well. While some browsers will * only re-request these images for each page load, others will re-request them * for each image on the page that is part of an image bundle. * </p> * * There are several ways to work around this issue: * * <ol> * <li> Modify the servlet which serves <code>png</code> and <code>gif</code> * files so that it explicitly sets the <code>Pragma</code>, * <code>Cache-Control</code>, and <code>Expires</code> headers. The * <code>Pragma</code> and <code>Cache-Control</code> headers should be * removed. The <code>Expires</code> header should be set according to the * caching recommendations mentioned in the previous section. </li> * <li> If using Tomcat, use the <code>disableProxyCaching</code> property in * your web application configuration file to prevent the <code>Pragma</code>, * <code>Cache-Control</code>, and <code>Expires</code> headers from being * changed by the server. Refer to your web application server's documentation * for more information. </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> * * <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. * * <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 browser. That way, the plugin can read the cached file * from the disk. Whenever the composite image is protected by a security * constraint, the web application server sets caching headers on the response * to prevent the browser from caching the image (see the previous section for * details). * </p> * * <p> * When using the HTTP protocol, Internet Explorer will disregard the * <code>Pragma: No-cache</code> and <code>Cache-Control: None</code> * headers, and will cache the image. However, When using the HTTPS protocol, * Internet Explorer will enforce these headers, and will not cache the 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> * To work around this issue, follow the recommendations outlined in the * previous section. * </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 * @see com.google.gwt.user.client.ui.Image#Image(String, int, int, int, int) * @see com.google.gwt.user.client.ui.Image#setVisibleRect(int, int, int, int) * @see com.google.gwt.user.client.ui.Image#setUrlAndVisibleRect(String, int, * int, int, int) * @deprecated replaced by {@link com.google.gwt.resources.client.ClientBundle} * and {@link com.google.gwt.resources.client.ImageResource} */ @Deprecated public interface ImageBundle { /** * Explicitly specifies a file name or path to the image resource to be * associated with a method in an {@link ImageBundle}. If the path is * unqualified (that is, if it contains no slashes), then it is sought in the * package enclosing the image bundle to which the annotation is attached. If * the path is qualified, then it is expected that the string can be passed * verbatim to <code>ClassLoader.getResource()</code>. */ @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) @Documented public @interface Resource { String value(); } }