BoxLang ORM

class 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()#" );
    }
}

BoxLang ORM 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;
    }
}

Hibernate Version Support

bx-orm bundles Hibernate 5.6.15.FINAL.

Open Source Product

Features In A Nutshell

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

• Use native built-in-functions (BIFs) to update and persist entities to the database (entityNew(), entitySave(), ormFlush(), etc.)

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

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

  • EntityDelete()

  • EntityLoad()

  • EntityLoadByExample()

  • EntityLoadByPK()

  • EntityMerge()

  • EntityNameArray()

  • EntityNameList()

  • EntityNew()

  • EntityReload()

  • EntitySave()

  • EntityToQuery()

  • ORMClearSession()

  • ORMCloseAllSessions()

  • ORMEvictCollection()

  • ORMEvictEntity()

  • ORMEvictQueries()

  • ORMExecuteQuery()

  • ORMFlush()

  • ORMGetSession()

  • ORMGetSessionFactory()

  • ORMReload()

Support

CommandBox

If you're using CommandBox to manage your BoxLang server, it's as easy as running install bx-orm:

box install bx-orm

You may need to install bx-compat-cfml as well for backwards-compatible ORM behaviors:

box install bx-orm bx-compat-cfml

install-bx-module

For miniserver usage outside of CommandBox, use the install-bx-module CLI command:

install-bx-module bx-orm

Note that bx-orm currently only supports the web runtime.

The source code for this book is hosted in GitHub:

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

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.

Application.bx

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

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

The UnderscoreNamingStrategy.bx class should then define two methods: getTableName() and getColumnName():

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.

v1.x

1.0.11 - 2025-06-10

🐛 Fixed

1.0.10 - 2025-05-03

🐛 Fixed

⭐ Added

1.0.9 - 2025-04-29

🐛 Fixed

1.0.8 - 2025-04-25

⭐ Added

🐛 Fixed

1.0.7 - 2025-04-14

🐛 Fixed

• Fix string casting error on lazy property annotation

1.0.6 - 2025-04-14

🐛 Fixed

⭐ Added

1.0.5 - 2025-04-07

🐛 Fixed

• Removed debugging code

1.0.4 - 2025-04-06

🐛 Fixed

1.0.3 - 2025-04-06

🐛 Fixed

1.0.2 - 2025-04-04

No significant changes.

1.0.1 - 2025-04-04

⭐ Added

🐛 Fixed

1.0.0 - 2025-03-26

• First iteration of this module

For full Hibernate configuration support, you can create an XML file containing any configuration properties you wish to configure:

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

There are several categories of logs generated during normal use of a bx-orm application:

1. bx-orm logs

2. SQL logs

3. Hibernate logs

bx-orm logs

Logging statements generated from bx-orm itself will be output to the orm.log file located in the boxlang runtime logs/ directory.

This log file may look something like the below when DEBUG mode is enabled:

[2025-04-25T09:50:34,965] [Test worker] [DEBUG] [ORM] beforeApplicationListenerLoad fired; checking for ORM configuration 
[2025-04-25T09:50:34,972] [Test worker] [DEBUG] [ORM] ORMEnabled, starting up ORM app for [myApp] 
[2025-04-25T09:50:34,979] [Test worker] [DEBUG] [ORM] ORMApp created for application: [myapp_1428735748] 
[2025-04-25T09:50:35,001] [Test worker] [DEBUG] [ORM] Found more than 20 entities; parallelizing metadata introspection 
[2025-04-25T09:50:35,006] [Test worker] [DEBUG] [ORM] Loading metadata for class /app/models/cms/Author.bx 
[2025-04-25T09:50:35,007] [Test worker] [DEBUG] [ORM] Parsing class file: [/app/models/cms/Author.bx] 
...

SQL Logs

bx-orm has the ability to log every SQL statement generated from ORM code. For example, firing entityDelete( myEntity ) will generate a DELETE SQL statement for deleting the entity (table row) in question from the entity table.

A quick example might be this log, generated after firing entityNew( "Manufacturer", properties ):

[2025-04-25T09:50:46,264] [Test worker] [DEBUG] [org.hibernate.SQL] 
    /* insert Manufacturer
        */ insert 
        into
            manufacturers
            (name, address, id) 
        values
            (?, ?, ?) 

To enable this behavior, set this.ormSettings.logSQL to true in your Application.bx:

this.ormSettings={
	"logSQL" : "true"
	// ...
}

These SQL statements will also log to the orm.log file located in ${boxlang-home}/logs.

Hibernate-native logs

Hibernate-native logging statements will also be captured in the orm.log file located in ${boxlang-home}/logs.

Identifier properties are denoted via fieldtype="id".

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

property name="id"
            fieldtype="id"
            ormtype="string"
            generator="assigned"
            update="false";

Common Generator Types

Assigned Generator

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

property name="id"
            fieldtype="id"
            generator="assigned"
            update="false";

function preInsert( entity ){
    setId( createUUID() );
}

Select Generator

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

property name="userID"
            fieldtype="id"
            generator="select"
            selectKey="ssn"
            update="false";

UUID Generator

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

property name="userID"
            fieldtype="id"
            generator="uuid"
            update="false";

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.

property name="userID"
            fieldtype="id"
            generator="increment"
            update="false";

Other Valid Generator Types

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

• foreign - use a specific property from a foreign entity

• seqhilo

• sequence

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

• uuid - use Hibernate's UUID generation

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

class entityName="User" persistent="true"{
    property name="posts"
        fieldtype="one-to-many"
        class="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"
    class="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"):

class entityName="Post" persistent="true"{
    property name="Authors"
        fieldtype="many-to-one"
        class="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:

class entityName="User" persistent="true"{
    property name="posts"
        fieldtype="many-to-many"
        class="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"
    class="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"
    class="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"
    class="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"
    class="Post"
    lazy="extra";

Relationship Methods

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

class persistent="true"{
    property name="name" type="string" persistent="true";
}

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

class persistent="true"{
    property name="name" type="string";
}

Common Property Annotations

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

property
    name     ="createdOn"
    ormtype  ="datetime"
    dbdefault="'2016-10-10'";

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:

property
    name="userID"
    fieldtype="id"
    type="string";

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

property name="totalPosts"
    ormType="integer"
    formula="(
        SELECT COUNT(*)
        FROM posts
        WHERE posts.FK_user = id
    )";

Unsupported Attributes

A persistent entity is a boxlang class that is marked as a database entity via the persistent annotation upon the class definition:

class persistent="true"{

}

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

class persistent="true" entityname="Author" {

}

And the table name via the table annotation:

class persistent="true" entityname="Author" table="authors" {

}

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

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!

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.

bx-orm implements a number of built-in-functions (BIFs) for loading and manipulating entities as well as managing the ORM session:

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|Class|null

EntityLoadByExample

Returns: Array|Class|null

EntityLoadByPK

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

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

EntityNameArray

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

EntityNameArray accepts no arguments.

Returns: Array

EntityNameList

True to its name, EntityNameList returns a string list of all mapped entity names for the boxlang 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: class [Auto] has no function with name [setPROPTHATDOESNTEXIST]

Returns: Class

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

Returns: Array|Struct|any

ORMReload

Returns: null

Hibernate ORM allows reacting to various events in the session lifecycle such as onPreInsert, onPostUpdate, onFlush, etc. You can enable event handling in bx-orm 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:

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.bx"
};

The EventHandler.bx 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:

class {

	public class 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 (class) itself:

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

transaction{
    // queries go here
}

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.

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.bx persistent class with caching enabled:

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