All pages
Powered by GitBook
2 of 5

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:

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

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:

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

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 sponsoring a feature or opening a support contract.

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 to MySQL8 and PostgreSQL

  • 60% faster startup than the Lucee Hibernate extension

  • 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 CFML functions:

    • EntityDelete()

    • EntityLoad()

    • EntityLoadByExample()

    • EntityLoadByPK()

    • EntityMerge()

    • EntityNameArray()

    • EntityNameList()

    • EntityNew()

    • EntityReload()

    • EntitySave()

    • EntityToQuery()

    • ORMClearSession()

    • ORMCloseAllSessions()

    • ORMEvictCollection()

    • ORMEvictEntity()

    • ORMEvictQueries()

    • ORMExecuteQuery()

    • ORMFlush()

    • ORMGetSession()

    • ORMGetSessionFactory()

    • ORMReload()

See the extension changelog 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 contact us for support.

Release History

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.

What's New With 6.x

Version 6.x release notes for the Ortus ORM Extension

6.5.2 - 2024-02-21

🐛 Fixed

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

6.5.1 - 2024-02-20

🐛 Fixed

  • Fixes empty string values coercing to NULL when no property type is declared. - Resolves OOE-25, introduced in 6.5.0.

6.5.0 - 2024-02-16

🐛 Fixed

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

🔐 Security

Bump Lucee build dependency to 5.4.4.38 to avoid vulnerable dependencies in the build process.

6.4.0 - 2023-12-05

🔐 Security

Resolve an Uncontrolled Resource Consumption vulnerability disclosed on 12/4/2023 by upgrading logback-core to 1.3.14. See vulnerability details.

⭐ Added

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() - LDEV-4461

♻️ Changed

While not technically a change in ORM functionality, the useDBforMapping implementation has been greatly improved "under the hood", with tests to boot.

6.3.2 - 2023-09-29

🐛 Fixed

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.

6.3.1 - 2023-09-26

🐛 Fixed

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.

6.3.0 - 2023-08-18

🔐 Security

Switched the EHCache library to use net.sf.ehcache.internal:ehcache-core.

  • Upgrades EHCache version from 2.10.6 to 2.10.9.2.

  • Drops an embedded rest-management-private-classpath directory

  • Drops a number of (unused) vulnerable jackson and jetty libraries such as jackson-core.

  • As an added bonus, this reduces the final .lex extension file size by over 6 MB. 🎉

Note: While it is not 100% clear, some of these CVEs may have been false positives.

6.2.0 - 2023-08-03

♻️ Changed

Hibernate Upgraded from 5.4 to 5.6

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)

See the migration guides for more info:

CLOB columns in Postgres81

Due to the Hibernate 5.6 upgrade, if you are using the PostgreSQL81 dialect and have CLOB columns in your database, it is recommended you migrate existing text columns for LOBs to oid.

Default EHCache Configuration

The default ehcache.xml for EHCache changed to include clearOnFlush="true" and diskSpoolBufferSizeMB="30MB" properties to match Adobe ColdFusion 9's default ehCache.xml config. Both these values represent default settings in EHCache itself.

🐛 Fixed

  • 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. OOE-9

6.1.0 - 2023-07-14

♻️ Changed

  • Lots of java source code cleanup that won't affect the CFML experience, but will aid in faster development and fewer bugs.

🐛Fixed

  • Any hibernate exceptions returned during schema generation are once again logged to the Lucee ORM log file.

💥 Removed

  • Dropped the public method from the Dialect class. This method was unused (to my knowledge) and unnecessary.

🔐 Security

6.0.0 - 2023-07-01

⭐ Added

Second-Level Caching

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

OWASP Dependency CVE Scans

The extension GitHub Release page now generates a dependency CVE report via Jeremy Long's OWASP dependency-check maven plugin. Any known CVEs contained in dependencies ( excluding and -scoped dependencies) will be noted in each release's CVE report artifact.

♻️ Changed

New Repo Layout

  • Java source moved to

  • All java classes are now under the package

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

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:

WARNING: Using non-standard property: javax.xml.bind.context.factory. Property javax.xml.bind.JAXBContextFactory should be used instead.

See OOE-3.

[5.4.29.27] - 2023-05-29

🐛 Fixed

  • 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

[5.4.29.26] - 2023-05-24

♻️ Changed

  • Improved logo for Lucee admin 🤩

🐛 Fixed

  • Entity changes made in and do not persist OOE-2

[5.4.29.25] - 2023-05-23

♻️ Changed

🐛 Fixed

[5.4.29.24] - 2023-05-17

🔐 Security

[5.4.29.23] - 2023-05-15

🐛 Fixed

  • ORMExecuteQuery ignores argument if struct is passed

[5.4.29.22] - 2023-05-11

⭐ Added

🐛 Fixed

♻️ Changed

  • Dramatic improvements in initialization performance

  • Cuts ORM reload time by 60%

  • Better build/test documentation

  • Improved maintenance and build docs

About This Book

More info on this documentation gitbook for the Ortus ORM Extension

The source code for this book is hosted in GitHub:

https://github.com/ortus-docs/orm-extension

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.

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 GitHub repository 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 - https://www.harvesting.org/. 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

LogoHarvesting in Spanish - Evangelism With A Heart
www.harvesting.org

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.