Module org.omnifaces
Package org.omnifaces.taghandler

Class ViewParamValidationFailed

java.lang.Object
jakarta.faces.view.facelets.TagHandler
org.omnifaces.taghandler.ViewParamValidationFailed
All Implemented Interfaces:
FaceletHandler
public class ViewParamValidationFailed extends TagHandler

<o:viewParamValidationFailed> allows the developer to handle a view parameter validation failure with either a redirect or an HTTP error status, optionally with respectively a flash message or HTTP error message. This tag can be placed inside <f:metadata> or <f|o:viewParam>. When placed in <f|o:viewParam>, it will be applied when the particular view parameter has a validation error as per UIInput.isValid(). When placed in <f:metadata>, and no one view parameter has already handled the validation error via its own <o:viewParamValidationFailed>, it will be applied when there's a general validation error as per FacesContext.isValidationFailed().

When the sendRedirect attribute is set, a call to Faces.redirect(String, Object...) is made internally to send the redirect. So, the same rules as to scheme and leading slash apply here. When the sendError attribute is set, a call to Faces.responseSendError(int, String) is made internally to send the error. You can therefore customize HTTP error pages via <error-page> entries in web.xml. Otherwise the server-default one will be displayed instead.

<f:viewParam required="true"> fail

As a precaution; be aware that <f:viewParam required="true"> has a design error in current Mojarra and MyFaces releases (as of now, Mojarra 2.2.7 and MyFaces 2.2.4). When the parameter is not specified in the query string, it is retrieved as null, which causes an internal isRequired() check to be performed instead of delegating the check to the standard UIInput implementation. This has the consequence that PreValidateEvent and PostValidateEvent listeners are never invoked, which the <o:viewParamValidationFailed> is actually relying on. This is fixed in <o:viewParam>.

Examples

In the example below the client will be presented an HTTP 400 error when at least one view param is absent. 

 <f:metadata>
     <o:viewParam name="foo" required="true" />
     <o:viewParam name="bar" required="true" />
     <o:viewParamValidationFailed sendError="400" />
 </f:metadata>

In the example below the client will be redirected to "login.xhtml" when the "foo" parameter is absent, regardless of the "bar" parameter. When the "foo" parameter is present, but the "bar" parameter is absent, nothing new will happen. The process will proceed "as usual". I.e. the validation error will end up as a faces message in the current view the usual way. 

 <f:metadata>
     <o:viewParam name="foo" required="true">
         <o:viewParamValidationFailed sendRedirect="login.xhtml" />
     </o:viewParam>
     <o:viewParam name="bar" required="true" />
 </f:metadata>

In the example below the client will be presented an HTTP 401 error when the "foo" parameter is absent, regardless of the "bar" or "baz" parameters. When the "foo" parameter is present, but either the "bar" or "baz" parameter is absent, the client will be redirected to "search.xhtml". 

 <f:metadata>
     <o:viewParam name="foo" required="true">
         <o:viewParamValidationFailed sendError="401" />
     </o:viewParam>
     <o:viewParam name="bar" required="true" />
     <o:viewParam name="baz" required="true" />
     <o:viewParamValidationFailed sendRedirect="search.xhtml" />
 </f:metadata>

In a nutshell: when there are multiple <o:viewParamValidationFailed> tags, they will be applied in the same order as they are declared in the view. So, with the example above, the one nested in <f|o:viewParam> takes precedence over the one nested in <f:metadata>.

Messaging

By default, the first occurring faces message on the parent component will be copied, or when there is none then the first occurring global faces message will be copied. When sendRedirect is used, it will be set as a global flash error message. When sendError is used, it will be set as HTTP status message.

You can override this message by explicitly specifying the message attribute. This is applicable for both sendRedirect and sendError. 

 <o:viewParamValidationFailed sendRedirect="search.xhtml" message="You need to perform a search." />
 ...
 <o:viewParamValidationFailed sendError="401" message="Authentication failed. You need to login." />

Note, although all of above examples use required="true", this does not mean that you can only use <o:viewParamValidationFailed> in combination with required="true" validation. You can use it in combination with any kind of conversion/validation on <f|o:viewParam>, even bean validation.

Design notes

You can technically nest multiple <o:viewParamValidationFailed> inside the same parent, but this is not the documented approach and only the first one would be used.

You can not change the HTTP status code of a redirect. This is not a Faces limitation, but an HTTP limitation. The status code of a redirect will always end up as the one of the redirected response. If you intend to "redirect" with a different HTTP status code, then you should be using sendError instead and specify the desired page as <error-page> in web.xml.

Since:
2.0
Author:
Bauke Scholtz