Release history for all versions of the Ortus ORM Extension
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.
Introduction
The Ortus ORM Extension is a native Lucee Extension that allows your CFML application to integrate with the powerful Hibernate ORM
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.)
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:
What's New With 6.x
Version 6.x release notes for the Ortus ORM Extension
Resolved "NoClassDefFoundError: javax/validation/ValidatorFactory" on Lucee 6 by adding missing javax.validation dependency. Big thanks to Zack Spitzer on the Lucee team! - Resolves OOE-29
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.
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>
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() -
♻️ Changed
While not technically a change in ORM functionality, the useDBforMapping implementation has been greatly improved "under the hood", with tests to boot.
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.
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.
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)
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.
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.
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 .)
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.
More info on this documentation gitbook for the Ortus ORM Extension
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.
What's New With 5.x
Version 5.x release notes for the Ortus ORM Extension
[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:
We now set a System property to ensure the JAXB API can find its implementation in CommandBox environments. This may trigger a log message, but shouldn't cause any concern. Vanilla Tomcat installations may need to overwrite or clear this property. LDEV-4276
