Module org.omnifaces
Package org.omnifaces.component.output

Class GraphicImage

java.lang.Object
jakarta.faces.component.UIComponent
jakarta.faces.component.UIComponentBase
jakarta.faces.component.UIGraphic
jakarta.faces.component.html.HtmlGraphicImage
org.omnifaces.component.output.GraphicImage
All Implemented Interfaces:
ClientBehaviorHolder, PartialStateHolder, StateHolder, TransientStateHolder, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder, EventListener
public class GraphicImage extends HtmlGraphicImage

The <o:graphicImage> is a component that extends the standard <h:graphicImage> with support for referencing an InputStream or byte[] property in the value attribute, optionally as a data URI.

Data URI

Set dataURI attribute to true in order to render image in data URI format. 

 <o:graphicImage name="icon.png" dataURI="true" /> <!-- Faces resource as data URI -->
 <o:graphicImage value="#{bean.icon}" dataURI="true" /> <!-- byte[]/InputStream property as data URI -->

This basically renders the image inline in HTML output immediately during Faces render response phase. This approach is very useful for a "preview" feature of uploaded images and works also in combination with view scoped beans. This approach is however not recommended for "permanent" and/or "large" images as it doesn't offer the browser any opportunity to cache the images for reuse, ~10KB would typically be the max even less so if there are more such images on the same page.

Image streaming

When not rendered as data URI, the InputStream or byte[] property must point to a stateless @GraphicImageBean or @Named @ApplicationScoped bean. The property will namely be evaluated at the moment the browser requests the image content based on the URL as specified in HTML <img src>, which is usually a different request than the one which rendered the Faces page. E.g. 

 @Named
 @RequestScoped
 public class Bean {

     private List<Image> images; // Image class should NOT have "content" property, or at least it be lazy loaded.

     @Inject
     private ImageService service;

     @PostConstruct
     public void init() {
         images = service.list();
     }

     public List<Image> getImages() {
         return images;
     }

 }
 
 @GraphicImageBean
 public class Images {

     @Inject
     private ImageService service;

     public byte[] get(Long id) {
         return service.getContent(id);
     }

 }
 
 <ui:repeat value="#{bean.images}" var="image">
     <o:graphicImage value="#{images.get(image.id)}" />
 </ui:repeat>

A @RequestScoped and @SessionScoped bean would theoretically work, but this is wrong design (a servlet is inherently also application scoped and stateless, not without reason). A @ViewScoped wouldn't work because the image request doesn't share the Faces view state.

In case the property is a method expression taking arguments, each of those arguments will be converted to a string HTTP request parameter and back to actual objects using the converters registered by class as available via Application.createConverter(Class). So, most of standard types like Long are already implicitly supported. In case you need to supply a custom object as argument for some reason, you need to explicitly register a converter for it yourself via @FacesConverter(forClass).

Caching

In case your "image" entity supports it, you can also supply the "last modified" property which will be used in the ETag and Last-Modified headers and in If-Modified-Since checks, hereby improving browser caching. The lastModified attribute supports both Date and Long as timestamp in milliseconds. 

 <ui:repeat value="#{bean.images}" var="image">
     <o:graphicImage value="#{images.get(image.id)}" lastModified="#{image.lastModified}" />
 </ui:repeat>

When unspecified, then the "default resource maximum age" as set in either the Mojarra specific context parameter com.sun.faces.defaultResourceMaxAge or MyFaces specific context parameter org.apache.myfaces.RESOURCE_MAX_TIME_EXPIRES will be used, else a default of 1 week will be assumed.

Image types

When rendered as data URI, the content type will be guessed based on content header. So far, WEBP, JPEG, PNG, GIF, ICO, SVG, BMP and TIFF are recognized. If the content header is unrecognized, or when the image is rendered as regular image source, then the content type will default to "image" without any subtype. This should work for most images in most browsers. This may however fail on newer images or in older browsers. In that case, you can explicitly specify the image type via the type attribute which must represent a valid file extension. E.g. 

 <o:graphicImage value="#{images.get(image.id)}" type="svg" />

The content type will be resolved via Faces.getMimeType(String). You can add unrecognized ones as <mime-mapping> in web.xml. E.g. 

 <mime-mapping>
     <extension>svg</extension>
     <mime-type>image/svg+xml</mime-type>
 </mime-mapping>

SVG view modes

When serving a SVG image, you can use fragment attribute to trigger SVG view modes (beware of browser support). E.g. 

 <o:graphicImage value="#{images.get(image.id)}" type="svg" fragment="svgView(viewBox(0,50,200,200))" />

Lazy loading

Since OmniFaces 3.10, you can set the lazy attribute to true to indicate that the referenced image should only be loaded when the window is finished loading and the image is visible in the viewport. 

 <o:graphicImage ... lazy="true" />

This attribute is ignored when the dataURI attribute is set to true.

Design notes

The bean class name and method name will end up in the image source URL. Although this is technically harmless and not tamperable by hackers, you might want to choose a "sensible" class and method name for this purpose.

Like <h:graphicImage>, the value attribute is ignored when the name attribute is specified (for Faces resources). And, the value attribute of <o:graphicImage> does not support URLs anymore. For that, just keep using <h:graphicImage> or even plain <img>.

Since:
2.0
Author:
Bauke Scholtz
See Also:

  • Field Details

    • COMPONENT_TYPE

      public static final String COMPONENT_TYPE
      The component type, which is "org.omnifaces.component.output.GraphicImage".
      See Also:

    • ATTRIBUTE_NAMES

      protected static final Map<String,String> ATTRIBUTE_NAMES
      Attribute names inherited from superclass.

  • Constructor Details

    • GraphicImage

      public GraphicImage()
      Constructs the GraphicImage component.

  • Method Details

    • encodeBegin

      public void encodeBegin(FacesContext context) throws IOException
      Overrides:
      encodeBegin in class UIComponentBase
      Throws:
      IOException

    • encodeEnd

      public void encodeEnd(FacesContext context) throws IOException
      Overrides:
      encodeEnd in class UIComponentBase
      Throws:
      IOException

    • getSrc

      protected String getSrc(FacesContext context) throws IOException
      Returns the URL needed for the 'src' attribute.
      Parameters:
      context - The involved faces context.
      Returns:
      The URL needed for the 'src' attribute.
      Throws:
      IOException - When something fails at I/O level.

    • getAlt

      public String getAlt()
      Returns an empty string as default value instead of null, so that the attribute is always rendered, as mandated by HTML5.
      Overrides:
      getAlt in class HtmlGraphicImage

    • isDataURI

      public boolean isDataURI()
      Returns whether or not to render image in data URI format.
      Returns:
      Whether or not to render image in data URI format.
      Since:
      3.10

    • setDataURI

      public void setDataURI(boolean dataURI)
      Sets whether or not to render image in data URI format.
      Parameters:
      dataURI - Whether or not to render image in data URI format.
      Since:
      3.10.1

    • isLazy

      public boolean isLazy()
      Returns whether or not to lazily load image.
      Returns:
      Whether or not to lazily load image.
      Since:
      3.10

    • setLazy

      public void setLazy(boolean lazy)
      Sets whether or not to lazily load image.
      Parameters:
      lazy - Whether or not to lazily load image.
      Since:
      3.10