Configuration

Easily configure Hibernate with CFML

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

Last updated