Restrictions
Last updated
Was this helpful?
Last updated
Was this helpful?
The ColdBox restrictions class allows you to create criterions upon certain properties, associations and even SQL for your ORM entities. This is the meat and potatoes of criteria queries, where you build a set of criteria to match against or in SQL terms, your WHERE statements.
The ColdBox criteria class offers most of the criterion methods found in the native hibernate Restrictions class:
If one isn't defined in the CFML equivalent, just call it as it appears in the Javadocs and we will proxy the call to the native Hibernate class for you.
You can get a direct reference to the Restrictions class via the Base/Virtual ORM services (getRestrictions()), or the Criteria object itself has a public property called restrictions which you can use rather easily. We prefer the latter approach. Now, please understand that the ColdBox Criteria Builder masks all this complexity and in very rare cases will you be going to our restrictions class directly. Most of the time you will just be happily concatenating methods on the Criteria Builder.
Ok, now that the formalities have been explained let's build some criterias.
To build our criteria queries we can 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. 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.
Where the property value is between two distinct values
Group expressions together in a single conjunction (A and B and C...) and return the conjunction
Group expressions together in a single disjunction (A or B or C...)
Where a property equals a particular value, you can also use eq()
Where a property is greater than a particular value, you can also use gt()
Where a one property must be greater than another
Where a property is greater than or equal to a particular value, you can also use ge()
Where one property must be greater than or equal to another
Where an object's id equals the specified value
A case-insensitive 'like' expression
Where a property is contained within the specified list of values, the property value can be a collection (struct) or array or list, you can also use in()
Where a collection property is empty
Where a collection property is not empty
Where a collection property is false
Where a property is null
Where a property is NOT null
Where a property is less than a particular value, you can also use lt()
Where a one property must be less than another
Where a property is less than or equal a particular value, you can also use le()
Where a one property must be less than or equal to another
Equivalent to SQL like expression
Where a property does not equal a particular value
Where one property does not equal another
Where a collection property's size equals a particular value
Where a collection property's size is greater than a particular value
Where a collection property's size is greater than or equal to a particular value
Where a collection property's size is less than a particular value
Where a collection property's size is less than or equal a particular value
Where a collection property's size is not equal to a particular value
Use arbitrary SQL to modify the resultset
Return the conjuction of N expressions as arguments
Return the disjunction of N expressions as arguments
Return the negation of an expression. You can also use not()
Returns if the property is true
You can also use the add() method to add a manual restriction or array of restrictions to the criteria you are building.
But as you can see from the code, the facade methods are much nicer.
Every restriction method you see above or in the docs can also be negated very easily by just prefixing the method with a not .
There are times where you need if statements in order to add criterias based on incoming input. That's ok, but we can do better by adding a when( test, target ) function that will evaluate the test argument or expression. If it evaluates to true then the target closure is called for you with the criteria object so you can do your criterias:
Adobe ColdFusion may throw an "Invalid CFML construct" error for certain CBORM methods that match , such as .and(), .or(), and .eq(). You can use .$and(), .$or(), and .isEq() to avoid these errors and build cross-engine compatible code.