Syntax of annotated methods for queries over in-memory Java collections

When you use annotated methods to query in-memory collections, the definitions of those methods must conform to the following syntax.
Read syntax diagramSkip visual syntax diagram
>>-@Select--(--sql--=--"--SQL-statement--"--)------------------->

>--+--------------------------------------------------------------------------------------+-->
   '-@Handler--(--+-parameterHandler--=--class-name----------------------------------+--)-'   
                  +-resultHandler--=--class-name-------------------------------------+        
                  +-resultHandler--=--class-name--,--parameterHandler--=--class-name-+        
                  +-rowHandler--=--class-name----------------------------------------+        
                  '-rowHandler--=--class-name--,--parameterHandler--=--class-name----'        

>--modifiers--return-type--method-name--(--+------------------------------------+--);-><
                                           | .-,------------------------------. |       
                                           | V                                | |       
                                           '---parameter-type--parameter-name-+-'       

To understand the conventions that are used in the syntax diagram, see How to read syntax diagrams.

Read syntax diagramSkip visual syntax diagram
return-type:

>>-+-Iterator<T>--------+--------------------------------------><
   +-List<T>------------+   
   +-Map<String,Object>-+   
   +-T------------------+   
   '-T[]----------------'   

@Select
Specifies that the method runs an SQL SELECT statement. This Java™ annotation signals that the corresponding method is a pureQuery method. The pureQuery Generator processes the interface to generate implementation for the method.
sql
Provides the SQL statement that to run when the associated method is invoked. With the exception of an added capability to refer to a collection in the FROM clause, the syntax must conform to the SQL92 standard syntax. pureQuery also defines a number of parameter markers. These markers correspond to input parameters in inline or annotated methods.
@Handler
Directs pureQuery to use a provided implementation class, instead of pureQuery's default procedure, when running the annotated method.
parameterHandler
Specifies an implementation of the com.ibm.pdq.handlers.ParameterHandler interface. If you specify this attribute, pureQuery uses the class to set the parameter values on the java.sql.PreparedStatement object for the SQL statement.
resultHandler
Specifies an implementation of the com.ibm.pdq.handlers.ResultHandler<RES> interface. If you specify this attribute, pureQuery uses the class to create the object that is returned by the annotated method. The class's handle() method processes the java.sql.ResultSet for an SQL statement and returns the contents in an Object of type <RES>.
rowHandler
Specifies an implementation of the com.ibm.pdq.handlers.RowHandler<ROW> interface. If you speicfy this attribute, pureQuery uses the class to create the object that represents each row of the query results that are returned by the annotated method. This class's handle() method processes one row from the java.sql.ResultSet for an SQL statement and returns the contents in an Object of type <ROW>.
return-type
Specifies the return type of the method.

The second table shows the possible return types for annotated methods that query in-memory collections.

Table 1. Key to the table of return types
Abbreviation Meaning
I Iterator
L List
M Map
O Object
S String
T Generic class, which can be a wrapper class for a primitive Java type, or a bean
Table 2. Return types according to type of annotation
  I<M<S,O>> I<T> L<M<S,O>> L<T> M<S,O> M<S,O>[] <T>
@Select X X X X X X X

When you use an annotated method, do not specify that a @Select returns a primitive Java type, or an Array, List, or Iterator of a primitive Java type.

Information regarding SQL null values is lost whenever information queried from SQL is stored in a primitive Java type. Also, Java requires that a generic method that specifies generic <T> class of a <primitive Java type>.class must return an instance of the wrapper class that is appropriate for that primitive Java type.

For example, Java does not allow method invocations such as this:
int tCount = myGenericMethod( int.class );
where this is the definition of myGenericMethod:
<T> T myGenericMethod( Class<T> cl );
The declared class of tCount must be Integer.
Integer tCount = myQuery.myGenericMethod( Integer.class );
Iterator<T>

Specifies that an Iterator object is returned, with each element corresponding to a row. The parameterized type T must be specified.

Iterators in pureQuery are of type ResultIterator. You must close them with the ResultIterator.close() method after you finish using them.

List<T>
Specifies that a List object of type T is returned. Each element corresponds to a row of the query result.
Map<String,Object>
Specifies that a Map object is constructed and returned. The return column labels of the specified SQL statement become the keys of the map. The column labels are converted to lowercase for closer conformity with common Java coding style. The corresponding column values from a row of the query result become the values of the Map object.
<T>

Specifies that a scalar or bean is returned. A scalar could be a wrapper such as Double, or a String, Date, or Timestamp.

If more than one row qualifies as a result of the query, the value from the first row is returned.

<T>[]
Specifies that an array of type T is returned, such as Employee[], Integer[], or String[]. Each element corresponds to a row of the query result.
method-name
Specifies the name of the interface method.
parameter-type parameter-name

These parameters are matched with the parameter markers specified in the SQL statement according to the rules below. These parameters can be scalar types, bean classes, or Map objects. If the SQL uses the :name notation for parameter references, the first parameter-type must be a bean or a Map. The property names from the bean or Map object are used for matching with the :name occurrences in the SQL string.

At least one parameter that is an Iterator, Array, or iterable List is required so that pureQuery can identify the corresponding SELECT statement as a query over an in-memory collection. Reference this parameter in the FROM clause of the SELECT statement by using the syntax that is described in Parameter markers in the FROM clause of queries over in-memory Java collections.

If the SQL uses the ? notation for parameter markers, you can provide only scalar values.

If you use the ?n notation, the corresponding parameters must be scalar types (unless they are in the FROM clause, in which case they must be collections or Array objects).

If you use the ?n.name notation, the corresponding parameters must be either bean classes or Map objects. The ?n and ?n.name notations can be mixed in a single query, but cannot be mixed with stand-alone ? parameter markers.


Feedback