Merge branch 'development'

Author: lmajano

.github/copilot-instructions.md

@@ -1,19 +1,41 @@
 # CBOrm Copilot Instructions
 
-CBOrm is a ColdBox module that enhances Hibernate ORM for CFML engines (BoxLang, Lucee, Adobe ColdFusion). It provides service layers, Active Record patterns, fluent criteria queries, and dynamic finders.
+CBOrm is a ColdBox module that **enhances and abstracts Hibernate ORM** for CFML engines (BoxLang, Lucee, Adobe ColdFusion). It extends Hibernate with service layers, Active Record patterns, fluent criteria queries, dynamic finders, RESTful resources, and AOP transaction management.
 
 ## Core Architecture
 
 **Service Layer Pattern**: CBOrm uses three main service types:
-- `BaseORMService` - Base service for any entity operations (`models/BaseORMService.cfc`)
-- `VirtualEntityService` - Auto-generated services per entity via WireBox DSL
-- `ActiveEntity` - Active Record pattern for entities (`models/ActiveEntity.cfc`)
-
-**Key Components**:
-- `models/criterion/CriteriaBuilder.cfc` - Fluent query builder for Hibernate criteria
+- `BaseORMService` - Base service for any entity operations with CRUD, dynamic finders, criteria queries (`models/BaseORMService.cfc`)
+- `VirtualEntityService` - Auto-generated entity-specific services via WireBox DSL, extends BaseORMService (`models/VirtualEntityService.cfc`)
+- `ActiveEntity` - Active Record pattern for entities with direct CRUD methods (`models/ActiveEntity.cfc`)
+
+**Criteria Query System**: Fluent API wrapping Hibernate Criteria API
+- `models/criterion/BaseBuilder.cfc` - Base builder with projections, restrictions, ordering, grouping
+- `models/criterion/CriteriaBuilder.cfc` - Main criteria query builder for regular queries
+- `models/criterion/DetachedCriteriaBuilder.cfc` - Detached criteria for subqueries and projections
+- `models/criterion/Restrictions.cfc` - Proxy to Hibernate Restrictions (eq, gt, like, between, etc.)
+- `models/criterion/Subqueries.cfc` - Extends Restrictions for subquery support (subEq, subGt, etc.)
+
+**Utilities & Helpers**:
+- `models/util/ORMUtilFactory.cfc` - Factory for cross-engine ORM utilities
+- `models/util/support/ORMUtilSupport.cfc` - Engine-agnostic ORM operations (session, transactions, metadata)
+- `models/util/support/AdobeORMUtil.cfc` - Adobe ColdFusion-specific ORM utilities
+- `models/util/support/LuceeORMUtil.cfc` - Lucee-specific ORM utilities
+- `models/util/support/BoxLangORMUtil.cfc` - BoxLang-specific ORM utilities
+- `models/util/DynamicProcessor.cfc` - Processes dynamic finders (findByName, countByStatus, etc.)
+- `models/util/JavaProxyBuilder.cfc` - Creates Java proxies for Hibernate classes
+- `models/sql/SQLHelper.cfc` - Extracts and formats SQL from criteria queries for debugging
+
+**Event Handling**:
+- `models/EventHandler.cfc` - ORM lifecycle event handler (preLoad, postLoad, preInsert, postInsert, etc.)
+- `models/ACFEventHandler.cfc` - Adobe ColdFusion-specific event handler with CFIDE interface
+
+**Integration Components**:
 - `dsl/OrmDsl.cfc` - WireBox DSL for `entityService:{entityName}` injection
-- `models/EventHandler.cfc` - ORM lifecycle event handling
-- `models/util/ORMUtilFactory.cfc` - Cross-engine ORM utilities
+- `aop/HibernateTransaction.cfc` - AOP aspect for @transactional annotation support
+- `interceptors/CriteriaBuilder.cfc` - ColdBox interceptor for SQL logging
+- `models/resources/BaseHandler.cfc` - RESTful base handler for automatic CRUD REST APIs
+- `models/validation/UniqueValidator.cfc` - Custom validator for unique entity properties
 
 ## Essential Patterns
 
@@ -32,17 +54,73 @@ component extends="cborm.models.ActiveEntity" persistent="true" {
     // Entity definition
 }
 
-// Usage: var user = new User().findByEmail("test@example.com");
+// Usage examples:
+var user = new User().findByEmail("test@example.com");
+user.setName("New Name").save();
+user.delete();
 ```
 
 **Fluent Criteria Queries**: Chain methods for complex queries:
 ```cfml
+// Basic criteria with restrictions
 userService.newCriteria()
     .isTrue("isActive")
+    .eq("status", "approved")
+    .like("name", "John%")
+    .list();
+
+// With joins and projections
+userService.newCriteria()
     .joinTo("role").eq("name", "admin")
-    .withProjections(property="id,name")
+    .withProjections(property="id,name,email")
     .asStream()
     .list();
+
+// Subqueries with DetachedCriteriaBuilder
+var subQuery = roleService.createSubcriteria("Role", "r")
+    .eq("type", "premium");
+userService.newCriteria()
+    .propertyIn("roleID", subQuery)
+    .list();
+```
+
+**Dynamic Finders**: Auto-generated methods from BaseORMService:
+```cfml
+// findBy{Property}, findAllBy{Property}
+userService.findByUsername("admin");
+userService.findAllByStatus("active");
+
+// countBy{Property}
+userService.countByRole("admin");
+
+// Conditional finders: LessThan, GreaterThan, Like, Between, InList, etc.
+userService.findByAgeLessThan(18);
+userService.findAllByCreatedDateBetween(startDate, endDate);
+```
+
+**RESTful Resources**: Automatic CRUD REST API handlers:
+```cfml
+component extends="cborm.models.resources.BaseHandler" {
+    property name="ormService" inject="entityService:User";
+
+    variables.entity = "User";
+    variables.sortOrder = "lastName,firstName";
+}
+// Provides: index, create, show, update, delete actions
+```
+
+**Transaction Management**: AOP-based transaction support:
+```cfml
+// Add @transactional annotation to methods
+function saveUser(user) transactional {
+    // Automatically wrapped in transaction
+    userService.save(arguments.user);
+}
+
+// Multi-datasource support
+function saveUser(user) transactional="myDatasource" {
+    userService.save(arguments.user);
+}
 ```
 
 ## Development Workflow

.github/workflows/tests.yml

@@ -19,7 +19,7 @@ jobs:
       fail-fast: false
       matrix:
         cfengine: [ "boxlang-cfml@1", "lucee@5", "lucee@6", "adobe@2023", "adobe@2025" ]
-        coldboxVersion: [ "^7.0.0" ]
+        coldboxVersion: [ "^7.0.0", "^8.0.0" ]
         experimental: [ false ]
         # Experimental: ColdBox BE vs All Engines
         include:
@@ -42,7 +42,7 @@ jobs:
             cfengine: "boxlang-cfml@be"
             experimental: true
           # BoxLang No CFML compat
-          - coldboxVersion: "be"
+          - coldboxVersion: "^8.0.0"
             cfengine: "boxlang@1"
             experimental: true
     steps:

models/ActiveEntity.cfc

@@ -48,16 +48,19 @@ component extends="cborm.models.VirtualEntityService" accessors="true" {
 	){
 		// Calculate name via metadata
 		var md               = getMetadata( this );
-		arguments.entityName = ( md.keyExists( "entityName" ) ? md.entityName : listLast( md.name, "." ) );
+		var annotations      = md.keyExists( "annotations" ) ? md.annotations : md;
+		arguments.entityName = (
+			annotations.keyExists( "entityName" ) ? annotations.entityName : listLast( md.name, "." )
+		);
 
 		// Store query cache region
 		if ( isNull( arguments.queryCacheRegion ) ) {
 			arguments.queryCacheRegion = "#arguments.entityName#.activeEntityCache";
 		}
 
 		// Verify datasource just in case.
-		if ( md.keyExists( "datasource" ) ) {
-			arguments.datasource = md.datasource;
+		if ( annotations.keyExists( "datasource" ) ) {
+			arguments.datasource = annotations.datasource;
 		}
 
 		// init the super class with our own arguments

models/EventHandler.cfc

@@ -127,7 +127,10 @@ component extends="coldbox.system.remote.ColdboxProxy" {
 			} else {
 				// Long Discovery
 				var md          = getMetadata( arguments.entity );
-				args.entityName = ( md.keyExists( "entityName" ) ? md.entityName : listLast( md.name, "." ) );
+				var annotations = md.keyExists( "annotations" ) ? md.annotations : md;
+				args.entityName = (
+					annotations.keyExists( "entityName" ) ? annotations.entityName : listLast( md.name, "." )
+				);
 			}
 		}
 

models/criterion/BaseBuilder.cfc

@@ -404,7 +404,7 @@ component accessors="true" {
 
 		// iterate and add dynamically if the incoming argument exists, man, so much easier if we had closures.
 		for ( var pType in arguments ) {
-			if ( structKeyExists( arguments, pType ) AND NOT listFindNoCase( excludes, pType ) ) {
+			if ( !isNull( arguments[ pType ] ) AND NOT listFindNoCase( excludes, pType ) ) {
 				addProjection(
 					arguments[ pType ],
 					lCase( pType ),
@@ -414,23 +414,23 @@ component accessors="true" {
 		}
 
 		// id
-		if ( structKeyExists( arguments, "id" ) ) {
+		if ( !isNull( arguments.id ) ) {
 			projectionList.add( this.PROJECTIONS.id() );
 		}
 
 		// rowCount
-		if ( structKeyExists( arguments, "rowCount" ) ) {
+		if ( !isNull( arguments.rowCount ) ) {
 			projectionList.add( this.PROJECTIONS.rowCount() );
 		}
 
 		// distinct
-		if ( structKeyExists( arguments, "distinct" ) ) {
+		if ( !isNull( arguments.distinct ) ) {
 			addProjection( arguments.distinct, "property", projectionList );
 			projectionList = this.PROJECTIONS.distinct( projectionList );
 		}
 
 		// detachedSQLProjection
-		if ( structKeyExists( arguments, "detachedSQLProjection" ) ) {
+		if ( !isNull( arguments.detachedSQLProjection ) ) {
 			// allow single or arrary of detachedSQLProjection
 			var projectionCollection = !isArray( arguments.detachedSQLProjection ) ? [
 				arguments.detachedSQLProjection
@@ -442,7 +442,7 @@ component accessors="true" {
 		}
 
 		// sqlProjection
-		if ( structKeyExists( arguments, "sqlProjection" ) ) {
+		if ( !isNull( arguments.sqlProjection ) ) {
 			// allow for either an array of sqlProjections, or a stand-alone config for one
 			var sqlargs = !isArray( arguments.sqlProjection ) ? [ arguments.sqlProjection ] : arguments.sqlProjection;
 			// loop over sqlProjections
@@ -460,7 +460,7 @@ component accessors="true" {
 		}
 
 		// sqlGroupProjection
-		if ( structKeyExists( arguments, "sqlGroupProjection" ) ) {
+		if ( !isNull( arguments.sqlGroupProjection ) ) {
 			// allow for either an array of sqlGroupProjections, or a stand-alone config for one
 			var sqlargs = !isArray( arguments.sqlGroupProjection ) ? [ arguments.sqlGroupProjection ] : arguments.sqlGroupProjection;
 			// loop over sqlGroupProjections

models/util/support/ORMUtilSupport.cfc

@@ -129,9 +129,10 @@ component singleton {
 			arguments.entity = entityNew( arguments.entity );
 		}
 
-		var md = getMetadata( arguments.entity );
-		if ( structKeyExists( md, "datasource" ) ) {
-			datasource = md.datasource;
+		var md          = getMetadata( arguments.entity );
+		var annotations = md.keyExists( "annotations" ) ? md.annotations : md;
+		if ( structKeyExists( annotations, "datasource" ) ) {
+			datasource = annotations.datasource;
 		}
 
 		return datasource;
@@ -207,16 +208,15 @@ component singleton {
 
 		// Hibernate Discovery
 		try {
-			return getSession( getEntityDatasource( arguments.entity ) ).getEntityName(
-				arguments.entity
-			);
+			return getSession( getEntityDatasource( arguments.entity ) ).getEntityName( arguments.entity );
 		} catch ( org.hibernate.TransientObjectException e ) {
 			// ignore it, it is not in session, go for long-discovery
 		}
 
 		// Long Discovery
-		var md = getMetadata( arguments.entity );
-		return ( md.keyExists( "entityName" ) ? md.entityName : listLast( md.name, "." ) );
+		var md          = getMetadata( arguments.entity );
+		var annotations = md.keyExists( "annotations" ) ? md.annotations : md;
+		return ( annotations.keyExists( "entityName" ) ? annotations.entityName : listLast( md.name, "." ) );
 	}
 
 	/**

server-boxlang-cfml@be.json

@@ -31,7 +31,7 @@
         "BOXLANG_DEBUG":true
     },
     "scripts":{
-        "onServerInitialInstall":"install bx-mysql,bx-derby,bx-compat-cfml@be,bx-orm@be --noSave"
+        "onServerInitialInstall":"install bx-mysql,bx-derby,bx-compat-cfml,bx-orm --noSave"
     },
     "-trace":true
 }