How to make an asynchronous processor in Apache Camel for generating and streaming files

We've had a case where we needed to generate a PDF file and stream it back to the client from Camel. The PDF generating library expects an OutputStream to write to, and as a file can grow big, it was important not to buffer an entire stream in memory. While Camel already provides many options when it comes to concurrency, they are centered on invoking a route asynchronously, which was not (or at least not nicely) applicable to our case as we want only a part of the logic to run in a separate thread. We needed an asynchronous processor. An interface AsyncProcessor already exists, but it only provides a callback to notify the caller of job done, but no actual mechanism to execute logic asynchronously. This needs to be done manually, but luckily, Camel does offer an easy way to create thread pools and use them to submit asynchronous tasks. To create a thread pool, add a stanza similar to the following into Camel's Spring configuration, inside the camelContext:

<threadPool id="smallPool" threadName="pdfWriter"
 poolSize="5" maxPoolSize="30" maxQueueSize="50"/>

This pool can then be used as normal to invoke routes asynchronously:

<route>
    <from uri="direct:start"/>
    <to uri="log:start"/>
    <threads executorServiceRef="smallPool">
        <to uri="log:hello"/>
    </threads>
</route>

but this is not what we're after. Instead, we can inject this pool into an AsyncProcessor where we can submit a task to it. In the following example, the processor with create an instance of a CircularByteBuffer and give its OutputStream to the PDF generation process running in a separate thread to write to, and immediately return the associated InputStream as a response (without blocking or buffering everything) to be consumed by the client.

@Component
public class PdfGenerationProcessor implements AsyncProcessor {
    @Resource(name="smallPool")
    private ExecutorService smallPool;
    @Override
        public void process(Exchange exchange) throws Exception {
        AsyncProcessorHelper.process(this, exchange); //Wrap synchronous invocations
    }
    @Override
    public boolean process(Exchange exchange, AsyncCallback callback) {
       CircularByteBuffer buffer = new CircularByteBuffer(1024 * 100); //Buffer a 100K
       smallPool.submit(new PDFGenerator(exchange, callback, buffer.getOutputStream())); //Generate the PDF in a separate thread
       exchange.getIn().setBody(buffer.getInputStream()); //Immediately return the stream for the client to read from
       return false; //Signifies that the job will be performed asynchronously
   }
   private class PDFGenerator implements Runnable {
       private Exchange exchange;
       private AsyncCallback callback;
       private OutputStream out;
       private PDFGenerator(Exchange exchange, AsyncCallback callback, OutputStream out) {
           this.exchange = exchange;
           this.callback = callback;
           this.out = out;
       }
       @Override
       public void run() {
           try {
               generatePDF(out); //Actual logic for generating the file and writing it to the stream is here
           } catch (Exception e) {
               exchange.setException(e); //Async processors must not throw exceptions and must add them to the Exchange instead
           } finally {
               // callback must be invoked
               callback.done(true);
               //Cleanup, close streams etc.
               try{out.flush(); out.close();} catch(Exception e) {/*ignore*/}
           }
       }
    }
}

References

• The library used here (CircularByteBuffer) is a convenient implementation of piped streams (see more here). To use it, add this to Maven:

  <dependency>
      <groupId>org.ostermiller</groupId>
      <artifactId>utils</artifactId>
      <version>1.07.00</version>
  </dependency>
  

• Camel in Action, chapter 10 has very good guides for concurrency in Camel

Spring Security Run-As example using annotations and namespace configuration

Spring Security offers an authentication replacement feature, often referred to as Run-As, that can replace the current user's authentication (and thus permissions) during a single secured object invocation. Using this feature makes sense when a backend system invoked during request processing requires different privileges than the current application.
For example, an application might want to expose a financial transaction log to the currently logged in user, but the backend system that provides it only permits this action to the members of a special "auditor" role. The application can not simply assign this role to the user as that would potentially permit them to execute other restricted actions. Instead, the user can be given this right exclusively for viewing their transaction log.

Only two classes are used to implement this feature. Instances of RunAsManager are tasked with producing the actual replacement authentication tokens. A sensible default implementation is already provided by Spring Security. As with other types of authentication, it is also necessary to register an instance of an appropriate AuthenticationProvider.

<bean id="runAsManager"
    class="org.springframework.security.access.intercept.RunAsManagerImpl">
  <property name="key" value="my_run_as_key"/>
</bean>

<bean id="runAsAuthenticationProvider"
    class="org.springframework.security.access.intercept.RunAsImplAuthenticationProvider">
  <property name="key" value="my_run_as_key"/>
</bean>

Tokens produced by runAsManager are signed with the provided key (my_run_as_key in the example above) and are later checked against the same key by runAsAuthenticationProvider, in order to mitigate the risk of fake tokens being provided. These keys can have any value, but need to be the same in both objects. Otherwise, runAsAuthenticationProvider will reject the produced tokens as invalid.

If an instance is registered, RunAsManager will be invoked by AbstractSecurityInterceptor for every intercepted object invocation for which the user has already been given access. If RunAsManager returns a token, this token will be used be used instead of the original one for the duration of the invocation, thus granting the user different privileges. There are two key points here. In order for the authentication replacement feature to do anything, the call has to actually be secured (and thus intercepted), and the user has to already have been granted access.

To register a RunAsManager instance with the method security interceptor, something similar to the following is needed:

<global-method-security secured-annotations="enabled" run-as-manager-ref="runAsManager"/>

Now, all methods secured by the @Secured annotation will be able to trigger RunAsManager. One important point here is that global-method-security will only work in the Spring context in which it is defined. In Spring MVC applications, there usually are two Spring contexts: the parent context, attached to ContextLoaderListener, and the child context, attached to DispatcherServlet. To secure Controller methods in this way, global-method-security must be added to DispatcherServlet's context. To secure methods in beans not in this context, global-method-security should also be added to ContextLoaderListener's context. Otherwise, security annotations will be ignored.

The default implementation of RunAsManager (RunAsManagerImpl) will inspect the secured object's configuration and if it finds any attributes prefixed with RUN_AS_, it will create a token identical to the original, with the addition of one new GrantedAuthorty per RUN_AS_ attribute found. The new GrantedAuthority will be a role (prefixed by ROLE_ by default) named like the found attribute without the RUN_AS_ prefix.

So, if a user with a role ROLE_REGISTERED_USER invokes a method annotated with @Secured({"ROLE_REGISTERED_USER","RUN_AS_AUDITOR"}), e.g.

@Controller
public class TransactionLogController {

 @Secured({"ROLE_REGISTERED_USER","RUN_AS_AUDITOR"}) //Authorities needed for method access and authorities added by RunAsManager prefixed with RUN_AS_
 @RequestMapping(value = "/transactions",  method = RequestMethod.GET) //Spring MVC configuration. Not related to security
 @ResponseBody //Spring MVC configuration. Not related to security
 public List<Transaction> getTransactionLog(...) {
  ... //Invoke something in the backend requiring ROLE_AUDITOR
 {

 ...  //User does not have ROLE_AUDITOR here
}

the resulting token created by RunAsManagerImpl with be granted ROLE_REGISTERED_USER and ROLE_AUDITOR. Thus, the user will also be allowed actions, normally reserved for ROLE_AUDITOR members, during the current invocation, permitting them, in this case, to access the transaction log.

To enable runAsAuthenticationProvider, register it as usual:

<authentication-manager alias="authenticationManager">
    <authentication-provider ref="runAsAuthenticationProvider"/>
    ... other authentication-providers used by the application ...
</authentication-manager>

This is all that is necessary to have the default implementation activated.

Still, this setting will not work for methods secured by @PreAuthorize and @PostAuthorize annotations as their configuration attributes are differently evaluated (they are SpEL expressions and not a simple list or required authorities like with @Secured) and will not be recognized by RunAsManagerImpl. For this scenario to work, a custom RunAsManager implementation is required, as, at least at the time of writing, no applicable implementation is provided by Spring.

A custom RunAsManager implementation for use with @PreAuthorize/@PostAuthorize

A convenient implementation relying on a custom annotation is provided below:

public class AnnotationDrivenRunAsManager extends RunAsManagerImpl {

    @Override
    public Authentication buildRunAs(Authentication authentication, Object object, Collection<ConfigAttribute> attributes) {
        if(!(object instanceof ReflectiveMethodInvocation) || ((ReflectiveMethodInvocation)object).getMethod().getAnnotation(RunAsRole.class) == null) {
            return super.buildRunAs(authentication, object, attributes);
        }

        String roleName = ((ReflectiveMethodInvocation)object).getMethod().getAnnotation(RunAsRole.class).value();
       
        if (roleName == null || roleName.isEmpty()) {
            return null;
        }

        GrantedAuthority runAsAuthority = new SimpleGrantedAuthority(roleName);
        List<GrantedAuthority> newAuthorities = new ArrayList<GrantedAuthority>();
        // Add existing authorities
        newAuthorities.addAll(authentication.getAuthorities());
        // Add the new run-as authority
        newAuthorities.add(runAsAuthority);

        return new RunAsUserToken(getKey(), authentication.getPrincipal(), authentication.getCredentials(),
                newAuthorities, authentication.getClass());
    }
}

This implementation will look for a custom @RunAsRole annotation on a protected method (e.g. @RunAsRole("ROLE_AUDITOR")) and, if found, will add the given authority (ROLE_AUDITOR in this case) to the list of granted authorities. RunAsRole itself is just a simple custom annotation:

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface RunAsRole {
    String value();
}

This new implementation would be instantiated in the same way as before:

<bean id="runAsManager"
    class="org.springframework.security.access.intercept.RunAsManagerImpl">
  <property name="key" value="my_run_as_key"/>
</bean>

And registered in a similar fashion:

<global-method-security pre-post-annotations="enabled" run-as-manager-ref="runAsManager">
    <expression-handler ref="expressionHandler"/>
</global-method-security>

The expression-handler is always required for pre-post-annotations to work. It is a part of the standard Spring Security configuration, and not related to the topic described here. Both pre-post-annotations and secured-annotations can be enabled at the same time, but should never be used in the same class. The protected controller method from above could now look like this:

@Controller
public class TransactionLogController {

 @PreAuthorize("hasRole('ROLE_REGISTERED_USER')") //Authority needed to access the method
 @RunAsRole("ROLE_AUDITOR") //Authority added by RunAsManager
 @RequestMapping(value = "/transactions",  method = RequestMethod.GET) //Spring MVC configuration. Not related to security
 @ResponseBody //Spring MVC configuration. Not related to security
 public List<Transaction> getTransactionLog(...) {
  ... //Invoke something in the backend requiring ROLE_AUDITOR
 {

 ... //User does not have ROLE_AUDITOR here
}

Varnish Cache and remember-me cookies

Automatically authenticating a previously logged in user upon their next visit (a feature often called "remember me") is an established Internet norm. While the exact implementations vary, they always rely on a special cookie that is set on the client and later recognized as a token signifying the client should be logged in automatically.

The problem

The cookie solution is perfectly fine, but in some environments, where cookies carry additional significance, it might be a source of problems. One such example is when the server is sitting behind a caching solution, such as Varnish. By default, Varnish will let all cookie-carrying requests pass right through it, without doing any processing or caching. This is a very sensible default behavior as it ensures that no personalized content will end up cached and returned to the wrong user, potentially revealing sensitive information. On the other hand, it also means that all clients sending any cookies (remember-me cookies included) will not benefit from the acceleration provided by the cache, nor will the server benefit from the decreased load in these cases as it will get hit every time. This will, of course, occur even if the cookies carry no information used for personalization of the content (as is the case with the remember-me cookie). Luckily, Varnish permits a very fine-grained handling of requests and responses through its excellent domain-specific configuration language, VCL. Yet, simply configuring Varnish to normally process requests carrying (only) the remember-me cookie is not a solution. The initial request carrying the remember-me cookie must pass through the cache and reach the application, so that the authentication process can take place, but all subsequent requests within the same session can be safely intercepted by Varnish (as long as they do not carry some other cookies with personalization info).

The problem that arises is how to distinguish the initial from all subsequents requests within the same session. Also, it must be taken into account that it is not predictable which URL within the application a cookie-carrying user will visit first. The user might visit the home page first, but might also land on some bookmarked page, or one they were sent to by a search engine. Checking the request for the presence of a session cookie might be enough, depending on whether this cookie is a temporary one or not. If it is temporary (and thus lost when the browser closes), this solution is probably enough. If the session cookie is persistent, it might get sent even after it had already expired, so its presence is not enough to determine whether the user has an active session.

A solution

One easy way to side-step all this complexity is to introduce an additional surely-temporary cookie which can be used as a flag indicating that the user has already signed in and that the request can be safely intercepted. Since this is a Java blog, the proposed solution will be demonstrated utilizing Spring Security, the platform's de facto standard security framework, but the general principle is reusable in any technology. Spring Security allows custom logic to fire after a successful log-in by implementing and registering an AuthenticationSuccessHandler. This is exactly the place where the new cookie should be added to the response.

Example

As with everything else in Spring, there are multiple ways to register a custom handler, but the most usual way is to add authentication-success-handler-ref attribute to the form-login element in your security context configuration XML.

<form-login ... authentication-success-handler-ref="authenticationSuccessHandler" ... />

<beans:bean id="authenticationSuccessHandler" class="com.example.security.AuthenticationSuccessHandler"/>

The class implementing the behavior should look similar to the following:

public class AuthenticationSuccessHandler extends SavedRequestAwareAuthenticationSuccessHandler {
     @Override
     public void onAuthenticationSuccess(HttpServletRequest request, HttpServletResponse response, Authentication authentication) throws ServletException, IOException {
        Cookie varnishCookie = new Cookie("VARNISH", "true");
        varnishCookie.setPath("/");
        varnishCookie.setMaxAge(-1); //It is very important that this cookie is temporary
        response.addCookie(varnishCookie);
     }
}

On Varnish side, it is enough to allow the request to pass if the remember-me cookie is present and the flag-cookie absent (signifying that the current request is the initial one):

if (req.http.cookie !~ "VARNISH" && req.http.cookie ~ "REMEMBER_ME") {
  return(pass);
}

This way, requests that should auto log-in the user will succeed, while subsequent ones will be intercepted normally, benefiting from Varnish.

Notes

• Since there is bound to be some part of the page that will be specific to the logged-in user, include that part using ESI, and exclude that URL from Varnish processing. Varnish supports ESI:include so the setup is relatively simple.

Conversation scope: CDI (JSR-299) vs Seam 2

CDI (JSR-299) is the new Java standard for contextual type-safe dependency injection and as such it is an integral part of Java EE 6 platform. Still, it will also work in any other environment, be it a servlet container or simple Java SE. It was insipered by Seam 2 (and what is therein known as 'bijection') and Guice.

The Naming Game

Initially, CDI was known as WebBeans but the name had been changed before the spec was finalized. The reference implementation is called Weld but was also at some point called WebBeans. Yet again, that name is now obsolete as should not be used. Thus, WebBeans now refers to... well... nothing, so you're free to forget all about it. You will still see the old name popping up around the Web occasionally but it should fade into oblivion soon enough. More info on this story can be found at the very beginning of the reference documentation.

Conversations

The existance of a built-in conversation scope in CDI will immediately lure most of the Seam 2 developers into a wrong assumption of familiarity. Wrong because although they serve the same purpose conversations in CDI and Seam 2 do not always behave identically.
While all Seam's conversations, both transient and long-running, invariantly survive redirects (unless specifically instructed not to through endBeforeRedirect=true), conversations in CDI will survive only if they are promoted to long-running (through conversation.begin() ) during the original request. A transient conversation will be destroyed at the end of the original request and a new one will be spawned for each redirect. In other words, without a long-running conversation, conversation scoped components in Seam 2 will behave (by default) as if they were in what you might know as flash scope from other frameworks and languages (this scope will also exist in Seam 3 with the related annotation @FlashScoped). Under the same conditions, @ConversationScoped beans in CDI will behave as if they were @RequestScoped. In case a long-running conversation is present, the behavior will be the same in both Seam 2 and CDI.

Reference documentation for some reason never states this explicitly so it can be very misleading for Seam 2 developers. Luckily though, there's a table on the official site mapping Seam 2 scopes to their CDI equivalents where possible and gives brief description of the differences.

Example

To further clarify this (probably needlessly), let's illustrate with a simple example implemented both in Seam 2 and CDI.
In order to keep everything at a bare minimum, we'll just create a single component (or bean if you prefer), named MessageBean, and a single Facelets view that accepts the new input and attempts to display the previous one after a redirect.
Note: Import and package statements are omitted from the following code listings.

Seam 2 version

MessageBean class:

@Name("msg")
@Scope(ScopeType.CONVERSATION)
public class MessageBean implements Serializable {

  private String message;

  public String getMessage() {
          return message;
  }

  public void setMessage(String message) {
    this.message = message;
  }

  public String redir() {
    return "redir";
  }
}

CDI version

You'll notice a striking resemblance to the Seam 2 version.

MesageBean class:

@Named("msg")
@ConversationScoped
public class MessageBean implements Serializable {

  // @Inject Conversation conversation;
  private String message;

  public String getMessage() {
    return message;
  }

  public void setMessage(String message) {
    this.message = message;
  }

  public String redir() {
    //if (conversation.isTransient())
    // conversation.begin();
    return "redir";
  }
}

Facelets view (the same in both cases):

Note: Again, extra headers are omitted.

input.xhtml:

<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:ui="http://java.sun.com/jsf/facelets"
xmlns:h="http://java.sun.com/jsf/html"
xmlns:f="http://java.sun.com/jsf/core">
<div>
Previous input: #{msg.message}
</div>

<h:form>
<h:inputText id="messageText" value="#{msg.message}" required="true"/>
<h:commandButton id="redirectButton" value="Redirect" action="#{msg.redir}"/>
</h:form>
</html>

Configuration (the same in both cases):

faces-config.xml:

<navigation-rule>
<navigation-case>
<from-outcome>redir</from-outcome>
<to-view-id>/input.xhtml</to-view-id>
<redirect />
</navigation-case>
</navigation-rule>

If you were to execute both these examples, you'd soon realize the difference between the frameworks. While Seam 2 version keeps your input across the redirect and displays it on the next rendering, even without promoting the conversation, CDI will destroy the context on redirect leaving you with no message to display. Note that if the commented lines in the CDI version of MessageBean were to be uncommented, thus promoting the conversation to a long-running one, the message would survive, together with the whole conversation context (which would afterwards be reused in the next cycle in this case). Normally, you'd also want a way to end the conversation at some point through conversation.end() instead of waiting for the timeout (which is ultimately decided by the server).

Download

Below you can find both implementations as war files ready for deployment. The examples are meant to be deployed to JBoss AS so some tweaks (like adding Weld or any other CDI implementation jar to the classpath) might be needed in order to get it running on Tomcat or other servers/containers.

conversationCDI.war (tested on JBoss AS 6)
conversationsSeam.war (tested on JBoss AS 5, does not work on JBoss AS 6 for some reason)

References

Weld main site
Seam 2 tutorial

Global transactions in Seam

Transactions grew to be a necessity in most today's applications, and managing them grew to be a demanding task. If the application is complex enough it can evolve into a nightmare in its own right. Thus, offloading this task to a framework whenever possible is a very desirable approach.
Being a powerful feature-packed framework that it is, Seam offers exceptional support for transactional behavior that in many instances surpasses all others. One feature not seen in other frameworks are global transactions.

The confusion

This topic is regarded as somewhat arcane, despite being essentially simple. The reason for this is twofold. Firstly, the documentation regarding global transactions is relatively poor. Secondly, and more importantly, the exiting documentation does not call this feature global transactions, and this is the term used most widely over the internet (it was originally coined by Dan Allen is his book Seam in Action, often regarded as the "default" book for Seam).

Clearing it up

In essence, global transactions refer to the two or three transactions that wrap each request in Seam. The first one wraps JSF phases beginning with Restore View (for JTA transactions) or Invoke Application (for resource-local transactions), and ending just before Render Response. The second wraps all page actions (if they are used), and the third wraps the Render Response phase. During this final transaction, context flushing is disabled, effectively rendering the whole transaction read-only.
In this fashion, Seam accomplishes a couple of things:

• an error in page preparation or rendering will never role back a successfully executed business logic,


• view rendering is executed atomically, which not only avoids opening and closing a transaction on every lazy initialization, but also guarantees isolation and guards against accidental changes of the state during this phase,


• page actions are executed atomically (with benefits similar to those mentioned above sans disabled context flushing).

This way, Seam effectively does away with a good portion of the most common problems of transaction management.
To effectively use global transactions, one should keep in mind that Seam turns them on by default. To turn them off, you'll need to disable Seam's transaction management all together. This is done by adding

<core:init transaction-management-enabled="false"/>

to the component descriptor file.

Notes

It should also be noted that, despite what can be read in some sources, @Transactional annotation is not unusable in conjunction with global transactions. The point here is that since there is an overarching transaction, no new transactions will be spawned to encompass annotated business methods, effectively ignoring @Transactional. Of course, an overarching transaction will only be present during a JSF postback. On non-JSF calls, @Transactional will still do it's job normally. This misunderstanding was caused by a somewhat ambiguous statement in Seam in Action.
To recap, global translations is just another name for (as Dan Allen would put it) "automatic transaction wrapped around the request". A useful feature which one should always keep in mind when developing applications in Seam.

Authentication and authorization with JBoss security domains

Authentication and authorization comprise the fundamentals of security, and as such, they are important aspects of almost any application. Having in mind that security is such a frequent issue, it comes as no surprise that many people have devised many different ways of carrying it out, and so we now have literally countless options to choose from. If you are going to deploy your application to JBoss AS, you can get the basic authentication and authorization set up in virtually no time. To carry out these tasks, JBoss uses the notion of a security domain overlaying the standard JAAS (Java Authentication and Authorization Service).

Configuring the data source (*-ds.xml)

In order to set up a security domain for your app to use, you first need to set up a data source against which you will check the user's credentials. More often than not, your source of data will be a relational database. JBoss conveniently provides templates for many populars databases, so setting up a data source should be a breeze. These templates can be found under
<JBoss home>/docs/examples/jca¹. Notice that all the filenames in this directory end with "-ds". This is the convention for naming the data source configuration files.

Let's assume we want to use MySQL. All we need to do, is make a copy of mysql-ds.xml, edit it to reflect our situation, and put it into the deployment directory. Editing this file is pretty straight forward, you decide on a JNDI name you want your data source bound to (I'll use MySqlDS), input your connection URL, username and password. There's really no need to change the driver class.

When this is done, you place this file under <JBoss home>/server/<profile name>/deploy². That's it for this step.

Configuring a security domain (login-config.xml)

Next, you need to edit JBoss' login-config.xml file (found under<JBoss home>/server/<profile name>/conf). There are other ways to set up the security domain, but is by far the easiest. All you need to do here is nest a snippet similar to the following inside the policy element.

<!-- My custom security domain -->
  <application-policy name="custom-domain">
   <authentication>
      <login-module code="org.jboss.security.auth.spi.DatabaseServerLoginModule"
        flag = "required">
         <module-option name="dsJndiName">java:/MySqlDS</module-option>
         <module-option name="principalsQuery">SELECT password FROM USERS WHERE username=?</module-option>
         <module-option name="rolesQuery">SELECT role, 'Roles' FROM ROLES WHERE username=?</module-option>
      </login-module>
   </authentication>
  </application-policy>

Pay attention that dsJndiName attribute value must be identical to the jndi-name you chose in your mysql-ds.xml, preceded by java:/.
principalsQuery is the SQL query used to retrieve the user's password which, of course, has to match the one entered, and rolesQuery is the SQL query used to retrieve the roles associated with the user (leave the 'Roles' part as it is, it's not clear from the JBoss' documentation what purpose it has).

Our security domain is now ready. The next thing to do would be to instruct our application to use it.

Declaring page-level security (web.xml)

Presume we have a web.xml with the following security constraints configured:

<security-constraint>
   <web-resource-collection>                     
      <web-resource-name>Secure Resource</web-resource-name>
      <url-pattern>/secure/*</url-pattern>           
   </web-resource-collection>
   <auth-constraint>                               
      <role-name>registereduser</role-name>  
   </auth-constraint>                              
  </security-constraint>                       
<login-config>
   <auth-method>FORM</auth-method>
   <form-login-config>
      <form-login-page>/login.html</form-login-page>
      <form-error-page>/error.html</form-error-page>
   </form-login-config>
</login-config>
<security-role>                                  
   <role-name>registereduser</role-name>
</security-role>
  <resource-ref>
    <res-ref-name>jdbc/mysql</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth>Container</res-auth>
  </resource-ref>

This tells our app server that only the users with the registereduser role can access the resources under /secure/ (this is the job of the url-pattern element). It also tells we are going to use a form to perform authentication (notice the auth-method element), and that this form is found on the page named login.html (the form-login-page element). The request gets redirected to the page specified under form-error-page in case the login failed. You can also use BASIC authentication method (just place BASIC instead of FORM inside auth-method element) . This will cause the browser to display a simple pop-up dialog that asks for username and password when a secured resource is requested. You don't need form-login-config for this approach.

Creating a login form (j_security_check)

The login page is obviously required to contain a login form. This form must specify j_security_check as it's action, and it also must have a username input field named j_username and a password input field named j_password.

This is how it might look like in it's simplest form:

<form name="loginForm" method="post" action="j_security_check">
<table>
    <tr>
        <td>User Name:</td>
        <td><input type="text" name="j_username"></td>
    </tr>
    <tr>
        <td>Password:</td>
        <td><input type="password" name="j_password"></td>
    </tr>
    <tr colspan="2">
        <td><input type="submit" value="login"></td>            
    </tr>
</table>
</form>

Binding the application to a security domain (jboss-web.xml)

So, web.xml dictates the security constraints, but there is no mention of how these constraints will be carried out. This is the job of the jboss-web.xml config file (which is, of course, JBoss specific). It is in this file where we specify what security domain we want to use for authentication. Here's how it should look like in this case:

<?xml version="1.0" encoding="UTF-8"?>
<jboss-web>
    <security-domain>java:/jaas/custom-domain</security-domain>
    <resource-ref>
        <res-ref-name>jdbc/mysql</res-ref-name>
        <res-type>javax.sql.DataSource</res-type>
        <jndi-name>java:/MySqlDS</jndi-name>
    </resource-ref>
</jboss-web>

Pay attention to the security-domain element. It is necessary to prefix the domain name with java:/jaas/, and the name its self must be exactly the same as the one you typed into the login-config.xml file.

That's it! Now every unauthenticated request to the secure resource (under /secure/, as specified in web.xml) will first be redirected to the login page (or, in case of BASIC auth-method, a login pop-up will displayed). If the user logs in successfully and is authorized i.e. associated with any of the required roles (only registereduser in our case), the requested resource will be displayed. Otherwise, if the login attempt fails, or the user doesn't have any of the required roles, the error page will be displayed instead. Users stay logged in for the entire duration of the session.

Method-level security (isUserInRole)

Declarative security in web.xml is enough if you only need page-level security (based on the URL pattern), but if you need to dynamically check user's role on a method level, you can do so by calling isUserInRole("registereduser") on a request object (acquired from the ExtrnalContext). Here's a short example of a method doing this:

public Boolean isRegisteredUser() {
HttpServletRequest httpServletRequest =
(HttpServletRequest) FacesContext.getCurrentInstance() //first get the current FacesContext instance
.getExternalContext() //than get the ExternalContext
.getRequest(); //get the underlying request
// return True if this request was issued by a user with a "registereduser" role
return httpServletRequest.isUserInRole("registereduser"); 
}

You can get the username in pretty much the same way, just call getRemoteUser() instead of isUserInRole("...").

Notes:
¹ <JBoss home> refers to your JBoss installation directory (the same as JBOSS_HOME environmental variable).
² <profile name> refers to your deployment profile name (you will probably be using default).

Validators in JSF

In JSF, validators are components that provide a mechanism for clean and easy validation of user input and, if necessary, generation of messages that can be displayed back to the client.

JSF comes with some basic built-in validators, but it allows for new, custom ones, to be added by the developer.

Built-in validators

The following validators are available out of the box:

• f:validateDoubleRange: Checks whether a numeric input (convertible to double) is within a specified range.
• f:validateLength: Checks if the string input length is within a given range.
• f:validateLongRange: Checks whether a numeric input (convertible to long) is within a given range.


In order to be used, a validator needs to be nested into an h:input component that requires it.
To dictate the boundaries of the acceptable range, you need to specify the values for the minimum and/or maximum attributes to each of these validators.

Let's exemplify this. Assume we were creating an application that calculates monthly rates for the chosen loan. The client is expected to input the number of months they require the loan for, but our application does not allows this to be less than 6 or greater than 120 (or 10 years).

If we had a backing bean called loansManager and, within it, a HtmlInputText field, the component we would use would look like this:

<h:inputText id="account" required="true"
binding="#{loansManager.client.accountNumber}"
requiredMessage="Value is required!">
<f:validator validatorId="AccountNumberValidator"/>
</h:inputText>

Custom validators

If you need validation beyond the scope of the afore mentioned built-in components, you will have to write a custom validator to take care of your requirements.

You have two options here, to create a validator class or to create a validator method in one of your backing beans.

The first approach means implementing the Validator interface and it's validate method.

This time assume our application expects the client to input his account number in form ***.*******.**, where each * represents one character (probably should be a digit, but let's keep it simple).

The implementing class would then look like this:

package loans.validators;

import javax.faces.application.FacesMessage;
import javax.faces.component.UIComponent;
import javax.faces.context.FacesContext;
import javax.faces.validator.Validator;
import javax.faces.validator.ValidatorException;

public class AccountNumberValidator implements Validator {

 public AccountNumberValidator() {
 }

 public void validate(FacesContext ctxt, UIComponent cmp, Object val) {
  
  String message = null;

  try {
   String[] parts = ((String)val).split("-");
   if (parts.length < 3)
    message = "Wrong account number!";
   else {
    if (parts[0].length() != 3 || parts[1].length() != 7 || parts[2].length() != 2)
     message = "Wrong account number!";
   }
  } catch (Exception e){}

  if (message != null) {
   FacesMessage msg = new FacesMessage(
     FacesMessage.SEVERITY_ERROR, message, message);
   throw new ValidatorException(msg);
  }
 }
}

To register this validator, you would have to add the following snippet to your faces-config.xml file:

<validator>
<validator-id>AccountNumberValidator</validator-id>
<validator-class>loans.validators.AccountNumberValidator</validator-class>
</validator>

Now, you can add your validator to any h:input component that requires it.

For example:

<h:inputText id="account" required="true"
binding="#{loansManager.client.accountNumber}"
requiredMessage="Value is required!">
<f:validator validatorId="AccountNumberValidator"/>
</h:inputText>

The second option, mentioned earlier, is writing a validator method instead. For this, we would make a validateAccountNumber method in our loansManager backing bean. The method should look like this:

public void validateAccountNumber(FacesContext ctxt, UIComponent cmp, Object val) {
  
  String message = null;

  try {
   String[] parts = ((String)val).split("-");
   if (parts.length < 3)
    message = "Wrong account number!";
   else {
    if (parts[0].length() != 3 || parts[1].length() != 7 || parts[2].length() != 2)
     message = "Wrong account number!";
   }
  } catch (Exception e){}

  if (message != null) {
   FacesMessage msg = new FacesMessage(
     FacesMessage.SEVERITY_ERROR, message, message);
   ctxt.addMessage(cmp.getClientId(ctxt), mess);
  }
 }

Note that this time, instead of throwing a validator exception, we're manually adding a message the FacesContext's queue. In the previous example this was done automatically.

To use this new validator, you would add it to your h:input component like this:

<h:inputText id="account" required="true"
binding="#{loansManager.client.accountNumber}"
validator="#{loansManager.validateAccountNumber}"
requiredMessage="Value is required!"/>

Note:
You might as well do validation anywhere inside your application and just add the message to the FacesContext in the same manner you've seen earlier, but this has one important constraint. In place of cmp.getClientId(ctxt) inside
ctxt.addMessage(cmp.getClientId(ctxt), msg);
you would have to hard code the component id:

ctxt.addMessage("account", msg);

since you no longer have the reference to the component itself.
Also, you might put a global message (not bound to any component) into a FacesContext message queue with

ctxt.addMessage(null, msg);

but these messages can only be displayed with <h:messages/> element.