In this section you will find the release notes for each version we release under this major version. If you are looking for the release notes of previous major versions use the version switcher at the top left of this documentation book. Here is a breakdown of our major version releases.

Version 2.0

A complete rewrite of the module to support a more modern and fluent approach to working with Hibernate/ColdFusion ORM. In this release we had to support 3 versions of Hibernate: 3 (Lucee), 4 (ACF 2016) and 5 (ACF 2018), which in itself proved to be a gargantuan task.

We also focused on bringing more functional programming aspects to working with collections of entities and even introduced cbStreams as part of the cborm module. This gives you the ability to produce streams out of any method that produces a collection of entities.

We also focused on converting the state of an object graph to a raw ColdFusion data struct as we live in the world of APIs. We include the mementifier module which allows every single entity to have a getMemento() method that will convert itself and its relationships to raw CF data constructs so you can take that state and either marshall it to another format (json,xml,excel) or audit the state.

Version 1.0

The first version of the cbORM series that focused on expanding the native ColdFusion ORM methods and exposing much more Hibernate functionality to the CFML world.

Added

• Removed usage of interface on DSL. Causes more issues than anything with multiple engines.

Changed

• Renamed default object DSL

Added

• New when( boolean, success, fail ) fluent construct for ActiveEntity, VirtualEntityService and the BaseORMService to allow for fluent chaining of operations on an entity or its service.

• Migration to new ColdBox Virtual App Testing approaches

• Removed unnecessary on load logging to increase performance

• Hibernate 5.4 on Lucee experimental testing

Fixed

• countWhere() invalid SQL exception if no arguments are provided: #54

Fixed

• CBORM-32 - Non-Primary DSN Entities not found. Multi-datasource discovery of entities using virtual services and active entity. This was a regression since version 1.5. This brings back multi-datasource support for active entity, and virtual entity services. #52

• Detached Subqueries was marked as a singleton when indeed it was indeed a transient. This could have created scoping issues on subquery based detached criteria building.

• Var scoping issues in BaseBuilder detached projections

• DetachedCriteriaBuilder was not passing the datasource to native criteria objects

Added

• Root docker-compose.yml to startup MySQL, or PostgreSQL in docker, for further hacking and testing.

• Java proxy caching to avoid Lucee OSGi issues and increase Java object building performance

• New method in the BaseOrmService: buildJavaProxy() which leverages our JavaProxyBuilder used mostly internally.

• Lazy loading of SQL Helper in criteria queries

• New module template guidelines and CI

• Leverage WireBox aliases for construction of internal objects

• Tons of internal docs and links to hibernate docs

Added

• CBORM-29 Allow SQL and SQL Group projections to be functions containing commas

Example:

r = categoryCriteria
.withProjections(
	groupProperty = "catid",
	sqlProjection = [
		{
			sql      : "count( category_id )",
			alias    : "count",
			property : "catid"
		}
	],
	sqlGroupProjection = [
		{
			sql      : "year( modifydate )",
			group    : "year( modifydate )",
			alias    : "modifiedDate",
			property : "id"
		},
		{
			sql      : "dateDiff('2021-12-31 23:59:59','2021-12-30')",
			group    : "dateDiff('2021-12-31 23:59:59','2021-12-30')",
			alias    : "someDateDiff",
			property : "id"
		}
	]
)
.asStruct()
.peek( function( c ){
	debug( c.getSql( true, true ) );
} )
.list();

debug( r );
assertTrue( isArray( r ) );

Fixed

CBORM-20 ActiveEntity evict() had the wrong method and arguments delegated to the parent class.

CBORM-9 ACF2021 - org.hibernate.SessionFactory.getAllClassMetadata is no longer supported

Improved

CBORM-14 Inline datasource discovery in base orm service to get a performance boost

CBORM-13 virtual entity service double creating the orm utility, use the parent one instead of duplicating the effort

CBORM-12 Lazy load the getORMUtil() and use it only when required.

Added

CBORM-22 New orm util support method: setupHibernateLogging() thanks to michael born

CBORM-19 Added a isInTransaction() util helper method to all the orm services.

CBORM-18 New ORM events based on Hibernate 5.4 Events: ORMFlush, ORMAutoFlush, ORMPreFlush, ORMDirtyCheck, ORMEvict, and ORMClear

CBORM-17 Hibernate 5.4 support for lucee new extension

CBORM-16 Adobe 2021 support and testing automations

CBORM-15 Migration to github actions

CBORM-11 Allow Criteria Builder Get() and getOrFail() Methods to Return Projection List Properties

CBORM-21 New cfformating rules

Compatibility

• If you upgrade your lucee ORM extension to use Hibernate 5.4, all positional paramters in HQL using ? has been deprecated. You will have to use the ?x approach where x is a number according to the position in the sql:

// Old Syntax
select p 
from Person p 
where p.name like ? and p.isStatus = ?

// New Syntax
select p 
from Person p 
where p.name like ?1 and p.isStatus = ?2

Added

• New eventPrefix setting so you can prefix the resource REST CRUD events with whatever you like.

• Useful exceptions when results struct does not have the required keys

• Ability to override the name of the method to use for persistence on the ORM services. Using the variables.saveMethod property or the savemethod argument.

• Ability to override the name of the method to use for deleting entities on the ORM services. Using the variables.deleteMethod property or the deleteMethod argument.

• cbSwagger docs added to the base resource handler

Changed

• Added ACF2016 compatibilities on elvis operator which sucks on ACF2016

• Avoid using member function son some arrays to allow for working with Java arrays

Added

• Support for Adobe 2021 on resource loader

Added

• Env templates using new lucee bundles and mysql 8 support

• New interception point: afterCriteriaBuilderGet, beforeCriteriaBuilderGet called after/before criteria get() calls

Fixed

• Fixed http to https for downloads

• Fixed watcher pathing

Added

• Exposed a getSQLHelper() from criterias to allow for usage of formmatting of sql

• New interception points: beforeOrmExecuteQuery, afterOrmExecuteQuery from the base orm service: executeQuery() method

Fixed

• Moved afterCriteriaBuilderList event before results conversions

[v3.2.1] => 2021-MAR-31

Fixed

• Wrong object to get the event handler manager when doing execute query calls

Compatibility Updates

In this major release we have two issues that are not backward compatible:

asQuery now false

All properties and arguments that received the asQuery argument are now defaulted to false. Meaning arrays of objects/structs is now the default instead of query objects. If you want to go back to queries, then make sure you add the asQuery : true to the method calls.

cbValidation => cbi18n v2 Upgrade

Our supporting modules have been also upgraded to their major versions mostly to support cbi18n v2. https://coldbox-i18n.ortusbooks.com/intro/release-history/whats-new-with-2.0.0

If you are using localization features with cborm then you must read the compat guide for cbi18n v2.

Release Notes

Bugs

• [CBORM-2] - isDirty() not working with ActiveEntity due to missing entity passed

New Features

• [CBORM-3] - Updated cbValidation to v3 to support cbi18n v2

• [CBORM-4] - asQuery update to default it to false

• [CBORM-5] - Document v3 variant in the docs

Improvements

• [CBORM-6] - Source code cleanups by applying formatting rules

Leverage CommandBox to install into your ColdBox app:

# Latest version
install cborm

# Bleeding Edge
install cborm@be

System Requirements

• Lucee 5.x+

• ColdFusion 2016+

Application.cfc Setup

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:

# In the pseudo constructor
this.mappings[ "/cborm" ] = COLDBOX_APP_ROOT_PATH & "modules/cborm";

WireBox DSL

The module registers a new WireBox DSL called entityservice which can produce virtual or base ORM entity services. Below are the injections you can use:

• entityservice - Inject a global ORM service

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

Module Settings

Here are the module settings you can place in your ColdBox.cfc under moduleSettings -> cborm structure:

moduleSettings = {
    cborm = {
        // Resource Settings
    		resources : {
    			// Enable the ORM Resource Event Loader
    			eventLoader 	: false,
    			// Pagination max rows
    			maxRows 		: 25,
    			// Pagination max row limit: 0 = no limit
    			maxRowsLimit 	: 500
    		},
        // WireBox Injection bridge
        injection = {
            // enable entity injection via WireBox
            enabled = true, 
            // Which entities to include in DI ONLY, if empty include all entities
            include = "", 
            // Which entities to exclude from DI, if empty, none are excluded
            exclude = ""
        }
    }
}

Validation

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

{ fieldName : { validator: "UniqueValidator@cborm" } }

Supported Hibernate Versions

Lucee 5

• Hibernate 3.5 - https://docs.jboss.org/hibernate/core/3.5/reference/en-US/html/querycriteria.html

• Hibernate 5.4 - https://hibernate.org/orm/documentation/5.4/

  • You will need to update to the latest ORM Beta Extension - https://download.lucee.org/#FAD1E8CB-4F45-4184-86359145767C29DE

  • 5.4.29.6-BETA (Aug 6, 2021)

Adobe 2016

• Hibernate 4.3 - https://hibernate.org/orm/documentation/4.3/

Adobe 2018, Adobe 2021

• Hibernate 5.2 - https://hibernate.org/orm/documentation/5.2/

Let's do a basic example of CRUD (Create-Read-Update-Delete). We will generate a ColdBox App, connect it to a database and leverage a virtual service layer for a nice quick CRUD App.

The source code for this full example can be found in Github: https://github.com/coldbox-samples/cborm-crud-demo or in ForgeBox: https://forgebox.io/view/cborm-crud-demo

ColdBox App

Let's start by creating a ColdBox app and preparing it for usage with ORM:

# Create folder
mkdir myapp --cd
# Scaffold App
coldbox create app
# Install cborm, dotenv, and cfconfig so we can get the CFML engine talking to the DB fast.
install cborm,commandbox-dotenv,commandbox-cfconfig
# Update the .env file
cp .env.example .env

Setup Environment

Season the environment file (.env) with your database credentials and make sure that database exists:

# ColdBox Environment
APPNAME=ColdBox
ENVIRONMENT=development

# Database Information
DB_CONNECTIONSTRING=jdbc:mysql://127.0.0.1:3306/cborm?useSSL=false&useUnicode=true&characterEncoding=UTF-8&serverTimezone=UTC&useLegacyDatetimeCode=true
DB_CLASS=com.mysql.jdbc.Driver
DB_DRIVER=MySQL
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=cborm
DB_USER=root
DB_PASSWORD=cborm

# S3 Information
S3_ACCESS_KEY=
S3_SECRET_KEY=
S3_REGION=us-east-1
S3_DOMAIN=amazonaws.com

Setup ORM

Now open the Application.cfc and let's configure the ORM by adding the following in the pseudo constructor and adding two lines of code to the request start so when we reinit the APP we can also reinit the ORM.

// Locate the cborm module for events
this.mappings[ "/cborm" ] = COLDBOX_APP_ROOT_PATH & "modules/cborm";

// The default dsn name in the ColdBox scaffold
this.datasource = "coldbox"; 
// ORM Settings + Datasource
this.ormEnabled = "true";
this.ormSettings = {
    cfclocation = [ "models" ], // Where our entities exist
    logSQL = true, // Remove after development to false.
    dbcreate = "update", // Generate our DB
    automanageSession = false, // Let cborm manage it
    flushAtRequestEnd = false, // Never do this! Let cborm manage it
    eventhandling = true, // Enable events
    eventHandler = "cborm.models.EventHandler", // Who handles the events
    skipcfcWithError = true // Yes, because we must work in all CFML engines
};

// request start
public boolean function onRequestStart( string targetPage ){
    // If we reinit our app, reinit the ORM too
    if( application.cbBootstrap.isFWReinit() )
        ormReload();

    // Process ColdBox Request
    application.cbBootstrap.onRequestStart( arguments.targetPage );

    return true;
}

Start Server

Let's start a server and start enjoying the fruits of our labor:

# Start a default Lucee Server
server start

Create Entity - Person.cfc

Let's start by creating a Person object with a few properties, let's use CommandBox for this and our super duper coldbox create orm-entity command:

coldbox create orm-entity 
    entityName="Person"
    properties=name,age:integer,lastVisit:timestamp

This will generate the models/Person.cfc as an ActiveEntity object and even create the unit test for it.

/**
 * A cool Person entity
 */
component persistent="true" table="Person"{

    // Primary Key
    property name="id" fieldtype="id" column="id" generator="native" setter="false";

    // Properties
    property name="name" ormtype="string";
    property name="age" ormtype="numeric";
    property name="lastVisit" ormtype="timestamp";

    // Validation
    this.constraints = {
        // Example: age = { required=true, min="18", type="numeric" }
    };

}

Setup for BDD

Since we love to promote tests at Ortus, let's configure our test harness for ORM testing. Open the /tests/Application.cfc and add the following code to setup the ORM and some functions for helping us test.

    // Locate the cborm module for events
    this.mappings[ "/cborm" ] = rootPath & "modules/cborm";

    // ORM Settings + Datasource
    this.datasource = "coldbox"; // The default dsn name in the ColdBox scaffold
    this.ormEnabled = "true";
    this.ormSettings = {
        cfclocation = [ "models" ], // Where our entities exist
        logSQL = true, // Remove after development to false.
        dbcreate = "update", // Generate our DB
        automanageSession = false, // Let cborm manage it
        flushAtRequestEnd = false, // Never do this! Let cborm manage it
        eventhandling = true, // Enable events
        eventHandler = "cborm.models.EventHandler", // Who handles the events
        skipcfcWithError = true // Yes, because we must work in all CFML engines
    };

    public boolean function onRequestStart( string targetPage ){
        ormReload();
        return true;
    }

Now that we have prepared the test harness for ORM testing, let's test out our Person with a simple unit test. We don't over test here because our integration test will be more pragmatic and cover our use cases:

component extends="coldbox.system.testing.BaseTestCase"{

    function run(){
        describe( "Person", function(){
            it( "can be created", function(){
                expect( getInstance( "Person" ) ).toBeComponent()
            });
        });
    }

}

Basic CRUD

We will now generate a handler and do CRUD actions for this Person:

coldbox create handler 
    name="persons" 
    actions="index,create,show,update,delete" 
    views=false

This creates the handlers/persons.cfc with the CRUD actions and a nice index action we will use to present all persons just for fun!

Inject Service

Open the handlers/persons.cfc and in the pseudo-constructor let's inject a virtual ORM service layer based on the Person entity:

/**
 * I manage Persons
 */
component{

 // Inject our service layer
 property name="personService" inject="entityService:Person";

}

The cborm module gives you the entityService:{entityName} DSL which allows you to inject virtual service layers according to entityName. With our code above we will have a personService in our variables scope injected for us.

Create

We will get an instance of a Person, populate it with data and save it. We will then return it as a json memento. The new() method will allow you to pass a struct of properties and/or relationships to populate the new Person instance with. Then just call the save() operation on the returned object.

/**
 * create a person
 */
function create( event, rc, prc ){
    prc.person = personService
        .new( {
            name     : "Luis",
            age     : 40,
            lastVisit : now()
        } );
    ;
    return personService
        .save( prc.person )
        .getMemento( includes="id" );
}

You might be asking yourself: Where does this magic getMemento() method come from? Well, it comes from the mementifier module which inspects ORM entities and injects them with this function to allow you to produce raw state from entities. (Please see: https://forgebox.io/view/mementifier)

Read

We will get an instance according to ID and show it's memento in json. There are many ways in the ORM service and Active Entity to get objects by criteria,

/**
 * show a person
 */
function show( event, rc, prc ){
    return personService
        .get( rc.id ?: 0 )
        .getMemento( includes="id" );
}

In this example, we use the get() method which retrieves a single entity by identifier. Also note the default value of 0 used as well. This means that if the incoming id is null then pass a 0. The ORM services will detect the 0 and by default give you a new Person object, the call will not fail. If you want your call to fail so you can show a nice exception for invalid identifiers you can use getOrFail() instead.

/**
 * show a person
 */
function show( event, rc, prc ){
    return personService
        .getOrFail( rc.id ?: -1 )
        .getMemento( includes="id" );
}

Update

Now let's retrieve an entity by Id, update it and save it again!

/**
 * Update a person
 */
function update( event, rc, prc ){
    prc.person = personService
        .getOrFail( rc.id ?: -1 )
        .setName( "Bob" )
    return personService
        .save( prc.person )
        .getMemento( includes="id" );
}

Delete

Now let's delete an incoming entity identifier

/**
 * Delete a Person
 */
function delete( event, rc, prc ){
    try{
        personService
            .getOrFail( rc.id ?: '' )
            .delete();
        // Or use the shorthnd notation which is faster
        // getIntance( "Person" ).deleteById( rc.id ?: '' )
    } catch( any e ){
        return "Error deleting entity: #e.message# #e.detail#";
    }

    return "Entity Deleted!";
}

Note that you have two choices when deleting by identifier:

1. Get the entity by the ID and then send it to be deleted

2. Use the deleteById() and pass in the identifier

The latter allows you to bypass any entity loading, and do a pure HQL delete of the entity via it's identifier. The first option is more resource intensive as it has to do a 1+ SQL calls to load the entity and then a final SQL call to delete it.

List All

For extra credit, we will get all instances of Person and render their memento's

/**
 * List all Persons
 */
function index( event, rc, prc ){
    return personService
        // List all as array of objects
        .list( asQuery=false )
        // Map the entities to mementos
        .map( function( item ){
            return item.getMemento( includes="id" );
        } );
}

That's it! We are now rolling with basic CRUD cborm style!

BDD Tests

Here are the full completed BDD tests as well

component extends="coldbox.system.testing.BaseTestCase" appMapping="/"{

    function run(){

        describe( "persons Suite", function(){

            aroundEach( function( spec ) {
                setup();
                transaction{
                    try{
                        arguments.spec.body();
                    } catch( any e ){
                        rethrow;
                    } finally{
                        transactionRollback();
                    }
                }
               });

            it( "index", function(){
                var event = this.GET( "persons.index" );
                // expectations go here.
                expect( event.getRenderedContent() ).toBeJSON();
            });

            it( "create", function(){
                var event = this.POST(
                    "persons.create"
                );
                // expectations go here.
                var person = event.getPrivateValue( "Person" );
                expect( person ).toBeComponent();
                expect( person.getId() ).notToBeNull();
            });

            it( "show", function(){
                // Create mock
                var event = this.POST(
                    "persons.create"
                );
                // Retrieve it
                var event = this.GET(
                    "persons.show", {
                        id : event.getPrivateValue( "Person" ).getId()
                    }
                );
                // expectations go here.
                var person = event.getPrivateValue( "Person" );
                expect( person ).toBeComponent();
                expect( person.getId() ).notToBeNull();
            });

            it( "update", function(){
                // Create mock
                var event = this.POST(
                    "persons.create"
                );
                var event = this.POST(
                    "persons.update", {
                        id : event.getPrivateValue( "Person" ).getId()
                    }
                );
                // expectations go here.
                var person = event.getPrivateValue( "Person" );
                expect( person ).toBeComponent();
                expect( person.getId() ).notToBeNull();
                expect( person.getName() ).toBe( "Bob" );
            });

            it( "delete", function(){
                // Create mock
                var event = this.POST(
                    "persons.create"
                );
                // Create mock
                var event = this.DELETE(
                    "persons.delete", {
                        id : event.getPrivateValue( "Person" ).getId()
                    }
                );
                expect( event.getRenderedContent() ).toInclude( "Entity Deleted" );
            });

        });

    }

}

The source code for this book is hosted in GitHub: https://github.com/ortus-docs/cbox-cborm-docs. You can freely contribute to it and submit pull requests. The contents of this book is copyright by Ortus Solutions, Corp and cannot be altered or reproduced without author's consent. All content is provided "As-Is" and can be freely distributed.

• The majority of code examples in this book are done in cfscript.

• The majority of code generation and running of examples are done via CommandBox: The ColdFusion (CFML) CLI, Package Manager, REPL - https://www.ortussolutions.com/products/commandbox

External Trademarks & Copyrights

Flash, Flex, ColdFusion, and Adobe are registered trademarks and copyrights of Adobe Systems, Inc.

ColdBox, CommandBox, FORGEBOX, TestBox, ContentBox, Ortus Solutions are all trademarks and copyrights of Ortus Solutions, Corp.

Notice of Liability

The information in this book is distributed “as is”, without warranty. The author and Ortus Solutions, Corp shall not have any liability to any person or entity with respect to loss or damage caused or alleged to be caused directly or indirectly by the content of this training book, software and resources described in it.

Contributing

We highly encourage contribution to this book and our open source software. The source code for this book can be found in our GitHub repository where you can submit pull requests.

Charitable Proceeds

10% of the proceeds of this book will go to charity to support orphaned kids in El Salvador - https://www.harvesting.org/. So please donate and purchase the printed version of this book, every book sold can help a child for almost 2 months.

Shalom Children's Home

Shalom Children’s Home is one of the ministries that is dear to our hearts located in El Salvador. During the 12 year civil war that ended in 1990, many children were left orphaned or abandoned by parents who fled El Salvador. The Benners saw the need to help these children and received 13 children in 1982. Little by little, more children came on their own, churches and the government brought children to them for care, and the Shalom Children’s Home was founded.

Shalom now cares for over 80 children in El Salvador, from newborns to 18 years old. They receive shelter, clothing, food, medical care, education and life skills training in a Christian environment. The home is supported by a child sponsorship program.

We have personally supported Shalom for over 6 years now; it is a place of blessing for many children in El Salvador that either have no families or have been abandoned. This is good earth to seed and plant.

The cborm module is a module that will enhance your experience when working with the ColdFusion ORM powered by Hibernate. It will not only enhance it with dynamic goodness but give you a fluent and human approach to working with Hibernate. Basically making working with Hibernate not SUCK!

Some Features

• Service Layers with all the methods you could probably think off to help you get started in any project

• Virtual service layers so you can create virtual services for any entity in your application

• Automatic RESTFul resources handler, focus on your domain objects and business logic, not the boilerplate of REST

• ActiveEntity our implementation of Active Record for ORM

• Fluent queries via Hibernate's criteria and detached criteria queries with some Dynamic CFML goodness

• Automatic transaction demarcation for save and delete operations

• Dynamic finders and counters for expressive and fluent shorthand SQL

• Automatic Java casting

• Entity population from json, structs, xml, and queryies including building up their relationships

• Entity validation via cbValidation

• Includes the Mementifier project to produce memento states from any entity, great for producing JSON

• Ability for finders and queries to be returned as Java streams using our cbStreams project.

# A quick preview of some functionality

var book = new Book().findByTitle( "My Awesome Book" );
var book = new Book().getOrFail( 2 );
new Book().getOrFail( 4 ).delete();
new Book().deleteWhere( isActive:false, isPublished:false );

property name="userService" inject="entityService:User";

return userService.list();
return userService.list( asStream=true );

var count = userService.countWhere( age:20, isActive:true );
var users = userService.findAllByLastLoginBetween( "01/01/2019", "05/01/2019" );

userService
    .newCriteria()
    .eq( "name", "luis" )
    .isTrue( "isActive" )
    .getOrFail();

userService
    .newCriteria()
    .isTrue( "isActive" )
    .joinTo( "role" )
        .eq( "name", "admin" )
    .asStream()
    .list();

userService
    .newCriteria()
    .withProjections( property="id,fname:firstName,lname:lastName,age" )
    .isTrue( "isActive" )
    .joinTo( "role" )
        .eq( "name", "admin" )
    .asStruct()
    .list();

In other words, it makes using an ORM not SUCK!

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://ortussolutions.atlassian.net/browse/CBORM

• ForgeBox: https://forgebox.io/view/cborm

Discussion & Help

The Ortus Community is the way to get any type of help for our entire platform and modules: https://community.ortussolutions.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

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 the Base Service, I can do this:

component extends="cborm.models.BaseORMService"{

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

}

These methods allows you to tap into the Criteria Queries API so you can do fluent and functional queries with your ORM objects.

Let's do a basic example of CRUD (Create-Read-Update-Delete). We will generate a ColdBox App, connect it to a database and leverage ActiveEntity for a nice quick CRUD App.

The source code for this full example can be found in Github: https://github.com/coldbox-samples/cborm-crud-demo or in ForgeBox: https://forgebox.io/view/cborm-crud-demo

ColdBox App

Let's start by creating a ColdBox app and preparing it for usage with ORM:

# Create folder
mkdir myapp --cd
# Scaffold App
coldbox create app
# Install cborm, dotenv, and cfconfig so we can get the CFML engine talking to the DB fast.
install cborm,commandbox-dotenv,commandbox-cfconfig
# Update the .env file
cp .env.example .env

Setup Environment

Season the environment file (.env) with your database credentials and make sure that database exists:

# ColdBox Environment
APPNAME=ColdBox
ENVIRONMENT=development

# Database Information
DB_CONNECTIONSTRING=jdbc:mysql://127.0.0.1:3306/cborm?useSSL=false&useUnicode=true&characterEncoding=UTF-8&serverTimezone=UTC&useLegacyDatetimeCode=true
DB_CLASS=com.mysql.jdbc.Driver
DB_DRIVER=MySQL
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=cborm
DB_USER=root
DB_PASSWORD=cborm

# S3 Information
S3_ACCESS_KEY=
S3_SECRET_KEY=
S3_REGION=us-east-1
S3_DOMAIN=amazonaws.com

Setup ORM

Now open the Application.cfc and let's configure the ORM by adding the following in the pseudo constructor and adding two lines of code to the request start so when we reinit the APP we can also reinit the ORM.

// Locate the cborm module for events
this.mappings[ "/cborm" ] = COLDBOX_APP_ROOT_PATH & "modules/cborm";

// The default dsn name in the ColdBox scaffold
this.datasource = "coldbox"; 
// ORM Settings + Datasource
this.ormEnabled = "true";
this.ormSettings = {
	cfclocation = [ "models" ], // Where our entities exist
	logSQL = true, // Remove after development to false.
	dbcreate = "update", // Generate our DB
	automanageSession = false, // Let cborm manage it
	flushAtRequestEnd = false, // Never do this! Let cborm manage it
	eventhandling = true, // Enable events
	eventHandler = "cborm.models.EventHandler", // Who handles the events
	skipcfcWithError = true // Yes, because we must work in all CFML engines
};

// request start
public boolean function onRequestStart( string targetPage ){
	// If we reinit our app, reinit the ORM too
	if( application.cbBootstrap.isFWReinit() )
		ormReload();
	
	// Process ColdBox Request
	application.cbBootstrap.onRequestStart( arguments.targetPage );

	return true;
}

Start Server

Let's start a server and start enjoying the fruits of our labor:

# Start a default Lucee Server
server start

Create Entity - Person.cfc

Let's start by creating a Person object with a few properties, let's use CommandBox for this and our super duper coldbox create orm-entity command:

coldbox create orm-entity 
    entityName="Person"
    activeEntity=true
    properties=name,age:integer,lastVisit:timestamp

This will generate the models/Person.cfc as an ActiveEntity object and even create the unit test for it.

/**
 * A cool Person entity
 */
component persistent="true" table="Person" extends="cborm.models.ActiveEntity"{

	// Primary Key
	property name="id" fieldtype="id" column="id" generator="native" setter="false";
	
	// Properties
	property name="name" ormtype="string";
	property name="age" ormtype="numeric";
	property name="lastVisit" ormtype="timestamp";
	
	// Validation
	this.constraints = {
		// Example: age = { required=true, min="18", type="numeric" }
	};
	
	// Constructor
	function init(){
		super.init( useQueryCaching="false" );
		return this;
	}
}

Setup for BDD

Since we love to promote tests at Ortus, let's configure our test harness for ORM testing. Open the /tests/Application.cfc and add the following code to setup the ORM and some functions for helping us test.

	// Locate the cborm module for events
	this.mappings[ "/cborm" ] = rootPath & "modules/cborm";

	// ORM Settings + Datasource
	this.datasource = "coldbox"; // The default dsn name in the ColdBox scaffold
	this.ormEnabled = "true";
	this.ormSettings = {
		cfclocation = [ "models" ], // Where our entities exist
		logSQL = true, // Remove after development to false.
		dbcreate = "update", // Generate our DB
		automanageSession = false, // Let cborm manage it
		flushAtRequestEnd = false, // Never do this! Let cborm manage it
		eventhandling = true, // Enable events
		eventHandler = "cborm.models.EventHandler", // Who handles the events
		skipcfcWithError = true // Yes, because we must work in all CFML engines
	};

	public boolean function onRequestStart( string targetPage ){
		ormReload();
		return true;
	}

Now that we have prepared the test harness for ORM testing, let's test out our Person with a simple unit test. We don't over test here because our integration test will be more pragmatic and cover our use cases:

component extends="coldbox.system.testing.BaseTestCase"{

	function run(){
		describe( "Person", function(){
			it( "can be created", function(){
				expect( getInstance( "Person" ) ).toBeComponent()
			});
		});
	}

}

Basic CRUD

We will now generate a handler and do CRUD actions for this Person:

coldbox create handler 
    name="persons" 
    actions="index,create,show,update,delete" 
    views=false

This creates the handlers/persons.cfc with the CRUD actions and a nice index action we will use to present all persons just for fun!

Create

We will get an instance of a Person, populate it with data and save it. We will then return it as a JSON memento. The new() method will allow you to pass a struct of properties and/or relationships to populate the new Person instance with. Then just call the save() operation on the returned object.

/**
 * create a person
 */
function create( event, rc, prc ){
	prc.person = getInstance( "Person" )
		.new( {
			name 	: "Luis",
			age 	: 40,
			lastVisit : now()
		} )
		.save();
	return prc.person.getMemento( includes="id" );
}

You might be asking yourself: Where does this magic getMemento() method come from? Well, it comes from the mementifier module wich inspects ORM entities and injects them with this function to allow you to produce raw state from entities. (Please see: https://forgebox.io/view/mementifier)

Read

We will get an instance according to ID and show it's memento in json. There are many ways in the ORM service and Active Entity to get objects by criteria,

/**
 * show a person
 */
function show( event, rc, prc ){
	return getInstance( "Person" )
		.get( rc.id ?: 0 )
		.getMemento( includes="id" );
}

In this example, we use the get() method which retrieves a single entity by identifier. Also note the default value of 0 used as well. This means that if the incoming id is null then pass a 0. The ORM services will detect the 0 and by default give you a new Person object, the call will not fail. If you want your call to fail so you can show a nice exception for invalid identifiers you can use getOrFail() instead.

/**
 * show a person
 */
function show( event, rc, prc ){
	return getInstance( "Person" )
		.getOrFail( rc.id ?: -1 )
		.getMemento( includes="id" );
}

Update

Now let's retrieve an entity by Id, update it and save it again!

/**
 * Update a person
 */
function update( event, rc, prc ){
	prc.person = getInstance( "Person" )
		.getOrFail( rc.id ?: -1 )
		.setName( "Bob" )
		.save();
	return prc.person.getMemento( includes="id" );
}

Delete

Now let's delete an incoming entity identifier

/**
 * Delete a Person
 */
function delete( event, rc, prc ){
	try{
		getInstance( "Person" )
			.getOrFail( rc.id ?: '' )
			.delete();
		// Or use the shorthnd notation which is faster
		// getIntance( "Person" ).deleteById( rc.id ?: '' )
	} catch( any e ){
		return "Error deleting entity: #e.message# #e.detail#";
	}

	return "Entity Deleted!";
}

Note that you have two choices when deleting by identifier:

1. Get the entity by the ID and then send it to be deleted

2. Use the deleteById() and pass in the identifier

The latter allows you to bypass any entity loading, and do a pure HQL delete of the entity via it's identifier. The first option is more resource intensive as it has to do a 1+ SQL calls to load the entity and then a final SQL call to delete it.

List All

For extra credit, we will get all instances of Person and render their memento's

/**
 * List all Persons
 */
function index( event, rc, prc ){
	return getInstance( "Person" )
		// List all as array of objects
		.list( asQuery=false )
		// Map the entities to mementos
		.map( function( item ){
			return item.getMemento( includes="id" );
		} );
}

That's it! We are now rolling with basic CRUD cborm style!

BDD Tests

Here are the full completed BDD tests as well

component extends="coldbox.system.testing.BaseTestCase" appMapping="/"{

	function run(){

		describe( "persons Suite", function(){

			aroundEach( function( spec ) {
				setup();
				transaction{
					try{
						arguments.spec.body();
					} catch( any e ){
						rethrow;
					} finally{
						transactionRollback();
					}
				}
		   	});

			it( "index", function(){
				var event = this.GET( "persons.index" );
				// expectations go here.
				expect( event.getRenderedContent() ).toBeJSON();
			});

			it( "create", function(){
				var event = this.POST(
					"persons.create"
				);
				// expectations go here.
				var person = event.getPrivateValue( "Person" );
				expect( person ).toBeComponent();
				expect( person.getId() ).notToBeNull();
			});

			it( "show", function(){
				// Create mock
				var event = this.POST(
					"persons.create"
				);
				// Retrieve it
				var event = this.GET(
					"persons.show", {
						id : event.getPrivateValue( "Person" ).getId()
					}
				);
				// expectations go here.
				var person = event.getPrivateValue( "Person" );
				expect( person ).toBeComponent();
				expect( person.getId() ).notToBeNull();
			});

			it( "update", function(){
				// Create mock
				var event = this.POST(
					"persons.create"
				);
				var event = this.POST(
					"persons.update", {
						id : event.getPrivateValue( "Person" ).getId()
					}
				);
				// expectations go here.
				var person = event.getPrivateValue( "Person" );
				expect( person ).toBeComponent();
				expect( person.getId() ).notToBeNull();
				expect( person.getName() ).toBe( "Bob" );
			});

			it( "delete", function(){
				// Create mock
				var event = this.POST(
					"persons.create"
				);
				// Create mock
				var event = this.DELETE(
					"persons.delete", {
						id : event.getPrivateValue( "Person" ).getId()
					}
				);
				expect( event.getRenderedContent() ).toInclude( "Entity Deleted" );
			});

		});

	}

}

Get our hibernate org.hibernate.criterion.Restrictions proxy object that will help you produce criterias.

Returns

• This function returns an instance of cborm.models.criterion.Restrictions

Examples

// Get an instance of the restrictions
var restrictions = ormService.getRestrictions();

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

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

Returns

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

Arguments

Examples

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

These methods allow you to create entities and populate them from external data like structures, json, xml, queries and much more.

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 the newly created entity

Arguments

Examples

// return empty post entity
var post = ormService.new("Post");
var user = ormService.new(entityName="User",properties={firstName="Luis", lastName="Majano", age="32", awesome=true});
var user = ormService.new("User",{fname="Luis",lname="Majano",cool=false,awesome=true});

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

Returns

• This function returns the populated object

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 the populated object

Arguments

Examples

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

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

Returns

• This function returns the populated object

Arguments

Examples

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

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 the populated object

Arguments

INFO With composeRelationships=true, you can populate one-to-many, many-to-one, many-to-many, and one-to-one relationships from property values in the memento. For 'many-to-one' and 'one-to-one' relationships, the value of the property in the memento should be a single value of the primary key of the target entity to be loaded. For 'one-to-many' and 'many-to-many' relationships, the value of the property in the memento should a comma-delimited list or array of the primary keys of the target entities to be loaded.

Examples

var user = ormService.populate( ormService.new("User"), data );

// populate with includes only
var user = ormService.populate( ormService.new("User"), data, "fname,lname,email" );

//populate with excludes
var user = ormService.populate(target=ormService.new("User"),memento=data,exclude="id,setup,total" );

// populate with null values when value is empty string
var user = ormService.populate(target=ormService.new("User"),memento=data,nullEmptyInclude="lastName,dateOfBirth" );

// populate many-to-one relationship
var data = {
    firstName = "Luis",
    role = 1 // "role" is the name of the many-to-one relational property, and one is the key value
};
var user = ormService.populate( target=ormService.new("User"), memento=data, composeRelationships=true );
// the role relationship will be composed, and the value will be set to the appropriate instance of the Role model

// populate one-to-many relationship
var data = {
    firstName = "Luis",
    favColors = "1,2,3" ( or [1,2,3] ) // favColors is the name of the one-to-many relational property, and 1, 2 and 3 are key values of favColor models
};
var user = ormService.populate( target=ormService.new("User"), memento=data, composeRelationships=true );
// the favColors property will be set to an array of favColor entities

// only compose some relationships
var data = {
    firstName = "Luis",
    role = 1,
    favColors = [ 1, 3, 19 ]
};
var user = ormService.populate( target=ormService.new("User"), memento=data, composeRelationships=true, exclude="favColors" );
// in this example, "role" will be composed, but "favColors" will be excluded

These methods allow you to do counting on entities with or without filtering.

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"});

These methods allow you to delete one or more entities in cascade style or bulk styles.

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");
    }
}

Luis Fernando Majano Lainez

Luis Majano is a Computer Engineer with over 15 years of software development and systems architecture experience. He was born in San Salvador, El Salvador in the late 70’s, during a period of economical instability and civil war. He lived in El Salvador until 1995 and then moved to Miami, Florida where he completed his Bachelors of Science in Computer Engineering at Florida International University

He is the CEO of Ortus Solutions, a consulting firm specializing in web development, ColdFusion (CFML), Java development and all open source professional services under the ColdBox, CommandBox and ContentBox stack. He is the creator of ColdBox, ContentBox, WireBox, MockBox, LogBox and anything “BOX”, and contributes to many open source projects. You can read his blog at www.luismajano.com

Luis has a passion for Jesus, tennis, golf, volleyball and anything electronic. Random Author Facts:

• He played volleyball in the Salvadorean National Team at the tender age of 17

• The Lord of the Rings and The Hobbit is something he reads every 5 years. (Geek!)

• His first ever computer was a Texas Instrument TI-86 that his parents gave him in 1986. After some time digesting his very first BASIC book, he had written his own tic-tac-toe game at the age of 9. (Extra geek!)

• He has a geek love for circuits, micro-controllers and overall embedded systems.

• He has of late (during old age) become a fan of organic gardening.