1 of 7

Detached Criteria Builder

Hibernate also supports the concept of detached criterias. They are most useful for join conditions, subselects, and to query outside the current session.

Some applications need to create criteria queries in "detached mode", where the Hibernate session is not available. Then you can execute the search in an arbitrary session.

To create an instance of Detached Criteria Builder, simply call the createSubcriteria() method on your existing criteria.

If you use ORM in your ColdBox apps, you are hopefully already taking full advantage of Criteria Builder, ColdBox’s powerful, programmatic DSL builder for Hibernate Criteria queries (and if you’re not using it, you should!). With the new Detached Criteria Builder, you can expand the power and flexibility of your criteria queries with support for criteria and projection subqueries, all while using the same intuitive patterns of Criteria Builder. No fuss, just more flexibility and control for your criteria queries!

"Some applications need to create criteria queries in "detached mode", where the Hibernate session is not available. It also allows you to express subqueries." Hibernate Docs

For more information about Detached Criteria and Subqueries, check out the following Hibernate documentation:

Hibernate Docs: http://docs.jboss.org/hibernate/orm/3.5/reference/en/html/querycriteria.html#querycriteria-detachedqueries
Hibernate DetachedCriteria: http://docs.jboss.org/hibernate/orm/3.5/api/org/hibernate/criterion/DetachedCriteria.html
Hibernate Subqueries: http://docs.jboss.org/hibernate/orm/3.5/api/org/hibernate/criterion/Subqueries.html

INFO The best place to see all of the functionality of the Detached Criteria Builder is to check out the latest API Docs.

Getting Started

Whether you want to create a criteria subquery, or a projection subquery, you'll first need to get a new instance of the Detached Criteria Builder class. Since all of the subqueries we're creating are being added to our main criteria query either as a criteria or a projection, we can get the Detached Criteria Builder like so:

// Get a reference to a criteria builder from an ORM base or virtual service
c = ormservice.newCriteria();

// detached criteria builder
c.createSubcriteria( entityName='Car', alias='CarSub' );

The arguments for the createSubcriteria() method are:

Once the Detached Criteria Builder is defined, you can add projections, criterias, and associations, just like you would with a normal Criteria Builder.

Examples

c.newCriteria( entityName=‘Car’ );

// all-in-one criteria subquery
c.add(
   c.createSubcriteria( ‘Car’, ‘CarSub’ )
    .withProjections( property=’CarID’ )
    .isEq( ‘Make’, ‘Ford’ )
    .propertyIn( ‘CarID’ )
).list();

// detached criteria builder separately, then add as criteria
var dc = c.createSubcriteria( ‘Car’, ‘CarSub’ )
          .withProjections( property=’CarID’ )
          .isEq( ‘Make’, ‘Ford’ );
// add criteria subquery
c.add( dc.propertyIn( ‘CarID’ ) );

Projections

When using Detached Criteria Builder for criteria or projection subqueries, you must use a projection. If you think about it from a SQL perspective, this makes sense. After all, we need our subquery to return a specific result (property values, a count, etc.) which will be compared to a property value on the root table (in the case of a criteria subquery), or which will be returned as a valid column value (in the case of a projection subquery).

All of the projections available for Criteria Builder are also available for Detached Criteria Builder.

Examples

Be careful when using projections and adding criterias to your query. Hibernate does not work well with projections and alias definitions, so if you want to add a criteria you must use this.yourPropertyName to tell Hibernate not to use the alias and build a correct SQL.

Subqueries

If you are using Detached Criteria Builder for a criteria subquery, you will also need to use one of the methods from the ColdBox subqueries class. This is what will ultimately bind the subquery result to the root entity.

The most important thing to remember is that this subquery is what needs to be added as a criterion to your criteria query. So whether you are doing a simple subquery or building up a complex detached criteria, the result of one of the methods below should be what is added as a criterion to the criteria query (see example below).

Examples

// wrong way...will fail because the subquery method “propertyIn()” is not what is added
c.add(
   c.createSubcriteria( ‘Car’, ‘CarSub’ )
    .withProjections( property=’CarID’ )
    .propertyIn( ‘CarID’ )
    .isEq( ‘Make’, ‘Ford’ )
).list();

// right way...since propertyIn() is last in the chain, it’s value will be what is ultimately added as a criteria
c.add(
   c.createSubcriteria( ‘Car’, ‘CarSub’ )
    .withProjections( property=’CarID’ )
    .isEq( ‘Make’, ‘Ford’ )
    .propertyIn( ‘CarID’ )
).list();

// right way--split up
dc = c.createSubcriteria( ‘Car’, ‘CarSub’ )
  .withProjections( property=’CarID’ )
  .isEq( ‘Make’, ‘Ford’ );
c.add( dc.propertyIn( ‘CarID’ ) ).list();

DetachedSQLProjection()

Besides using it for creating criteria subqueries, Detached Criteria Builder can also be used in conjunction with the new detachedSQLProjection() method to return a projected result based on a subquery. The detachedSQLProjection() method can be called just like any other Criteria Builder projection.

Examples

c = newCriteria();
c.withProjections(
        detachedSQLProjection= 
          c.createSubcriteria( "Car", "Car2" )
           .withProjections( count="Car2.Year" )
           .isLT( "Year", javaCast( "int", 2006 ) )
           .isEQ( "CarID", "{alias}.CarID" ),           
        groupProperty="Make"
).list();

INFO If you need to use a property from the root entity in one of your criterias, simply prepend the property name with {alias}. MORE otice how a subquery method was not used in this example of the Detached Criteria Builder.

Criterias

All of the same criterias defined in Criteria Builder can be utilized in a Detached Criteria Builder as well. Easy, huh?

Here they go again...

To build our criteria queries we will mostly use the methods in the criteria object or go directly to the restrictions object for very explicit criterions as explained above. We will also go to the restrictions object when we do conjunctions and disjunctions, which are fancy words for AND's, OR's and NOT's. So to build criterias we will be calling these criterion methods and concatenate them in order to form a nice DSL language that describes what we will retrieve. Once we have added all the criteria then we can use several other concatenated methods to set executions options and then finally retrieve our results or do projections on our results.

So let's start with all the different supported criterion methods in the Criteria object, which are the most commonly used. If you need to use methods that are not in the Criteria object you will request them via the Restrictions object, which can proxy calls to the underlying Hibernate native Restrictions class (http://docs.jboss.org/hibernate/core/3.5/javadoc/org/hibernate/criterion/Restrictions.html).

Note In some cases (isEq(), isIn(), etc), you may receive data type mismatch errors. These can be resolved by using JavaCast on your criteria value.

c.isEq("userID", JavaCast( "int", 3 ));

You can also use the add() method to add a manual restriction or array of restrictions to the criteria you are building.

c.add( c.restrictions.eq("name","luis") )

But as you can see from the code, the facade methods are much nicer.

Associations

Yes, you can also create associations in Detached Criteria Builder, just like you would with Criteria Builder. Go on, make some uber-complicated queries!

Here we go!...

You can also navigate associations by nesting the criterias using the createCriteria("association_name") method and then concatenating the properties of the association to query upon. You will basically be switching the pivot point of the query.

var c = newCriteria("User");
var users = c.like("name","lui%")
     .createCriteria("admins")
          .like("name","fra%")
     .list();

var c = newCriteria("User");
var users = c.like("name","lui%")
     .withAdmins().like("name","fra%")
     .list();

You can also use a hibernate property approach which aliases the association much how HQL approaches it by using the createAlias("associationName","alias") method:

var c = newCriteria("User");
var users = c.like("name","lui%")
     .createAlias("admins","a")
     .eq("a.name","Vero")
     .list();

Let's see the method signatures for these guys:

createCriteria(required string associationName,numeric joinType)
createAlias(required string associationName, required string alias, numeric joinType)
with{AssociationName}( joinType )