Pitfalls in Constructing Java Persistence Query Language Queries, and
EJB 3.0 Interceptors -- Continued

Using an IN operator In a Conditional Expression

An IN operator in a conditional expression determines whether a value is in an item or in a set of items. An NOT IN operator determines whether a value is not in an item or not in a set of items.

The formal syntax for an IN or NOT IN comparison operator in a conditional expression looks like this:

The state_field_path_expression is the expression that contains the value for the comparison, and in_item is the item or set of items against which the value is checked.

For example, the expression o.country IN ('UK', 'US', 'FRANCE') is true if the value of o.country is UK, and false if the value of o.country is PERU. The expression o.country NOT IN ('UK', 'US', 'FRANCE') is false if the value of o.country is UK, and true if the value of o.country is PERU.

When you use an IN or NOT IN operator in a conditional expression, you need to keep the following in mind:

• The state_field_path_expression must have a string, numeric, or enum value. Other types are not supported.
• The item or set of items in in_item must have the same type as the state_field_path_expression.
• The result of the subquery must have the same type as the state_field_path_expression.

Here are some working examples:

Using Native Queries

The Java Persistence Query Language supports native queries. In other words, you can express a Java Persistence Query Language query using the SQL of the target database. Native queries are not guaranteed to be portable across databases.

The result of a native query can consist of entities, scalar values, or a combination of entities and scalar values.

When multiple entity types are returned by a native query, the entities must be specified and mapped to the column results of the SQL statement in a @SqlResultSetMapping annotation. The result set mapping metadata can then be used by the persistence runtime to map the JDBC results into the expected objects.

Here is an example in which a native SQL query returns entities of a single entity class. The entity class that specifies the type of the result is passed in as an argument. Because the native query returns a single entity type it does not require a @SqlResultSetMapping annotation. When executed, this query returns a Collection of all Order entities for the customer named "SUN_SALE".

The following query returns multiple entity types and so it requires a @SqlResultSetMapping annotation. The example assumes default metadata and column name defaults. Note that the @SqlResultSetMapping annotation always needs to be specified before the entity class definition.

The following code executes the native query:

Using NULL Values

It's important to keep the following in mind if you use a NULL value in a Java Persistence Query Language query:

• 'IS NULL' and '= NULL' have different semantics.
• Comparison or arithmetic operations with a NULL value always yield an unknown value.
• Two NULL values are not considered to be equal, the comparison yields an unknown value.

So the following query:

does not return any customers, even if there are customers who do not have a name. The reason is that the expression customer.name = NULL does not evaluate to true if the name is null. It evaluates to an unknown value. This is also the case for a query using an input parameter if you set the value of the input parameter to null.

The correct syntax for checking whether or not a singled-valued path expression or input parameter is a NULL value is:

For example, the following query:

For More Information

The Java Persistence Query Language is a full structured query language and includes language features for bulk update and delete operations, outer join operations, projection, and subqueries. For a description of the language see "Chapter 27: The Java Persistence Query Language" in the Java EE 5 Tutorial.

Running the Sample Code

To install and run the sample code that accompanies this tip:

1. If you haven't already done so, download Java EE 5 SDK from the Java EE Downloads Page, and install it.


2. Set the following environment variables:
   • JAVAEE_HOME. This should point to where you installed the Java EE 5 SDK.
   • ANT_HOME. This should point to where ant is installed. Ant is included in the Java EE 5 SDK bundle that you downloaded. (In Windows, it's in the lib\ant subdirectory.)
   • JAVA_HOME. This should point to the location of JDK 5.0 on your system. JDK is included in the Java EE 5 SDK bundle that you downloaded. (In Windows, it's in the jdk subdirectory.)
   Add $JAVA_HOME/bin, $ANT_HOME/bin, and $JAVAEE_HOME/bin to your PATH environment variable.


3. Download the sample package and extract its contents. The JPQL directory below ttdec2006jpql contains the source files and other support files for the sample.


4. Change to the JPQL directory and edit the build.xml file as appropriate. For example, set the value of javaee.home to where you installed the Java EE 5 SDK.


5. Start database server:
   
      $JAVAEE_HOME/bin/asadmin start-database

In response you should see output similar to this:

            ...

      start-db:
           [exec] Database started in Network Server mode on host 
           ... and port ...
      
           [exec] Starting database in the background.  Log 
           redirected to ...
           [exec] Command start-database executed successfully. 



6. Build and run the sample application. From the JPQL directory enter the following command:
   
      ant all
   
   

   In response you should see output produced by the Java Persistence Query Language queries shown in this tip. The output should look similar to this:
   
      ...
   
        [java] JPQL query for LIKE/ESCAPE with named parameters 
   SELECT c from Customer c WHERE c.name LIKE :pattern ESCAPE :e
   sc returns Customers: [ejbql.models.Customer@1264eab, ejbql.m
   odels.Customer@1e184cb]
        [java] JPQL query for LIKE/ESCAPE SELECT c FROM Customer 
   c WHERE c.name LIKE 'SUN\_%' ESCAPE '\' returns Customers: [e
   jbql.models.Customer@1264eab, ejbql.models.Customer@1e184cb]
        [java] JPQL query for ENUMERATED type SELECT c FROM Cust
   omer c WHERE c.status = :status returns Customers: [ejbql.mod
   els.Customer@1e184cb]
        [java] JPQL query for IN subquery SELECT o FROM Order o 
   WHERE o.customer.name IN (SELECT c.name FROM Customer c WHERE 
   c.customerId > 2) returns Orders: [ejbql.models.Order@1a99347
   , ejbql.models.Order@221e9e]
   ...
        
        [java] JPQL query for Native Query SELECT o FROM Order o 
   WHERE o.customer.name IN ('foo', 'SUN_SALE') returns Orders: 
   [ejbql.models.Order@1a99347]
   ...
   
        [java] JPQL query for NULL handling SELECT c FROM Custom
   er c WHERE c.name IS NULL returns Customers: []   
     

About the Author

Jie Lin Leng is a member of the Java Persistence Engineering group at Sun. She is currently involved in the development of the Java Persistence Query Language for EJB 3.0.

One of the new features introduced in the EJB 3.0 specification is interceptors. An interceptor is a method that you can interpose in the invocation flow of an enterprise bean. You can define an interceptor to intercept an enterprise bean's business methods -- the interceptor method runs before any of the bean's business methods are invoked. Or you can define an interceptor to intercept lifecycle events for an enterprise bean -- the interceptor method runs as a callback method for the bean's lifecycle events.

A recent Tech Tip introduced the concept of EJB 3.0 interceptors and described how to write multiple interceptors and chain them together. The following Tech Tip discusses how to add interceptors at the method level and further discusses interceptor ordering.

A sample package accompanies the tip. The code examples in the tip are taken from the source code of the sample (which is included in the package). The sample uses the Java EE 5 SDK. You can download the Java EE 5 SDK from the Java EE Downloads page.

An Example Bean

To demonstrate the concepts in this tip, let's use a simple stateless session bean named NumberUtilbean. The bean provides a set of simple utility methods, and implements a business interface named NumberUtil.

Here is what umberUtil looks like:

Note that the isOddNumber method is so trivial that it could have been implemented in client code. However, to demonstrate interceptors the method is included in the remote interface.

Class Level Interceptors

The previous tip showed how to define an interceptor and add it to a bean. It included as an example of an interceptor, a method profiler that prints the time it takes to run an intercepted business method. Let's create another method profiler that will be used as an interceptor. The new method profiler prints the time taken by each of the methods in NumberUtilBean

As explained in the previous tip, you define an interceptor with an @AroundInvoke method, and you can add the interceptor to a class using the @Interceptors annotation. Adding the interceptor at the class level ensures that the interceptor's around invoke methods are invoked before every business method in the class.

Here is the new method profiler, MethodProfileInterceptor:

Here is NumberUtilBeanwith the new interceptor added to the class:

Method Level Interceptors

Say you want to add an interceptor to NumberUtilBean that checks if an argument passed to its methods is null or not. You can easily add the interceptor to the class using the @Interceptors annotation. In this case, the interceptor's around invoke method is invoked before each bean method.

But what if you want to restrict the interceptor to a specific method in the bean? For example, suppose you want to validate that the parameter passed to the intToBytes() method in NumberUtilBean is not null. To do that, you need to specify the @Interceptors annotation at the method level rather than at the class level. This ensures that the interceptor's around invoke method is invoked only before the specific method.

Here is the code for an interceptor that checks if a parameter is not null:

   import javax.interceptor.AroundInvoke;
   
   public class NumberUtilArgumentsChecker {
   
       public NumberUtilArgumentsChecker() {
       }
   
       @AroundInvoke
       private Object validate(InvocationContext invCtx)
           throws Exception {
       
           Object[] params = invCtx.getParameters();
           if (params.length == 0) {
               throw new IllegalArgumentException(
                   invCtx.getMethod().getName()
                   + "Requires a non null argument");
           }
           
           return invCtx.proceed();
           
       }  

Notice how invCtx.getMethod().getName() is used to get the method name, which is added to the exception text if the parameter is null.

Here is the NumberUtilBean with the new interceptor added for the intToBytes() method:

   package com.sun.techtip2.interceptor;
   
   import javax.ejb.Stateless
   import javax.interceptor.Interceptors;
   
   @Interceptors(
    {com.sun.techtip2.interceptor.MethodProfileInterceptor.class})  
   @Stateless
   public class NumberUtilBean
      implements NumberUtil {
 
      public byte[] intToBytes(int val) {...}
      
      @Interceptors(
       {com.sun.techtip2.interceptor.NumberUtilArgumentsChecker.class})
      public int bytesToInt(byte[] data) {...}
      
      public boolean isOddNumber(int data) {...}
      
   }

Changing the Invocation Order of Interceptors

It's possible to have a class in which interceptors are defined at both the class level and the method level. In that case, it's important to know the order in which the interceptors are invoked. The EJB 3.0 specification declares the following invocation order if both class-level and method-level interceptors are specified:

1. Any interceptor classes defined on the bean class. These class-level interceptors are invoked in the order that they are specified in the @Interceptors annotation.
2. Any interceptors that are specified at the method level. These method-level interceptors are invoked in the order that they are specified in the @Interceptors annotation.
3. The interceptor method on the bean, if any.

Excluding Interceptors

In the method profiler example, the class-level interceptor, MethodProfileInterceptor, is run before all the methods in the NumberUtilbean class, including the isOddNumber() method. However the implementation of isOddNumber() is so trivial that it doesn't really need any profiling.

You could exclude the interceptor from running before the isOddNumber() method by removing it as a class-level interceptor and explicitly specifying it as method interceptor for only the intToBytes() and byteToInt() methods.

But there is an easier way to exclude interceptors from a method. You can use the @ExcludeClassInterceptors annotation to exclude class-level interceptors from a specific method. Let's use the @ExcludeClassInterceptors annotation to prevent MethodProfileInterceptor from being executed before the isOddNumber() method.

Here is the NumberUtilBean with the addition of the @ExcludeClassInterceptors annotation:

   package com.sun.techtip2.interceptor;
   
   import javax.ejb.Stateless;
   import javax.interceptor.Interceptors;
   import javax.interceptor.ExcludeClassInterceptors;
     
   @Interceptors(
     {com.sun.techtip2.interceptor.MethodProfileInterceptor.class})
   @Stateless
   public class NumberUtilBean
      implements NumberUtil {
 
      public byte[] intToBytes(int val) {...}
      
      @Interceptors(
        {com.sun.techtip2.interceptor.NumberUtilArgumentsChecker.class})
      public int bytesToInt(byte[] data) {...}
      
      @ExcludeClassInterceptors
      public boolean isOddNumber(int data) {...}
      
   }

Now MethodProfileInterceptor will be invoked only before the intToBytes() and bytesToInt() methods are run.

Running the Sample Code

1. If you haven't already done so, download Java EE 5 SDK from the Java EE Downloads Page, and install it.


2. Download the sample package to the <appsrv_install>/samples/javaee5/enterprise directory, where <appsrv_install> is where you installed the Java EE 5 application server. Ensure that you set up your environment as described in the <appsrv_install>/samples/javaee5/index.html file.


3. Extract the contents of the sample package:
   
      jar xvf ttdec2006intrcpt_2.jar


4. Change to the interceptor_2 directory. The directory contains the source files and other support files for the sample.


5. Start the Application Server by entering the following command:
   
      <appsrv_install>/bin/asadmin start-domain domain1


6. Build and run the sample application. From the interceptor_2 directory enter the following command:
   
         ant all
   }
   bpp-run-app-client:
        [echo] running application client container.
        [exec] intToBytes(1234) ==> 0 0 4 -46
        [exec] bytesToInt(intToBytes(1234))) ==> 1234
        [exec] isOddNumber(7) ==> true
   
   

Summary

EJB 3.0 interceptors give you an elegant way to extend the functionality of enterprise beans. They are especially useful for implementing crosscutting operations in a portable way.

A previous Tech Tip introduced interceptors and demonstrated the use of a class-level interceptors. Class-level interceptors are executed before every business method in a bean. This tip introduced method-level interceptors and demonstrated how these interceptors are executed for a specific method in addition to class-lLevel interceptors.

The tip also showed how to use the @ExcludeClassInterceptors annotation, which provides an elegant way to exclude class-level interceptors from executing before a specific method.

There are more advanced topics related to EJB interceptors, such as default interceptors and excluding default interceptors. Also, interceptors can declare dependency injection. This allows the container to inject resources and enterprise beans into interceptors.

About the Author

Mahesh Kannan is member of the EJB container team. He has been involved with Java EE development for the last 6 years.