This module provides you with several enhancements when interacting with the ColdFusion ORM via Hibernate. It provides you with virtual service layers, active record patterns, criteria and detached criteria queries, entity compositions, populations and so much more to make your ORM life easier!

Versioning

The ColdBox ORM Module is maintained under the Semantic Versioning guidelines as much as possible.Releases will be numbered with the following format:

<major>.<minor>.<patch>

And constructed with the following guidelines:

• Breaking backward compatibility bumps the major (and resets the minor and patch)

• New additions without breaking backward compatibility bumps the minor (and resets the patch)

• Bug fixes and misc changes bumps the patch

License

Apache 2 License: http://www.apache.org/licenses/LICENSE-2.0

Important Links

• Code: https://github.com/coldbox-modules/cbox-cborm

• Issues: https://github.com/coldbox-modules/cbox-cborm/issues

• Documentation: http://coldbox-orm.ortusbooks.com

Professional Open Source

The ColdBox ORM Module is a professional open source software backed by Ortus Solutions, Corp offering services like:

• Custom Development

• Professional Support & Mentoring

• Training

• Server Tuning

• Security Hardening

• Code Reviews

• Much More

HONOR GOES TO GOD ABOVE ALL

Because of His grace, this project exists. If you don't like this, then don't read it, it's not for you.

"Therefore being justified by faith, we have peace with God through our Lord Jesus Christ: By whom also we have access by faith into this grace wherein we stand, and rejoice in hope of the glory of God." Romans 5:5

Deletes entities by using name value pairs as arguments to this function. One mandatory argument is to pass the 'entityName'. The rest of the arguments are used in the where class using AND notation and parameterized. Ex: deleteWhere(entityName="User",age="4",isActive=true);

Returns

• This function returns numeric

Examples

Open your config/ColdBox.cfc and either uncomment or add the following settings:

The virtual entity service is another support class that can help you create virtual service layers that are bounded to a specific ORM entity for convenience. This class inherits from our Base ORM Service and allows you to do everything the base class provides, except you do not need to specify to which entityName you are working with. You can also use this class as a base class and template out its methods to more concrete usages. The idea behind this virtual entity service layer is to allow you to have a very nice abstraction to all the CF ORM capabilities (hibernate) and promote best practices.

A method expression is made up of the prefixes: findBy, findAllBy, countBy followed by the expression that combines a query upon one or more properties:

User.findBy{property}[Conditional=equal][Operator]?{property}[Conditional][Operator]
User.findAllBy{property}[Conditional=equal][Operator]?{property}[Conditional][Operator]
User.countBy{property}[Conditional=equal][Operator]?{property}[Conditional][Operator]

If a conditional keyword is not passed, we assume you want equality. Remember that!

IMPORTANT The ? means that you can concatenate the same pattern over and over again.

Conditionals

The available conditionals in ColdBox are:

• LessThanEquals - Less than or equal to passed value

• LessThan - Less than to passed value

• GreaterThanEquals - Greater than or equal to passed value

• GreaterThan - Greater than to passed value

• Like - Equivalent to the SQL like expression

• NotEqual - Not equal to the passed value

• isNull - The property must be null

• isNotNull - The property must not be null

• NotBetween - The property value must not be between two values

• Between - The property value must be between two values

• NotInList - The property value must not be in the passed in simple list or array

• inList - The property value must be in the passed in simple list or array

Operators

The only valid operators are:

• And

• Or

Returns the count by passing name value pairs as arguments to this function. One mandatory argument is to pass the 'entityName'. The rest of the arguments are used in the where class using AND notation and parameterized. Ex: countWhere(entityName="User",age="20");

Returns

• This function returns numeric

Arguments

Get our hibernate org.hibernate.criterion.Restrictions proxy object

Returns

• This function returns coldbox.system.orm.hibernate.criterion.Restrictions

Examples

// Restrictions used with criteria queries
var r = ormService.getRestrictions();
var users = ormService.newCriteria("User")
    .or( r.eq("lastName","majano"), r.gt("createDate", now()) )
    .list();

Clear the session removes all the entities that are loaded or created in the session. This clears the first level cache and removes the objects that are not yet saved to the database.

Returns

• This function returns void

Examples

ormService.clear();

The ORM module supports the concept of dynamic finders and counters for ColdFusion ORM entities. A dynamic finder/counter looks like a real method but it is a virtual method that is intercepted by via onMissingMethod. This is a great way for you to do finders and counters using a programmatic and visual representation of what HQL to run.

This feature works on the Base ORM Service, Virtual Entity Services and also Active Entity services. The most semantic and clear representations occur in the Virtual Entity Service and Active Entity as you don't have to pass an entity name around.

Most of the Hibernate extensions like criteria builders and even some dynamic finders and counters will have to rely on the underlying Java type in order to work. You do this in ColdFusion by using the javaCast() function available to you. So if you are using a primary key that is an Integer you might have to do the following in order to match your variable to the underlying Java type:

criteria.eq( "id", javaCast( "int", arguments.id ) );

If you do not type it, then ColdFusion assumes it is a string and passes a string to Hibernate which will throw an exception as it is supposed to be an integer.

Auto Types

We have created two methods available to you in the base orm service, virtual service, criteria builders, active entity, etc to help you with these translations by automatically casting the values for you:

// Coverts a value to the correct javaType for the property passed in The method returns the value in the proper Java Type
any convertValueToJavaType( any propertyName, any value )

// Coverts an ID, list of ID's, or array of ID's values to the proper java type The method returns a coverted array of ID's
any convertIDValueToJavaType( any id )

So instead of casting it manually you can just let us do the work:

criteria.eq( "id", criteria.convertIDValueToJavaType( arguments.id ) );

Please remember that you can use ANY method found in the Base ORM Service except that you will not pass an argument of entityName anymore as you have now bounded to that specific entity.

You can refer to the ORM:BaseORMService methods without the entityName usage or refer to our API Docs.

By enabling the global event handler, WireBox can also be enabled to listen to these events and use them to wire up dependencies in these ORM entities and thus provide dependency injection for ORM entities. The injection takes place during the postLoad() and postNew() event cycles. All you need to do is enable ORM injection via the ConfigurationCFC

Important If you have to also override the event handler's postLoad(),postNew() method, you will then need to call the super class method so the injection procedures can take place: super.postLoad(entity) super.postNew(entity)

The video below describes the entire process:

Installation

Just drop into your modules folder or use the box-cli to install

box install cborm

WARNING

Unfortunately, due to the way that ORM is loaded by ColdFusion, if you are using the ORM EventHandler or ActiveEntity or any ColdBox Proxies that require ORM, you must create an Application Mapping in the Application.cfc like this:

SYSTEM REQUIREMENTS

• Lucee 4.5+

• ColdFusion 9.02+

WireBox DSL

The module also registers a new WireBox DSL called entityservice which can produce virtual or base orm entity services:

• entityservice - Inject a global ORM service

• entityservice:{entityName} - Inject a Virtual entity service according to entityName

Settings

Here are the module settings you can place in your ColdBox.cfc under an orm structure:

Validation

We have also migrated the UniqueValidator from the validation module into our ORM module. It is mapped into wirebox as UniqueValidator@cborm so you can use in your constraints like so:

1.2.1

• Fixed box.json version number

1.2.0

• BaseORMService.merge doesn't seem to merge entities back into session #10

• Variable scoping in SQLHelper.cfc bug #9

• Update build process to leverage Travis

• Updated cbvalidation to v1.1.0

• Build cleanup

• Replaced StringBuffer with StringBuilder for performance

1.1.0

• Updated cbvalidation dependency

• Prevent conditionals from being stripped from property names

• Updated build for api docs and commandbox usage for dependencies

• ORM Unique validation not working

1.0.2

• updates to all dependencies

• production ignore lists

1.0.1

• CF11Compat - arrayContainsNoCase() Is not a function

• Lucee support

1.0.0

• Create first module version

Create a virtual service for a specfic entity. Basically a new service layer that inherits from the BaseORMService object but no need to pass in entity names, they are bound to the entity name passed here.

Returns

• This function returns VirtualEntityService

Arguments

Examples

Delete an entity using safe transactions. The entity argument can be a single entity or an array of entities. You can optionally flush the session also after committing.

Returns

• This function returns void

Arguments

Examples

Finds and returns the first result for the given query or null if no entity was found. You can either use the query and params combination or send in an example entity to find.

Returns

• This function returns any

Arguments

Examples

Merge an entity or array of entities back into the session

Returns

• Same entity if one passed, array if an array of entities passed.

Arguments

Examples

Find all entities according to criteria structure. Ex: findAllWhere(entityName="Category", {category="Training"}), findAllWhere(entityName="Users", {age=40,retired=true});

Returns

• This function returns array

Arguments

Examples

Evict entity objects from session. The argument can be one persistence entity or an array of entities

Returns

• This function returns void

Arguments

Examples

Returns the persisted Property Names of the entity in array format

Returns

• This function returns array

Arguments

Examples

Find all/single entities by example

Returns

• This function returns array

Arguments

Examples

Refresh the state of an entity or array of entities from the database

Returns

• This function returns void

Arguments

Examples

Checks if the session contains dirty objects that are awaiting persistence

Returns

• This function returns boolean

Arguments

Examples

If you pass a structure as the last argument to your dynamic finder/counter call, we will consider that by convention to be your query options.

The valid query options are:

• ignorecase : Ignores the case of sort order when you set it to true. Use this option only when you specify the sortorder parameter.

• maxResults : Specifies the maximum number of objects to be retrieved.

• offset : Specifies the start index of the resultset from where it has to start the retrieval.

• cacheable : Whether the result of this query is to be cached in the secondary cache. Default is false.

• cachename : Name of the cache in secondary cache.

• timeout : Specifies the timeout value (in seconds) for the query

Returns the entity name from a given entity object via session lookup or if new object via metadata lookup

Returns

• This function returns string

Arguments

Examples

Returns the table name of the passed in entity

Returns

• This function returns string

Arguments

Examples

Information about the first-level (session) cache for the current session

Returns

• This function returns struct

Arguments

Examples

Evict all queries in the default cache or the cache region that is passed in.

Returns

• This function returns void

Arguments

Examples

The following are vanilla configurations for enabling the ORM in ColdFusion:

To work with Active Entity you must do a few things to tell ColdBox you want to use Active Entity and enable validation and injections:

1. Enable the ORM in your Application.cfc with event handling turned on, manage session and flush at request end as false.

2. Enable the orm configuration structure in your to allow for ColdBox to do entity injections

You just use entityNew() like you would with any ORM entity and then just call our cool methods:

Returns the key (id field) of a given entity, either simple or composite keys. If the key is a simple pk then it will return a string, if it is a composite key then it returns an array

Returns

• This function returns any

Arguments

Examples

This class allows you to simulate the Active Record pattern in your ORM entities by inheriting from our Active Entity class. This will make your ORM entities get all the functionality of our Virtual and Base ORM services so you can do finds, searches, listings, counts, execute queries, transaction safe deletes, saves, updates, criteria building, and even right from within your ORM Entity. The idea behind the Active Entity is to allow you to have a very nice abstraction to all the ColdFusion ORM capabilities (hibernate) and all of our ORM extensions like our ColdBox Criteria Builder. With Active Entity you will be able to:

• Find entities using a variety of filters and conditions

• ORM paging

• Specify order, searches, criterias and grouping of orm listing and searches

• Use DLM style hibernate operations for multiple entity deletion, saving, and updating

• Check for existence of records

• Check for counts using criterias

• Use our extensive ColdBox Criteria Builder to build Object Oriented HQL queries

• Validate your entity using our awesome

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.

Checks if the given entityName and id exists in the database

Returns

• This function returns boolean

Arguments

Examples

Get a new entity object by entity name. You can also pass in a structure called properties that will be used to populate the new entity with or you can use optional named parameters to call setters within the new entity to have shorthand population.

Returns

• This function returns any

Arguments

Examples

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.

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

Let's see the method signatures for these guys:

Since we’re not writing SQL, it can sometimes be frustrating to uncover why results from Criteria Builder and Detached Criteria Builder don’t match up with what you’re expecting.

An easy way to debug in these scenarios is to enable SQL logging and actually look at the query which is ultimately executed after Hibernate does it magic.

For a good guide on setting up SQL logging for ColdFusion ORM, check out

Once SQL logging is setup, you’ll be able to instantly see the SQL which is executed to deliver the result you’re getting from your criteria queries. You can then run these queries independently (such as in SQL Server Management Studio), identify where the issues are, and tweak your criteria query until it’s perfect.

Delete using an entity name and an incoming id, you can also flush the session if needed. The ID can be a single ID or an array of ID's to batch delete using hibernate DLM style deletes. The function also returns the number of records deleted.

Returns

• This function returns numeric

Arguments

Examples

// just delete
count = ormService.deleteByID("User",1);

// delete and flush
count = ormService.deleteByID("User",4,true);

// Delete several records, or at least try
count = ormService.deleteByID("User",[1,2,3,4]);

Return the count of instances in the DB for the given entity name. You can also pass an optional where statement that can filter the count. Ex: count('User','age > 40 AND name="joe"'). You can even use named or positional parameters with this method: Ex: count('User','age > ? AND name = ?',[40,"joe"])

Returns

• This function returns numeric

Arguments

Examples

// Get the count of instances for all books
ormService.count("Book");
// Get the count for users with age above 40 and named Bob
ormService.count("User","age > 40 AND name='Bob'");
// Get the count for users with passed in positional parameters
ormService.count("User","age > ? AND name=?",[40,'Bob']);
// Get the count for users with passed in named parameters
ormService.count("Post","title like :title and year = :year",{title="coldbox",year="2007"});

Update: Please use our updated Hibernate Criteria Builder objects instead so you can have much more control, granularity and coolness!

Get the record count using hibernate projections and criterion for specific queries

Returns

• This function returns numeric

Arguments

Examples

// The following is handler code which has been wired with a virtual entity service

property name="authorService" inject="entityService:Author";

function showAuthors(event){
var rc = event.getCollection();
// Get the hibernate restrictions proxy object
var restrictions = authorService.getRestrictions();
// build criteria
var criteria = [];
// Apply a "greater than" constraint to the named property
ArrayAppend(criteria, restrictions.ge("firstName","M"));

// Get the criteria query first        
prc.example1 = authorService.criteriaQuery(criteria=criteria, offset=(prc.boundaries.STARTROW-1), max=getSetting("PagingMaxRows"), sortOrder="firstName ASC");

// get the total records found via projections
prc.foundcount = authorService.criteriaCount(criteria=criteria);
}

Find one entity (or null if not found) according to a criteria structure ex: findWhere(entityName="Category", {category="Training"}), findWhere(entityName="Users",{age=40,retired=false});

Returns

• This function returns any

Arguments

Examples

// Find a category according to the named value pairs I pass into this method
var category = ormService.findWhere(entityName="Category", criteria={isActive=true, label="Training"});
var user = ormService.findWhere(entityName="User", criteria={isActive=true, username=rc.username,password=rc.password});

Get a brand new criteria builder object to do criteria queries with (See ORM:CriteriaBuilder)

Returns

• This function returns This function returns coldbox.system.orm.hibernate.CriteriaBuilder

Arguments

Examples

var users = ORMService.newCriteria(entityName="User",useQueryCaching=true)
    .gt("age", javaCast("int", 30) )
    .isTrue("isActive")
    .list(max=30,offset=10,sortOrder="lname");

Save an entity using hibernate transactions or not. You can optionally flush the session also.

Returns

• This function returns void

Arguments

Examples

var user = ormService.new("User");
populateModel(user);
ormService.save(user);

// Save with immediate flush
var user = ormService.new(entityName="User", lastName="Majano");
ormService.save(entity=user, flush=true);

The WireBox injection DSL has an injection namespace called entityService that can be used to wire in a Virtual Entity Service. You will use this DSL in conjunction with the name of the entity to manage.

component{
    // Virtual service layer based on the User entity
    property name="userService" inject="entityService:User";
}

Once a virtual entity service is bounded it will be injected wherever you define it. Then just use it!

The following methods alters the behavior of the executed query:

c.timeout( 5000 )
c.readOnly(true)
c.firstResult(20).maxResults(50).fetchSize(10).cacheRegsion('my.awesome.region')
c.cache(true,'my.region')
c.order('lastName','desc',true);

Saves an array of passed entities in specified order and transaction safe

Returns

• This function returns void

Arguments

Examples

var user = ormService.new("User");
populateModel(user);
var user2 = ormService.new("User");
populateModel(user);

ormService.saveAll( [user1,user2] );

Evict an entity from session, the id can be a string or structure for the primary key You can also pass in a collection name to evict from the collection

Returns

• This function returns void

Arguments

Examples

ormService.evict(entityName="Account",account.getID());
ormService.evict(entityName="Account");
ormService.evict(entityName="Account", collectionName="MyAccounts");

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’ ) );

The ColdBox Hibernate Criteria Builder is a powerful object that will help you build and execute hibernate criteria queries. HQL is extremely powerful, but some developers prefer to build queries dynamically using an object-oriented API, rather than building query strings and concatenating them in strings or buffers. The ColdBox Criteria builder offers a powerful programmatic DSL builder for Hibernate Criteria queries. You can see below some of the Hibernate documentation on criteria queries.

1. Hibernate Criteria Queries: http://docs.jboss.org/hibernate/core/3.5/reference/en-US/html/querycriteria.html

2. Hibernate Criteria Interface: http://docs.jboss.org/hibernate/core/3.5/javadoc/org/hibernate/Criteria.html

3. Hibernate Restrictions: http://docs.jboss.org/hibernate/core/3.5/javadoc/org/hibernate/criterion/Restrictions.html

As you will soon discover, they are fantastic but doing it the java way is not that fun, so we took our lovely ColdFusion dynamic language funkyness and added some ColdBox magic to it.

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

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:

1. Hibernate Docs: http://docs.jboss.org/hibernate/orm/3.5/reference/en/html/querycriteria.html#querycriteria-detachedqueries

2. Hibernate DetachedCriteria: http://docs.jboss.org/hibernate/orm/3.5/api/org/hibernate/criterion/DetachedCriteria.html

3. 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.

By using the ColdBox ORM event handler as your base class for your application's event handler you will inherently get the ability to talk to your ColdBox application instance and even inject objects into your ColdFusion ORM entities using WireBox. Not only that but we have also enabled the event handler to re-transmit the Hibernate Interceptions and announce them as ColdBox Interceptions. This way, you can intercept very easily the ColdBox way, create several chains, etc. The first thing you need to do is tell the CF Engine that you want to enable event handling and also which CFC will handle your global ORM entity events.

Important: You can also use the WireBox-EntityInjection approach which allows your event handler to be portable between ColdBox and Non-ColdBox applications and also allows you to NOT even create an event handler but just point it to the appropriate class.

Please remember that you can use ANY method found in the Base ORM Service except that you will not pass an argument of entityName anymore as you have now binded to an ORM entity. You can also visit our API for all the methods.

component persistent="true" table="your_table" extends="cborm.models.ActiveEntity"{

}

The inheritance is what will make your Entity come alive with tons of useful methods!

this.ormSettings = {
    cfclocation="model",
    dbcreate = "update",
    dialect = "MySQLwithInnoDB",
    logSQL = true,
    // Enable event handling
    eventhandling = true,
    // Set the event handler to use, which will be inside our application.
    eventhandler = "model.ORMEventHandler"
};

In this basic ORM configuration structure I have two lines that deal with ORM events:

// Enable event handling
eventhandling = true,
// Set the event handler to use, which will be inside our application.
eventhandler = "model.ORMEventHandler"

This enables the internal Hibernate interceptors and then you map a global CFC that will handle them. Mine will be in my local application's model folder named ORMEventHandler. It has to be inside of my application's folder structure in order to be able to talk to the ColdBox application. This is extremely important, as this creates the bridge between the ORM and ColdBox.

Imporant The ORM Event Handler CFC MUST exist within the application in order for the bridge to work.

Let's say you are using the virtual services and base ORM service but you find that they do not complete your requirements, or you need some custom methods or change functionality. Then you will be building concrete services that inherit from the base or virtual entity services. This is the very purpose of these support classes as most of the time you will have custom requirements and your own style of coding. Here is a custom AuthorService we created:

/**
* Service to handle author operations.
*/
component extends="cborm.models.VirtualEntityService" accessors="true" singleton{

    // User hashing type
    property name="hashType";

    AuthorService function init(){
        // init it via virtual service layer
        super.init(entityName="bbAuthor", useQueryCaching=true);
        setHashType( "SHA-256" );

        return this;
    }

    function search(criteria){
        var params = {criteria="%#arguments.criteria#%"};
        var r = executeQuery(query="from bbAuthor where firstName like :criteria OR lastName like :criteria OR email like :criteria",params=params,asQuery=false);
        return r;
    }

    function saveAuthor(author,passwordChange=false){
        // hash password if new author
        if( !arguments.author.isLoaded() OR arguments.passwordChange ){
            arguments.author.setPassword( hash(arguments.author.getPassword(), getHashType()) );
        }
        // save the author
        save( author );
    }

    boolean function usernameFound(required username){
        var args = {"username" = arguments.username};
        return ( countWhere(argumentCollection=args) GT 0 );
    }

}

Then you can just inject your concrete service in your handlers, or other models like any other normal model object.

component{
    // Concrete ORM service layer
    property name="authorService" inject="security.AuthorService";
    // Aliased 
    property name="authorService" inject="id:AuthorService";

    function index( event, rc, prc ){
        // Get all authors or search
        if( len(event.getValue( "searchAuthor", "" )) ){
            prc.authors = authorService.search( rc.searchAuthor );
            prc.authorCount = arrayLen( prc.authors );
         } else {
            prc.authors        = authorService.list( sortOrder="lastName desc", asQuery=false );
            prc.authorCount     = authorService.count();
        }

        // View
        event.setView("authors/index");
    }
}

There are a few properties you can instantiate a base service with or set them afterwards that affect operation. Below you can see a nice chart for them:

So if I was to base off my services on top of this gem, I can do this:

The BaseORMService is a core model CFC of the module that will provide you with a tremendous gammut of API methods to interact with ColdFusion ORM Entities.

Concept

The idea behind this support class is to provide a very good base or parent service layer that can interact with ColdFusion ORM via hibernate and entities inspired by support. This means that you don't need to create a service layer CFC in order to work with ORM entities.

It provides tons of methods for query executions, paging, transactions, session metadata, caching and much more. You can either use the class on its own or create more concrete service layers by inheriting from this class.

Usage

In order to get started with the base ORM service you need to know how to get access to it. You can do this via WireBox injection DSL or by the model's ID.

WireBox DSL

The module also registers a new WireBox DSL called entityservice which can produce virtual or base orm entity services that you can use to inject into your own event handlers or models.

• entityservice - Inject a global ORM service

• entityservice:{entityName} - Inject a Virtual entity service according to entityName

Injection

You can also request a Base ORM Service via the registered WireBox ID which is exactly the same as the entityService DSL:

Implementation

Once you have access to the injected base ORM service, you can use it in all of its glory.

Important Please check out the latest API Docs for the latest methods and functionality.

Once you have a reference to the base ORM service then you can use any of its methods to interact with ORM entities. The drawback about leveraging the base ORM model is that you cannot add custom functions to it or tell it to work on a specific entity for all operations. It is a very simple API, but if you need more control then we can start using other approaches shown below.

Virtual Services

We also have a that can be mapped to specific entities and create entity driven service layers virtually. Meaning you don't have to be passing any entity names to the API methods to save you precious typing time.

Concrete Services

This is where you create your own CFC that inherits from our Base ORM Service model and either add or override methods. You can read more about it in our

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 criterion to match against. The ColdBox criteria class offers almost all of the criterion methods found in the native hibernate Restrictions class () but if you need to add very explicit criterion directly you have access to the ColdBox Restrictions class which proxies calls to the native Hibernate class. You do this by either retrieving it from the Base/Virtual ORM services (getRestrictions()), create it manually, or the Criteria object itself has a public property called restrictions which you can use rather easily. We prefer the latter approach. Now, plese 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.

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.

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

Let's see the method signatures for these guys:

We have three types of dynamic finders and counters:

• findBy : Find ONE entity according to method signature, if more than one record is found an exception is thrown

• findAllBy : Find ALL entities according to method signature

• countBy : Give you a count of entities according to method signature

Let's say you have the following entity:

Then we could do the following:

You can also use the virtual entity service instead of active entity.

If you just use a vanilla Base ORM Service, then the first argument must be the entityName:

Get an entity using a primary key, if the id is not found this method returns null. You can also pass an id = 0 and the service will return to you a new entity.

Returns

• This function returns any

Arguments

Examples

You can now use the to create programmatically create criteria and projection subqueries.

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

The arguments for createSubcriteria() are:

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

Examples

See the documentation for for more information.

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

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.

Once you have concatenated criterias together, you can execute the query via the execution methods. Please remember that these methods return the results, so they must be executed last.

Note You can call count() and list() on the same criteria, but due to the internal workings of Hibernate, you must call count() first, then list().

Checks if the current session contains the passed in entity

Returns

• This function returns boolean

Arguments

Examples

List all of the instances of the passed in entity class name. You can pass in several optional arguments like a struct of filtering criteria, a sortOrder string, offset, max, ignorecase, and timeout. Caching for the list is based on the useQueryCaching class property and the cachename property is based on the queryCacheRegion class property.

Returns

• This function returns array

Arguments

Examples

users = ormService.list(entityName="User",max=20,offset=10,asQuery=false);
users = ormService.list(entityName="Art",timeout=10);
users = ormService.list("User",{isActive=false},"lastName, firstName");
users = ormService.list("Comment",{postID=rc.postID},"createdDate desc");

Populate an entity with an XML packet. Make sure the names of the elements match the keys in the structure.

Returns

• This function returns void

Arguments

Examples

var user = ormService.populateFromXML( ormService.new("User"), xml, "User");

Populate an entity with a JSON structure packet. Make sure the names of the properties match the keys in the structure.

Returns

• This function returns void

Arguments

Examples

var user = ormService.populateFromJSON( ormService.new("User"), jsonString );

Find all the entities for the specified query, named or positional arguments or by an example entity

Returns

• This function returns array

Arguments

Examples

// find all blog posts
ormService.findAll("Post");
// with a positional parameters
ormService.findAll("from Post as p where p.author=?",['Luis Majano']);
// 10 posts from Luis Majano staring from 5th post ordered by release date
ormService.findAll("from Post as p where p.author=? order by p.releaseDate",['Luis majano'],offset=5,max=10);

// Using paging params
var query = "from Post as p where p.author='Luis Majano' order by p.releaseDate" 
// first 20 posts 
ormService.findAll(query=query,max=20) 
// 20 posts starting from my 15th entry
ormService.findAll(query=query,max=20,offset=15);

// examples with named parameters
ormService.findAll("from Post as p where p.author=:author", {author='Luis Majano'})
ormService.findAll("from Post as p where p.author=:author", {author='Luis Majano'}, max=20, offset=5);

// query by example
user = ormService.new(entityName="User",firstName="Luis");
ormService.findAll( example=user );

Populate an entity with a query object. Make sure the names of the columns match the keys in the object.

Returns void

• This function returns

Arguments

Examples

var user = ormService.populateFromQuery( ormService.new("User"), list("User",{id=4}) );

If you override the constructor in your ORM entity, then make sure that you call the super.init() with the optional arguments below:

component persistent="true" table="your_table" extends="coldbox.system.orm.hibernate.ActiveEntity"{

    function init(){

        setCreatedDate( now() );

        super.init(useQueryCaching=true);

        return this;
    }

}

Allows the execution of HQL queries using several nice arguments and returns either an array of entities or a query as specified by the asQuery argument. The params filtering can be using named or positional.

Returns

• This function returns any

Arguments

Examples

// simple query
ormService.executeQuery( "select distinct a.accountID from Account a" );
// using with list of parameters
ormService.executeQuery( "select distinct e.employeeID from Employee e where e.department = ? and e.created > ?", ['IS','01/01/2010'] );
// same query but with paging
ormService.executeQuery( "select distinct e.employeeID from Employee e where e.department = ? and e.created > ?", ['IS','01/01/2010'],1,30);

// same query but with named params and paging
ormService.executeQuery( "select distinct e.employeeID from Employee e where e.department = :dep and e.created > :created", {dep='Accounting',created='01/01/2010'],10,20);

// GET FUNKY!!

There are a few properties you can instantiate a base service with or set them afterwards that affect operation. Below you can see a nice chart for them:

So if I was to base off my services on top of this gem, I can do this:

component extends="cborm.models.BaseORMService"{

  public UserService function init(){
      super.init( useQueryCaching=true, eventHandling=false );
      return this;    
  }

}

The BaseORMService is a core model CFC of the module that will provide you with a tremendous gammut of API methods to interact with ColdFusion ORM Entities.

Concept

The idea behind this support class is to provide a very good base or parent service layer that can interact with ColdFusion ORM via hibernate and entities inspired by Spring's Hibernate Template support. This means that you don't need to create a service layer CFC in order to work with ORM entities.

It provides tons of methods for query executions, paging, transactions, session metadata, caching and much more. You can either use the class on its own or create more concrete service layers by inheriting from this class.

Usage

In order to get started with the base ORM service you need to know how to get access to it. You can do this via WireBox injection DSL or by the model's ID.

WireBox DSL

The module also registers a new WireBox DSL called entityservice which can produce virtual or base orm entity services that you can use to inject into your own event handlers or models.

• entityservice - Inject a global ORM service

• entityservice:{entityName} - Inject a Virtual entity service according to entityName

Injection

You can also request a Base ORM Service via the registered WireBox ID which is exactly the same as the entityService DSL:

// Inject
inject name="ORMService" inject="BaseORMService@cborm";

// Retrieve
wireBox.getInstance( "BaseORMService@cborm" );
getModel( "BaseORMService@cborm" );

Implementation

Once you have access to the injected base ORM service, you can use it in all of its glory.

Important Please check out the latest API Docs for the latest methods and functionality.

component{

  inject name="ORMService" inject="entityService";

  function saveUser( event, rc, prc ){
      // retrieve and populate a new user object
      var user = populateModel( ORMService.new( "User" ) );

      // save the entity using hibernate transactions
      ORMService.save( user );

      setNextEvent( "user.list" );
  }

  function list( event, rc, prc ){

    //get a listing of all users with paging
    prc.users = ORMService.list(
        entityName= "User",
        sortOrder = "fname",
        offset     = event.getValue("startrow",1),
        max         = 20
    );

    event.setView( "user/list" );
  }
}

function index( event, rc, prc ){
    prc.data = ORMService.findAll( "Permission" );
}

Once you have a reference to the base ORM service then you can use any of its methods to interact with ORM entities. The drawback about leveraging the base ORM model is that you cannot add custom functions to it or tell it to work on a specific entity for all operations. It is a very simple API, but if you need more control then we can start using other approaches shown below.

Virtual Services

We also have a virtual service layer that can be mapped to specific entities and create entity driven service layers virtually. Meaning you don't have to be passing any entity names to the API methods to save you precious typing time.

Concrete Services

This is where you create your own CFC that inherits from our Base ORM Service model and either add or override methods. You can read more about it in our Concrete Services Section

Let's say you are using the virtual service but you find that they do not complete your requirements, or you need some custom methods or change functionality. Then you will be building concrete services that inherit from the virtual entity service. This is the very purpose of these support classes as most of the time you will have custom requirements and your own style of coding. Below is a sample templated service layer:

 component extends="cborm.models.VirtualEntityService" singleton{

    // DI
    property name="mailService"     inject="coldbox:plugin:MailService";
    property name="renderer"        inject="coldbox:plugin:Renderer";
    property name="settingService"  inject="id:settingService@cb";
    property name="CBHelper"        inject="id:CBHelper@cb";
    property name="log"             inject="logbox:logger:{this}";

    /**
    * Constructor
    */
    public CommentService function init(){
        super.init(entityName="cbComment",useQueryCaching="true");
        return this;
    }

    /**
    * Get the total number of approved comments in the system
    */
    numeric function getApprovedCommentCount(){
        var args = { "isApproved" = true };
        return countWhere(argumentCollection=args);
    }

    /**
    * Get the total number of unapproved comments in the system
    */
    numeric function getUnApprovedCommentCount(){
        var args = { "isApproved" = false };
        return countWhere(argumentCollection=args);
    }

    /**
    * Comment listing for UI of approved comments, returns struct of results=[comments,count]
    * @contentID.hint The content ID to filter on
    * @contentType.hint The content type discriminator to filter on
    * @max.hint The maximum number of records to return, 0 means all
    * @offset.hint The offset in the paging, 0 means 0
    * @sortOrder.hint Sort the comments asc or desc, by default it is desc
    */
    function findApprovedComments(contentID,contentType,max=0,offset=0,sortOrder="desc"){
        var results = {};
        var c = newCriteria();

        // only approved comments
        c.isTrue("isApproved");

        // By Content?
        if( structKeyExists(arguments,"contentID") AND len(arguments.contentID) ){
            c.eq("relatedContent.contentID",javaCast("int", arguments.contentID));
        }
        // By Content Type Discriminator: class is a special hibernate deal
        if( structKeyExists(arguments,"contentType") AND len(arguments.contentType) ){
            c.createCriteria("relatedContent")
                .isEq("class", arguments.contentType);
        }

        // run criteria query and projections count
        results.count    = c.count();
        results.comments = c.list(offset=arguments.offset,max=arguments.max,sortOrder="createdDate #arguments.sortOrder#",asQuery=false);

        return results;
    }
}

The ColdFusion documentation says that in order to create a global event handler that it must implement the CFIDE.orm.IEventHandler interface. So all you need to do is create the CFC and make it extend the core class that will provide you with all these capabilities: cborm.models.EventHandler

 component extends="cborm.models.EventHandler"{
}

That's it! Just by doing this the CF ORM will call your CFC's event methods in this CFC and satisfy the interface. Of course you can override the methods, but always remember to fire off the parent class methods in order for the ColdBox interceptions to still work. You can then override each event method as needed. Below is a chart of methods you can override:

The base event handler CFC you inherit from has all the ColdBox interaction capabilities you will ever need. You can find out all its methods by referring to the API and looking at that class or by inspecting the ColdBox Proxy class, which is what is used for enabling ColdBox interactions: coldbox.system.remote.ColdboxProxy

A criteria builder can be requested from our Base ORM services or a virtual service, which will bind itself automatically to the binded entity, by calling on their newCriteria() method. The corresponding class is: cborm.models.CriteriaBuilder

The arguments for the newCriteria() method are:

If you call newCriteria() from a virtual service layer, then you don't pass the entityName argument as it roots itself automatically.

Examples

Once you have an instance of the Criteria Builder class you can start adding restrictions, projections and configuration data for your query. All by concatenating methods in a nice programmatic DSL. Once all the restrictions, projections and/or configuration data are in place, you will execute the query/projections using our result methods. Please note that you can request as many new criteria builders as you like and each of them will execute different queries. So let's start with the restrictions.

Our active entity object will also give you access to our validation engine by giving your ORM entities the following functions:

Important In order for validation to work, WireBox ORM entity injection must be enabled first!

• ColdBox ORM Entity Injection

• WireBox Standalone ORM Entity Injection

This makes it really easy for you to validate your ORM entities.

Sample:

Handlers Sample:

Please refer to the ORM:BaseORMService for all the cool methods and functionality you can use with Active Entity. Like always, refer to the latest CFC Docs for methods and arguments.

Retrieve all the instances from the passed in entity name using the id argument if specified. The id can be a list of IDs or an array of IDs or none to retrieve all. If the id is not found or returns null the array position will have an empty string in it in the specified order

Returns

• This function returns array of entities found

Arguments

Examples

Delete by using an HQL query and iterating via the results, it is not performing a delete query but it actually is a select query that should retrieve objects to remove

Returns

• This function returns void

Arguments

| Key | Type | Required | Default | description | | query | string | Yes | --- | | | params | any | No | --- | | | max | numeric | No | 0 | | | offfset | numeric | No | 0 | | | flush | boolean | No | false | | | transactional | boolean | No | From Property | Use transactions or not | | datasource | string | false | | The datasource to use or use the default datasource |

Examples

By default you will need to do some javaCasting() on the values in order for the criteria builder to work correctly on some values. Remember that ColdFusion is a typeless language and Java is not. However, we have added to convenience methods for you so you can just pass in values without caring about casting:

• convertIDValueToJavaType(id)

• convertValueToJavaType(propertyName, value)

You can also find these methods in the Base ORM services and Virtual Entity Services.

Populate an entity with a structure of name-value pairs. Make sure the names of the properties match the keys in the structure.

Returns

• This function returns void

Arguments