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