com.google.gwt.user.client.ui.ImageBundle Maven / Gradle / Ivy
/*
* 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
* GWT.create(T), where T is an
* interface that directly or indirectly extends ImageBundle.
*
*
* To create and use an image bundle, extend the ImageBundle
* 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 gwt.resource javadoc metadata tag
* supporting in GWT 1.4 has been superceded by the Resource
* annotation.) Valid image name extensions are png,
* gif, or jpg. 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
* ClassLoader.getResource(String).
*
* Otherwise, the image must be located in the same package as the user-defined
* image bundle.
*
*
*
* 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 png, gif,
* or jpg, 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 png, gif,
* jpg.
*
*
Example
*
*
* 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();
* }
*
*
*
*
*
* An image bundle that uses the Resource annotation to specify
* image names might look something like this:
*
*
* 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();
* }
*
*
*
*
*
* Here is how MyImageBundle might be used in an application:
*
*
* ...
*
* // 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());
*
* ...
*
*
*
*
* Security Warning: Image Bundle's use of the javax.image.imageio Classes
* 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.
*
*
* 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:
*
*
*
* http://sunsolve.sun.com/search/document.do?assetkey=1-26-102934-1
*
*
*
* Alternatively, if the images to be used in the bundle are trusted, then it is
* not necessary to upgrade the JVM.
*
*
* Caching Recommendations for Image Bundle Files
* 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.
*
*
* To make all image bundle files permanently cacheable, set up a rule in your
* web server to emit the Expires response header for any files
* ending with ".cache.*". Such a rule would automatically match
* generated image bundle filenames (e.g.
* 320ADF600D31858000C612E939F0AD1A.cache.png). The HTTP/1.1
* specification recommends specifying date of approximately one year in the
* future for the Expires header to indicate that the resource is
* permanently cacheable.
*
*
* Using Security Constraints to Protect Image Bundle Files
* 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 Pragma: No-cache,
* Cache-Control: None, and
* Expires: Thu, 1 Jan 1970 00:00:00 (or some other date in the
* past).
*
*
* This can lead to performance problems when using image bundles, because the
* large composite image will be re-requested unnecessarily. In addition,
* clear.cache.gif, 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.
*
*
* There are several ways to work around this issue:
*
*
* - Modify the servlet which serves
png and gif
* files so that it explicitly sets the Pragma,
* Cache-Control, and Expires headers. The
* Pragma and Cache-Control headers should be
* removed. The Expires header should be set according to the
* caching recommendations mentioned in the previous section.
* - If using Tomcat, use the
disableProxyCaching property in
* your web application configuration file to prevent the Pragma,
* Cache-Control, and Expires headers from being
* changed by the server. Refer to your web application server's documentation
* for more information.
* - Exclude the image bundle's composite image from the web application's
* security constraint.
* - 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.
*
*
* Image Bundles and the HTTPS Protocol
* There is an issue with displaying image bundle images in Internet Explorer
* when:
*
*
* - The image bundle's composite image is requested using the HTTPS
* protocol, and
* - The web application has a security constraint set for the composite
* image
*
*
* This issue is known to occur with the web application servers Tomcat and
* Glassfish.
*
*
* The native format for the composite image is png, and
* versions of Internet Explorer prior to 7 cannot render png
* transparerency. To get around this problem, we make use of a plugin built
* into the operating system.
*
*
*
* 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).
*
*
*
* When using the HTTP protocol, Internet Explorer will disregard the
* Pragma: No-cache and Cache-Control: None
* 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.
*
*
*
* To work around this issue, follow the recommendations outlined in the
* previous section.
*
*
* For More Information
* 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 ClassLoader.getResource().
*/
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Resource {
String value();
}
}