• cdi
  • components
  • contexts
  • converters
  • eventlisteners
  • exceptionhandlers
  • facesviews
  • filters
  • functions
  • managedbeans
  • push
  • renderkits
  • resourcehandlers
  • scripts
  • servlets
  • taghandlers
  • utils
  • validators
  • viewhandlers
-
  • cache
  • commandScript
  • componentIdParam
  • conditionalComment
  • deferredScript
  • form
  • graphicImage
  • highlight
  • messages
  • moveComponent
  • onloadScript
  • outputFormat
  • outputLabel
  • param
  • resolveComponent
  • resourceInclude
  • tree
  • viewAction
  • viewParam

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" /> <!-- JSF 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 JSF 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 @ApplicationScoped bean (both JSF and CDI scopes are supported). 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 JSF 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;
    }

}
@Named
@ApplicationScoped
public class ImageStreamer {

    @Inject
    private ImageService service;

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

}
<ui:repeat value="#{bean.images}" var="image">
    <o:graphicImage value="#{imageStreamer.getById(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 JSF 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="#{imageStreamer.getById(image.id)}" lastModified="#{image.lastModified}" />
</ui:repeat>

Image types

When rendered as data URI, the content type will be guessed based on content header. So far, 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="#{imageStreamer.getById(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="#{imageStreamer.getById(image.id)}" type="svg" fragment="svgView(viewBox(0,50,200,200))" />

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 JSF resources). And, the value attribute of <o:graphicImage> does not support URLs anymore. For that, just keep using <h:graphicImage> or even plain <img>.

Demo

The below one renders JSF resource as data URI

The below one renders InputStream property as resource

The below one renders InputStream property as data URI

The below one renders byte[] property taking a Long argument as resource in <ui:repeat> loop

The below one renders InputStream property with SVG content as resource

The below one renders byte[] property of uploaded file as data URI

Demo source code
<h3>The below one renders JSF resource as data URI</h3>
<p>
    <o:graphicImage library="layout" name="img/OmniFaces-logo-90x90-black.png" dataURI="true" />
</p>

<h3>The below one renders InputStream property as resource</h3>
<p>
    <o:graphicImage value="#{graphicImageBean.logo}" lastModified="#{startup.time}" />
</p>

<h3>The below one renders InputStream property as data URI</h3>
<p>
    <o:graphicImage value="#{graphicImageBean.logo}" dataURI="true" />
</p>

<h3>The below one renders byte[] property taking a Long argument as resource in <code>&lt;ui:repeat&gt;</code> loop</h3>
<p>
    <ui:repeat value="#{graphicImageBean.ids}" var="id">
        <o:graphicImage value="#{graphicImageBean.getContent(id)}" lastModified="#{startup.time}" />
    </ui:repeat>
</p>

<h3>The below one renders InputStream property with SVG content as resource</h3>
<p>
    <o:graphicImage value="#{graphicImageBean.svgLogo}" type="svg" lastModified="#{startup.time}" height="90" />
</p>

<h3>The below one renders byte[] property of uploaded file as data URI</h3>
<h:form enctype="multipart/form-data">
    <h:panelGrid columns="3">
        <o:outputLabel for="file" value="Image" />
        <h:inputFile id="file" value="#{uploadImageBean.file}" >
            <f:attribute name="maxSize" value="1048576" />
            <f:attribute name="matchType" value="^image/.*$" />
            <f:validator validatorId="uploadFileSizeValidator" />
            <f:validator validatorId="uploadFileTypeValidator" />
            <f:ajax listener="#{uploadImageBean.read()}" render="@form" />
        </h:inputFile>
        <h:message for="file" />
    </h:panelGrid>
    <o:graphicImage value="#{uploadImageBean.content}" dataURI="true" width="600" 
        rendered="#{not empty uploadImageBean.content}" />
</h:form>