That Java Thing

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

2010-05-18T14:23:00.000-07:00

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

2010-03-14T16:00:00.001-07:00

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, the 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

2009-05-30T06:18:00.000-07:00

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

2009-04-05T04:21:00.000-07:00

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.

Extended Persistence Context

2009-04-04T11:54:00.000-07:00

Extended persistence context is an interesting feature of the JPA specification. It allows one to declare that the injected EntityManager lives beyond the scope of the JTA transaction, that is, to extend it to the lifetime of the stateful session bean itself. This is achieved with the following annotation:

@PersistenceContext(type=PersistenceContextType.EXTENDED) EntityManager em;

Doing this has a couple of implications.
First of all, within the extended persistence context, managed entities remain managed even after the transaction commits (or is rolled back). This behavior is very different than that of a transaction scoped context, were entities get detached at the end of the transaction.
Second implication important to note is that changes done to the managed entities from outside of a transaction will not be propagated to the database immediately, and will be buffered instead. In order to get the changes reflected in the database, the EntitiyManager needs to be accessed from a transaction context and flushed (by invoking it's flush() method).

For obvious reasons, extended persistence context is only available within stateful Session Beans.

The most frequently quoted example of use is a multi-step conversation with a client, where the data that is to be persisted in a single transaction is acquired form a client in a series of steps with arbitrary periods of time in between. In this scenario, changes are sequentially applied to the managed entity in question, and the EntityManager is flushed at the very end of the conversation.

To illustrate this, image you were dealing with a multi-page client registration form. On each page, the client is expected to input some information about themselves, but each time the information pertains to a different aspect. For example, the first page could ask for general details, like name and title, the second would deal with the contact info, and the third could ask for some optional data, like an average income or a favorite hobby.
Now, to achieve this, you could create a stateful bean similar to the following:

@Stateful
public class RegistrationBean implements Registration
{
   @PersistenceContext(type=PersistenceContextType.EXTENDED) EntityManager em;

   private Customer customer;

   public long createCustomer(String name, String lastName)
   {
      customer = new Customer();
      customer.setName(name);
      customer.setLastName(lastName);
      em.persist(customer);
      return customer.getId();
   }

   public void setContacts(String address, String phoneNumber, String email)
   {
      customer.setAddress(address);
      customer.setPhoneNumber(phoneNumber);
      customer.setEmail(email);
   }

   public void setOptionals(...)
   {
      ...
   }

  @TransactionAttribute(TransactionAttributeType.REQUIRED)
   public void confirmRegistration() {
      em.flush();
   }
}

In conclusion, it's worth to note that the same effect could have been achieved by wrapping the whole conversation in a single user-managed transaction, but that it still makes more sense to exploit the power of an extended persistence context as it provides both a simpler and cleaner solution.