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:

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.

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

• 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:

• ForgeBox:

Discussion & Help

The Ortus Community is the way to get any type of help for our entire platform and modules:

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

Added

• Support for Adobe 2021 on resource loader

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

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

Added

• Allow SQL and SQL Group projections to be functions containing commas

Example:

Added

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

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

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.

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

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

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.

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.

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

Release Notes

Bugs

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

New Features

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

• [] - asQuery update to default it to false

• [] - Document v3 variant in the docs

Improvements

• [] - Source code cleanups by applying formatting rules

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

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

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

Returns

• This function returns back the BaseORMService (this)

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

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

Returns

• This function returns boolean

Arguments

Examples

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

Returns

• A null value

Examples

The source code for this book is hosted in GitHub: . You can freely contribute to it and submit pull requests. The contents of this book is copyright by 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 -

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

Returns the table name of the passed in entity

Returns

• This function returns string

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

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

Returns

• This function returns string

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.

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

Returns

• This function returns any

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

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

The valid query options are:

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

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

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

Returns

• An array of property names

Added

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

Added

• Env templates using new lucee bundles and mysql 8 support

• New interception point:

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 ){
        var user = getInstance( "User" );
        prc.data = user.list( sortOrder="fname" );
        prc.stream = 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 )
            .when( rc.isActive, (user) => user.checkIfActive() )
            .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";
    }

}

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

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

Returns

• This function returns struct

Arguments

Examples

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

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

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

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

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

This method gives you the ability to fluently create chains of executions by evaluating the incoming target as a boolean. If true it will execute the success closure, else the failure closure if passed.

Returns

• The ORM Service so you can do concatenated calls

Arguments

Examples

Returns the persisted Property Names of the entity in array format

Returns

• This function returns array

Arguments

Examples

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:

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

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

Returns

• The Hibernate Java ClassMetadata Object (https://docs.jboss.org/hibernate/orm/3.5/javadocs/org/hibernate/metadata/ClassMetadata.html)

Arguments

Examples

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

Arguments

Examples

Merge an entity or array of entities back into the session

Returns

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

Arguments

Examples

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

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

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

• An entity object

• An array of entity objects

Returns

• This function returns void

Arguments

Examples

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

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.

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

Returns

• This function returns void

Fixed

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

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

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:

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

Checks if the session contains dirty objects that are awaiting persistence

Returns

• This function returns boolean

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

Find all/single entities by example

Returns

• This function returns array

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

Returns

• This function returns void

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

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

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

Returns

• This function returns void

Arguments

Examples

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 good base or parent service layer that can interact with ColdFusion ORM via hibernate and entities inspired by Spring's Hibernate Template support. This means that you don't need to create a service layer CFC in order to work with ORM entities.

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

Usage

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

WireBox DSL

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

• entityservice - Inject a global ORM service

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

Injection

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

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 simple API, but if you need more control then we can start using other approaches shown below.

Virtual Services

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

Concrete Services

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

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:

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

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:

Here is a nice example of calling the super.init() class with some of these constructor properties.

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

Returns

• This function returns array

Arguments

Examples

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

Operators

The only valid operators are:

• And

• Or

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

Returns

• This function returns void

Arguments

Examples

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

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

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

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

Leverage CommandBox to install into your ColdBox app:

System Requirements

• Lucee 5.x+

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:

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

Returns

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

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 asStream boolean argument to get either an array of objects or a Java stream via cbStreams.

Returns

• This function returns array of entities found

Arguments

Examples

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

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

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

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.

This class allows you to implement the pattern in your ORM entities by inheriting from our Active Entity class. This will make your ORM entities get all the functionality of our Virtual and Base ORM services so you can do finds, searches, listings, counts, execute queries, transaction safe deletes, saves, updates, criteria building, and even right from within your ORM Entity.

The idea behind the Active Entity is to allow you to have a very nice abstraction to all the ColdFusion ORM capabilities (hibernate) and all of our ORM extensions like our ColdBox Criteria Builder. With Active Entity you will be able to:

• Find entities using a variety of filters and conditions