- 

Available since OmniFaces 1.0

Collection of utility methods for the Faces API that are mainly shortcuts for obtaining stuff from the thread local FacesContext. In effects, it 'flattens' the hierarchy of nested objects. Do note that using the hierarchy is actually a better software design practice, but can lead to verbose code.

Next to those oneliner delegate calls, there are also some helpful methods which eliminates multiline boilerplate code, such as getLocale() which returns sane fallback values, a more convenient redirect(String, Object...) which automatically prepends the context path when the path does not start with / and offers support for URL encoding of request parameters supplied by varargs argument, and several useful sendFile(File, boolean) methods which allows you to provide a File, byte[] or InputStream as a download to the client.

Usage

Here are some examples:

// Get a session attribute (no explicit cast necessary!).
User user = Faces.getSessionAttribute("user");
// Evaluate EL programmatically (no explicit cast necessary!).
Item item = Faces.evaluateExpressionGet("#{item}");
// Get a cookie value.
String cookieValue = Faces.getRequestCookie("cookieName");
// Get all supported locales with default locale as first item.
List<Locale> supportedLocales = Faces.getSupportedLocales();
// Check in e.g. preRenderView if session has been timed out.
if (Faces.hasSessionTimedOut()) {
    Messages.addGlobalWarn("Oops, you have been logged out because your session was been timed out!");
}
// Get value of <f:metadata><f:attribute name="foo"> of different view without building it.
String foo = Faces.getMetadataAttribute("/other.xhtml", "foo");
// Send a redirect with parameters UTF-8 encoded in query string.
Faces.redirect("product.xhtml?id=%d&name=%s", product.getId(), product.getName());
// Invalidate the session and send a redirect.
public void logout() {
    Faces.invalidateSession();
    Faces.redirect("login.xhtml"); // Can by the way also be done by return "login?faces-redirect=true" if in action method.
}
// Provide a file as attachment.
public void download() {
    Faces.sendFile(new File("/path/to/file.ext"), true);
}
// Provide a file as attachment via output stream callback.
public void download() {
    Faces.sendFile("file.txt", true, output -> {
        try (PrintWriter writer = new PrintWriter(new OutputStreamWriter(output, StandardCharsets.UTF_8))) {
            writer.println("Hello world");
        }
    });
}

For a full list, check the method summary.

FacesLocal

Note that there's normally a minor overhead in obtaining the thread local FacesContext. In case client code needs to call methods in this class multiple times it's expected that performance will be slightly better if instead the FacesContext is obtained once and the required methods are called on that, although the difference is practically negligible when used in modern server hardware.

In such case, consider using FacesLocal instead. The difference with Faces is that no one method of FacesLocal obtains the FacesContext from the current thread by FacesContext.getCurrentInstance(). This job is up to the caller.

#{faces} in EL

Since OmniFaces 2.6, all methods of Faces utility class which start with "get" or "is", and take no parameters, and return either String or boolean, and are not related to response nor to session or flash (for which already implicit EL objects #{session} and #{flash} exist), will be available as properties of the implicit object #{faces}. Examples are:

#{faces.development}
#{faces.serverInfo}
#{faces.ajaxRequest}
#{faces.requestBaseURL}
#{faces.requestURLWithQueryString}

Feature request

If you know more useful methods/functions which you think should be added to this OmniFaces utility class so that everyone can benefit from a "standard" Faces utility library, feel free to post a feature request.