Module org.omnifaces
Package org.omnifaces.util

Class Faces

java.lang.Object
org.omnifaces.util.Faces
public final class Faces extends Object

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}
Author:
Arjan Tijms, Bauke Scholtz
See Also:

  • Method Details

    • getContext

      public static FacesContext getContext()
      Returns the current faces context.

      Note that whenever you absolutely need this method to perform a general task, you might want to consider to submit a feature request to OmniFaces in order to add a new utility method which performs exactly this general task.

      Returns:
      The current faces context.
      See Also:

    • getContext

      public static FacesContext getContext(ELContext elContext)
      Returns the faces context that's stored in an ELContext.

      Note that this only works for an ELContext that is created in the context of Faces.

      Parameters:
      elContext - the EL context to obtain the faces context from.
      Returns:
      the faces context that's stored in the given ELContext.
      Since:
      1.2

    • setContext

      public static void setContext(FacesContext context)
      Sets the given faces context as current instance. Use this if you have a custom FacesContextWrapper which you'd like to (temporarily) use as the current instance of the faces context.
      Parameters:
      context - The faces context to be set as the current instance.
      Since:
      1.3

    • hasContext

      public static boolean hasContext()
      Returns true when the current faces context is available (i.e. it is not null).
      Returns:
      true when the current faces context is available.
      Since:
      2.0

    • getExternalContext

      public static ExternalContext getExternalContext()
      Returns the current external context.

      Note that whenever you absolutely need this method to perform a general task, you might want to consider to submit a feature request to OmniFaces in order to add a new utility method which performs exactly this general task.

      Returns:
      The current external context.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getApplication

      public static Application getApplication()
      Returns the application singleton.

      Note that whenever you absolutely need this method to perform a general task, you might want to consider to submit a feature request to OmniFaces in order to add a new utility method which performs exactly this general task.

      Returns:
      The faces application singleton.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getApplicationFromFactory

      public static Application getApplicationFromFactory()
      Gets the Faces Application singleton from the FactoryFinder.

      This method is an alternative for getApplication() for those situations where the FacesContext isn't available.

      Returns:
      The faces application singleton.

    • getPackage

      public static Package getPackage()
      Returns the package of the currently loaded Faces implementation.

      This is also available in EL as #{faces['package']}.

      Returns:
      The package of the currently loaded Faces implementation.
      Since:
      3.14

    • getImplInfo

      public static String getImplInfo()
      Returns the implementation information of currently loaded Faces implementation. E.g. "Mojarra 2.1.7-FCS".

      This is also available in EL as #{faces.implInfo}.

      Returns:
      The implementation information of currently loaded Faces implementation.
      See Also:

    • getServerInfo

      public static String getServerInfo()
      Returns the server information of currently running application server implementation.

      This is also available in EL as #{faces.serverInfo}.

      Returns:
      The server information of currently running application server implementation.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getProjectStage

      public static ProjectStage getProjectStage()
      Returns the project stage. This will return the jakarta.faces.PROJECT_STAGE context parameter in web.xml.
      Returns:
      The project stage.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      2.6
      See Also:

    • isDevelopment

      public static boolean isDevelopment()
      Returns whether we're in development stage. This will be the case when the jakarta.faces.PROJECT_STAGE context parameter in web.xml is set to Development.

      This is also available in EL as #{faces.development}.

      Returns:
      true if we're in development stage, otherwise false.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • isSystemTest

      public static boolean isSystemTest()
      Returns whether we're in system test stage. This will be the case when the jakarta.faces.PROJECT_STAGE context parameter in web.xml is set to SystemTest.

      This is also available in EL as #{faces.systemTest}.

      Returns:
      true if we're in system test stage, otherwise false.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      2.6
      See Also:

    • isProduction

      public static boolean isProduction()
      Returns whether we're in production stage. This will be the case when the jakarta.faces.PROJECT_STAGE context parameter in web.xml is set to Production.

      This is also available in EL as #{faces.production}.

      Returns:
      true if we're in production stage, otherwise false.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      2.6
      See Also:

    • getMapping

      public static String getMapping()
      Determines and returns the faces servlet mapping used in the current request. If Faces is prefix mapped (e.g. /faces/*), then this returns the whole path, with a leading slash (e.g. /faces). If Faces is suffix mapped (e.g. *.xhtml), then this returns the whole extension (e.g. .xhtml). If there is no extension, then this falls back to ViewHandler.DEFAULT_SUFFIX_PARAM_NAME.

      This is also available in EL as #{faces.mapping}.

      Returns:
      The faces servlet mapping (without the wildcard).
      Throws:
      NullPointerException - When faces context is unavailable.
      IllegalStateException - When mapping could not be determined.
      See Also:

    • isPrefixMapping

      public static boolean isPrefixMapping()
      Returns whether the faces servlet mapping used in the current request is a prefix mapping.

      This is also available in EL as #{faces.prefixMapping}.

      Returns:
      true if the faces servlet mapping used in the current request is a prefix mapping, otherwise false.
      See Also:

    • isPrefixMapping

      public static boolean isPrefixMapping(String mapping)
      Returns whether the given faces servlet mapping is a prefix mapping. Use this method in preference to isPrefixMapping() when you already have obtained the mapping from getMapping() so that the mapping won't be calculated twice.
      Parameters:
      mapping - The mapping to be tested.
      Returns:
      true if the faces servlet mapping used in the current request is a prefix mapping, otherwise false.
      Throws:
      NullPointerException - When mapping is null.

    • getCurrentPhaseId

      public static PhaseId getCurrentPhaseId()
      Returns the current phase ID.
      Returns:
      The current phase ID.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • validationFailed

      public static void validationFailed()
      Signals Faces that the validations phase of the current request has failed. This can be invoked in any other phase than the validations phase. The value can be read by isValidationFailed() in Java and by #{facesContext.validationFailed} in EL.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • isValidationFailed

      public static boolean isValidationFailed()
      Returns whether the validations phase of the current request has failed.

      This is also available in EL as #{faces.validationFailed}.

      Returns:
      true if the validations phase of the current request has failed, otherwise false.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getELContext

      public static ELContext getELContext()
      Returns the current EL context.
      Returns:
      The current EL context.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      2.0
      See Also:

    • evaluateExpressionGet

      public static <T> T evaluateExpressionGet(String expression)
      Programmatically evaluate the given EL expression and return the evaluated value.
      Type Parameters:
      T - The expected return type.
      Parameters:
      expression - The EL expression to be evaluated.
      Returns:
      The evaluated value of the given EL expression.
      Throws:
      NullPointerException - When faces context is unavailable.
      ClassCastException - When T is of wrong type.
      See Also:

    • evaluateExpressionSet

      public static void evaluateExpressionSet(String expression, Object value)
      Programmatically evaluate the given EL expression and set the given value.
      Parameters:
      expression - The EL expression to be evaluated.
      value - The value to be set in the property behind the given EL expression.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.1
      See Also:

    • resolveExpressionGet

      public static <T> T resolveExpressionGet(Object base, String property)
      Programmatically EL-resolve the given property on the given base object and return the resolved value.
      Type Parameters:
      T - The expected return type.
      Parameters:
      base - The base object whose property value is to be returned, or null to resolve a top-level variable.
      property - The property or variable to be resolved on the given base.
      Returns:
      The resolved value of the given property on the given base object.
      Throws:
      NullPointerException - When faces context is unavailable.
      ClassCastException - When T is of wrong type.
      Since:
      2.1
      See Also:

    • resolveExpressionSet

      public static void resolveExpressionSet(Object base, String property, Object value)
      Programmatically EL-resolve the given property on the given base object and set the given value.
      Parameters:
      base - The base object whose property value is to be set, or null to set a top-level variable.
      property - The property or variable to be set on the given base.
      value - The value to be set in the property on the given base.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      2.1
      See Also:

    • getContextAttribute

      public static <T> T getContextAttribute(String name)
      Returns the Faces context attribute value associated with the given name.
      Type Parameters:
      T - The expected return type.
      Parameters:
      name - The Faces context attribute name.
      Returns:
      The Faces context attribute value associated with the given name.
      Throws:
      NullPointerException - When faces context is unavailable.
      ClassCastException - When T is of wrong type.
      Since:
      1.3
      See Also:

    • getContextAttribute

      public static <T> T getContextAttribute(String name, Supplier<T> computeIfAbsent)
      Returns the Faces context attribute value associated with the given name, or computes the supplied value if absent.
      Type Parameters:
      T - The expected return type.
      Parameters:
      name - The Faces context attribute name.
      computeIfAbsent - The computed Faces context attribute value when absent. Useful if it represents a collection, map or bean.
      Returns:
      The Faces context attribute value associated with the given name.
      Throws:
      NullPointerException - When faces context is unavailable.
      ClassCastException - When T is of wrong type.
      Since:
      3.1
      See Also:

    • setContextAttribute

      public static void setContextAttribute(String name, Object value)
      Sets the Faces context attribute value associated with the given name.
      Parameters:
      name - The Faces context attribute name.
      value - The Faces context attribute value.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.3
      See Also:

    • createConverter

      public static <T> Converter<T> createConverter(Object identifier)
      Creates and returns a Faces converter associated with given object identifier. If the given identifier is an instance of string, then delegate to createConverter(String). If the given identifier is an instance of class, then delegate to createConverter(Class). If the given identifier is a concrete converter instance, then return it directly. If no converter instance can be associated, then return null.
      Type Parameters:
      T - The expected converter type.
      Parameters:
      identifier - The Faces converter object identifier. This can be a string representing the converter ID, or a class representing the target type, or a class representing the converter class, or even the converter instance itself.
      Returns:
      A Faces converter associated with given object identifier.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      2.5

    • createConverter

      public static <T> Converter<T> createConverter(String identifier)
      Creates and returns a Faces converter associated with given string identifier. First use the identifier as converter ID in Application.createConverter(String). If that didn't return anything, then try to interpret the string identifier as class name and delegate to createConverter(Class). If no converter instance can be associated, then return null.
      Type Parameters:
      T - The expected converter type.
      Parameters:
      identifier - The Faces converter string identifier.
      Returns:
      A Faces converter associated with given string identifier.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      2.5

    • createConverter

      public static <T> Converter<T> createConverter(Class<?> identifier)
      Creates and returns a Faces converter associated with given class identifier. If the given identifier is not assignable to Converter.class, then use that as target type in Application.createConverter(Class). If the given identifier is assignable to Converter.class, and the FacesConverter annotation is present, then instantiate it using CDI, else instantiate it using default constructor. If no converter instance can be associated, then return null.
      Type Parameters:
      T - The expected converter type.
      Parameters:
      identifier - The Faces converter class identifier.
      Returns:
      A Faces converter associated with given class identifier.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      2.5

    • createValidator

      public static <T> Validator<T> createValidator(Object identifier)
      Creates and returns a Faces validator associated with given object identifier. If the given identifier is an instance of string, then delegate to createValidator(String). If the given identifier is an instance of class, then delegate to createValidator(Class). If the given identifier is a concrete validator instance, then return it directly. If no validator instance can be associated, then return null.
      Type Parameters:
      T - The expected validator type.
      Parameters:
      identifier - The Faces validator object identifier. This can be a string representing the validator ID, or a class representing the validator class, or even the validator instance itself.
      Returns:
      A Faces validator associated with given object identifier.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      2.5

    • createValidator

      public static <T> Validator<T> createValidator(String identifier)
      Creates and returns a Faces validator associated with given string identifier. First use the identifier as validator ID in Application.createValidator(String). If that didn't return anything, then try to interpret the string identifier as class name and delegate to createValidator(Class). If no validator instance can be associated, then return null.
      Type Parameters:
      T - The expected validator type.
      Parameters:
      identifier - The Faces validator string identifier.
      Returns:
      A Faces validator associated with given string identifier.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      2.5

    • createValidator

      public static <T> Validator<T> createValidator(Class<?> identifier)
      Creates and returns a Faces validator associated with given class identifier. If the given identifier is assignable to Validator.class, and the FacesValidator annotation is present, then instantiate it using CDI, else instantiate it using default constructor. If no validator instance can be associated, then return null.
      Type Parameters:
      T - The expected validator type.
      Parameters:
      identifier - The Faces validator class identifier.
      Returns:
      A Faces validator associated with given class identifier.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      2.5

    • createResource

      public static Resource createResource(String resourceName)
      Creates and returns a Faces resource associated with given resource name. If no resource can be allocated, then return null.
      Parameters:
      resourceName - The resource name.
      Returns:
      A Faces resource associated with given resource name.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      3.6
      See Also:

    • createResource

      public static Resource createResource(String libraryName, String resourceName)
      Creates and returns a Faces resource associated with given library name and resource name. If no resource can be allocated, then return null.
      Parameters:
      libraryName - The library name.
      resourceName - The resource name.
      Returns:
      A Faces resource associated with given library name and resource name.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      3.6
      See Also:

    • createResource

      public static Resource createResource(ResourceIdentifier resourceIdentifier)
      Creates and returns a Faces resource associated with given resource identifier. If no resource can be allocated, then return null.
      Parameters:
      resourceIdentifier - The resource identifier.
      Returns:
      A Faces resource associated with given resource identifier.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      3.6
      See Also:

    • createResource

      public static Resource createResource(UIComponent component)
      Creates and returns a Faces resource associated with given resource component. If no resource can be allocated, then return null.
      Parameters:
      component - The resource component.
      Returns:
      A Faces resource associated with given resource component.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      5.0
      See Also:

    • getLifecycle

      public static Lifecycle getLifecycle()
      Returns The Lifecycle associated with current Faces application.
      Returns:
      The Lifecycle associated with current Faces application.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      2.5
      See Also:

    • getViewRoot

      public static UIViewRoot getViewRoot()
      Returns the current view root.
      Returns:
      The current view root.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • setViewRoot

      public static void setViewRoot(String viewId)
      Sets the current view root to the given view ID. The view ID must start with a leading slash. If an invalid view ID is given, then the response will simply result in a 404.
      Parameters:
      viewId - The ID of the view which needs to be set as the current view root.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.1
      See Also:

    • getViewId

      public static String getViewId()
      Returns the ID of the current view root, or null if there is no view.

      This is also available in EL as #{faces.viewId}, although #{view.viewId} could be used.

      Returns:
      The ID of the current view root, or null if there is no view.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getViewIdWithParameters

      public static String getViewIdWithParameters()
      Returns the ID of the current view root with view and hash parameters.

      This is also available in EL as #{faces.viewIdWithParameters}.

      Returns:
      The ID of the current view root with view and hash parameters.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      2.5
      See Also:

    • getViewName

      public static String getViewName()
      Returns the base name of the current view, without extension, or null if there is no view. E.g. if the view ID is /path/to/some.xhtml, then this will return some.

      This is also available in EL as #{faces.viewName}.

      Returns:
      The base name of the current view, without extension, or null if there is no view.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      2.3
      See Also:

    • getViewDeclarationLanguage

      public static ViewDeclarationLanguage getViewDeclarationLanguage()
      Returns the ViewDeclarationLanguage associated with the "current" view ID.

      The current view ID is the view ID that's set for the view root that's associated with the current faces context.

      Returns:
      The ViewDeclarationLanguage associated with the "current" view ID.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.8

    • getRenderKit

      public static RenderKit getRenderKit()
      Returns the RenderKit associated with the "current" view ID or view handler.

      The current view ID is the view ID that's set for the view root that's associated with the current faces context. Or if there is none, then the current view handler will be assumed, which is the view handler that's associated with the requested view.

      Returns:
      The RenderKit associated with the "current" view ID or view handler.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      2.2
      See Also:

    • normalizeViewId

      public static String normalizeViewId(String path)
      Normalize the given path as a valid view ID based on the current mapping, if necessary.
      • If the current mapping is a prefix mapping and the given path starts with it, then remove it.
      • If the current mapping is a suffix mapping and the given path ends with it, then replace it with the default Facelets suffix.
      Parameters:
      path - The path to be normalized as a valid view ID based on the current mapping.
      Returns:
      The path as a valid view ID.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getViewParameters

      public static Collection<UIViewParameter> getViewParameters()
      Returns the view parameters of the current view, or an empty collection if there is no view.
      Returns:
      The view parameters of the current view, or an empty collection if there is no view.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getViewParameterMap

      public static Map<String,List<String>> getViewParameterMap()
      Returns the view parameters of the current view as a parameter map, or an empty map if there is no view. This is ready for usage in among others ViewHandler.getBookmarkableURL(FacesContext, String, Map, boolean).
      Returns:
      The view parameters of the current view as a parameter map, or an empty map if there is no view.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getHashParameters

      public static Collection<HashParam> getHashParameters()
      Returns the hash parameters of the current view, or an empty collection if there is no view.
      Returns:
      The hash parameters of the current view, or an empty collection if there is no view.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      3.2
      See Also:

    • getHashParameterMap

      public static Map<String,List<String>> getHashParameterMap()
      Returns the hash parameters of the current view as a parameter map, or an empty map if there is no view.
      Returns:
      The hash parameters of the current view as a parameter map, or an empty map if there is no view.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      3.2
      See Also:

    • getHashQueryString

      public static String getHashQueryString()
      Returns the hash query string of the current view, or null if there is none. This is the part after the # in the request URL as the enduser sees in browser address bar. This works only if the hash parameters are via <o:hashParam> registered in the view.
      Returns:
      The hash query string of the current view, or null if there is none.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      3.2
      See Also:

    • getScriptParameters

      public static Collection<ScriptParam> getScriptParameters()
      Returns the script parameters of the current view, or an empty collection if there is no view.
      Returns:
      The script parameters of the current view, or an empty collection if there is no view.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      3.6
      See Also:

    • getMetadataAttributes

      public static Map<String,Object> getMetadataAttributes(String viewId)
      Returns the metadata attribute map of the given view ID, or an empty map if there is no view metadata.
      Parameters:
      viewId - The view ID to return the metadata attribute map for.
      Returns:
      The metadata attribute map of the given view ID, or an empty map if there is no view metadata.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.4
      See Also:

    • getMetadataAttributes

      public static Map<String,Object> getMetadataAttributes()
      Returns the metadata attribute map of the current view, or an empty map if there is no view metadata.
      Returns:
      The metadata attribute map of the current view, or an empty map if there is no view metadata.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      2.0
      See Also:

    • getMetadataAttribute

      public static <T> T getMetadataAttribute(String viewId, String name)
      Returns the metadata attribute of the given view ID associated with the given name. Note: this is not the same as the view scope, for that use getViewAttribute(String).
      Type Parameters:
      T - The expected return type.
      Parameters:
      viewId - The view ID to return the metadata attribute for.
      name - The metadata attribute name.
      Returns:
      The metadata attribute of the given view ID associated with the given name.
      Throws:
      NullPointerException - When faces context is unavailable.
      ClassCastException - When T is of wrong type.
      Since:
      1.4
      See Also:

    • getMetadataAttribute

      public static <T> T getMetadataAttribute(String name)
      Returns the metadata attribute of the current view associated with the given name. Note: this is not the same as the view scope, for that use getViewAttribute(String).
      Type Parameters:
      T - The expected return type.
      Parameters:
      name - The metadata attribute name.
      Returns:
      The metadata attribute of the current view associated with the given name.
      Throws:
      NullPointerException - When faces context is unavailable.
      ClassCastException - When T is of wrong type.
      Since:
      1.4
      See Also:

    • getLocale

      public static Locale getLocale()
      Returns the current locale. If the locale set in the Faces view root is not null, then return it. Else if the client preferred locale is not null and is among supported locales, then return it. Else if the Faces default locale is not null, then return it. Else return the system default locale.
      Returns:
      The current locale.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getDefaultLocale

      public static Locale getDefaultLocale()
      Returns the default locale, or null if there is none.
      Returns:
      The default locale, or null if there is none.
      See Also:

    • getSupportedLocales

      public static List<Locale> getSupportedLocales()
      Returns an unordered list of all supported locales on this application, with the default locale as the first item, if any. This will return an empty list if there are no locales definied in faces-config.xml.
      Returns:
      An unordered list of all supported locales on this application, with the default locale as the first item, if any. If you need an ordered list, use FacesConfigXml.getSupportedLocales() instead.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • setLocale

      public static void setLocale(Locale locale)
      Set the locale of the current view, which is to be used in localizing of the response.
      Parameters:
      locale - The locale of the current view.
      Throws:
      NullPointerException - When faces context is unavailable.
      IllegalStateException - When there is no view (i.e. when it is null). This can happen if the method is called at the wrong moment in the Faces lifecycle, e.g. before the view has been restored/created.
      Since:
      1.2
      See Also:

    • getMessageBundle

      public static ResourceBundle getMessageBundle()
      Returns the application message bundle as identified by <message-bundle> in faces-config.xml. The instance is already localized via getLocale(). If there is no <message-bundle>, then this method just returns null.
      Returns:
      The message bundle as identified by <message-bundle> in faces-config.xml.
      Throws:
      NullPointerException - When faces context is unavailable.
      MissingResourceException - When the <message-bundle> in faces-config.xml does not refer an existing resource in the classpath.
      Since:
      2.0
      See Also:

    • getResourceBundle

      public static ResourceBundle getResourceBundle(String varName)
      Returns the application resource bundle as identified by the given <var> of the <resource-bundle> in faces-config.xml. If there is no <resource-bundle> with the given <var>, then this method just returns null.
      Parameters:
      varName - The value of the <var> which identifies the <resource-bundle> in faces-config.xml.
      Returns:
      The application resource bundle as identified by the given <var> of the <resource-bundle> in faces-config.xml.
      Throws:
      NullPointerException - When faces context is unavailable.
      MissingResourceException - When the <resource-bundle> as identified by the given <var> in faces-config.xml does not refer an existing resource in the classpath.
      Since:
      2.0
      See Also:

    • getResourceBundles

      public static Map<String,ResourceBundle> getResourceBundles()
      Returns all application resource bundles registered as <resource-bundle> in faces-config.xml. If there are no resource bundles registered, then this method just returns an empty map.
      Returns:
      all application resource bundles registered as <resource-bundle> in faces-config.xml. <base-name> of the <resource-bundle> in faces-config.xml.
      Throws:
      NullPointerException - When faces context is unavailable.
      MissingResourceException - When the <resource-bundle> in faces-config.xml does not refer an existing resource in the classpath.
      Since:
      2.1
      See Also:

    • getBundleString

      public static String getBundleString(String key, Object... params)
      Gets a string for the given key searching declared resource bundles, order by declaration in faces-config.xml. If the string is missing, then this method returns ???key???.
      Parameters:
      key - The bundle key.
      params - Since 4.6.2 The MessageFormat parameters, if any.
      Returns:
      a string for the given key searching declared resource bundles, order by declaration in faces-config.xml.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      2.1

    • getBookmarkableURL

      public static String getBookmarkableURL(Map<String,List<String>> params, boolean includeViewParams)
      Returns the concrete domain-relative URL to the current view with the given params URL-encoded in the query string and optionally include view parameters as well. This URL can ultimately be used as redirect URL, or in <form action>, or in <a href>. Any parameter with an empty name or value will be skipped. To skip empty view parameters as well, use <o:viewParam> instead.
      Parameters:
      params - The parameters to be URL-encoded in the query string. Can be null.
      includeViewParams - Whether the view parameters of the current view should be included as well.
      Returns:
      The concrete domain-relative URL to the current view.
      Throws:
      NullPointerException - When faces context is unavailable.
      IllegalStateException - When there is no view (i.e. when it is null). This can happen if the method is called at the wrong moment in the Faces lifecycle, e.g. before the view has been restored/created.
      Since:
      1.6
      See Also:

    • getBookmarkableURL

      public static String getBookmarkableURL(String viewId, Map<String,List<String>> params, boolean includeViewParams)
      Returns the concrete domain-relative URL to the given view with the given params URL-encoded in the query string and optionally include view parameters as well. This URL can ultimately be used as redirect URL, or in <form action>, or in <a href>. Any parameter with an empty name or value will be skipped. To skip empty view parameters as well, use <o:viewParam> instead.
      Parameters:
      viewId - The view ID to create the bookmarkable URL for.
      params - The parameters to be URL-encoded in the query string. Can be null.
      includeViewParams - Whether the view parameters of the current view which are also declared in the target view should be included as well. Note thus that this does not include the view parameters which are not declared in the target view!
      Returns:
      The concrete domain-relative URL to the target view.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.6
      See Also:

    • getBookmarkableURL

      public static String getBookmarkableURL(Collection<? extends ParamHolder<?>> params, boolean includeViewParams)
      Returns the concrete domain-relative URL to the current view with the given params URL-encoded in the query string and optionally include view parameters as well. This URL can ultimately be used as redirect URL, or in <form action>, or in <a href>. Any parameter with an empty name or value will be skipped. To skip empty view parameters as well, use <o:viewParam> instead.
      Parameters:
      params - The parameters to be URL-encoded in the query string. Can be null.
      includeViewParams - Whether the view parameters of the current view should be included as well.
      Returns:
      The concrete domain-relative URL to the current view.
      Throws:
      NullPointerException - When faces context is unavailable.
      IllegalStateException - When there is no view (i.e. when it is null). This can happen if the method is called at the wrong moment in the Faces lifecycle, e.g. before the view has been restored/created.
      Since:
      1.7
      See Also:

    • getBookmarkableURL

      public static String getBookmarkableURL(String viewId, Collection<? extends ParamHolder<?>> params, boolean includeViewParams)
      Returns the concrete domain-relative URL to the given view with the given params URL-encoded in the query string and optionally include view parameters as well. This URL can ultimately be used as redirect URL, or in <form action>, or in <a href>. Any parameter with an empty name or value will be skipped. To skip empty view parameters as well, use <o:viewParam> instead.
      Parameters:
      viewId - The view ID to create the bookmarkable URL for.
      params - The parameters to be URL-encoded in the query string. Can be null.
      includeViewParams - Whether the view parameters of the current view which are also declared in the target view should be included as well. Note thus that this does not include the view parameters which are not declared in the target view!
      Returns:
      The concrete domain-relative URL to the target view.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.7
      See Also:

    • isOutputHtml5Doctype

      public static boolean isOutputHtml5Doctype()
      Returns whether the output of the current view is using HTML5 doctype.
      Returns:
      Whether the output of the current view is using HTML5 doctype.
      Since:
      5.0
      See Also:

    • getFaceletContext

      public static FaceletContext getFaceletContext()
      Returns the Facelet context.

      Note that whenever you absolutely need this method to perform a general task, you might want to consider to submit a feature request to OmniFaces in order to add a new utility method which performs exactly this general task.

      Returns:
      The Facelet context.
      Throws:
      NullPointerException - When faces context is unavailable.
      IllegalStateException - When the Facelet context is not available.
      Since:
      1.1
      See Also:

    • getFaceletAttribute

      public static <T> T getFaceletAttribute(String name)
      Returns the Facelet attribute value associated with the given name. This basically returns the value of the <ui:param> which is been declared inside the Facelet file, or is been passed into the Facelet file by e.g. an <ui:include>.
      Type Parameters:
      T - The expected return type.
      Parameters:
      name - The Facelet attribute name.
      Returns:
      The Facelet attribute value associated with the given name.
      Throws:
      NullPointerException - When faces context is unavailable.
      IllegalStateException - When the Facelet context is not available.
      ClassCastException - When T is of wrong type.
      Since:
      1.1
      See Also:

    • setFaceletAttribute

      public static void setFaceletAttribute(String name, Object value)
      Sets the Facelet attribute value associated with the given name. This basically does the same as an <ui:param> which is been declared inside the Facelet file, or is been passed into the Facelet file by e.g. an <ui:include>.
      Parameters:
      name - The Facelet attribute name.
      value - The Facelet attribute value.
      Throws:
      NullPointerException - When faces context is unavailable.
      IllegalStateException - When the Facelet context is not available.
      Since:
      1.1
      See Also:

    • getRequest

      public static HttpServletRequest getRequest()
      Returns the HTTP servlet request.

      Note that whenever you absolutely need this method to perform a general task, you might want to consider to submit a feature request to OmniFaces in order to add a new utility method which performs exactly this general task.

      Returns:
      The HTTP servlet request.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • isAjaxRequest

      public static boolean isAjaxRequest()
      Returns whether the current request is an ajax request.

      This is also available in EL as #{faces.ajaxRequest}.

      Returns:
      true for an ajax request, false for a non-ajax (synchronous) request.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • isAjaxRequestWithPartialRendering

      public static boolean isAjaxRequestWithPartialRendering()
      Returns whether the current request is an ajax request with partial rendering. That is, when it's an ajax request without render="@all".

      This is also available in EL as #{faces.ajaxRequestWithPartialRendering}.

      Returns:
      true for an ajax request with partial rendering, false an ajax request with render="@all" or a non-ajax (synchronous) request.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      2.3
      See Also:

    • isPostback

      public static boolean isPostback()
      Returns whether the current request is a postback. This not only delegates to FacesContext.isPostback() which checks the presence of jakarta.faces.ViewState request parameter, but this also explicitly checks the HTTP request method. So this should exclude GET requests having a jakarta.faces.ViewState request parameter in query string.

      This is also available in EL as #{faces.postback}.

      Returns:
      true for a postback, false for a non-postback (GET) request.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getRequestParameterMap

      public static Map<String,String> getRequestParameterMap()
      Returns the HTTP request parameter map.
      Returns:
      The HTTP request parameter map.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getMutableRequestParameterMap

      public static Map<String,List<String>> getMutableRequestParameterMap()
      Returns the mutable request parameter map. This requires installation of MutableRequestFilter.
      Returns:
      The mutable request parameter map.
      Throws:
      IllegalStateException - When the MutableRequestFilter is not installed or not invoked yet.
      Since:
      3.14
      See Also:

    • getRequestParameter

      public static String getRequestParameter(String name)
      Returns the HTTP request parameter value associated with the given name.
      Parameters:
      name - The HTTP request parameter name.
      Returns:
      The HTTP request parameter value associated with the given name.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getRequestParameter

      public static <T> T getRequestParameter(String name, Class<T> type)
      Returns the HTTP request parameter value associated with the given name and implicitly converted to given type using the Faces converter registered by forClass on the given type. Note that empty strings are already implicitly converted to null.
      Type Parameters:
      T - The expected return type.
      Parameters:
      name - The HTTP request parameter name.
      type - The converter forClass type.
      Returns:
      The HTTP request parameter value associated with the given name and implicitly converted to given type.
      Throws:
      NullPointerException - When faces context is unavailable.
      ConverterException - When conversion fails.
      ClassCastException - When T is of wrong type.
      Since:
      2.6
      See Also:

    • getRequestParameter

      public static <T> T getRequestParameter(String name, Function<String,T> converter)
      Returns the HTTP request parameter value associated with the given name and converted using the given converter. Note that empty strings are already implicitly converted to null.
      Type Parameters:
      T - The expected return type.
      Parameters:
      name - The HTTP request parameter name.
      converter - The converter.
      Returns:
      The HTTP request parameter value associated with the given name and converted using the given converter.
      Throws:
      NullPointerException - When faces context is unavailable or given converter is null.
      ClassCastException - When T is of wrong type.
      Since:
      3.10
      See Also:

    • getRequestParameter

      public static <T> T getRequestParameter(String name, Function<String,T> converter, Supplier<T> defaultValue)
      Returns the HTTP request parameter value associated with the given name and convert it using the given converter, or else the supplied value if absent. Note that empty strings are already implicitly converted to null.
      Type Parameters:
      T - The expected return type.
      Parameters:
      name - The HTTP request parameter name.
      converter - The converter.
      defaultValue - The default request parameter value when absent.
      Returns:
      The HTTP request parameter value associated with the given name and convert it using the given converter, or else the supplied value if absent.
      Throws:
      ClassCastException - When T is of wrong type.
      NullPointerException - When faces context is unavailable or given converter or supplier is null.
      Since:
      3.10
      See Also:

    • getRequestParameterValuesMap

      public static Map<String,String[]> getRequestParameterValuesMap()
      Returns the HTTP request parameter values map.
      Returns:
      The HTTP request parameter values map.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getRequestParameterValues

      public static String[] getRequestParameterValues(String name)
      Returns the HTTP request parameter values associated with the given name.
      Parameters:
      name - The HTTP request parameter name.
      Returns:
      The HTTP request parameter values associated with the given name.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getRequestParameterValues

      public static <T> T[] getRequestParameterValues(String name, Class<T> type)
      Returns the HTTP request parameter values associated with the given name and implicitly convert it to given type using the Faces converter registered by forClass on the given type.
      Type Parameters:
      T - The expected return type.
      Parameters:
      name - The HTTP request parameter name.
      type - The converter forClass type.
      Returns:
      The HTTP request parameter values associated with the given name and implicitly convert it to given type.
      Throws:
      NullPointerException - When faces context is unavailable.
      ConverterException - When conversion fails.
      ClassCastException - When T is of wrong type.
      Since:
      2.6
      See Also:

    • getRequestParts

      public static Collection<Part> getRequestParts()
      Returns all HTTP request parts, provided that request is of type multipart/form-data. If there are no parts, an empty collection is returned.
      Returns:
      all HTTP request parts.
      Throws:
      NullPointerException - When faces context is unavailable.
      FacesException - Whenever something fails at servlet or I/O level. The caller should preferably not catch it, but just let it go. The servletcontainer will handle it.
      Since:
      2.5
      See Also:

    • getRequestPart

      public static Part getRequestPart(String name)
      Returns the HTTP request part associated with the given name, else return null.
      Parameters:
      name - The HTTP request part name.
      Returns:
      The HTTP request part associated with the given name.
      Throws:
      NullPointerException - When faces context is unavailable.
      FacesException - Whenever something fails at servlet or I/O level. The caller should preferably not catch it, but just let it go. The servletcontainer will handle it.
      Since:
      2.5
      See Also:

    • getRequestParts

      public static Collection<Part> getRequestParts(String name)
      Returns all HTTP request parts associated with the given name, provided that request is of type multipart/form-data. If there are no parts, an empty collection is returned.
      Parameters:
      name - The HTTP request part name.
      Returns:
      All HTTP request parts associated with the given name.
      Throws:
      NullPointerException - When faces context is unavailable.
      FacesException - Whenever something fails at servlet or I/O level. The caller should preferably not catch it, but just let it go. The servletcontainer will handle it.
      Since:
      2.5
      See Also:

    • getRequestHeaderMap

      public static Map<String,String> getRequestHeaderMap()
      Returns the HTTP request header map.
      Returns:
      The HTTP request header map.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getMutableRequestHeaderMap

      public static Map<String,List<String>> getMutableRequestHeaderMap()
      Returns the mutable request header map. This requires installation of MutableRequestFilter.
      Returns:
      The mutable request header map.
      Throws:
      IllegalStateException - When the MutableRequestFilter is not installed or not invoked yet.
      Since:
      3.14
      See Also:

    • getRequestHeader

      public static String getRequestHeader(String name)
      Returns the HTTP request header value associated with the given name.
      Parameters:
      name - The HTTP request header name.
      Returns:
      The HTTP request header value associated with the given name.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getRequestHeaderValuesMap

      public static Map<String,String[]> getRequestHeaderValuesMap()
      Returns the HTTP request header values map.
      Returns:
      The HTTP request header values map.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getRequestHeaderValues

      public static String[] getRequestHeaderValues(String name)
      Returns the HTTP request header values associated with the given name.
      Parameters:
      name - The HTTP request header name.
      Returns:
      The HTTP request header values associated with the given name.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getRequestContextPath

      public static String getRequestContextPath()
      Returns the HTTP request context path. It's the webapp context name, with a leading slash. If the webapp runs on context root, then it returns an empty string.

      This is also available in EL as #{faces.requestContextPath}.

      Returns:
      The HTTP request context path.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getRequestServletPath

      public static String getRequestServletPath()
      Returns the HTTP request servlet path. If Faces is prefix mapped (e.g. /faces/*), then this returns the whole prefix mapping (e.g. /faces). If Faces is suffix mapped (e.g. *.xhtml), then this returns the whole part after the context path, with a leading slash.

      This is also available in EL as #{faces.requestServletPath}.

      Returns:
      The HTTP request servlet path.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getRequestPathInfo

      public static String getRequestPathInfo()
      Returns the HTTP request path info, taking into account whether FacesViews is used with MultiViews enabled. If the resource is prefix mapped (e.g. /faces/*), then this returns the whole part after the prefix mapping, with a leading slash. If the resource is suffix mapped (e.g. *.xhtml), then this returns null. If MultiViews is enabled, then this returns the part after the mapped view, if any.

      This is also available in EL as #{faces.requestPathInfo}.

      Returns:
      The HTTP request path info.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getRequestHostname

      public static String getRequestHostname()
      Returns the HTTP request hostname. This is the entire domain, without any scheme and slashes. Noted should be that this value is extracted from the request URL, not from ServletRequest.getServerName() as its outcome can be influenced by proxies.

      This is also available in EL as #{faces.requestHostName}.

      Returns:
      The HTTP request hostname.
      Throws:
      NullPointerException - When faces context is unavailable.
      IllegalArgumentException - When the URL is malformed. This is however unexpected as the request would otherwise not have hit the server at all.
      Since:
      1.6
      See Also:

    • getRequestBaseURL

      public static String getRequestBaseURL()
      Returns the HTTP request base URL. This is the URL from the scheme, domain until with context path, including the trailing slash. This is the value you could use in HTML <base> tag.

      This is also available in EL as #{faces.requestBaseURL}.

      Returns:
      The HTTP request base URL.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getRequestDomainURL

      public static String getRequestDomainURL()
      Returns the HTTP request domain URL. This is the URL with the scheme and domain, without any trailing slash.

      This is also available in EL as #{faces.requestDomainURL}.

      Returns:
      The HTTP request domain URL.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.1
      See Also:

    • getRequestURL

      public static String getRequestURL()
      Returns the HTTP request URL. This is the full request URL as the enduser sees in browser address bar. This does not include the request query string.

      This is also available in EL as #{faces.requestURL}.

      Returns:
      The HTTP request URL.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.1
      See Also:

    • getRequestURI

      public static String getRequestURI()
      Returns the HTTP request URI. This is the part after the domain in the request URL, including the leading slash. This does not include the request query string.

      This is also available in EL as #{faces.requestURI}.

      Returns:
      The HTTP request URI.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.1
      See Also:

    • getRequestQueryString

      public static String getRequestQueryString()
      Returns the HTTP request query string. This is the part after the ? in the request URL as the enduser sees in browser address bar.

      This is also available in EL as #{faces.requestQueryString}.

      Returns:
      The HTTP request query string.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.1
      See Also:

    • getRequestQueryStringMap

      public static Map<String,List<String>> getRequestQueryStringMap()
      Returns the HTTP request query string as parameter values map. Note this method returns only the request URL (GET) parameters, as opposed to getRequestParameterValuesMap(), which contains both the request URL (GET) parameters and the request body (POST) parameters. This is ready for usage in among others ViewHandler.getBookmarkableURL(FacesContext, String, Map, boolean).
      Returns:
      The HTTP request query string as parameter values map.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.6
      See Also:

    • getRequestURLWithQueryString

      public static String getRequestURLWithQueryString()
      Returns the HTTP request URL with query string. This is the full request URL with query string as the enduser sees in browser address bar.

      This is also available in EL as #{faces.requestURLWithQueryString}.

      Returns:
      The HTTP request URL with query string.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.5
      See Also:

    • getRequestURIWithQueryString

      public static String getRequestURIWithQueryString()
      Returns the HTTP request URI with query string. This is the part after the domain in the request URL, including the leading slash and the request query string.

      This is also available in EL as #{faces.requestURIWithQueryString}.

      Returns:
      The HTTP request URI with query string.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.6
      See Also:

    • getRemoteAddr

      public static String getRemoteAddr()
      Returns the Internet Protocol (IP) address of the client that sent the request. This will first check the X-Forwarded-For request header and if it's present, then return its first IP address, else just return ServletRequest.getRemoteAddr() unmodified.

      This is also available in EL as #{faces.remoteAddr}.

      Returns:
      The IP address of the client.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.2
      See Also:

    • getUserAgent

      public static String getUserAgent()
      Returns the User-Agent string of the client.

      This is also available in EL as #{faces.userAgent}.

      Returns:
      The User-Agent string of the client.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      3.2
      See Also:

    • getReferrer

      public static String getReferrer()
      Returns the referrer of the request.

      This is also available in EL as #{faces.referrer}.

      Returns:
      The referrer of the request.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      3.10
      See Also:

    • isRequestSecure

      public static boolean isRequestSecure()
      Returns true if connection is secure, false otherwise. This method will first check if ServletRequest.isSecure() returns true, and if not true, check if the X-Forwarded-Proto is present and equals to https.
      Returns:
      true if connection is secure, false otherwise.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      3.0
      See Also:

    • getResponse

      public static HttpServletResponse getResponse()
      Returns the HTTP servlet response.

      Note that whenever you absolutely need this method to perform a general task, you might want to consider to submit a feature request to OmniFaces in order to add a new utility method which performs exactly this general task.

      Returns:
      The HTTP servlet response.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getResponseBufferSize

      public static int getResponseBufferSize()
      Returns the HTTP response buffer size. If Facelets is used and the jakarta.faces.FACELETS_BUFFER_SIZE context parameter is been set, then it's the context parameter value which will be returned. Otherwise it returns the implementation independent default value, which is 1024 in Mojarra.
      Returns:
      The HTTP response buffer size.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.2
      See Also:

    • getResponseCharacterEncoding

      public static String getResponseCharacterEncoding()
      Returns the HTTP response character encoding.
      Returns:
      The HTTP response character encoding.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.2
      See Also:

    • setResponseStatus

      public static void setResponseStatus(int status)
      Sets the HTTP response status code. You can use the constant field values of HttpServletResponse for this. For example, Faces.setResponseStatus(HttpServletResponse.SC_BAD_REQUEST).
      Parameters:
      status - The HTTP status code to be set on the current response.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.6

    • redirect

      public static void redirect(String url, Object... paramValues)
      Sends a temporary (302) redirect to the given URL. If the given URL does not start with http://, https:// or /, then the request context path will be prepended, otherwise it will be the unmodified redirect URL. So, when redirecting to another page in the same web application, always specify the full path from the context root on (which in turn does not need to start with /). 
       Faces.redirect("other.xhtml");

      You can use String.format(String, Object...) placeholder %s in the redirect URL to represent placeholders for any request parameter values which needs to be URL-encoded. Here's a concrete example: 

       Faces.redirect("other.xhtml?foo=%s&bar=%s", foo, bar);
      Parameters:
      url - The URL to redirect the current response to.
      paramValues - The request parameter values which you'd like to put URL-encoded in the given URL.
      Throws:
      NullPointerException - When faces context is unavailable or given url is null.
      UncheckedIOException - When HTTP response is not available anymore.
      See Also:

    • redirectPermanent

      public static void redirectPermanent(String url, Object... paramValues)
      Sends a permanent (301) redirect to the given URL. If the given URL does not start with http://, https:// or /, then the request context path will be prepended, otherwise it will be the unmodified redirect URL. So, when redirecting to another page in the same web application, always specify the full path from the context root on (which in turn does not need to start with /). 
       Faces.redirectPermanent("other.xhtml");

      You can use String.format(String, Object...) placeholder %s in the redirect URL to represent placeholders for any request parameter values which needs to be URL-encoded. Here's a concrete example: 

       Faces.redirectPermanent("other.xhtml?foo=%s&bar=%s", foo, bar);

      This method does by design not work on ajax requests. It is not possible to return a "permanent redirect" via Faces ajax XML response.

      Parameters:
      url - The URL to redirect the current response to.
      paramValues - The request parameter values which you'd like to put URL-encoded in the given URL.
      Throws:
      NullPointerException - When faces context is unavailable or given url is null.
      See Also:

    • refresh

      public static void refresh()
      Refresh the current page by a GET request. This basically sends a temporary (302) redirect to current request URI, without query string.
      Throws:
      NullPointerException - When faces context is unavailable.
      UncheckedIOException - When HTTP response is not available anymore.
      Since:
      2.2
      See Also:

    • refreshWithQueryString

      public static void refreshWithQueryString()
      Refresh the current page by a GET request, maintaining the query string. This basically sends a temporary (302) redirect to current request URI, with the current query string.
      Throws:
      NullPointerException - When faces context is unavailable.
      UncheckedIOException - When HTTP response is not available anymore.
      Since:
      2.2
      See Also:

    • resetResponse

      public static void resetResponse()
      Resets the HTTP response. This basically clears out any uncommitted data written to headers/body, and sets the content type and character encoding to originally set values, with fall back to "text/html" and "UTF-8". This also resets the Faces partial response.
      Throws:
      IllegalStateException - When the response has already been committed.
      Since:
      5.0
      See Also:

    • responseSendError

      public static void responseSendError(int status, String message)
      Sends a HTTP response error with the given status and message. This will end up in either a custom <error-page> whose <error-code> matches the given status, or in a servlet container specific default error page if there is none. The message will be available in the error page as a request attribute with name jakarta.servlet.error.message. The FacesContext.responseComplete() will implicitly be called after sending the error.
      Parameters:
      status - The HTTP response status which is supposed to be in the range 4nn-5nn. You can use the constant field values of HttpServletResponse for this.
      message - The message which is supposed to be available in the error page.
      Throws:
      NullPointerException - When faces context is unavailable.
      UncheckedIOException - When HTTP response is not available anymore.
      See Also:

    • addResponseHeader

      public static void addResponseHeader(String name, String value)
      Add a header with given name and value to the HTTP response.
      Parameters:
      name - The header name.
      value - The header value.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getResponseHeaders

      public static Collection<String> getResponseHeaders(String name)
      Returns all headers with given name from the HTTP response.
      Parameters:
      name - The header name.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      5.0
      See Also:

    • isResponseCommitted

      public static boolean isResponseCommitted()
      Returns whether the response is already committed. That is, when the response headers and a part of the response body has already been sent to the client. This is usually a point of no return and you can't change the response anymore.
      Returns:
      true if the response is already committed, otherwise false.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.1
      See Also:

    • responseReset

      public static void responseReset()
      Resets the current response. This will clear any headers which are been set and any data which is written to the response buffer which isn't committed yet.
      Throws:
      NullPointerException - When faces context is unavailable.
      IllegalStateException - When the response is already committed.
      Since:
      1.1
      See Also:

    • renderResponse

      public static void renderResponse()
      Signals Faces that, as soon as the current phase of the lifecycle has been completed, control should be passed to the Render Response phase, bypassing any phases that have not been executed yet.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.4
      See Also:

    • isRenderResponse

      public static boolean isRenderResponse()
      Returns true if we're currently in the render response phase. This explicitly checks the current phase ID instead of FacesContext.getRenderResponse() as the latter may unexpectedly return false during a GET request when <f:viewParam> is been used.

      This is also available in EL as #{faces.renderResponse}.

      Returns:
      true if we're currently in the render response phase.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.4
      See Also:

    • responseComplete

      public static void responseComplete()
      Signals Faces that the response for this request has already been generated (such as providing a file download), and that the lifecycle should be terminated as soon as the current phase is completed.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.4
      See Also:

    • isResponseComplete

      public static boolean isResponseComplete()
      Returns true if the FacesContext.responseComplete() has been called.
      Returns:
      true if the FacesContext.responseComplete() has been called.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.4
      See Also:

    • login

      public static void login(String username, String password) throws ServletException
      Perform programmatic login for container managed FORM based authentication. Note that configuration is container specific and unrelated to Faces. Refer the documentation of the servletcontainer using the keyword "realm".
      Parameters:
      username - The login username.
      password - The login password.
      Throws:
      NullPointerException - When faces context is unavailable.
      ServletException - When the login is invalid, or when container managed FORM based authentication is not enabled.
      See Also:

    • authenticate

      public static boolean authenticate() throws ServletException
      Trigger the default container managed authentication mechanism on the current request. It expects the username and password being available as predefinied request parameters on the current request and/or a custom JASPIC implementation.
      Returns:
      true if the authentication was successful, otherwise false.
      Throws:
      NullPointerException - When faces context is unavailable.
      ServletException - When the authentication has failed. The caller is responsible for handling it.
      UncheckedIOException - When HTTP request or response is not available anymore.
      Since:
      1.4
      See Also:

    • isAuthenticated

      public static boolean isAuthenticated()
      Returns whether the current request is authenticated, i.e. it has a logged-in user.

      This is also available in EL as #{faces.authenticated}.

      Returns:
      true if the current request is authenticated, otherwise false.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      4.3
      See Also:

    • logout

      public static void logout() throws ServletException
      Perform programmatic logout for container managed FORM based authentication. Note that this basically removes the user principal from the session. It's however better practice to just invalidate the session altogether, which will implicitly also remove the user principal. Just invoke invalidateSession() instead. Note that the user principal is still present in the response of the current request, it's therefore recommend to send a redirect after logout() or invalidateSession(). You can use redirect(String, Object...) for this.
      Throws:
      NullPointerException - When faces context is unavailable.
      ServletException - When the logout has failed.
      See Also:

    • getRemoteUser

      public static String getRemoteUser()
      Returns the name of the logged-in user for container managed FORM based authentication, if any.

      This is also available in EL as #{faces.remoteUser}.

      Returns:
      The name of the logged-in user for container managed FORM based authentication, if any.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • isUserInRole

      public static boolean isUserInRole(String role)
      Returns whether the currently logged-in user has the given role.
      Parameters:
      role - The role to be checked on the currently logged-in user.
      Returns:
      true if the currently logged-in user has the given role, otherwise false.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getRequestCookie

      public static String getRequestCookie(String name)
      Returns the value of the HTTP request cookie associated with the given name. The value is implicitly URL-decoded with a charset of UTF-8.
      Parameters:
      name - The HTTP request cookie name.
      Returns:
      The value of the HTTP request cookie associated with the given name.
      Throws:
      NullPointerException - When faces context is unavailable.
      UnsupportedOperationException - When this platform does not support UTF-8.
      See Also:

    • addResponseCookie

      public static void addResponseCookie(String name, String value, int maxAge)
      Add a cookie with given name, value and maxage to the HTTP response. The cookie value will implicitly be URL-encoded with UTF-8 so that any special characters can be stored. The cookie will implicitly be set in the domain and path of the current request URL. The cookie will implicitly be set to HttpOnly as JavaScript is not supposed to manipulate server-created cookies. The cookie will implicitly be set to secure when the current request is a HTTPS request.
      Parameters:
      name - The cookie name.
      value - The cookie value.
      maxAge - The maximum age of the cookie, in seconds. If this is 0, then the cookie will be removed. Note that the name and path must be exactly the same as it was when the cookie was created. If this is -1 then the cookie will become a session cookie and thus live as long as the established HTTP session.
      Throws:
      NullPointerException - When faces context is unavailable.
      UnsupportedOperationException - When this platform does not support UTF-8.
      Since:
      1.8
      See Also:

    • addResponseCookie

      public static void addResponseCookie(String name, String value, String path, int maxAge)
      Add a cookie with given name, value, path and maxage to the HTTP response. The cookie value will implicitly be URL-encoded with UTF-8 so that any special characters can be stored. The cookie will implicitly be set in the domain of the current request URL. The cookie will implicitly be set to HttpOnly as JavaScript is not supposed to manipulate server-created cookies. The cookie will implicitly be set to secure when the current request is a HTTPS request.
      Parameters:
      name - The cookie name.
      value - The cookie value.
      path - The cookie path. If this is /, then the cookie is available in all pages of the webapp. If this is /somespecificpath, then the cookie is only available in pages under the specified path.
      maxAge - The maximum age of the cookie, in seconds. If this is 0, then the cookie will be removed. Note that the name and path must be exactly the same as it was when the cookie was created. If this is -1 then the cookie will become a session cookie and thus live as long as the established HTTP session.
      Throws:
      NullPointerException - When faces context is unavailable.
      UnsupportedOperationException - When this platform does not support UTF-8.
      See Also:

    • addResponseCookie

      public static void addResponseCookie(String name, String value, String domain, String path, int maxAge)
      Add a cookie with given name, value, domain, path and maxage to the HTTP response. The cookie value will implicitly be URL-encoded with UTF-8 so that any special characters can be stored. The cookie will implicitly be set to HttpOnly as JavaScript is not supposed to manipulate server-created cookies. The cookie will implicitly be set to secure when the current request is a HTTPS request.
      Parameters:
      name - The cookie name.
      value - The cookie value.
      domain - The cookie domain. You can use .example.com (with a leading period) if you'd like the cookie to be available to all subdomains of the domain. Note that you cannot set it to a different domain. Defaults to getRequestHostname() when null.
      path - The cookie path. If this is /, then the cookie is available in all pages of the webapp. If this is /somespecificpath, then the cookie is only available in pages under the specified path.
      maxAge - The maximum age of the cookie, in seconds. If this is 0, then the cookie will be removed. Note that the name and path must be exactly the same as it was when the cookie was created. If this is -1 then the cookie will become a session cookie and thus live as long as the established HTTP session.
      Throws:
      NullPointerException - When faces context is unavailable.
      UnsupportedOperationException - When this platform does not support UTF-8.
      Since:
      1.8
      See Also:

    • addResponseCookie

      public static void addResponseCookie(String name, String value, String domain, String path, int maxAge, boolean httpOnly)
      Add a cookie with given name, value, domain, path, maxage and HttpOnly flag to the HTTP response. The cookie value will implicitly be URL-encoded with UTF-8 so that any special characters can be stored. The cookie will implicitly be set to secure when the current request is a HTTPS request.
      Parameters:
      name - The cookie name.
      value - The cookie value.
      domain - The cookie domain. You can use .example.com (with a leading period) if you'd like the cookie to be available to all subdomains of the domain. Note that you cannot set it to a different domain. Defaults to getRequestHostname() when null.
      path - The cookie path. If this is /, then the cookie is available in all pages of the webapp. If this is /somespecificpath, then the cookie is only available in pages under the specified path.
      maxAge - The maximum age of the cookie, in seconds. If this is 0, then the cookie will be removed. Note that the name and path must be exactly the same as it was when the cookie was created. If this is -1 then the cookie will become a session cookie and thus live as long as the established HTTP session.
      httpOnly - When set to true, then JavaScript is not allowed to manipulate the cookie.
      Throws:
      NullPointerException - When faces context is unavailable.
      UnsupportedOperationException - When this platform does not support UTF-8.
      Since:
      3.3
      See Also:

    • addResponseCookie

      public static void addResponseCookie(String name, String value, String domain, String path, int maxAge, boolean httpOnly, Map<String,String> attributes)
      Add a cookie with given name, value, domain, path, maxage, HttpOnly flag and custom attributes to the HTTP response. The cookie value will implicitly be URL-encoded with UTF-8 so that any special characters can be stored. The cookie will implicitly be set to secure when the current request is a HTTPS request.
      Parameters:
      name - The cookie name.
      value - The cookie value.
      domain - The cookie domain. You can use .example.com (with a leading period) if you'd like the cookie to be available to all subdomains of the domain. Note that you cannot set it to a different domain. Defaults to getRequestHostname() when null.
      path - The cookie path. If this is /, then the cookie is available in all pages of the webapp. If this is /somespecificpath, then the cookie is only available in pages under the specified path.
      maxAge - The maximum age of the cookie, in seconds. If this is 0, then the cookie will be removed. Note that the name and path must be exactly the same as it was when the cookie was created. If this is -1 then the cookie will become a session cookie and thus live as long as the established HTTP session.
      httpOnly - When set to true, then JavaScript is not allowed to manipulate the cookie.
      attributes - Any custom attributes you'd like to add to the cookie, such as SameSite:None. Any key whose name matches a predefined cookie attribute name, such as domain, path, HttpOnly, etc, will override them. If the underlying Faces and/or Servlet implementation does not allow a certain custom attribute, then it will throw IllegalArgumentException.
      Throws:
      NullPointerException - When faces context is unavailable.
      UnsupportedOperationException - When this platform does not support UTF-8.
      IllegalArgumentException - When a custom attribute is specified which is not supported by the underlying Faces and/or Servlet implementation. As of now, it's only supported when running minimally Faces 4 on on top of minimally Servlet 6.
      Since:
      4.0
      See Also:

    • removeResponseCookie

      public static void removeResponseCookie(String name, String path)
      Remove the cookie with given name and path from the HTTP response. Note that the name and path must be exactly the same as it was when the cookie was created.
      Parameters:
      name - The cookie name.
      path - The cookie path.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getSession

      public static HttpSession getSession()
      Returns the HTTP session and creates one if one doesn't exist.

      Note that whenever you absolutely need this method to perform a general task, you might want to consider to submit a feature request to OmniFaces in order to add a new utility method which performs exactly this general task.

      Returns:
      The HTTP session.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getSession

      public static HttpSession getSession(boolean create)
      Returns the HTTP session and creates one if one doesn't exist and create argument is true, otherwise don't create one and return null.

      Note that whenever you absolutely need this method to perform a general task, you might want to consider to submit a feature request to OmniFaces in order to add a new utility method which performs exactly this general task.

      Parameters:
      create - Whether or not to create a new session if one doesn't exist.
      Returns:
      The HTTP session.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getSessionId

      public static String getSessionId()
      Returns a string containing the unique identifier assigned to this session. The identifier is assigned by the servlet container and is implementation dependent.
      Returns:
      The HTTP session ID.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.2
      See Also:

    • invalidateSession

      public static void invalidateSession()
      Invalidates the current HTTP session. So, any subsequent HTTP request will get a new one when necessary.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • hasSession

      public static boolean hasSession()
      Returns whether the HTTP session has already been created.
      Returns:
      true if the HTTP session has already been created, otherwise false.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.1
      See Also:

    • isSessionNew

      public static boolean isSessionNew()
      Returns whether the HTTP session has been created for the first time in the current request. This returns also false when there is no means of a HTTP session.
      Returns:
      true if the HTTP session has been created for the first time in the current request, otherwise false.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.1
      See Also:

    • isRequestedSessionExpired

      public static boolean isRequestedSessionExpired()
      Returns whether the requested HTTP session is expired.

      This is also available in EL as #{faces.requestedSessionExpired}.

      Returns:
      true if the requested HTTP session is expired, otherwise false.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      3.13
      See Also:

    • getSessionCreationTime

      public static long getSessionCreationTime()
      Returns the time when the HTTP session was created, measured in epoch time. This implicitly creates the session if one doesn't exist.
      Returns:
      The time when the HTTP session was created.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.1
      See Also:

    • getSessionLastAccessedTime

      public static long getSessionLastAccessedTime()
      Returns the time of the previous request associated with the current HTTP session, measured in epoch time. This implicitly creates the session if one doesn't exist.
      Returns:
      The time of the previous request associated with the current HTTP session.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.1
      See Also:

    • getSessionMaxInactiveInterval

      public static int getSessionMaxInactiveInterval()
      Returns the HTTP session timeout in seconds. This implicitly creates the session if one doesn't exist.
      Returns:
      The HTTP session timeout in seconds.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.1
      See Also:

    • setSessionMaxInactiveInterval

      public static void setSessionMaxInactiveInterval(int seconds)
      Sets the HTTP session timeout in seconds. A value of 0 or less means that the session should never timeout. This implicitly creates the session if one doesn't exist.
      Parameters:
      seconds - The HTTP session timeout in seconds.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.1
      See Also:

    • getServletContext

      public static ServletContext getServletContext()
      Returns the servlet context.

      Note that whenever you absolutely need this method to perform a general task, you might want to consider to submit a feature request to OmniFaces in order to add a new utility method which performs exactly this general task.

      Returns:
      the servlet context.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getInitParameterMap

      public static Map<String,String> getInitParameterMap()
      Returns the application initialization parameter map. This returns the parameter name-value pairs of all <context-param> entries in in web.xml.
      Returns:
      The application initialization parameter map.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.1
      See Also:

    • getInitParameter

      public static String getInitParameter(String name)
      Returns the application initialization parameter. This returns the <param-value> of a <context-param> in web.xml associated with the given <param-name>.
      Parameters:
      name - The application initialization parameter name.
      Returns:
      The application initialization parameter value associated with the given name, or null if there is none.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.1
      See Also:

    • getInitParameterOrDefault

      public static String getInitParameterOrDefault(String name, String defaultValue)
      Returns the application initialization parameter. This returns the <param-value> of a <context-param> in web.xml associated with the given <param-name>.
      Parameters:
      name - The application initialization parameter name.
      defaultValue - The default value if there is no application initialization parameter value associated with the given name.
      Returns:
      The application initialization parameter value associated with the given name, or defaultValue if there is none.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      3.1
      See Also:

    • getMimeType

      public static String getMimeType(String name)
      Returns the mime type for the given file name. The mime type is determined based on file extension and configureable by <mime-mapping> entries in web.xml. When the mime type is unknown, then a default of application/octet-stream will be returned.
      Parameters:
      name - The file name to return the mime type for.
      Returns:
      The mime type for the given file name.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getResource

      public static URL getResource(String path) throws MalformedURLException
      Returns a URL for an application resource mapped to the specified path, if it exists; otherwise, return null.
      Parameters:
      path - The application resource path to return an input stream for.
      Returns:
      An input stream for an application resource mapped to the specified path.
      Throws:
      NullPointerException - When faces context is unavailable.
      MalformedURLException - When the specified path is not in correct URL form.
      Since:
      1.2
      See Also:

    • getResourceAsStream

      public static InputStream getResourceAsStream(String path)
      Returns an input stream for an application resource mapped to the specified path, if it exists; otherwise, return null.
      Parameters:
      path - The application resource path to return an input stream for.
      Returns:
      An input stream for an application resource mapped to the specified path.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getResourcePaths

      public static Set<String> getResourcePaths(String path)
      Returns a set of available application resource paths matching the specified path.
      Parameters:
      path - The partial application resource path used to return matching resource paths.
      Returns:
      A set of available application resource paths matching the specified path.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getRealPath

      public static String getRealPath(String webContentPath)
      Returns the absolute disk file system path representation of the given web content path. This thus converts the given path of a web content resource (e.g. /index.xhtml) to an absolute disk file system path (e.g. /path/to/server/work/folder/some.war/index.xhtml) which can then be used in File, FileInputStream, etc.

      Note that this will return null when the WAR is not expanded into the disk file system, but instead into memory. If all you want is just an InputStream of the web content resource, then better use getResourceAsStream(String) instead.

      Also note that it wouldn't make sense to modify or create files in this location, as those changes would get lost anyway when the WAR is redeployed or even when the server is restarted. This is thus absolutely not a good location to store for example uploaded files.

      Parameters:
      webContentPath - The web content path to be converted to an absolute disk file system path.
      Returns:
      The absolute disk file system path representation of the given web content path.
      Throws:
      NullPointerException - When faces context is unavailable.
      Since:
      1.2

    • getRequestMap

      public static Map<String,Object> getRequestMap()
      Returns the request scope map.
      Returns:
      The request scope map.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getRequestAttribute

      public static <T> T getRequestAttribute(String name)
      Returns the request scope attribute value associated with the given name.
      Type Parameters:
      T - The expected return type.
      Parameters:
      name - The request scope attribute name.
      Returns:
      The request scope attribute value associated with the given name.
      Throws:
      NullPointerException - When faces context is unavailable.
      ClassCastException - When T is of wrong type.
      See Also:

    • getRequestAttribute

      public static <T> T getRequestAttribute(String name, Supplier<T> computeIfAbsent)
      Returns the request scope attribute value associated with the given name, or computes the supplied value if absent.
      Type Parameters:
      T - The expected return type.
      Parameters:
      name - The request scope attribute name.
      computeIfAbsent - The computed request scope attribute value when absent. Useful if it represents a collection, map or bean.
      Returns:
      The request scope attribute value associated with the given name.
      Throws:
      NullPointerException - When faces context is unavailable.
      ClassCastException - When T is of wrong type.
      Since:
      3.0
      See Also:

    • setRequestAttribute

      public static void setRequestAttribute(String name, Object value)
      Sets the request scope attribute value associated with the given name.
      Parameters:
      name - The request scope attribute name.
      value - The request scope attribute value.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • removeRequestAttribute

      public static <T> T removeRequestAttribute(String name)
      Removes the request scope attribute value associated with the given name.
      Type Parameters:
      T - The expected return type.
      Parameters:
      name - The request scope attribute name.
      Returns:
      The request scope attribute value previously associated with the given name, or null if there is no such attribute.
      Throws:
      NullPointerException - When faces context is unavailable.
      ClassCastException - When T is of wrong type.
      Since:
      1.1
      See Also:

    • getFlash

      public static Flash getFlash()
      Returns the flash scope. Note that Flash implements Map<String, Object>, so you can just treat it like a Map<String, Object>.
      Returns:
      The flash scope.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getFlashAttribute

      public static <T> T getFlashAttribute(String name)
      Returns the flash scope attribute value associated with the given name.
      Type Parameters:
      T - The expected return type.
      Parameters:
      name - The flash scope attribute name.
      Returns:
      The flash scope attribute value associated with the given name.
      Throws:
      NullPointerException - When faces context is unavailable.
      ClassCastException - When T is of wrong type.
      See Also:

    • getFlashAttribute

      public static <T> T getFlashAttribute(String name, Supplier<T> computeIfAbsent)
      Returns the flash scope attribute value associated with the given name, or computes the supplied value if absent.
      Type Parameters:
      T - The expected return type.
      Parameters:
      name - The flash scope attribute name.
      computeIfAbsent - The computed flash scope attribute value when absent. Useful if it represents a collection, map or bean.
      Returns:
      The flash scope attribute value associated with the given name.
      Throws:
      NullPointerException - When faces context is unavailable.
      ClassCastException - When T is of wrong type.
      Since:
      3.0
      See Also:

    • setFlashAttribute

      public static void setFlashAttribute(String name, Object value)
      Sets the flash scope attribute value associated with the given name.
      Parameters:
      name - The flash scope attribute name.
      value - The flash scope attribute value.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • removeFlashAttribute

      public static <T> T removeFlashAttribute(String name)
      Removes the flash scope attribute value associated with the given name.
      Type Parameters:
      T - The expected return type.
      Parameters:
      name - The flash scope attribute name.
      Returns:
      The flash scope attribute value previously associated with the given name, or null if there is no such attribute.
      Throws:
      NullPointerException - When faces context is unavailable.
      ClassCastException - When T is of wrong type.
      Since:
      1.1
      See Also:

    • getViewMap

      public static Map<String,Object> getViewMap()
      Returns the view scope map.
      Returns:
      The view scope map.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getViewAttribute

      public static <T> T getViewAttribute(String name)
      Returns the view scope attribute value associated with the given name.
      Type Parameters:
      T - The expected return type.
      Parameters:
      name - The view scope attribute name.
      Returns:
      The view scope attribute value associated with the given name.
      Throws:
      NullPointerException - When faces context is unavailable.
      ClassCastException - When T is of wrong type.
      See Also:

    • getViewAttribute

      public static <T> T getViewAttribute(String name, Supplier<T> computeIfAbsent)
      Returns the view scope attribute value associated with the given name, or computes the supplied value if absent.
      Type Parameters:
      T - The expected return type.
      Parameters:
      name - The view scope attribute name.
      computeIfAbsent - The computed view scope attribute value when absent. Useful if it represents a collection, map or bean.
      Returns:
      The view scope attribute value associated with the given name.
      Throws:
      NullPointerException - When faces context is unavailable.
      ClassCastException - When T is of wrong type.
      Since:
      3.0
      See Also:

    • setViewAttribute

      public static void setViewAttribute(String name, Object value)
      Sets the view scope attribute value associated with the given name.
      Parameters:
      name - The view scope attribute name.
      value - The view scope attribute value.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • removeViewAttribute

      public static <T> T removeViewAttribute(String name)
      Removes the view scope attribute value associated with the given name.
      Type Parameters:
      T - The expected return type.
      Parameters:
      name - The view scope attribute name.
      Returns:
      The view scope attribute value previously associated with the given name, or null if there is no such attribute.
      Throws:
      NullPointerException - When faces context is unavailable.
      ClassCastException - When T is of wrong type.
      Since:
      1.1
      See Also:

    • getSessionMap

      public static Map<String,Object> getSessionMap()
      Returns the session scope map.
      Returns:
      The session scope map.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getSessionAttribute

      public static <T> T getSessionAttribute(String name)
      Returns the session scope attribute value associated with the given name.
      Type Parameters:
      T - The expected return type.
      Parameters:
      name - The session scope attribute name.
      Returns:
      The session scope attribute value associated with the given name.
      Throws:
      NullPointerException - When faces context is unavailable.
      ClassCastException - When T is of wrong type.
      See Also:

    • getSessionAttribute

      public static <T> T getSessionAttribute(String name, Supplier<T> computeIfAbsent)
      Returns the session scope attribute value associated with the given name, or computes the supplied value if absent.
      Type Parameters:
      T - The expected return type.
      Parameters:
      name - The session scope attribute name.
      computeIfAbsent - The computed session scope attribute value when absent. Useful if it represents a collection, map or bean.
      Returns:
      The session scope attribute value associated with the given name.
      Throws:
      NullPointerException - When faces context is unavailable.
      ClassCastException - When T is of wrong type.
      Since:
      3.0
      See Also:

    • setSessionAttribute

      public static void setSessionAttribute(String name, Object value)
      Sets the session scope attribute value associated with the given name.
      Parameters:
      name - The session scope attribute name.
      value - The session scope attribute value.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • removeSessionAttribute

      public static <T> T removeSessionAttribute(String name)
      Removes the session scope attribute value associated with the given name.
      Type Parameters:
      T - The expected return type.
      Parameters:
      name - The session scope attribute name.
      Returns:
      The session scope attribute value previously associated with the given name, or null if there is no such attribute.
      Throws:
      NullPointerException - When faces context is unavailable.
      ClassCastException - When T is of wrong type.
      Since:
      1.1
      See Also:

    • getApplicationMap

      public static Map<String,Object> getApplicationMap()
      Returns the application scope map.
      Returns:
      The application scope map.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • getApplicationAttribute

      public static <T> T getApplicationAttribute(String name)
      Returns the application scope attribute value associated with the given name.
      Type Parameters:
      T - The expected return type.
      Parameters:
      name - The application scope attribute name.
      Returns:
      The application scope attribute value associated with the given name.
      Throws:
      NullPointerException - When faces context is unavailable.
      ClassCastException - When T is of wrong type.
      See Also:

    • getApplicationAttribute

      public static <T> T getApplicationAttribute(String name, Supplier<T> computeIfAbsent)
      Returns the application scope attribute value associated with the given name, or computes the supplied value if absent.
      Type Parameters:
      T - The expected return type.
      Parameters:
      name - The application scope attribute name.
      computeIfAbsent - The computed application scope attribute value when absent. Useful if it represents a collection, map or bean.
      Returns:
      The application scope attribute value associated with the given name.
      Throws:
      NullPointerException - When faces context is unavailable.
      ClassCastException - When T is of wrong type.
      Since:
      3.0
      See Also:

    • setApplicationAttribute

      public static void setApplicationAttribute(String name, Object value)
      Sets the application scope attribute value associated with the given name.
      Parameters:
      name - The application scope attribute name.
      value - The application scope attribute value.
      Throws:
      NullPointerException - When faces context is unavailable.
      See Also:

    • removeApplicationAttribute

      public static <T> T removeApplicationAttribute(String name)
      Removes the application scope attribute value associated with the given name.
      Type Parameters:
      T - The expected return type.
      Parameters:
      name - The application scope attribute name.
      Returns:
      The application scope attribute value previously associated with the given name, or null if there is no such attribute.
      Throws:
      NullPointerException - When faces context is unavailable.
      ClassCastException - When T is of wrong type.
      Since:
      1.1
      See Also:

    • sendFile

      public static void sendFile(File file, boolean attachment) throws IOException
      Send the given file to the response. The file name will be derived from File.getName(). The content type will be determined based on file name. The content length will be set to the length of the file. The FacesContext.responseComplete() will implicitly be called after successful streaming.
      Parameters:
      file - The file to be sent to the response.
      attachment - Whether the file should be provided as attachment, or just inline.
      Throws:
      NullPointerException - When faces context is unavailable.
      IOException - When given file cannot be read.
      UncheckedIOException - When HTTP response is not available anymore.

    • sendFile

      public static void sendFile(File file, String filename, boolean attachment) throws IOException
      Send the given file to the response. The content type will be determined based on file name. The content length will be set to the length of the file. The FacesContext.responseComplete() will implicitly be called after successful streaming.
      Parameters:
      file - The file to be sent to the response.
      filename - The file name which should appear in content disposition header.
      attachment - Whether the file should be provided as attachment, or just inline.
      Throws:
      NullPointerException - When faces context is unavailable.
      IOException - When given file cannot be read.
      UncheckedIOException - When HTTP response is not available anymore.
      Since:
      3.9

    • sendFile

      public static void sendFile(Path path, boolean attachment) throws IOException
      Send the given path as a file to the response. The file will be derived from Path.toFile() and then the file name will be derived from File.getName(). The content type will be determined based on file name. The content length will be set to the length of the file. The FacesContext.responseComplete() will implicitly be called after successful streaming.
      Parameters:
      path - The path to be sent as a file to the response.
      attachment - Whether the file should be provided as attachment, or just inline.
      Throws:
      NullPointerException - When faces context is unavailable.
      IOException - When given file cannot be read.
      UncheckedIOException - When HTTP response is not available anymore.
      Since:
      3.9

    • sendFile

      public static void sendFile(Path path, String filename, boolean attachment) throws IOException
      Send the given path as a file to the response. The file will be derived from Path.toFile(). The content type will be determined based on file name. The content length will be set to the length of the file. The FacesContext.responseComplete() will implicitly be called after successful streaming.
      Parameters:
      path - The path to be sent as a file to the response.
      filename - The file name which should appear in content disposition header.
      attachment - Whether the file should be provided as attachment, or just inline.
      Throws:
      NullPointerException - When faces context is unavailable.
      IOException - When given file cannot be read.
      UncheckedIOException - When HTTP response is not available anymore.
      Since:
      3.9

    • sendFile

      public static void sendFile(byte[] content, String filename, boolean attachment)
      Send the given byte array as a file to the response. The content type will be determined based on file name. The content length will be set to the length of the byte array. The FacesContext.responseComplete() will implicitly be called after successful streaming.
      Parameters:
      content - The file content as byte array.
      filename - The file name which should appear in content disposition header.
      attachment - Whether the file should be provided as attachment, or just inline.
      Throws:
      NullPointerException - When faces context is unavailable.
      UncheckedIOException - When HTTP response is not available anymore.

    • sendFile

      public static void sendFile(InputStream content, String filename, boolean attachment)
      Send the given input stream as a file to the response. The content type will be determined based on file name. The content length may not be set because that's not predictable based on input stream. The client may receive a download of an unknown length and thus the download progress may be unknown to the client. Only if the input stream is smaller than the default buffer size, then the content length will be set. The InputStream.close() will implicitly be called after streaming, regardless of whether an exception is been thrown or not. The FacesContext.responseComplete() will implicitly be called after successful streaming.
      Parameters:
      content - The file content as input stream.
      filename - The file name which should appear in content disposition header.
      attachment - Whether the file should be provided as attachment, or just inline.
      Throws:
      NullPointerException - When faces context is unavailable.
      UncheckedIOException - When HTTP response is not available anymore.

    • sendFile

      public static void sendFile(String filename, boolean attachment, FunctionalInterfaces.ThrowingConsumer<OutputStream> outputCallback)
      Send a file to the response whose content is provided via given output stream callback. The content type will be determined based on file name. The content length will not be set because that would require buffering the entire file in memory or temp disk. The client may receive a download of an unknown length and thus the download progress may be unknown to the client. If this is undesirable, write to a temp file instead and then use sendFile(File, boolean). The FacesContext.responseComplete() will implicitly be called after successful streaming.
      Parameters:
      filename - The file name which should appear in content disposition header.
      attachment - Whether the file should be provided as attachment, or just inline.
      outputCallback - The output stream callback to write the file content to.
      Throws:
      NullPointerException - When faces context is unavailable.
      UncheckedIOException - When HTTP response is not available anymore.
      Since:
      2.3