All Downloads are FREE. Search and download functionalities are using the official Maven repository.

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: * *
    *
  1. 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.
  2. *
  3. 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.
  4. *
  5. Exclude the image bundle's composite image from the web application's * security constraint.
  6. *
  7. 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.
  8. *
* *

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




© 2015 - 2024 Weber Informatics LLC | Privacy Policy