All pages
Powered by GitBook
1 of 4

Configuration

Easily configure Hibernate with BL

Application.bx

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

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

Setting Name
Default
Description

autoGenMap

true

Specifies whether ColdFusion should automatically generate entity mappings for the persistent classes. If autogenmap=false, the mapping should be provided in the form of .HBMXML files.

autoManageSession

true

Allows the engine to manage the Hibernate session. It is recommended not to let the engine manage it for you. Use transaction blocks in order to demarcate your regions that should start, flush and end a transaction. https://docs.jboss.org/hibernate/orm/5.4/userguide/html_single/Hibernate_User_Guide.html#transactions

cacheConfig

true

Specifies the location of the configuration file that the secondary cache provider should use. This setting is used only when secondaryCacheEnabled=true. See Secondary Cache below.

cacheProvider

"ehcache"

Specifies the cache provider that ORM should use as a secondary cache. The values can be:

  • Ehcache

  • ConcurrentHashMap

  • The fully qualified name of the class for any other cache provider.

See Secondary Cache below.

catalog

Specifies the default Database Catalog that ORM should use.

entityPaths

empty

Specifies the directory (or array of directories) that should be used to search for persistent CFCs to generate the mapping.

Always specify it or pay a performance startup price.

Important:

If it is not set, the extension looks at the application directory, its sub-directories, and its mapped directories to search for persistent CFCs.

datasource

application.datasource

This setting defines the data source to be utilized by the ORM. If not used, defaults to the this.datasource in the Application.bx

dbcreate

none

  • update : Creates the database according to your ORM model. It only does incremental updates. It will never remove tables, indexes, etc.

  • dropcreate : Same as above but it destroys the database if it has ny content and recreates it every time the ORM is reloaded.

  • none : Does not change the database at all.

dialect

autodiscover

The dialect to use for your database. By default Hibernate will introspect the datasource and try to figure it out. See the dialects section below. You can also use the fully Java qualified name of the class. See the dialects section below.

eventHandling

false

If true, then it enables the ORM event callbacks in entities and globally via the eventHandler

eventHandler

Path to the .bx class that will manage the global ORM events.

flushAtRequestEnd

true

Specifies if an orm flush should be called automatically at the end of a request. In our opinion this SHOULD never be true. A database persistence should be done via transaction tags and good transaction demarcation.

logSQL

false

Specifies if the SQL queries should be logged to the console.

namingstrategy

default

Defines the naming convention to use on table and column names. - default : Uses the table or column names as is - smart : This strategy changes the logical table or column name to uppercase. - CFC PATH : Use your own CFC to determine naming - see Custom Naming Strategy.

ormconfig

The path to a custom Hibernate configuration file: - hibernate.properties - hibernate.bx.xml Please see Custom Hibernate Config

savemapping

false

If enabled, the ORM will create the Hibernate mapping XML (*.hbmxml) files alongside the entities. This is great for debugging your entities and relationships.

schema

The default database schema to use

secondaryCacheEnabled

false

Enable the secondary cache or not. See our Caching section.

ignoreParseErrors

false

If true, then the ORM will ignore classes that have compile time errors in them. Use false to throw exceptions.

sqlScript

Path to a SQL script file that will be executed after the ORM is initialized. A great way to seed a database.

useDBForMapping

true

Specifies whether the database has to be inspected to identify the missing information required to generate the Hibernate mapping.

The database is inspected to get the column data type, primary key and foreign key information.

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.

Dialect (short name)
Remarks

Cache71

Support for the Caché database, version 2007.1.

CockroachDB192

Support for the CockroachDB database version 19.2.

CockroachDB201

Support for the CockroachDB database version 20.1.

CUBRID

Support for the CUBRID database, version 8.3. May work with later versions.

DB2

Support for the DB2 database, version 8.2.

DB297

Support for the DB2 database, version 9.7.

DB2390

Support for DB2 Universal Database for OS/390, also known as DB2/390.

DB2400

Support for DB2 Universal Database for iSeries, also known as DB2/400.

DB2400V7R3

Support for DB2 Universal Database for i, also known as DB2/400, version 7.3

DerbyTenFive

Support for the Derby database, version 10.5

DerbyTenSix

Support for the Derby database, version 10.6

DerbyTenSeven

Support for the Derby database, version 10.7

Firebird

Support for the Firebird database

FrontBase

Support for the Frontbase database

H2

Support for the H2 database

HANACloudColumnStore

Support for the SAP HANA Cloud database column store.

HANAColumnStore

Support for the SAP HANA database column store, version 2.x. This is the recommended dialect for the SAP HANA database. May work with SAP HANA, version 1.x

HANARowStore

Support for the SAP HANA database row store, version 2.x. May work with SAP HANA, version 1.x

HSQL

Support for the HSQL (HyperSQL) database

Informix

Support for the Informix database

Ingres

Support for the Ingres database, version 9.2

Ingres9

Support for the Ingres database, version 9.3. May work with newer versions

Ingres10

Support for the Ingres database, version 10. May work with newer versions

Interbase

Support for the Interbase database.

JDataStore

Support for the JDataStore database

McKoi

Support for the McKoi database

Mimer

Support for the Mimer database, version 9.2.1. May work with newer versions

MySQL5

Support for the MySQL database, version 5.x

MySQL5InnoDB

Support for the MySQL database, version 5.x preferring the InnoDB storage engine when exporting tables.

MySQL57InnoDB

Support for the MySQL database, version 5.7 preferring the InnoDB storage engine when exporting tables. May work with newer versions

MariaDB

Support for the MariaDB database. May work with newer versions

MariaDB53

Support for the MariaDB database, version 5.3 and newer.

Oracle8i

Support for the Oracle database, version 8i

Oracle9i

Support for the Oracle database, version 9i

Oracle10g

Support for the Oracle database, version 10g

Pointbase

Support for the Pointbase database

PostgresPlus

Support for the Postgres Plus database

PostgreSQL81

Support for the PostgrSQL database, version 8.1

PostgreSQL82

Support for the PostgreSQL database, version 8.2

PostgreSQL9

Support for the PostgreSQL database, version 9. May work with later versions.

Progress

Support for the Progress database, version 9.1C. May work with newer versions.

SAPDB

Support for the SAPDB/MAXDB database.

SQLServer

Support for the SQL Server 2000 database

SQLServer2005

Support for the SQL Server 2005 database

SQLServer2008

Support for the SQL Server 2008 database

Sybase11

Support for the Sybase database, up to version 11.9.2

SybaseAnywhere

Support for the Sybase Anywhere database

SybaseASE15

Support for the Sybase Adaptive Server Enterprise database, version 15

SybaseASE157

Support for the Sybase Adaptive Server Enterprise database, version 15.7. May work with newer versions.

Teradata

Support for the Teradata database

TimesTen

Support for the TimesTen database, version 5.1. May work with newer versions

See the Hibernate Dialect Section: Hibernate_User_Guide.html#database-dialect

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
	entityPaths           : [
		// 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", "" ),
	flushAtRequestEnd    : false,
	autoManageSession    : false,
	eventHandling        : true,
	eventHandler         : "cborm.models.EventHandler",
	ignoreParseErrors     : 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 boxlang class:

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

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

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

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

Custom Hibernate Config

For full Hibernate configuration support, you can create 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>

Secondary Caches

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.

Looking for alternate cache providers? Contact our Support team to consider sponsoring this feature.

Logging

How do Hibernate logs work in bx-orm?

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

For more information on configuring loggers, see the Boxlang Logging documentation.

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.