Application.cfc

The ORM can be configured by a struct of settings set in this.ormSettings in your main Application.cfc:

component{
    this.ORMenabled = true;
    this.ormSettings = {
        // << Here Be ORM Configuration! 🤪 >>
    };
}

ORM Settings

The full list of available properties you can use to configure the ORM are the following:

Dialects

By using the ormsettings.dialect you can tell Hibernate which specific database dialect to use for building queries. By default, Hibernate tries to inspect the datasource and define it for you. 95% of the time, this works. However, if you want a specific one, then you can use the following names or a fully qualified Java class name.

Sample Config

Here is an example configuration from the popular ContentBox Modular CMS application

// THE CONTENTBOX DATASOURCE NAME
this.datasource  = "contentbox";
// ORM SETTINGS
this.ormEnabled  = true;
// cfformat-ignore-start
this.ormSettings = {
	// ENTITY LOCATIONS, ADD MORE LOCATIONS AS YOU SEE FIT
	cfclocation           : [
		// If you create your own app entities
		"models",
		// The ContentBox Core Entities
		"modules/contentbox/models",
		// Custom Module Entities
		"modules_app",
		// Custom Module User Entities
		"modules/contentbox/modules_user"
	],
	// THE DIALECT OF YOUR DATABASE OR LET HIBERNATE FIGURE IT OUT, UP TO YOU TO CONFIGURE.
	dialect              : request.$systemHelper.getSystemSetting( "ORM_DIALECT", "" ),
	// DO NOT REMOVE THE FOLLOWING LINE OR AUTO-UPDATES MIGHT FAIL.
	dbcreate             : "update",
	secondarycacheenabled: request.$systemHelper.getSystemSetting( "ORM_SECONDARY_CACHE", false ),
	cacheprovider        : request.$systemHelper.getSystemSetting( "ORM_SECONDARY_CACHE", "ehCache" ),
	logSQL               : request.$systemHelper.getSystemSetting( "ORM_LOGSQL", false ),
	sqlScript            : request.$systemHelper.getSystemSetting( "ORM_SQL_SCRIPT", "" ),
	// ORM SESSION MANAGEMENT SETTINGS, DO NOT CHANGE
	flushAtRequestEnd    : false,
	autoManageSession    : false,
	// ORM EVENTS MUST BE TURNED ON FOR CONTENTBOX TO WORK DO NOT CHANGE
	eventHandling        : true,
	eventHandler         : "cborm.models.EventHandler",
	// THIS IS ADDED SO OTHER CFML ENGINES CAN WORK WITH CONTENTBOX
	skipCFCWithError     : true,
	// TURN ON FOR Debugging if ORM mappings are not working.
	savemapping          : false
};

Custom Naming Strategy

You can define your own naming convention for table and column names by pointing this.ormSettings.namingStrategy to a custom CFC path:

this.ormSettings = {
	// ...
	namingStrategy : "models.orm.UnderscoreNamingStrategy"
}

The UnderscoreNamingStrategy.cfc component should then define two methods: getTableName() and getColumnName():

// models/orm/UnderscoreNamingStrategy.cfc
component{
	function getTableName( string tableName ){
		// funky table name conversion here...
	}

	function getColumnName( string columnName ){
		// funky column name conversion here...
	}
}

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

A new layout, cache and logging improvements, and much more.

Version 5.x

Our initial fork of the Lucee Extension.

CommandBox

You can install this extension by adding the extension ID to the lucee-extensions environment variable and restarting the server:

box server set env.LUCEE_EXTENSIONS="D062D72F-F8A2-46F0-8CBC91325B2F067B" && box restart

You can install a specific version by appending a version string to the extension ID:

box server set env.LUCEE_EXTENSIONS="D062D72F-F8A2-46F0-8CBC91325B2F067B;version=6.5.2" && box restart

(For all available version numbers, see our Release History or the GitHub Releases page.)

Running the box server set env.lucee-extensions command will edit your server.json file to look something like this:

{
    // ...
    "env":{
        "LUCEE_EXTENSIONS":"D062D72F-F8A2-46F0-8CBC91325B2F067B;version=6.5.2"
    }
}

This config instructs Lucee (not CommandBox) to install the Ortus ORM Extension when Lucee starts up.

From the Lucee Server Admin

You can manually install the extension by opening the Lucee server admin page and browsing to Extension > Applications page, where you'll see a "Ortus ORM Extension" option. Clicking this option will open the installation screen, where you can choose any extension version and click "Install" to install from Forgebox.

Direct Download

You can also download a .lex file from our downloads page and upload this through the Lucee Server admin's Applications page.

Don't Forget To Restart!

Whichever method you use to install the extension, we recommend restarting the server after installing.

Via CommandBox:

server restart

Ortus ORM Extension

The Ortus ORM Extension is a native Lucee Extension that allows your CFML application to integrate with the powerful Hibernate ORM. With Hibernate, you can interact with your database records in an object oriented fashion, using components to denote each record and simple getters and setters for each field value:

component entityName="Auto" persistent="true" {

	property name="id" type="string" fieldtype="id" ormtype="string";
	property name="make" type="string";
	property name="model" type="string";

    function onPreInsert(){
        log.info( "Inserting new Auto: #getMake()# #getModel()#" );
    }
}

The Ortus ORM extension also enables transactional persistence, where an error during a save will roll back the entire transaction to prevent leaving the database in a broken state:

transaction{
    try{
        entitySave(
            entityNew( "Purchase", {
                productID : "123-expensive-watch",
                purchaseTime : now(),
                customerID : customer.getId()
            })
        );
        var cartProducts = entityLoad( "CartProduct", customer.getID() );
        entityDelete( cartProducts );
    } catch ( any e ){
        // don't clear the user's cart if the purchase failed
        transactionRollback();
        rethrow;
    }
}

Requirements

• Lucee 5.3.9.73 and above

• Java 8, 11 or 17

Hibernate Version Support

Extension v6.2+

The Ortus ORM Extension bundles Hibernate 5.6.15.FINAL since extension version 6.2.0.

• https://hibernate.org/orm/releases/5.6/

• https://docs.jboss.org/hibernate/orm/5.6/userguide/html_single/Hibernate_User_Guide.html

• https://docs.jboss.org/hibernate/orm/5.6/javadocs/

Extension v6.1-

Previous versions of the Ortus ORM Extension bundle Hibernate 5.4.29.FINAL:

• https://hibernate.org/orm/releases/5.4/

• https://docs.jboss.org/hibernate/orm/5.4/userguide/html_single/Hibernate_User_Guide.html

• https://docs.jboss.org/hibernate/orm/5.4/javadocs/

Open Source Product

The Ortus ORM extension is an open source Lucee server extension with no license purchase necessary. If you are looking to further the development of this extension, consider sponsoring a feature or opening a support contract.

Features In A Nutshell

• Add Object Relational Mapping to any CFML app with Hibernate ORM

• Use native CFML methods to update and persist entities to the database (entityNew(), entitySave(), ormFlush(), etc.)

• Supports 80+ database dialects, from SQLServer2005 to MySQL8 and PostgreSQL

• 60% faster startup than the Lucee Hibernate extension

• Generate your mapping XML once and never again with the autoGenMap=false ORM configuration setting

• React to entity changes with pre and post event listeners such as onPreInsert(), onPreUpdate() and onPreDelete()

• Over 20 native CFML functions:

  • EntityDelete()

  • EntityLoad()

  • EntityLoadByExample()

  • EntityLoadByPK()

  • EntityMerge()

  • EntityNameArray()

  • EntityNameList()

  • EntityNew()

  • EntityReload()

  • EntitySave()

  • EntityToQuery()

  • ORMClearSession()

  • ORMCloseAllSessions()

  • ORMEvictCollection()

  • ORMEvictEntity()

  • ORMEvictQueries()

  • ORMExecuteQuery()

  • ORMFlush()

  • ORMGetSession()

  • ORMGetSessionFactory()

  • ORMReload()

See the extension changelog for a full list of enhancements and bug fixes.

Support

Our expertise with Hibernate ORM and Lucee Server allows us to give back to the community, as well as offer premium support to enterprises looking for a level up in their Hibernate implementations. If you need performance optimization, session management or caching integrations, please contact us for support.

• Source Code: https://github.com/Ortus-Solutions/extension-hibernate

• Support Plans: https://www.ortussolutions.com/services/support

• Bug Tracker: https://ortussolutions.atlassian.net/browse/OOE

The source code for this book is hosted in GitHub:

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

External Licensing

Both Lucee Server and Hibernate ORM are licensed under the LGPL v2.1.

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

Charitable Proceeds

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.

[5.4.29.28] - 2023-06-07

🐛 Fixed

We now set the JAXB system property based on the JRE version. If less than JRE 11, we set . If JRE 11 or greater, we set .

This prevents the following warning from being logged on each ORM method call:

[5.4.29.27] - 2023-05-29

🐛 Fixed

[5.4.29.26] - 2023-05-24

♻️ Changed

• Improved logo for Lucee admin 🤩

🐛 Fixed

[5.4.29.25] - 2023-05-23

♻️ Changed

• Switched to Maven for a faster, more stable build process

🐛 Fixed

[5.4.29.24] - 2023-05-17

🔐 Security

[5.4.29.23] - 2023-05-15

🐛 Fixed

• ORMExecuteQuery ignores argument if struct is passed

[5.4.29.22] - 2023-05-11

⭐ Added

🐛 Fixed

♻️ Changed

• Dramatic improvements in initialization performance

• Cuts ORM reload time by 60%

• Better build/test documentation

• Improved maintenance and build docs

How can I configure/acquire Hibernate logging in the Ortus ORM Extension?

The Ortus ORM Extension reconfigures all Hibernate logging output on startup to log ERROR-level events to the server console.

How can I configure/acquire Hibernate logging in the Lucee Hibernate Extension?

This depends on the version of Lucee you are running - specifically, on whether you're on Log4J 2 or not.

Lucee versions running Log4J 1.x

Lucee versions containing the older log4j 1.x can use this code to set a custom logging level and redirect the Hibernate logs to the server console:

Lucee versions running Log4J 2.x

Identifier properties are denoted via fieldtype="id".

We highly recommend disabling updates on identifier properties via update="false":

Common Generator Types

Assigned Generator

The Assigned generator is the default identifier generator type, and simply allows the application (your CFML) to assign identifier values prior to insertion. You can think of this as generator=none.

Select Generator

A select generator will attempt to select the next identifier value from the specified selectKey column:

UUID Generator

The UUID generator uses Hibernate's uuid generator under the hood:

Increment Generator

The Increment generator uses a simple incrementing value to create identifiers. Do not use in concurrent applications, as the values may no longer be unique.

Other Valid Generator Types

There are several lesser-known identifier generator types, including:

• foreign - use a foreign CFC's generator configuration

• seqhilo

• sequence

• select - select the next value from the column denoted in selectKey

• uuid - use Hibernate's UUID generation

Entity properties are how we map table columns to CFML object values. You can specify an entity property by setting persistent="true" on any property inside a persistent CFML component:

By default, all properties inside a persistent=true component are assumed to be persistent as well. Thus, we can skip the persistent=true annotation for brevity:

Common Property Annotations

Make sure you quote datetime dbdefault values to avoid invalid date errors in MySQL:

Property Types

There are several "type" concepts and annotations you may need to use to keep the proper format when persisting or retrieving table data. While these may look similar, they are not equivalent.

Field Type

The fieldtype attribute allows you to define the behavior and purpose of this property:

There are several options for the fieldtype value:

• column - By far the most common, this is the default behavior of every field.

• id - Notes this field as the primary key or part of the a composite key.

• collection - Denote a collection of items - this could represent a struct, an array

• timestamp - Denote a timestamp field

• primary - Not currently used.

Generator Annotations

Validation

Collection Modifiers

These property annotations are used when setting fieldtype="collection" and collectiontype is either struct or map.

Relationship Modifiers

Other

Formula Property

Unsupported Attributes

For full Hibernate configuration support, you can point the ORM extension to an XML file containing any configuration properties you wish to configure:

this.ormSettings = {
    // ...
    ormconfig : "./config/persistence.xml"
};

You can then populate the XML file with valid Hibernate configuration syntax:

<!-- persistence.xml -->
<?xml version="1.0" encoding="UTF-8"?>    
<!DOCTYPE hibernate-configuration PUBLIC    
        "-//Hibernate/Hibernate Configuration DTD 3.0//EN"    
        "https://hibernate.org/dtd/hibernate-reverse-engineering-3.0.dtd">    
<hibernate-configuration>    
    <session-factory>    
    
    <!-- https://docs.jboss.org/hibernate/orm/5.4/javadocs/org/hibernate/cfg/AvailableSettings.html#USE_SQL_COMMENTS -->
    <property name="hibernate.use_sql_comments">true</property>
    <property name="hibernate.cache.use_query_cache">true</property>
         
    </session-factory>
</hibernate-configuration>

Hibernate's secondary cache is a powerful tool that can greatly improve the performance of your application. By storing frequently accessed data in memory, the secondary cache can reduce the number of database queries that need to be made, resulting in faster response times and more efficient use of system resources. Whether you're working on a small project or a large enterprise application, the secondary cache is an essential part of any Hibernate-based system. So if you want to get the most out of your Hibernate application, take advantage of this powerful caching feature!

Please see the caching section for all the wonderful caching strategies you can do with Hibernate.

Configuration

A secondary cache provider is a class that manages a level of caching secondary to Hibernate's main caching context - the Hibernate session. A secondary cache enables longer-running cache contexts, more fine-grained control over cache busting, and other performance-related benefits.

The only setting necessary to enable secondary caching is the secondaryCacheEnabled setting:

this.ormSettings = {
    secondaryCacheEnabled : true
};

To configure the caching, specify the path to an XML cache configuration file in cacheConfig:

this.ormSettings = {
    secondaryCacheEnabled: true,
    cacheConfig          : "./config/ehcache.xml"
};

This ehcache.xml cache configuration then should look something like this:

<?xml version="1.0" encoding="UTF-8"?>
<ehcache
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="ehcache.xsd" updateCheck="true" name="default">
    <diskStore path="java.io.tmpdir"/>
        <defaultCache
            maxElementsInMemory="10000" eternal="false"
            timeToIdleSeconds="120" timeToLiveSeconds="120"
            maxElementsOnDisk="10000000" diskExpiryThreadIntervalSeconds="120"
            memoryStoreEvictionPolicy="LRU">
            <persistence strategy="localTempSwap"/>
        </defaultCache>
        <cache
            name="Autos"
            maxElementsInMemory="20"
            overflowToDisk="false"
            eternal="true">
        </cache>
</ehcache>

Alternate Cache Providers Are Unsupported

While there is a cacheProvider setting, only EHCache (currently) is supported as a secondary cache provider.

this.ormSettings = {
    secondaryCacheEnabled : true,
    // NOT SUPPORTED!
    cacheProvider : "ConcurrentHashMap"
};

Thus, any usage of cacheProvider other than "ehcache" will be ignored.

Savepoints are not currently supported on ORM transactions.

The Ortus ORM Extension offers a number of CFML functions for loading and manipulating entities as well as managing the ORM session:

• Built-In Functions

  • EntityDelete

  • EntityLoad

  • EntityLoadByExample

  • EntityLoadByPK

  • EntityMerge

  • EntityNameArray

  • EntityNameList

  • EntityNew

  • EntityReload

  • EntitySave

  • EntityToQuery

  • IsValidDatasource

  • ORMClearSession

  • ORMCloseAllSessions

  • ORMCloseSession

  • ORMEvictCollection

  • ORMEvictEntity

  • ORMEvictQueries

  • ORMExecuteQuery

  • ORMFlush

  • ORMGetSession

  • ORMGetSessionFactory

  • ORMQueryExecute

  • ORMReload

EntityDelete

EntityDelete allows you to delete the row associated with an instantiated entity from the database:

entityDelete( myEntity );

Only a single argument is accepted - the entity to delete - and the deletion is not persisted until the session is flushed.

entityDelete( myEntity );
// entity (row) still exists in the database.
ormFlush();
// entity (row) is now wiped from the database.

Returns: null

EntityLoad

Returns: Array|Component|null

EntityLoadByExample

Returns: Array|Component|null

EntityLoadByPK

EntityLoadByPK() allows you to instantiate an entity using the row identified by a primary key:

var theUser = entityLoadByPk( "User", url.userID );

A third argument, unique, is documented but not implemented in either the Lucee Hibernate extension or the Ortus ORM Extension.

Returns: Component|null

EntityMerge

EntityMerge() will merge a "detached" entity (meaning, not connected to any open session) back into the session.

For example, running ormClearSession() will detach all loaded entities from the session. If you then make changes to an entity via a setter and run ormFlush(), those entity modifications will not be persisted unless you first merge the entity back to the session:

var detachedAutoEntity = entityLoadByPK( "Auto", "12345" );

// make a change but don't save it
detachedAutoEntity.setModel( "Fusion" );

// clear session - will "detach" the entity
ormClearSession();

// "merge" it back to the session
var merged = entityMerge( detachedAutoEntity );

// changes should be reflected in the new entity
expect( merged.getModel() ).toBe( "Fusion" );

Returns: Component

EntityNameArray

EntityNameArray() returns an array of all mapped entity names for the CFML application:

var entityTypes = entityNameArray();

EntityNameArray accepts no arguments.

Returns: Array

EntityNameList

True to its name, EntityNameList returns a string list of all mapped entity names for the CFML application:

var entityTypes = entityNameList();

You can pass a string delimiter value as the first argument, if you don't like commas:

var entityTypes = entityNameList( "|" );

Returns: string

EntityNew

The entityNew() method allows you to create a new instance of a known entity type:

var myCar = entityNew( "Auto" );

You can also pass a struct of properties to populate into the entity:

var myCar = entityNew( "Auto", {
  make : "Ford",
  model : "Fusion",
  id : createUUID()
} );

Note that if you try to populate a property which does not exist, you will get an error:

var myCar = entityNew( "Auto", {
    make : "Ford",
    model : "Fusion",
    propThatDoesntExist : "abc"
} );

This will throw an error: component [Auto] has no function with name [setPROPTHATDOESNTEXIST]

Returns: Component

EntityReload

entityReload() will reload or refresh the entity state from the database. Local, unpersisted modifications will be replaced with database values.

Here's a quick example:

var myCar = entityLoadByPK( "Auto", "12345" );

// make a change but don't save it
myCar.setModel( "Revuelto" );

// reload the entity
entityReload( myCar );

// our local changes should be replaced with the DB value
expect( myCar.getModel() ).toBe( "Aventador" );

Returns: null

EntitySave

EntitySave() is how you save entity modifications. The changes will not persist to the database until ormFlush() is called:

var myCar = entityNew( "Auto", {
  make : "Ford",
  model : "Fusion",
  id : createUUID()
} );
entitySave( myCar );
ormFlush();

EntitySave accepts an optional boolean parameter, forceInsert, which will tell Hibernate to skip the entity existence check and insert the entity:

var myCar = entityNew( "User", {
  username : "Johnny.Appleseed",
  password : "McinT0sh"
} );
entitySave( myCar, true );

Most of the time this will be unnecessary.

Returns: null

EntityToQuery

Returns: Query

IsValidDatasource

Returns: Boolean

ORMClearSession

Returns: null

ORMCloseAllSessions

Returns: null

ORMCloseSession

Returns: null

ORMEvictCollection

Returns: null

ORMEvictEntity

Returns: null

ORMEvictQueries

Returns: null

ORMExecuteQuery

Returns: Array|Struct|any

ORMFlush

Returns: null

ORMGetSession

Returns: Session

ORMGetSessionFactory

Returns: SessionFactory

ORMQueryExecute

Alias for ORMExecuteQuery().

Added in v6.4.0 (unreleased, version number subject to change.) - 5600833

Returns: Array|Struct|any

ORMReload

Returns: null

A persistent entity is a CFML component that is marked as a database entity via the persistent annotation upon the component definition:

By default, the entity name will be the CFC file name - minus the file extension, of course. We can modify the entity name via the entityname annotation:

And the table name via the table annotation:

Here's the full list of available annotations for a persistent component:

Hibernate ORM allows reacting to various events in the session lifecycle such as onPreInsert, onPostUpdate, onFlush, etc. You can enable event handling in CFML by setting eventHandling to true in your this.ormSettings struct:

this.ormSettings = {
    eventHandling: true
};

This will enable two different event listener types for listening to Hibernate events:

• Listen to all events across all entities via the global event handler

• Listen to specific events on a specific entity via entity event handler methods

Global Event Handler

To use a global event handler, you must set a path to the global event handler using the eventHandler setting:

this.ormSettings = {
    eventHandling: true,
    eventHandler : "path/to/global/EventHandler.cfc"
};

The EventHandler.cfc must then contain function definitions matching the ORM events you wish to listen for.

Currently, the available event names are:

• onFlush

• preLoad

• postLoad

• preInsert

• postInsert

• preUpdate

• postUpdate

• preDelete

• onDelete

• postDelete

• onEvict

• onClear

• onDirtyCheck

• onAutoFlush

Here's an example of an EventHandler configured for all events:

component {

	public component function init(){
		return this;
	}

	function onFlush( entity ) {
		// Do something upon function call
	}

	function preLoad( entity ){
		// Do something upon function call
	}
	function postLoad( entity ){
		// Do something upon function call
	}

	function preInsert( entity ){
		// Do something upon function call
	}
	function postInsert( entity ){
		// Do something upon function call
	}

	function preUpdate( entity, Struct oldData  ){
		// Do something upon function call
	}
	function postUpdate( entity ){
		// Do something upon function call
	}

	function preDelete( entity ){
		// Do something upon function call
	}	
	function onDelete( entity ) {
		// Do something upon function call
	}
	function postDelete( entity ) {
		// Do something upon function call
	}

	function onEvict() {
		// Do something upon function call
	}
	function onClear( entity ) {
		// Do something upon function call
	}
	function onDirtyCheck( entity ) {
		// Do something upon function call
	}
	function onAutoFlush( entity ) {
		// Do something upon function call
	}
}

Entity Event Handler

You can also listen to events on a specific entity at the entity level by adding methods to the entity (component) itself:

component persistent="true"{
	function preInsert( entity ){
		setDateCreated( now() );
	}
	function preUpdate( entity ){
		setDateModified( now() );
	}
}

Here is the full list of event types which can be listened to in entity event listeners:

• preLoad

• postLoad

• preInsert

• postInsert

• preUpdate

• postUpdate

• preDelete

• onDelete

• postDelete

A transaction is any discrete unit of work used to pool database queries and statements to execute at once. This helps us to prevent a failed update from leaving the database in a broken state.

To denote a transaction, we wrap it in the transaction{} tag:

The transaction will automatically commit (persist) at the end of the transaction block.

Transaction Rollback

Transaction Commit

Transaction Savepoint

Savepoints are not currently supported on ORM transactions.

Relationships

Every relationship property must define the state of the relationship. In each case, the relationship property is defined in an entity which represents the "left" side of the relationship. If you bring a Posts relationship into the User entity, then from the User entity, the User is the left side of the relationship, and Posts is the right.

One To One

A one to one relationship couples a single row on the left side to a single row on the right side:

property name="Contact"
    fieldtype="one-to-one"
    cfc="Contact";

One to one relationships can be seen as simply extending the entity with additional information. Since there is no possibility of multiple records per entity instance, it may be worthwhile to set lazy=false to fetch the related entity along with any entity load:

property name="Contact"
    fieldtype="one-to-one"
    cfc="Contact"
    lazy="false";

One To Many

A one to many relationship couples a single row on the left side (the "one") to multiple rows on the right side (the "many"):

component entityName="User" persistent="true"{
    property name="posts"
        fieldtype="one-to-many"
        cfc="Post";
}

You'll normally want to set lazy="true" to (for example) avoid fetching every Post on a User:

property name="posts"
    fieldtype="one-to-many"
    cfc="Post"
    lazy="true";

Many To One

A many to one relationship couples multiple rows on the left side (the "many") to a single row on the right side( the "one"):

component entityName="Post" persistent="true"{
    property name="Authors"
        fieldtype="many-to-one"
        cfc="User";
}

Thus, a single Post can have only one Author... but an author (or a User, really) can have many Posts.

Many To Many

A many to many relationship allows each entity to relate to multiple rows on the opposite side. A good example might be a blog which allows multiple authors for a single blog post. Each blog post can then have multiple authors, and each author has (likely) written multiple blog posts:

component entityName="User" persistent="true"{
    property name="posts"
        fieldtype="many-to-many"
        cfc="Post"
        linktable="user_posts_link";
}

The linktable attribute is required on a many-to-many property to set the locationfor storing join records. You can further alter the storage location via linkschema and linkcatalog:

property name="posts"
    fieldtype="many-to-many"
    cfc="Post";
    linkschema="blog"
    linkcatalog="dbo";

Singular Name

On many* relationships like one-to-many, many-to-one, etc., you'll be manipulating the full set of items via the property name: hasAuthors(), setAuthors(), etc. However, this plural terminology becomes weird when used on a single item addition or removal, such as addAuthors( Author ). For this reason, you can define a singularName=STRING attribute to clean up your entity manipulation:

property name="Authors"
    singularName="Author"
    fieldtype="many-to-one"
    cfc="User";

Lazy

Man, you wanna get lazy? How about don't-fetch-the-data-until-you-need-it kinda lazy?

Using lazy=true, we can tell Hibernate not to fetch the relational data unless and until a method call such as Authors() attempts to load it. This greatly improves performance on page requests which do not need that particular data:

property name="posts"
    fieldtype="one-to-many"
    cfc="Post"
    lazy="true";

We can also use lazy=extra to only retrieve the rows that we touch. This may work well if we commonly only access a few rows out of the full set of child items:

property name="posts"
    fieldtype="one-to-many"
    cfc="Post"
    lazy="extra";

Relationship Methods

6.5.2 - 2024-02-21

🐛 Fixed

• Fixes a regression on OOE-26 where empty string values are coerced to NULL when an ORM type is declared. Originally reported against 6.4.0, resolved in 6.5.0, then regressed in 6.5.1. - Resolves OOE-26.

6.5.1 - 2024-02-20

🐛 Fixed

• Fixes empty string values coercing to NULL when no property type is declared. - Resolves OOE-25, introduced in 6.5.0.

6.5.0 - 2024-02-16

🐛 Fixed

• Fixes an incorrect property name lookup for the unsavedValue persistent property attribute.

• Fixes the pre-event listeners to ignore empty strings in entity state properties if the field type is one of string, character, or text. This resolves issues where a preInsert() or preUpdate() throws a "can't cast [] to date value" when processing event listeners if a date field (for example) is unpopulated or has an empty default attribute.

♻️ Changed

Add the entity name to the exception message when attempting to persist changes from preInsert or preUpdate event listeners. The updated exception message is now:

Error populating event state for persistance in [<entity name>] entity pre-event listener method: <error message from Hibernate>

🔐 Security

Bump Lucee build dependency to 5.4.4.38 to avoid vulnerable dependencies in the build process.

6.4.0 - 2023-12-05

🔐 Security

Resolve an Uncontrolled Resource Consumption vulnerability disclosed on 12/4/2023 by upgrading logback-core to 1.3.14. See vulnerability details.

⭐ Added

New ORMQueryExecute() alias for the ORMExecuteQuery. This new alias behaves identically to the ORMExecuteQuery() method, but is named consistently with the queryExecute() method.

🐛 Fixed

• Fixes custom configuration support via this.ormSettings.ormConfig.

• Fixes named argument support for entityLoad() - LDEV-4285

• Fixes named argument support for entityLoadByPK() - LDEV-4461

♻️ Changed

While not technically a change in ORM functionality, the useDBforMapping implementation has been greatly improved "under the hood", with tests to boot.

6.3.2 - 2023-09-29

🐛 Fixed

Fixed pre-event listeners to include parent component properties when checking for entity mutations to persist back to the event entity state. This resolves issues with changes made in preInsert()/preUpdate() not persisting if the changes are made on a persistent property from a parent component. Resolves OOE-14.

6.3.1 - 2023-09-26

🐛 Fixed

Refactored nullability checks to occur after pre-event listener methods fire. Resolves OOE-12

⭐ Added

Added context to the error message in CFCGetter, which handles retrieving entity values from Hibernate code. This improves odd error messages in some edge cases with the Hibernate tuplizer.

6.3.0 - 2023-08-18

🔐 Security

Switched the EHCache library to use net.sf.ehcache.internal:ehcache-core.

• Upgrades EHCache version from 2.10.6 to 2.10.9.2.

• Drops an embedded rest-management-private-classpath directory

• Drops a number of (unused) vulnerable jackson and jetty libraries such as jackson-core.

• As an added bonus, this reduces the final .lex extension file size by over 6 MB. 🎉

Note: While it is not 100% clear, some of these CVEs may have been false positives.

6.2.0 - 2023-08-03

♻️ Changed

Hibernate Upgraded from 5.4 to 5.6

This brings the Hibernate dependencies up to date (released Feb. 2023), and should not change any CFML-facing features for most users. (See CLOB columns in Postgres81)

See the migration guides for more info:

• Hibernate 5.4 -> 5.4 migration guide

• Hibernate 5.5 -> 5.6 migration guide

CLOB columns in Postgres81

Due to the Hibernate 5.6 upgrade, if you are using the PostgreSQL81 dialect and have CLOB columns in your database, it is recommended you migrate existing text columns for LOBs to oid.

Default EHCache Configuration

The default ehcache.xml for EHCache changed to include clearOnFlush="true" and diskSpoolBufferSizeMB="30MB" properties to match Adobe ColdFusion 9's default ehCache.xml config. Both these values represent default settings in EHCache itself.

🐛 Fixed

• Fixes handling of "timezone"-typed column values. Previously, fields defined with ormtype="timezone" would neither use the default value nor allow new values to be set. OOE-10

• Fixes entity state changes in preInsert()/preUpdate() listeners for properties with no default defined. OOE-9

6.1.0 - 2023-07-14

♻️ Changed

• Lots of java source code cleanup that won't affect the CFML experience, but will aid in faster development and fewer bugs.

🐛Fixed

• Any hibernate exceptions returned during schema generation are once again logged to the Lucee ORM log file.

💥 Removed

• Dropped the public method from the Dialect class. This method was unused (to my knowledge) and unnecessary.

🔐 Security

• Switched to Snyk vulnerability scanner to limit false positives. Security vulnerabilities will now be published on the GitHub repository's Security Advisories page.

• Bumped Lucee dependency to to remove vulnerability notices on org.apache.tika:tika-core and commons-net:commons-net. These vulnerabilities are only theoretical, since Lucee is a dependency and not bundled with the extension.

6.0.0 - 2023-07-01

⭐ Added

Second-Level Caching

The extension will now throw an error if you try to configure an unsupported cache provider like , , etc. Previously, the extension would silently switch to ehcache if any cache provider besides EHCache was configured.

Hibernate Logging

This version re-enables Hibernate logging via SLF4j and LogBack. Hibernate root and cache loggers are defaulted to level, while SQL logging is set to if is enabled. (Set to .)

OWASP Dependency CVE Scans

The extension GitHub Release page now generates a dependency CVE report via Jeremy Long's OWASP dependency-check maven plugin. Any known CVEs contained in dependencies ( excluding and -scoped dependencies) will be noted in each release's CVE report artifact.

♻️ Changed

New Repo Layout

• Java source moved to

• All java classes are now under the package

• Dropped the java source format-on-push in favor of format-on-save IDE tooling

New Test Layout

• Internal tests rewritten to native Testbox specs

• Cloned all ORM tests from the Lucee repository

• Updated to TestBox 5.0

New Build (and .jar file) Layout

We re-architected the build to inline most dependencies. I.e. we no longer copy in extension dependencies as (custom-built) OSGI bundles, but instead as compiled classes.

• This resolves intermittent issues with bundle resolution and/or duplicate bundle collision upon installing the ORM extension into a Lucee server prior to uninstalling the Lucee Hibernate extension.

• This also removes a number of direct dependencies on custom OSGI bundles, thus it is more reliable and will offer easier dependency upgrades with less pain.

Other

• The attribute is deprecated in Hibernate 5.x, and is no longer generated on HBM/XML mapping files to avoid Hibernate warning that Use of DOM4J entity-mode is considered deprecated.

🐛Fixed

• The definition file for all built-ins was missed during the conversion to a Maven build. (Since v5.4.29.25). This caused the and built-in method calls to be picked up by Lucee core before being routed to this extension. No known errors resulted from this mistake, but we feel embarrassed anyway. 😅

• Clear ORM context data once per ORM reload, not once per ORM entity parsing. This should improve ORM startup/reload time and avoid difficult session or cache manager lifecycle issues.

Secondary Cache

A secondary cache provider is a class which manages a level of caching that is secondary to Hibernate's main caching context - the Hibernate session. A secondary cache enables longer-running cache contexts, more fine-grained control over cache busting, and other performance-related benefits.

The only setting necessary to enable secondary caching is the secondaryCacheEnabled setting:

this.ormSettings = {
    secondaryCacheEnabled : true
};

To configure the caching, specify the path to an XML cache configuration file in cacheConfig:

this.ormSettings = {
    secondaryCacheEnabled: true,
    cacheConfig          : "./config/ehcache.xml"
};

This ehcache.xml cache configuration then should look something like this:

<?xml version="1.0" encoding="UTF-8"?>
<ehcache
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="ehcache.xsd" updateCheck="true" name="default">
    <diskStore path="java.io.tmpdir"/>
        <defaultCache
            maxElementsInMemory="10000" eternal="false"
            timeToIdleSeconds="120" timeToLiveSeconds="120"
            maxElementsOnDisk="10000000" diskExpiryThreadIntervalSeconds="120"
            memoryStoreEvictionPolicy="LRU">
            <persistence strategy="localTempSwap"/>
        </defaultCache>
        <cache
            name="Autos"
            maxElementsInMemory="20"
            overflowToDisk="false"
            eternal="true">
        </cache>
</ehcache>

Configure Each Entity Cache

Notice how our ehcache.xml defines a default cache configuration?

<defaultCache
    maxElementsInMemory="10000" eternal="false"
    timeToIdleSeconds="120" timeToLiveSeconds="120"
    maxElementsOnDisk="10000000" diskExpiryThreadIntervalSeconds="120"
    memoryStoreEvictionPolicy="LRU">
    <persistence strategy="localTempSwap"/>
</defaultCache>

We highly recommend adding a cache configuration for each cacheable entity. This will help you optimize caching, and will silence error logs like the below:

WARN: HHH90001006: Missing cache[default-update-timestamps-region] was created on-the-fly. The created cache will use a provider-specific default configuration: make sure you defined one. You can disable this warning by setting 'hibernate.cache.ehcache.missing_cache_strategy' to 'create'

Here's a quick example. Say we have an Autos.cfc persistent component with caching enabled:

component persistent="true" cacheUse="true"{
    // persistent properties...
}

For this entity, we'll want to create a <cache></cache> entry with a name attribute that matches the entity name OR our cacheName component annotation:

<cache
    name="Autos"
    maxElementsInMemory="20"
    overflowToDisk="false"
    eternal="true">
</cache>

Alternate Cache Providers Are Unsupported

While there is a cacheProvider setting, only EHCache (currently) is supported as a secondary cache provider.

this.ormSettings = {
    secondaryCacheEnabled : true,
    // NOT SUPPORTED!
    cacheProvider : "ConcurrentHashMap"
};

Thus, any usage of cacheProvider other than "ehcache" will be ignored.