ORM

edit

Lucee's ORM extension provides Object-Relational Mapping powered by Hibernate 5.6. Define persistent CFCs, map properties to database columns, and use built-in functions to create, read, update, and delete data without writing SQL.

History

1. Lucee core (Hibernate 3.5) — ORM was originally built into Lucee core
2. Extension extraction — ORM was pulled out of core into a standalone extension
3. Lucee 5.4 (beta) — Lucee began upgrading to Hibernate 5.4 but it only reached beta
4. Ortus fork — Ortus Solutions forked the extension, completed the Hibernate 5.4 upgrade, and maintained it
5. Lucee 5.6 (current) — Lucee resumed active development, merging the Ortus work and upgrading to Hibernate 5.6 with native logging, transaction integration, and expanded test coverage

Recipes

• ORM - Getting Started — Enable ORM, define an entity, CRUD operations
• ORM - Configuration — All ormSettings, schema management, naming strategies
• ORM - Entity Mapping — Entity properties, primary keys, inheritance
• ORM - Relationships — many-to-one, one-to-many, many-to-many, cascade, fetching
• ORM - Querying — HQL queries, entity loading, pagination, JOIN FETCH
• ORM - Sessions and Transactions — Sessions, flush behaviour, transactions, multi-datasource
• ORM - Events — Entity lifecycle events and global event handlers
• ORM - Caching — Second-level cache and query cache
• ORM - Logging and Debugging — SQL logging, debugging techniques
• ORM - Migration Guide — What's new in 5.6, migrating from ACF
• ORM - Troubleshooting — Common pitfalls, error messages, performance tips

Functions

• EntityDelete()

  Deletes the record from the database for the specified entity. EntityDelete(entity)

• EntityLoad()

  Loads and returns an array of entities of the specified entityName. EntityLoad (entityName, filterCriteria [,unique] EntityLoad(entityName, filterCriteria, sortOrder [, options])

• EntityLoadByExample()

  Loads and returns an array of objects that match the sample entity. entityLoadByExample(sampleEntity,[unique])

• EntityLoadByPK()

  Loads and returns the entity for the given primary key, or null if not found.

• EntityMerge()

  Attaches the given entity to the current ORM session.

• EntityNameArray()

  Returns all loaded entity names as an array.

• EntityNameList()

  Returns all loaded entity names as a delimited string list.

• EntityNew()

  Creates a new instance of the persistent CFC with the entity name that you provide.

• EntityReload()

  Reloads data for an entity that is already loaded.

• EntitySave()

  Saves or updates data of the entity and all related entities to the database. EntitySave(entity, [forceInsert])

• EntityToQuery()

  Converts the input entity object or the input array of entity objects to a query object.

• GetORMTransactionIsolation()

  Returns the JDBC transaction isolation level from the ORM session's connection as a string (e.g. "serializable"). Returns "" if no ORM session is active. Matches the convention of the core getTransactionIsolation() BIF.

• getTransactionIsolation()

  Returns the isolation level of the current transaction as a string. If a datasource is provided and no explicit isolation is set, returns the datasource's default isolation level.

• IsWithinORMTransaction()

  Returns true if a Hibernate ORM transaction is currently active on any ORM datasource. Safe to call when ORM is not configured — returns false.

• ORMClearSession()

  Removes all the entities that are loaded or created in the session. This clears the first level cache and removes the objects that are not yet saved to the database.

• ORMCloseAllSessions()

  Closes all ORM sessions.

• ORMCloseSession()

  Closes the current ORM session.

• ORMEvictCollection()

  Evicts all cached entries for the specified collection/relationship on the given entity from the second-level cache.

• ORMEvictEntity()

  Evicts all cached entries for the specified entity from the second-level cache.

• ORMEvictQueries()

  Evicts all queries from the named query cache. If cacheName is not specified, evicts the default query cache.

• ORMExecuteQuery()

  Runs the HQL on the default data source specified for the application.

• ORMFlush()

  Flushes the current ORM session. ORMFlush flushes all the pending CRUD operations in that request. Any changes made in the objects, in the current ORM session, are saved to the database.

• ORMFlushAll()

  Flushes all open ORM sessions across all datasources. All pending CRUD operations in every active ORM session are saved to the database.

• ORMGetSession()

  Returns the current ORM session.

• ORMGetSessionFactory()

  Returns the Hibernate SessionFactory for the given datasource.

• ORMQueryExecute()

  Modern alias to ORMExecuteQuery(). Run an HQL query on the default ORM datasource.

• ORMReload()

  Reinitializes ORM for the application. Rebuilds all entity mappings and the Hibernate SessionFactory. Active idle sessions are closed and their connections released; sessions with in-flight transactions are invalidated for cleanup by their owning thread. Intended for development use only.

• TransactionCommit()

  commits a pending transaction

• TransactionRollback()

  rolls back a pending transaction

• TransactionSetSavePoint()

  Saves a specific state within a transaction

Tags

• <cftransaction>

  Groups multiple queries into a single unit. The cftransaction tag provides commit and rollback processing.

Categories

• Queries

Guides

• ORM - Caching

  Configuring the Hibernate second-level cache and query cache with EHCache in Lucee ORM

• ORM - Configuration

  Complete guide to ORM settings, schema management, naming strategies, and custom Hibernate mappings in Lucee

• ORM - Entity Mapping

  Defining ORM entities, property types, primary key strategies, computed properties, and inheritance patterns in Lucee

• ORM - Events

  Entity lifecycle events, global event handlers, event firing order, and patterns for setting values in preInsert/preUpdate handlers in Lucee ORM

• ORM - Getting Started

  Quick start guide to using ORM in Lucee: enable ORM, define an entity, and perform CRUD operations

• ORM - Logging and Debugging

  ORM logging settings, debugging techniques, inspecting generated SQL, savemapping, and advanced Hibernate session API in Lucee

• ORM - Migration Guide

  What's new in the 5.6 ORM extension, migrating from older versions, and migrating from Adobe ColdFusion ORM to Lucee

• ORM - Querying

  HQL queries, entity loading functions, pagination, bulk DML, JOIN FETCH, aggregate functions, and query caching in Lucee ORM

• ORM - Relationships

  Mapping relationships between ORM entities: many-to-one, one-to-many, one-to-one, many-to-many, collections, cascade, fetching strategies, and batch loading

• ORM - Sessions and Transactions

  Understanding ORM sessions, entity lifecycle states, flush behaviour, dirty checking, transactions, savepoints, and multi-datasource usage in Lucee

• ORM - Troubleshooting

  Common ORM pitfalls, error messages decoded, performance tips, and design patterns for Lucee ORM

See also

• Queries