CommandBox

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

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

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

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

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

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.

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:

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:

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.

Extension v6.1-

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

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 .

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

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

• Source Code:

• Support Plans:

• Bug Tracker:

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

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

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.

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:

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

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

Alternate Cache Providers Are Unsupported

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

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

Savepoints are not currently supported on ORM transactions.

- 2025-09-01

🐛 Fixed

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>

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

For versions of Lucee running log4j 2.x, the above workaround does not apply. If you are interested in tweaking the Hibernate logging level in the Lucee Hibernate extension, I would suggest and future users can benefit from the shared knowledge.

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

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:

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

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:

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:

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"):

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

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"):

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:

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:

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:

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:

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:

Relationship Methods

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 will enable two different event listener types for listening to Hibernate events:

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:

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

EntityDelete

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

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

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:

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:

Returns: Component

EntityNameArray

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

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:

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

Returns: string

EntityNew

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

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

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

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:

Returns: null

EntitySave

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

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

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

Returns: Array|Struct|any

ORMReload

Returns: null

Application.cfc

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

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

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:

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

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

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

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.

lets the application assign an identifier to the object before save() is called. This is the default strategy if no element is specified. -

Assigned generators will commonly use to assign the identifer value:

Select Generator

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

retrieves a primary key, assigned by a database trigger, by selecting the row by some unique key and retrieving the primary key value. -

UUID Generator

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

uses a 128-bit UUID algorithm to generate identifiers of type string that are unique within a network (the IP address is used). The UUID is encoded as a string of 32 hexadecimal digits in length. -

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.

Generates identifiers of type long, short or int that are unique only when no other process is inserting data into the same table. Do not use in a cluster. -

Other Valid Generator Types

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

• foreign - use a foreign CFC's generator configuration

• seqhilo

• sequence