Release Notes

• improvement : In executeQuery() Determine if we are in a UPDATE, INSERT or DELETE, if we do, just return the results instead of a stream or query as the result is always numeric, the rows that were altered.

• bug : Fixed asStream typo on executeQuery()

• bug : Missing ACF2016 compat on tests

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.

Release Notes

• Features : Introduction of the automatic resource handler for ORM Entities based on ColdBox's 6 resources and RestHandler

• Improvement : Natively allow for nested transactions and savepoints by not doing preemptive transaction commits when using transactions.

• Bug : Fix on getOrFail() where if the id was 0, it would still return an empty object.

• Task : Added formatting via cfformat

You can read more about the RESTFul Resources here:

Release Notes

• Feature : Upgraded to cbValidation 2.0.0

• Feature : Updated the unique validator to match 2.0.0 standards

• Feature : Upgraded to mementifier 2.0.0

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.

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://github.com/coldbox-modules/cbox-cborm/issues

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

Release Notes

• bug : virtual entity service still had entity required for casting methods

• Change populate() in ActiveEntity so the target is the last argument so you can just pass a struct as the first argument #29

• Make the save() operation return the saved entity or array of entities instead of the Base ORM service to allow for concatenated fluent design #28

This release not only has some bug fixes but several new features that pack a punch.

Major Features

Criteria Query Fluent If Statements - when()

How many times have you been dealing with if statements in order to add some restrictions into your criteria object? Many, this was the only way before, not anymore. So instead of doing something like the following:

c = newCriteria();

if( isBoolean( arguments.isPublished ) ){
  
	c.isEq( "isPublished", isPublished );

	// Published eq true evaluate other params
    if( isPublished ){
        c.isLt( "publishedDate", now() )
        .$or( c.restrictions.isNull( "expireDate" ), c.restrictions.isGT( "expireDate", now() ) )
        .isEq( "passwordProtection","" );
    }

}

if( !isNull( arguments.showInSearch ) ){
	c.isEq( "showInSearch", showInSearch );
}


return c.list();

This looks like normal code, but we can do a more functional approach by introducing the when() function:

/**
* @test The boolean evaluation
* @target The closure to execute if test is true
*/
when( boolean test, function target )

This function takes in as the first argument a boolean value, if the value is true, then the target closure will be called for you and the criteria will be passed via the arguments scope:

newCriteria()
    .when( isBoolean( arguments.isPublished ), function( c ){
        // Published bit
        c.isEq( "isPublished", isPublished )
        	.when( isPublished, function( c ){
        		c.isLt( "publishedDate", now() )
	            .$or( c.restrictions.isNull( "expireDate" ), c.restrictions.isGT( "expireDate", now() ) )
	            .isEq( "passwordProtection","" );
        	} )
    } )
  .when( !isNull( arguments.showInSearch ), function( criteria ){	
  	c.isEq( "showInSearch", showInSearch );
   } )
  .list()

This construct will help you create more fluent designs when building criteria queries, enjoy!

PeekaBoo! - peek()

We have also enhanced the criteria queries with a peek() function which allows you to peek in the current position of the criteria build up. This allows you to debug or inspect the SQL/HQL inside the criteria at that point in time. You can use it for sending debug data or logging, or auditing.

/**
* @target the closure to execute, the criteria is passed as an argument
*/
peek( target )

Enjoy your peekaboo function!

newCriteria()
    .when( isBoolean( arguments.isPublished ), function( c ){
        // Published bit
        c.isEq( "isPublished", isPublished )
        	.when( isPublished, function( c ){
        		c.isLt( "publishedDate", now() )
	            .$or( c.restrictions.isNull( "expireDate" ), c.restrictions.isGT( "expireDate", now() ) )
	            .isEq( "passwordProtection","" );
        	} )
    } )
  .peek( function( c ){
      systemOutput( "HQL after publish: #criteria.getSql()# ");
  } )
  .when( !isNull( arguments.showInSearch ), function( criteria ){	
  	c.isEq( "showInSearch", showInSearch );
   } )
   .peek( function( c ){
      systemOutput( "HQL before listing: #criteria.getSql()# ");
  } )
  .list()

ValidateOrFail()

We have added a new function on the ActiveEntity object to assist with validations. The validateOrFail() function will allow you to validate the entity and if it validates it just returns the instance of the entity for a nice fluent design. However, if the validation fails, it throws a ValidationException and the errors are passed to the exception object via the extendedInfo key. You can then deal with the exception as needed.

getInstance( "User" )
    .populate( rc )
    .validateOrFail()
    .save();

Release Notes

• Features: New function for criteria query when( boolean, target ) that you can use to build functional criterias without the use of if statements.

• Feature: Missing nullValue() is BaseBuilder class

• Feature: Added new criteria query peek( closure ) function to allow for peeking into the building process. Pass in your closure that receives the criteria and interact with it.

• Feature: Added a validateOrFail() to the active entity, which if the validation fails it will throw an exception or return back to you the same entity validated now.

• Improvement: Better documentation for deleteById() since it does bulk deletion, which does not do any type of cascading.

• Improvement: isValid() in active entity missing includeFields argument

• Improvement: Timeout hints for criteria builder

• Improvement: Updated exception type for criteria builder get()

• Bug: ACF2016 issues with elvis operator.

• Bug: getOrFail() had an invalid throw statement

Compatibility Updates

• You will need to move the orm configuration structure in your config/ColdBox.cfc to the moduleSettings struct and rename it to cborm to standardize it to module settings.

moduleSettings = {

    cborm = {
        inject = {
            enabled = true,
            includes = "",
            excludes = ""
        }
    }

};

• deleteByQuery() reworked entirely to do native bulk delete queries. It now also returns the number of records removed

• The evict() method was renamed to evictCollection() to better satisfy the same contract in hibernate

• The evictEntity() method was renamed to evict() to better satisfay the same contract in hibernate

• Removed byExample on many listing methods

General Updates

• Mementifier is now a dependency for cborm (www.forgebox.io/view/mementifier), which can be used for producing state out of ORM entities for auditing or building JSON Api's.

• cbStreams is now a dependency for cborm (www.forgebox.io/view/cbstreams), all criteria queries and major listing methods support the return of streams instead of array of objects

• Full Null Support

• Performance update on creating active entities as datasource discovery has been reworked

• Updated build process to latest in Ortus template

• Dropped Railo, Lucee 4.5, ACF11 support

• More direct scoping for performance updates

• Optimized EventHandler so it is lighter and quicker when doing orm injections

• Documented all functions with extra examples and notes and hibernate references

• ColdBox 5 and 4 discrete ORM Injection DSLs

Criteria Queries

• They have been adapted to work with Hibernate 3, 4 and 5

• New fail fast method for get() -> getOrFail() to throw an entity not found exception

• New alias methods for controlling the result transformations asStruct(), asStream(), asDistinct() that will apply result transformers for you instead of doing .resultTransformer( c.ALIAS_TO_ENTITY_MAP ), whish is long and boring, or return to you a java stream via cbStreams.

• When calling native restrictions, no more reflection is used to discover the restriction type thus increasing over 70% in performance when creating criteria queries

• You can now negate any criteria restriction by prefixing it with a not. So you can do: .notEq(), notBetween(), notIsNull(), notIsIn() and much more.

• The list() method has a new asStream boolean argument that if true, will return the results as a cbStream. ((www.forgebox.io/view/cbStreams))

• New Methods: idCast() and autoCast() added for quick casting of values

• New method: queryHint() so you can add your own vendor specific query hints for optimizers.

• New method: comment( string ) so you can add arbitrary comments to the generated SQL, great for debugging

• sqlRestriction() deprecated in favor of the shorthand notation: sql()

• The sql() restriction now supports binding positional parameters. You can pass them in an array and we will infer the types: sql( "id = ? and isActive = ?", [ "123", true ] ). Or you can pass in a struct of {value:"", type:""} instead:

restrictions.sql( "userName = ? and firstName like ?", [
    { value : "joe", type : "string" },
    { value : "%joe%", type : "string" }
] );

The available types are the following which match the Hibernate Types

this.TYPES = {
    "string"         : "StringType",
    "clob"            : "ClobType",
    "text"            : "TextType",
    "char"            : "ChareacterType",
    "boolean"         : "BooleanType",
    "yesno"         : "YesNoType",
    "truefalse"        : "TrueFalseType",
    "byte"             : "ByteType",
    "short"         : "ShortType",
    "integer"         : "IntegerType",
    "long"             : "LongType",
    "float"            : "FloatType",
    "double"         : "DoubleType",
    "bigInteger"    : "BigIntegerType",
    "bigDecimal"    : "BigDecimalType",
    "timestamp"     : "TimestampType",
    "time"             : "TimeType",
    "date"             : "DateType",
    "calendar"        : "CalendarType",
    "currency"        : "CurrencyType",
    "locale"         : "LocaleType",
    "timezone"        : "TimeZoneType",
    "url"             : "UrlType",
    "class"         : "ClassType",
    "blob"             : "BlobType",
    "binary"         : "BinaryType",
    "uuid"             : "UUIDCharType",
    "serializable"    : "SerializableType"
};

• Detached Criteria builder now has a maxResults( maxResults ) method to limit the results by

• Detached Criteria sql projections now take aliases into account

• SQL Projections and SQL Group By projections now respect aliases

Base ORM Service

• New Fail fast methods: getOrFail() proxies to get(), findOrFail() proxies to findIt() that if not entity is produced will throw a EntityNotFound exception

• All listing methods can now return the results as a cbStream by passing the asStream boolean argument.

• Removed criteriaCount(), criteriaQuery() from BaseService, this was the legacy criteria builder approach, please use newCriteria() instead.

• Update getEntityGivenName to support ACF2018

• Lazy loading BeanPopulator for performance on creations

• Lazy loading ORMEventHandler for performance on creations

• Lazy loading restrictions for performance on creations

• Base service can now be initialized with a datasource, or uses the default one declared

• Added optional datasource to many listing methods

• Added consistency on querying options to all major functions to include ignoreCase, sorting and timeouts.

• Added ability to getAll() to retrieve read only entities using the readOnly argument.

• The getAll() method has a new properties argument that if passed will allow you to retrieve an array of structs according to the passed in properties.

• New method: idCast( entity, id ) to auto cast your entity id value to java type automatically for you, no more javacasting

• New method: autoCast( entity, propertyName, value ) to auto cast any value for any entity property automatically, no more javacasting.

• New method: getKeyValue( entity ) which will give you the value of the entity's unique identifier

• New method: isDirty( entity ) which will let you know if the entity has dirty values or has its values changed since loaded from the db

• New method: getEntityMetadata( entity ) which will return to you the hibernate's metadata for a specific entity.

• getPropertyNames() argument of entityname renamed to entity to allow not only for a name but an actual entity as well.

• getTableName() argument of entityname renamed to entity to allow not only for a name but an actual entity as well.

• getKey() argument of entityname renamed to entity to allow not only for a name but an actual entity as well.

• ORM Encapsulation of hibernate metadata retrieval via getEntityMetadata()

• deleteByQuery() reworked entirely to do native bulk delete queries. It now also returns the number of records removed

• deleteWhere() missing flush argument, added datasource as well

• New properties: wirebox : a WireBox reference already injected, logger : a prepared logger for the class, datasource The default datasource or constructed datasource for the class.

• Logging of all activity now available via the debug level, even for dynamic methods.

• Refactored all dynamic finders and counters to their own class, which improves not only performance but weight of orm service based entities.

• All dynamic method calls can now return cbStreams as the results

• All dynamic method calls accept a structure as an argument or named as options that can have the following keys now:

{
    ignoreCase     : boolean (false)
    maxResults     : numeric (0)
    offset         : numeric (0)
    cacheable      : boolean (false)
    cacheName      : string (default)
    timeout        : numeric (0)
    datasource     : string (defaults)
    sortBy         : hql to sort by,
    autoCast       : boolean (true),
    asStream    : boolean (false)
}

results = ormservice.findByLastLoginBetween( "User", "01/01/2008", "11/01/2008", { sortBy="LastName" } );

• All dynamic finders/counters values are autocasted, you no longer need to cast the values, we will do this for you. You can turn it off via the autocast:false in the options to the calls.

Virtual Entity Service

Remember this entity extends Base Service, so we get all the features above plus the following:

Active Entity

Remember this entity extends the Virtual Service, so we get all the features above plus the following:

• Faster creation speeds due to lazy loading of dependencies and better datasource determination.

• refresh(), merge(), evict() refactored to encapsulate login in the base orm service and not itself

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.

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.

Luis Fernando Majano Lainez

Luis Majano is a Computer Engineer that has been developing and designing software systems since the year 2000. 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. Luis resides in Houston, Texas with his beautiful wife Veronica, baby girl Alexia and baby boy Lucas!

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 and ContentBox stack. He is the creator of ColdBox, ContentBox, WireBox, MockBox, LogBox and anything “BOX”, and contributes to many open source ColdFusion/Java 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, microcontrollers and overall embedded systems.

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

Keep Jesus number one in your life and in your heart. I did and it changed my life from desolation, defeat and failure to an abundant life full of love, thankfulness, joy and overwhelming peace. As this world breathes failure and fear upon any life, Jesus brings power, love and a sound mind to everybody!

“Trust in the LORD with all your heart, and do not lean on your own understanding.” Proverbs 3:5

Contributors

Will de Bruin

Brad Wood

Leverage CommandBox to install into your ColdBox app:

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:

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:

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:

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

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.

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

Concrete Services

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:

Let's do a basic example of how to work with cborm when doing basic 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: or in ForgeBox:

ColdBox App

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

Setup Environment

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

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.

Start Server

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

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:

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

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.

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:

Basic CRUD

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

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:

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.

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,

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.

Update

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

Delete

Now let's delete an incoming entity identifier

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

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

BDD Tests

Here are the full completed BDD tests as well

Let's do a basic example of how to work with cborm when doing basic 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: or in ForgeBox:

ColdBox App

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

Setup Environment

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

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.

Start Server

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

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:

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

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.

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:

Basic CRUD

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

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.

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,

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.

Update

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

Delete

Now let's delete an incoming entity identifier

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

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

BDD Tests

Here are the full completed BDD tests as well

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!

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

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.

users = getInstance( "User" )
    .findAllByLastLoginBetweeninGreaterThan( "01/01/2010" );

users = getInstance( "User" )
    .findAllByLastLoginGreaterThanAndLastNameLike( "01/01/2010", "jo%" );

count = getInstance( "User" )
    .countByLastLoginGreaterThan( "01/01/2010" );

count = getInstance( "User" )
    .countByLastLoginGreaterThanAndLastNameLike( "01/01/2010", "jo%" );

Automatic Casting

Another important aspect of the dynamic finders is that we will AUTO CAST all the values for you. So you don't have to mess with the right Java type, we will do it for you.

Streams

We have also enabled the ability to return a stream of objects if you are using the findAll semantics via cbStreams.

userStream = getInstance( "User" )
    .findAllByLastLoginBetweeninGreaterThan( "01/01/2010", {asStream:true} );

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:

component persistent="true" name="User" extends="cborm.models.ActiveEntity"{

     property name="id" column="user_id" fieldType="id" generator="uuid";
     property name="lastName";
     property name="userName";
     property name="password";
     property name="lastLogin" ormtype="date";
}

Then we could do the following:

user = getInstance( "User" ).findByLastName( "Majano" );

users = getInstance( "User" ).findAllByLastNameLike( "Ma%" );

users = getInstance( "User" ).findAllByLastLoginBetween( "01/01/2010", "01/01/2012" );

users = getInstance( "User" ).findAllByLastLoginGreaterThan( "01/01/2010" );

users = getInstance( "User" ).findAllByLastLoginGreaterThanAndLastNameLike( "01/01/2010", "jo%" );

count = getInstance( "User" ).countByLastLoginGreaterThan( "01/01/2010" );

count = getInstance( "User" ).countByLastLoginGreaterThanAndLastNameLike( "01/01/2010", "jo%" );

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

// Get a virtual entity service via DI, there are many ways to get a virtual entity service
// Look at virtual entity service docs for retrieval
property name="userService" inject="entityservice:userService";

user = userService.findByLastName( "Majano" );

users = userService.findAllByLastNameLike( "Ma%" );

users = userService.findAllByLastLoginBetween( "01/01/2010", "01/01/2012" );

users = userService.findAllByLastLoginGreaterThan( "01/01/2010" );

users = userService.findAllByLastLoginGreaterThanAndLastNameLike( "01/01/2010", "jo%" );

count = userService.countByLastLoginGreaterThan( "01/01/2010" );

count = userService.countByLastLoginGreaterThanAndLastNameLike( "01/01/2010", "jo%" );

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

// Get a virtual entity service via DI, there are many ways to get a base entity service
// Look at base entity service docs for retrieval
property name="userService" inject="entityservice";

user = userService.findByLastName( "User", "Majano" );

Most of the Hibernate extensions like criteria builders and even some dynamic finders and counters will have to rely on the underlying Java types 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:

nullValue()

Produce a null value that can be used anywhere you like!

autoCast( entity, propertyName, value )

This method allows you to cast any value to the appropriate type in Java for the property passed in. The entity argument can be the entity name or an entity object.

idCast( entity, id )

This method allows you to cast the identifier value to the appropriate type in Java. The entity argument can be the entity name or an entity object.

Example

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

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

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

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

}