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 :

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

Release Notes

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

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

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

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

Finders are convenience methods that will help you find a single entity or a collection of entities by using criterias. If you want to use primary keys, then use the getters.

Here is a collection of useful getter methods for entities by primary identifiers. Getters mostly deal with retrieving entities by primary keys instead of finders which rely on criteria operations. You can use the get() for a single entity, getOrFail() for throwing exceptions if an entity is not found and getAll() for multiple entities.

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

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

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

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

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

Versioning

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

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:

Important Links

• Code:

• Issues:

Professional Open Source

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

• Custom Development

• Professional Support & Mentoring

• Training

• Server Tuning

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

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

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

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:

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:

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:

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

This method will return to you the hibernate's metadata for a specific entity.

Returns

• The Hibernate Java ClassMetadata Object ()

Get the unique identifier value for the passed in entity, or null if the instance is not in session

Returns

• This function returns any

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

These collection of methods will give you information about the currently loaded entity or the entity class itself.

These methods are used for doing a-la-carte querying of entities with extra pizzaz!

Now that you have created your entities, how do we use them? Well, you will be using them from your handlers or other services by leveraging WireBox's getInstance() method. You can use entityNew() as well, but if you do, you will loose any initial dependency injection within the entity. This is a ColdFusion limitation where we can't listen for new entity constructions. If you want to leverage DI, as best practice retrieve everything from WireBox.

Once you have an instance of the entity, then you can use it to satisfy your requirements with the entire gamut of functions available from the base services.

component{
    
    function index( event, rc, prc ){
        prc.data = getInstance( "User" ).list( sortOrder="fname" );
        prc.stream = getInstance( "User" ).list( sortOrder="fname", asStream=true );
    }
    
    function count( event, rc, prc ){
        return getInstance( "User" ).count()
        return getInstance( "User" ).countWhere( { isActive : true } );
    }
    
    function show( event, rc, prc ){
        return getInstance( "User" )
            .getOrFail( 123 )
            .getMemento();
    }
    
    function save( event, rc, prc ){
        return populateModel( model="User", composeRelationships=true )
            .save()
            .getMemento();
    }
    
    function delete( event, rc, prc ){
        getInstance( "User" )
            .getOrFail( rc.id ?: -1 )
            .delete();
        return "User 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.

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

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!)

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

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.

user = entityNew( "User" )
    .findByLastName( "Majano", { ignoreCase=true, timeout=20 } );

users = entityNew( "User" )
    .findAllByLastNameLike( "Ma%", { ignoreCase=false, max=20, offset=15 } );

The valid query options are:

• ignorecase : Ignores the case of sort order when you set it to true.

• 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

• datasource : The datasource to use, it defaults to the application

• sortBy : The HQL to sort the query by

• autoCast : No more casting, let us do auto casting for you

• asStream : Want a stream back instead of the results, no problem!

Here is a more descriptive key set with the types and defaults

The Base ORM Service has a ton of methods to assist you with your ORM needs. We have compiled them under this section under several different categories:

• Criteria Queries

• Creation - Population

• Counters

• Deleting Entities

• Entity Convenience

• Finders

• Getters

• ORM Session

• Querying

• Saving

• Utility

Like always, you can find the latest in the link below:

Checks if the given entityName and id exists in the database, this method does not load the entity into session. A very useful approach to check for data existence.

Returns

• This function returns boolean

Arguments

Examples

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

Returns the table name of the passed in entity

Returns

• This function returns string

Arguments

Examples

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

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

Find all/single entities by example

Returns

• This function returns array

Arguments

Examples

Verifies if the passed in entity has dirty values or not since loaded from the database.

Returns

• This function returns true if the entity values have been changed since loaded into the hibernate session, else false

Arguments

Examples

Returns the persisted Property Names of the entity in array format

Returns

• This function returns array

Arguments

Examples

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

Examples

Checks if the current hibernate session contains the passed in entity.

Returns

• This function returns boolean

Arguments

Examples

Checks if the session contains dirty objects that are awaiting persistence

Returns

• This function returns boolean

Arguments

Examples

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.

• If the key cannot be identified then a blank string is returned.

Returns

• This function returns any

Arguments

Examples

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 the base service reference (this)

Arguments

Examples

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

Returns

• This function returns string

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

Returns

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

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

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

Returns

• This function returns back the BaseORMService (this)

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

Merge an entity or array of entities back into the session

Returns

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

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

Returns

• This function returns void

Get an array of property names that that have been changed from the original loaded session state.

Returns

• An array of property names

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

Returns

• This function returns void

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

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.

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.

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.

Returns

• This function returns the value casted to the right Java type

Evict entity object(s) from the hibernate session or first-level cache.

• An entity object

• An array of entity objects

Get an entity using a primary key, if the id is not found this method throws an EntityNotFound Exception

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. Please note that this is ONLY used for identifier casting not for any property!

Returns

• This function returns the value casted to the right Java type

Leverage CommandBox to install into your ColdBox app:

System Requirements

• Lucee 5.x+

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

Returns

• A null value

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

Deletes all the entity records found in the database in a transaction safe matter and returns the number of records removed

Returns

• This function returns numeric

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

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

Evict all the collection or association data for a given entity name and collection name from the secondary cache ONLY, not the hibernate session.

Evict an entity name with or without an ID from the secondary cache ONLY, not the hibernate session

Returns

• This function returns void

Arguments

Examples

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

Major Features

Criteria Query Fluent If Statements - when()

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:

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:

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

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

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

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.

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

You can use the readOnly argument to give you the entities as read only entities.

You can use the properties argument so this method can return to you array of structs instead of array of objects. The property list must include the as alias if not you will get positional keys.

Example Positional: properties="catID,category Example Aliases: properties="catID as id, category as category, role as role"

You can use the

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.

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

Hibernate provides several ways to retrieve data from the database. We have seen the normal entity loading operations in our basic CRUD and we have seen several HQL and SQL query methods as well. The last one is the .

The ColdBox Hibernate Criteria Builder is a powerful object that will help you build and execute in a fluent and dynamic manner. 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. This is error prone, syntax crazy and sometimes untestable.

The ColdBox Criteria Builders offers a powerful programmatic DSL builder for Hibernate Criteria queries. It focuses on a criteria object that you will build up to represent the query to execute. The cool thing is that you can even retrieve the exact HQL or even SQL the criteria query will be executing. You can get the explain plans, provide query hints and much more. In our experience, criteria queries will make your life much easier when doing complicated queries.

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

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

Finds and returns the first result for the given query or throws an exception if not found, this method delegates to the findIt() method

Returns

• This function returns any

• This function could throw an EntityNotFound exception

Arguments

Examples

Create a virtual service for a specific 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

List all of the instances of the passed in entity class name with or without any filtering of properties, no HQL needed.

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 if asQuery = false

• This function returns a query if asQuery = true

• This function returns a stream if asStream = true

Arguments

Examples

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. You will do this in two steps:

1. Inherit from cborm.models.VirtualEntityService

2. Call the super.init() constructor with the entity to root the service and any other options

Below is a sample service layer:

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

Allows the execution of Custom HQL queries with binding, pagination, and many options. Underlying mechanism is ORMExecuteQuery. The params filtering can be using named or positional.

Returns

• This function returns any

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 or entity 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.

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