codefilarete/stalactite
47.1
Weak · 22 October 2026
82.8k
lines of production code
Java
primary language
5
measurements over time
What this system is
Stalactite is a Java ORM and SQL persistence library that maps Java entities to relational databases with support for complex inheritance, relationships, and batch operations. It provides vendor-specific adapters for major databases like MySQL, PostgreSQL, Oracle, and SQLite, handling dialect differences, type mapping, and schema generation. The system includes a fluent DSL for entity configuration, a Spring Boot integration for auto-configuration and Spring Data repositories, and robust features for optimistic locking, cyclic graph loading, and polymorphic queries.
How it got here
2014–2022 — Version 3.0 architecture and ORM engine
64 changes.
The project underwent a major structural overhaul, migrating to a multi-module Maven build and replacing the legacy persistence layer with a new, fluent ORM engine. This period focused on rebuilding core components, including a refined SQL query builder, centralized dialect management, and robust entity mapping with support for composite keys and polymorphism. Extensive test coverage was added to validate the new transaction handling, cascade operations, and database adapter integrations.
2023–2025 — Polymorphism, Spring Boot, and DSL Refactoring
57 changes.
This period focused on implementing comprehensive polymorphism support across single-table, join-table, and table-per-class inheritance strategies, alongside a major refactoring of the fluent mapping DSL to improve configuration clarity and type safety. The ORM engine was significantly expanded with new database adapters for Oracle and SQLite, indexed collection support, and pooled HiLo identifier generation. Concurrently, deep integration with the Spring ecosystem was achieved through a new Spring Boot auto-configuration module and a robust Spring Data repository implementation featuring native queries and projections.
2026 — ORM metadata model and resolver rewrite
26 changes.
The project underwent a major architectural overhaul of its ORM engine, introducing a dedicated metadata model and a new DSL-driven resolution pipeline for entity mappings. This rewrite implemented comprehensive support for complex relationships, including one-to-one, one-to-many, many-to-many, and map associations, alongside robust polymorphic inheritance strategies. The work was accompanied by extensive test coverage and the addition of SQLite support with reorganized database adapter packages.
Features
Add Oracle database adapter support
This change introduces a new Oracle adapter module that enables the SQL library to work with Oracle databases. It provides Oracle-specific type mappings (e.g., mapping Java types to Oracle SQL types like 'varchar(255)' and 'timestamp with time zone'), parameter binders for handling BLOBs and date/time types (ZonedDateTime, OffsetDateTime) that require specific JDBC handling, and dedicated result set readers/writers. The module also includes test infrastructure, such as an embedded Oracle container setup and specific test cases to verify correct behavior with Oracle's quirks (e.g., nanosecond rounding).
sql-adapter/sql-oracle-adapter · high confidence
Add SQLite 3.45 adapter support
This change introduces a new adapter for SQLite 3.45, enabling the ORM to persist data to SQLite databases. The implementation includes a dialect resolver, SQL generation logic (DML/DDL), and specific handling for SQLite's limitations, such as simulating auto-generated keys and using unique indexes instead of constraints. It also provides integration tests to verify the adapter's functionality.
core-adapter/core-sqlite-adapter · high confidence
Constructor options aligned for composite key mapping
The fluent DSL for composite key mapping now supports specifying constructor arguments via \usingConstructor\ and \usingFactory\ methods, mirroring the capabilities already available for single-key mapping. This allows users to configure how entity instances are instantiated from composite primary keys, including support for no-arg, 1-arg, 2-arg, and 3-arg constructors, as well as a flexible factory function. The change introduces new interfaces (\CompositeKeyConstructorOptions\, \CompositeKeyOptions\, \ConstructorOptions\, \KeyOptions\, \PropertyOptions\) and updates existing ones (\FluentEntityMappingBuilderCompositeKeyOptions\, \FluentEntityMappingBuilderKeyOptions\, \FluentCompositeKeyMappingBuilder\, \FluentCompositeKeyMappingConfiguration\) to expose these options. Additionally, the \CompositeKeyMappingConfiguration\ interface has been updated to include \columnSize\ and \enumBindType\ in its linkage metadata, and the \FluentCompositeKeyMappingBuilder\ now uses \SerializablePropertyAccessor\ and \SerializablePropertyMutator\ instead of \SerializableFunction\ and \SerializableBiConsumer\ for property mapping.
orm/src/main/java/org/codefilarete/stalactite/dsl/key · high confidence
Expanded SQL operator and function support in query model
The query model in the operator package now includes a broader set of SQL functions and comparison operators, enabling more complex query construction. New capabilities include case-insensitive comparisons via \EqualsIgnoreCase\, \InIgnoreCase\, and \LikeIgnoreCase\, as well as new aggregate functions like \Avg\, \Max\, \Min\, and \Sum\. The \Count\ operator now supports distinct values and multiple columns. Additional string and date functions such as \Trim\, \Substring\, \DateFormat\, \Coalesce\, and \Cast\ are available. The \Like\ operator has been enhanced with shortcuts for \startsWith\, \endsWith\, and \contains\. Furthermore, \In\ conditions can now be combined with subqueries via \InSubQuery\, and \TupleIn\ allows for multi-column IN clauses.
core/src/main/java/org/codefilarete/stalactite/query/model/operator · high confidence
Initial MySQL 5.6 adapter implementation
This change introduces the core MySQL 5.6 adapter, providing dialect resolution, SQL generation, and persistence support for MySQL databases. It includes an \InnoDBLockRetryer\ to automatically handle InnoDB lock wait timeouts during write operations, a \MySQLDDLTableGenerator\ for MySQL-specific DDL syntax (such as \auto\_increment\ and \drop foreign key\), and a sequence selector that mimics sequences using a table. The adapter is registered via Java SPI and includes integration tests to verify dialect detection and SQL execution.
core-adapter/core-mysql-adapter · high confidence
Initial MySQL adapter implementation with type mapping and test infrastructure
This change introduces the MySQL-specific SQL adapter, providing the necessary components to interact with MySQL databases. It includes a type mapping configuration that handles Java-to-SQL conversions, specifically ensuring timestamp fields are nullable and have precision 6 to comply with SQL-92 and handle MySQL's default behavior. A parameter binder registry is also added to manage statement binding. To support development and verification, the adapter includes a comprehensive test suite with MySQL-specific test helpers, a data source selector for external and embedded (Testcontainers) MySQL instances, and optimized connection properties like batch rewriting and prepared statement caching.
sql-adapter/sql-mysql-adapter · high confidence
Initial Spring Boot auto-configuration for Stalactite
This change introduces Spring Boot auto-configuration support for the Stalactite persistence library, enabling automatic setup of the \PersistenceContext\, \PlatformTransactionManager\, and Spring Data repositories when Stalactite is on the classpath. It registers \StalactiteAutoConfiguration\ and \StalactiteRepositoriesAutoConfiguration\ via Spring Boot's auto-configuration mechanism, allowing users to configure Stalactite via \spring.stalactite\ properties (such as DDL auto-generation) without manual bean definitions. The configuration also includes a \DialectCustomizer\ interface to allow customization of the database dialect.
spring-integration/autoconfigure/src/main · high confidence
Introduction of Pooled HiLo identifier generator
The library now includes a new pooled HiLo sequence implementation for generating long identifiers. This feature introduces a pooling mechanism that reserves ranges of identifiers in memory to reduce database round-trips, with the current sequence state persisted in a configurable database table (defaulting to 'sequence\_table' with Hibernate-compatible defaults). Users can configure the pool size, sequence name, and storage table/column details via the new PooledHiLoSequenceOptions and PooledHiLoSequenceStorageOptions classes.
core/src/main/java/org/codefilarete/stalactite/mapping/id/sequence/hilo · high confidence
Introduction of a formal database schema structure model
The \core/src/main/java/org/codefilarete/stalactite/sql/ddl/structure\ package now provides a dedicated meta-model for defining database schemas, replacing ad-hoc definitions with explicit classes for \Table\, \Column\, \ForeignKey\, \PrimaryKey\, \Index\, \UniqueConstraint\, and \Sequence\. This change allows users to declaratively define schema elements—including composite keys and unique constraints—which are then utilized by the DDL generator to create the corresponding database objects. The model also introduces case-insensitive column lookup to prevent schema duplication errors and supports schema-scoped naming for tables and sequences.
core/src/main/java/org/codefilarete/stalactite/sql/ddl/structure · high confidence
Many-to-one relations now support separate fetching and polymorphic targets
The ORM engine for many-to-one relations has been expanded to support fetching related entities separately (via a two-phase load) in addition to the standard SQL join approach. This change also adds support for polymorphic targets, allowing many-to-one associations to resolve to different entity types based on the database strategy (e.g., single-table, table-per-class, or join-table). Users can now configure these relations to load targets independently to optimize query performance or handle complex inheritance hierarchies, while write cascades and foreign key maintenance continue to be handled automatically by the new resolver components.
orm/src/main/java/org/codefilarete/stalactite/engine/configurer/resolver/manytoone · high confidence
New Many-to-One Relationship Engine for Source-Owned Relations
A new ManyToOneEngine class has been introduced to handle persistence logic for many-to-one relationships where the source entity owns the link. This engine manages foreign key shadow columns and implements cascade behaviors for inserts, updates, and deletes, including optional orphan removal. It ensures that target entities are persisted or updated as needed to satisfy foreign key constraints before the source entity is modified.
orm/src/main/java/org/codefilarete/stalactite/engine/runtime/manytoone · high confidence
New Spring Data query resolution and annotation support
This change introduces the core query resolution infrastructure for Stalactite's Spring Data integration within the \spring.repository.query\ package. It adds the \CreateQueryLookupStrategy\ to map derived method names to specific query implementations (such as \PartTreeStalactiteQuery\ for standard finds, \PartTreeStalactiteDelete\ for deletions, and projection handlers for counts/exists checks). It also introduces new annotations: \@BeanQuery\ allows overriding a repository method's query with a custom Spring bean, while \@NativeQuery\ and \@NativeQueries\ enable direct SQL query definitions on repository methods. Supporting classes like \QueryMethodValidator\ and \StalactiteQueryMethod\ ensure parameter correctness and handle return type detection (Collection, Page, Stream, etc.).
spring-integration/spring-data/src/main/java/org/codefilarete/stalactite/spring/repository/query · high confidence
New Spring transaction integration module with dedicated transaction manager
A new \spring-integration/transaction\ module has been introduced to bridge Stalactite with Spring's transaction management. It provides \StalactitePlatformTransactionManager\, which extends Spring's \JdbcTransactionManager\ to allow Stalactite to use connections managed by Spring transactions, ensuring that commits and rollbacks are handled by the Spring context. The module also includes \PlatformTransactionManagerConnectionProvider\ for executing JDBC operations in new transactions and registers a \StalactiteRepositoryFactory\ via Spring factories for repository support.
spring-integration/transaction · high confidence
New batch CRUD operations and unified executable interfaces
The core CRUD engine now supports batch operations for insert, update, and delete, allowing multiple rows to be processed in a single execution via the new BatchInsert, BatchUpdate, and BatchDelete interfaces and their default implementations. These batch operations use a row-based builder pattern (newRow/set) and execute via JDBC batching for improved performance. Additionally, the single-row operations are now exposed through unified ExecutableInsert, ExecutableUpdate, and ExecutableDelete interfaces, which standardize the API for setting values and executing statements, replacing the previous mixed set/where method patterns with a more consistent fluent interface.
core/src/main/java/org/codefilarete/stalactite/engine/crud · high confidence
New cascade listener support and collection cascader classes
The cascade engine now includes a comprehensive set of new classes to handle entity persistence operations. Support classes (Before/After Insert/Update/Delete/ById) allow custom actions to be triggered before or after specific persistence events, enabling post-processing of related entities. Additionally, collection cascaders (Before/After Insert/Update/Delete) have been introduced to automatically cascade write operations for one-to-many relationships, ensuring that associated target entities are persisted, updated, or deleted in sync with their triggers.
orm/src/main/java/org/codefilarete/stalactite/engine/cascade · high confidence
New identifier provider components for ORM engine
The \orm/src/main/java/org/codefilarete/stalactite/engine/idprovider\ package now includes a new \IdentifierProvider\ interface and several implementations: \IdentifierSupplier\ (wrapping a \java.util.function.Supplier\), \LongProvider\ (atomic long increment), \UUIDProvider\ (random UUID strings), and a pooled base class \PooledIdentifierProvider\ with a \PooledSequenceIdentifierProvider\ implementation for HiLo sequence-based ID generation. These classes provide thread-safe, reusable mechanisms for generating unique identifiers within the ORM engine.
orm/src/main/java/org/codefilarete/stalactite/engine/idprovider · high confidence
New metadata model for entity mapping and relations
The ORM engine now uses a dedicated metadata model in the \orm/src/main/java/org/codefilarete/stalactite/engine/configurer/model\ package to represent entity mappings, replacing the previous runtime engine structures. This new model introduces \AbstractEntity\ and \PolymorphicEntity\ to support polymorphism strategies (single table, join table, and table-per-class), and defines specific relation types such as \ResolvedOneToOneRelation\, \ResolvedOneToManyRelation\, \ResolvedManyToManyRelation\, and \ResolvedMapRelation\ to handle complex associations. It also includes \PropertyMappingHolder\ for column mappings and \AncestorJoin\ for mapped-superclass hierarchies, providing a cleaner, properties-and-joins-focused view of the aggregate mapping to improve query building and resolution logic.
orm/src/main/java/org/codefilarete/stalactite/engine/configurer/model · high confidence
New transaction lifecycle observation and connection retry mechanisms
This change introduces a comprehensive system for observing transaction commit and rollback events, allowing users to register listeners that are notified before and after these operations. It also adds a new connection provider that automatically retries connection acquisition if the underlying connection is found to be closed, improving resilience against transient database connectivity issues.
sql/src/main/java/org/codefilarete/stalactite/sql · high confidence
Oracle database support added via new adapter module
This change introduces the \core-oracle-adapter\ module, enabling the framework to connect to and operate on Oracle databases (specifically targeting Oracle 23.0). The adapter provides Oracle-specific dialect settings, including reserved keywords, SQL type mappings, and parameter binders. It implements Oracle-specific behaviors for DDL generation (such as identity column syntax), sequence-based identifier providers, and generated key reading. The module registers itself via Java SPI so the dialect is automatically detected, and includes integration tests to verify persistence operations against an Oracle database.
core-adapter/core-oracle-adapter · high confidence
Polymorphic entity persistence and selection engine
The ORM engine now supports polymorphic entity mappings (such as table-per-class inheritance). This change introduces a new runtime layer with \AbstractPolymorphicEntityFinder\ and \AbstractPolymorphismPersister\ to handle selecting and persisting entities across multiple subtypes. It also adds dedicated support for association tables via \AssociationTable\ and \AssociationRecordPersister\, enabling complex many-to-many and one-to-many relationships with separate join tables.
orm/src/main/java/org/codefilarete/stalactite/engine/runtime · high confidence
Support for Element Collection mapping in resolving mechanisms
The ORM engine now supports mapping element collections (such as lists of values or embedded objects) by introducing new resolution components in the \elementcollection\ package. This includes \ElementCollectionResolver\ to configure write operations (insert, update, delete cascades) and \AggregateElementCollectionAppender\ to handle read operations, supporting both separate fetching (with optional sorting) and direct join strategies. The implementation reuses \SeparateFetchQueryExecutor\ for efficient batch loading and ensures that collection elements are correctly grafted to the root aggregate during entity reads.
orm/src/main/java/org/codefilarete/stalactite/engine/configurer/resolver/elementcollection · high confidence
Support for Map keys and values as entities with unified mapping infrastructure
The ORM engine now supports using JPA entities as both keys and values in Map collections, resolving previous limitations where only simple or embedded types were allowed. This change introduces new configuration classes (EntityAsKeyMapRelationConfigurer, EntityAsValueMapRelationConfigurer, EntityAsKeyAndValueMapRelationConfigurer) and a dedicated mapping class (KeyValueRecordIdMapping) to handle the complex association tables required for entity-based maps. It also standardizes the internal reflection API by replacing PropertyAccessor with ReadWritePropertyAccessPoint and renames MapEntryTableNamingStrategy to MapTableNamingStrategy for consistency.
orm/src/main/java/org/codefilarete/stalactite/engine/configurer/map · high confidence
Support for Map relations with entity keys and values
The ORM engine now supports Map associations where both the key and the value are entities, not just scalars. This change introduces a new resolution and persistence layer for map relations, enabling cascading write operations (insert, update, delete) to both key and value entities. It also supports fetching these maps either via direct joins or through a separate second-phase load, including support for ordered maps and composite identifiers.
orm/src/main/java/org/codefilarete/stalactite/engine/configurer/resolver/map · high confidence
Support for Spring Data projections, count, and exists queries
The Spring Data integration now supports derived queries that return projections, counts, and existence checks. Users can define repository methods that return projection interfaces (e.g., \findByName(String name, MyProjection projection)\), and the framework will automatically map the selected columns to the projection properties. Additionally, methods returning \long\ are treated as count queries, and methods returning \boolean\ are treated as existence checks, optimizing the underlying SQL to only fetch the necessary data (e.g., limiting to 1 row for existence checks).
spring-integration/spring-data/src/main/java/org/codefilarete/stalactite/spring/repository/query/projection · high confidence
Support for Stream return types in Spring Data derived queries
The query execution layer in the Spring Data integration now supports returning Java Streams from derived query methods. This is implemented by adding a \QueryResultStreamer\ and a dedicated \StreamResultWindower\ that handle result windowing and limit adaptation for streaming, alongside refactoring the core \AbstractRepositoryQuery\ to route \STREAM\ return types to this new reducer. Existing windowing logic for \Page\ and \Slice\ results has also been consolidated into shared \QueryResultWindower\ classes to reduce duplication.
spring-integration/spring-data/src/main/java/org/codefilarete/stalactite/spring/repository/query/execution · high confidence
Support for database sequences as identifier providers
The framework now supports using database sequences to generate entity identifiers. For databases with native sequence support, a new DatabaseSequenceSelector retrieves values directly from the database. For databases that do not support sequences (such as SQLite and MySQL), the system mimics sequence behavior by storing and incrementing values in a dedicated table via SequenceStoredAsTableSelector. Configuration for these sequences, including initial values, batch sizes, and schema names, is managed through DatabaseSequenceSettings.
core/src/main/java/org/codefilarete/stalactite/mapping/id/sequence · high confidence
Support for indexed element collections
The ORM now supports mapping collections of elements that preserve insertion order. This change introduces dedicated classes (ElementCollectionRelation, ElementCollectionRelationConfigurer, ElementRecord, IndexedElementRecord) to handle the persistence of ordered collections, including the storage of element indices in the database and the ability to sort the collection upon retrieval. Users can now configure element collections to be ordered, ensuring that the sequence of elements is maintained across database operations.
orm/src/main/java/org/codefilarete/stalactite/engine/configurer/elementcollection · high confidence
Support for indexed one-to-many relations with association and mapped tables
The ORM engine now supports one-to-many relationships where the collection order is persisted in the database, either via an explicit index column in an association table or via an index column on the target entity's table. This change introduces new engine classes (OneToManyWithIndexedAssociationTableEngine, OneToManyWithIndexedMappedAssociationEngine) and descriptors that manage the persistence and retrieval of these indexes, ensuring that collections like Lists and LinkedHashSets are loaded and updated in the correct order defined by the application.
orm/src/main/java/org/codefilarete/stalactite/engine/runtime/onetomany · high confidence
Support for join-table and single-table polymorphism strategies
The ORM engine now supports two additional polymorphic inheritance mapping strategies: join-table and single-table. This change introduces new configuration resolvers and appenders (JoinTableResolver, JoinTableAppender, SingleTableResolver, SingleTableAppender) that handle the creation of necessary database joins and the wiring of polymorphic readers and writers. Users can now map entity hierarchies using a join table to store subclass data separately or a single table with a discriminator column, allowing for more flexible database schema designs for polymorphic relationships.
orm/src/main/java/org/codefilarete/stalactite/engine/configurer/resolver/polymorphism/jointable · high confidence
Support for join-table polymorphism with multiple subclasses
The ORM now supports join-table inheritance strategies where a root entity has multiple subclasses, addressing a previous limitation where only single-subclass polymorphism was handled correctly. This change introduces new runtime components—JoinTablePolymorphismEntityFinder, JoinTablePolorphismPersister, JoinTablePolymorphismReader, and JoinTablePolymorphismWriter—to manage the loading, persistence, and querying of these polymorphic hierarchies. Users can now define complex inheritance structures using join tables without encountering errors related to missing sub-class support or incorrect join configurations.
orm/src/main/java/org/codefilarete/stalactite/engine/runtime/jointable · high confidence
Support for loading cyclic entity graphs
The ORM engine now handles entity graphs containing cycles (e.g., A references B which references A) by introducing a dedicated cycle resolution mechanism in the runtime. New classes such as AbstractCycleLoader, OneToOneCycleLoader, OneToManyCycleLoader, ManyToOneCycleLoader, and ManyToManyCycleLoader manage the recursive loading process, ensuring that circular references are resolved without causing infinite loops or duplicate loads. This allows users to persist and retrieve complex, self-referential entity structures that were previously unsupported or prone to errors.
orm/src/main/java/org/codefilarete/stalactite/engine/runtime/cycle · high confidence
Support for native SQL queries with projection and pagination in Spring Data repositories
The Spring Data integration now supports the @NativeQuery annotation, allowing users to define custom SQL statements in repository methods. This change introduces a new query execution path that handles both domain entity results and typed projections (returning maps of column values). It also adds support for pagination (limit/offset) and count queries for paged results, enabling native SQL to work seamlessly with Spring Data's paging abstractions.
spring-integration/spring-data/src/main/java/org/codefilarete/stalactite/spring/repository/query/nativ · high confidence
Support for one-to-many relations with association tables and indexed collections
The ORM engine now supports one-to-many relationships backed by an association table, including ordered (indexed) collections and polymorphic targets. This change introduces a new \AbstractOneToManyEngine\ base class and a suite of dedicated appenders (\AggregateOneToManyWithAssociationTableAppender\, \AggregateOneToManyWithIndexedAssociationTableAppender\, etc.) that handle both joined loading and a separate 2-phase fetch strategy to avoid cartesian products. Users can now map complex one-to-many associations with explicit join tables and maintain collection order via index columns, with the engine automatically handling the necessary SQL joins and in-memory sorting.
orm/src/main/java/org/codefilarete/stalactite/engine/configurer/resolver/onetomany · high confidence
Support for overriding repository queries via Spring beans
Users can now define custom Spring beans to override the queries executed by Stalactite Spring Data repositories. By annotating a bean with @BeanQuery, developers can specify a custom ExecutableQuery (or ExecutableEntityQuery) and an optional counter bean for pagination, allowing fine-grained control over query execution and paging behavior without modifying repository interfaces.
spring-integration/spring-data/src/main/java/org/codefilarete/stalactite/spring/repository/query/bean · high confidence
Support for single-table polymorphism in entity persistence
The ORM engine now supports single-table polymorphism, allowing a hierarchy of entities to be stored in a single database table distinguished by a discriminator column. This change introduces new runtime components—SingleTablePolymorphismEntityFinder, SingleTablePolymorphismPersister, SingleTablePolymorphismReader, and SingleTablePolymorphismWriter—which coordinate the loading, saving, and querying of polymorphic entity trees. Users can now define entity hierarchies that share a table structure, with the framework automatically handling discriminator values and delegating operations to the appropriate subclass persisters.
orm/src/main/java/org/codefilarete/stalactite/engine/runtime/singletable · high confidence
Support for table-per-class polymorphic inheritance
The ORM now supports table-per-class inheritance strategies, allowing entities with polymorphic relationships to be mapped across separate database tables for each subclass. This change introduces a new resolver and appender mechanism that constructs SQL unions to query all subclass tables simultaneously, using a discriminator column to identify the specific entity type. It also enables separate fetching for these polymorphic associations, improving performance by loading related polymorphic entities in distinct queries rather than complex joins.
orm/src/main/java/org/codefilarete/stalactite/engine/configurer/resolver/polymorphism/tableperclass · high confidence
Support for table-per-class polymorphism
The ORM engine now supports table-per-class inheritance mapping, allowing a base entity and its subclasses to be persisted across separate database tables. This change introduces a new runtime layer in the \tableperclass\ package, including \TablePerClassPolymorphismEntityFinder\ for reading entities via a UNION ALL query with a discriminator column, and \TablePerClassPolymorphismPersister\/\Writer\ for routing insert, update, and delete operations to the correct subclass tables based on the entity type. Users can now model inheritance hierarchies where each class has its own table, with the engine handling the necessary joins and discriminator logic automatically.
orm/src/main/java/org/codefilarete/stalactite/engine/runtime/tableperclass · high confidence
Removals
Removal of early persistence structure and SQL builder stubs
This change removes a set of early-stage, largely empty or placeholder classes from the persistence layer, including SQL builders (InsertBuilder, SelectBuilder, UpdateBuilder), DML/DDL generators, and core structural models (Database, Table, Column, ForeignKey, Index). It also deletes utility classes for bean instantiation and ordered collections (IFactory, EntryFactoryHashMap, KeepOrderSet). These files appear to be preliminary scaffolding that has been superseded by the new mapping and persistence strategies introduced in the same commit series.
src/main · high confidence
Architecture
Refactored query API into dedicated model and API packages
The query model classes have been migrated from the \query.model\ package to \query.api\, introducing a new set of interfaces (such as \CriteriaChain\, \FluentSelect\, \FromAware\, and \JoinChain\) that define the fluent query-building contract. This change separates the API definitions from the underlying model implementations, providing a cleaner structure for constructing SQL queries and supporting features like joins, unions, and pagination through a more explicit interface hierarchy.
core/src/main/java/org/codefilarete/stalactite/query/model · high confidence
Behavioural changes
Centralized SQL dialect configuration and resolution
The SQL layer now uses a centralized \Dialect\ interface and a \ServiceLoaderDialectResolver\ to automatically detect and select the appropriate database dialect based on the connection's product name and version. Users can customize dialect behavior, such as identifier quoting, type mappings, and SQL keywords, through the new \DialectOptions\ builder. This change also introduces factories for managing DML naming (\DMLNameProviderFactory\) and database sequences (\DatabaseSequenceSelectorFactory\), allowing for more flexible and vendor-specific SQL generation without implementing full dialect classes.
core/src/main/java/org/codefilarete/stalactite/sql · high confidence
Derby adapter refactored to use Vendor Settings and Dialect Builder
The Derby adapter has been restructured to align with the new Vendor Settings principle. The previous dialect implementation is replaced by DerbyDatabaseSettings, which centralizes configuration such as SQL keywords, type mappings, and parameter binders. A new DerbyDialectBuilder and DerbyDialectResolver handle dialect creation and service registration, while specific behaviors like identity column generation and auto-generated key reading are adapted to Derby's constraints. This change ensures the adapter integrates cleanly with the updated engine architecture.
core-adapter/core-derby-adapter · high confidence
Embeddable beans now support entity relations and enhanced column configuration
Users can now define many-to-one, one-to-one, one-to-many, and many-to-many relationships directly within embeddable bean mappings using the fluent DSL (e.g., \mapManyToOne\, \mapOneToOne\). The configuration API has been updated to use \SerializablePropertyAccessor\ and \SerializablePropertyMutator\ instead of generic serializable functions, and new methods allow forcing column nullability (\nullable()\), enforcing uniqueness (\unique()\), and specifying column sizes (\columnSize\). Additionally, the \extraTableName\ method was renamed to \extraTable\ to accept a \Table\ argument, and the internal reflection accessors were replaced with \ReadWritePropertyAccessPoint\ for improved type safety and performance.
orm/src/main/java/org/codefilarete/stalactite/dsl/embeddable · high confidence
Enhanced SQL statement execution with fetch size support and composite parameter handling
Read operations now support configurable fetch sizes to optimize large result set retrieval, while SQL statement execution returns the number of affected rows for better visibility into write operations. The SQL engine also introduces support for composite parameters (such as nested collections) in queries and improves the SQL parser to correctly handle escaped strings within quoted text.
sql/src/main/java/org/codefilarete/stalactite/sql/statement · high confidence
Expanded Fluent DSL for property and collection configuration
The property configuration API has been refactored and expanded to support more granular control over database schema and persistence behavior. Users can now enforce unique constraints on columns via the new \unique()\ method, explicitly control nullability with \nullable()\, and define column sizes using \columnSize()\. Read and write converters have been generalized to accept different data types, allowing conversion between property values and database columns of varying types. Additionally, collection mapping now supports indexing elements (\indexed()\), fetching collections separately (\fetchSeparately()\), and configuring element-specific column sizes and names. Cascade options have been moved to the DSL layer and enhanced with helper methods to clarify write and deletion permissions, while method names have been standardized (e.g., \withTable\ to \onTable\) for better consistency.
orm/src/main/java/org/codefilarete/stalactite/dsl/property · high confidence
Expanded embeddable mapping configuration with new relation and collection options
The embeddable mapping engine now supports configuring many-to-many and one-to-many relations directly on embeddables, including the ability to specify association tables and reverse join columns. It also introduces support for indexed collections of elements and allows forcing column nullability. Additionally, the fluent API has been updated to use SerializablePropertyAccessor and SerializablePropertyMutator for property access, and the mappedBy method has been renamed to reverseJoinColumn for consistency.
orm/src/main/java/org/codefilarete/stalactite/engine/configurer/embeddable · high confidence
H2 adapter refactored to use Vendor Settings and ServiceLoader-based dialect resolution
The H2 adapter has been restructured to align with the new Vendor Settings principle, replacing the previous dialect implementation with a dedicated H2DatabaseSettings class that defines H2-specific SQL keywords, type mappings, and parameter binders. This change introduces a ServiceLoader-based resolution mechanism (via H2DialectResolver) to automatically detect and configure the H2 dialect at runtime, ensuring correct handling of H2-specific features such as identity columns and sequence generation.
core-adapter/core-h2-adapter · high confidence
HSQLDB adapter refactored for version 2.7 with configurable dialect builder
The HSQLDB adapter has been updated to target HSQLDB 2.7, replacing the previous static dialect with a new builder pattern (HSQLDBDialectBuilder) that allows users to configure dialect options, such as enabling an extended set of SQL keywords for identifier quoting. This change introduces HSQLDBDatabaseSettings to manage vendor-specific configurations and updates the DDL generation to correctly handle HSQLDB's identity columns and unique constraints. Existing tests have been migrated to use the new builder, ensuring compatibility with the updated dialect resolution and SQL generation logic.
core-adapter/core-hsqldb-adapter · high confidence
Many-to-many relation loading and persistence refactored for performance and ordering
The ORM engine now supports a 'fetch-separately' strategy for many-to-many relations, which loads the association and target entities in a dedicated second-phase query rather than joining them into the main aggregate query. This prevents the Cartesian product explosion when loading aggregates with multiple many-to-many collections. The implementation also adds support for indexed (ordered) many-to-many relations, preserving the order defined by an index column in the association table during both joined and separate fetch modes. Additionally, polymorphic targets in many-to-many relations are now fully supported across all fetching and ordering combinations.
orm/src/main/java/org/codefilarete/stalactite/engine/configurer/resolver/manytomany · high confidence
MariaDB adapter with InnoDB lock retry and dialect support
The MariaDB adapter now includes an InnoDB lock retryer that automatically retries write operations on 'Lock wait timeout exceeded' errors, improving reliability under heavy concurrency. It also provides a complete dialect implementation for MariaDB 10.0, featuring specific DDL generation (such as 'drop foreign key' syntax), correct handling of generated keys, and proper keyword quoting.
core-adapter/core-mariadb-adapter · high confidence
New DDL generation and deployment infrastructure with sequence support
The DDL subsystem has been refactored to centralize SQL script generation and execution. A new DDLDeployer class now serves as the entry point for deploying schema changes, automatically collecting tables and sequences from the persistence context. The system introduces explicit support for database sequences as identifier providers, allowing vendors that support them to use this mechanism. Additionally, the schema generation now includes support for unique constraints (generated as ALTER TABLE statements) and ensures that foreign keys are created after indexes and constraints to satisfy database requirements. The DML name provider is now integrated into the SQL appenders to handle table and column naming consistently.
core/src/main/java/org/codefilarete/stalactite/sql/ddl · high confidence
New DSL-based metadata resolution engine for entity inheritance and relations
The ORM engine now uses a new set of resolver classes in the \dslresolver\ package to process entity mapping configurations. \AggregateMetadataResolver\ orchestrates the resolution of an entity's inheritance hierarchy, identifier mapping, and relations. \InheritanceConfigurationResolver\ and \InheritanceMetadataResolver\ handle the traversal of \mapSuperClass\ chains, applying naming conventions, identifier policies, and table definitions (including joining tables) to build a graph of \AbstractEntity\ instances. \IdentifierMappingBuilder\ constructs specific identifier strategies (single key, composite key, generated keys, sequences) and validates composite keys. \ElementCollectionMetadataResolver\ resolves element collections, creating necessary tables, foreign keys, and primary keys for ordered or unordered collections. This change replaces the previous resolution logic with a more structured, DSL-driven approach that supports complex inheritance and polymorphism scenarios.
orm/src/main/java/org/codefilarete/stalactite/engine/configurer/dslresolver · high confidence
New SQL naming strategy interfaces for tables, columns, and constraints
The ORM's \orm/src/main/java/org/codefilarete/stalactite/dsl/naming\ package now exposes a comprehensive set of interfaces to control how database objects are named. Users can customize the naming of entity tables (\TableNamingStrategy\), columns (\ColumnNamingStrategy\), foreign keys (\ForeignKeyNamingStrategy\), and unique constraints (\UniqueConstraintNamingStrategy\). Additionally, new strategies have been introduced for association tables (\AssociationTableNamingStrategy\), element collections (\ElementCollectionTableNamingStrategy\), and map entries (\MapTableNamingStrategy\). These interfaces provide default implementations and specific strategies compatible with Hibernate 4 and Hibernate 7, allowing users to align the generated database schema with their existing naming conventions or framework requirements.
orm/src/main/java/org/codefilarete/stalactite/dsl/naming · high confidence
New aggregate persister resolution pipeline
The ORM's entity resolution mechanism has been restructured to use a new \AggregateResolver\ entry point that builds a complete \ConfiguredRelationalPersister\ for an entity aggregate. This change introduces a separation of concerns: \SkeletonAggregateResolver\ handles the structural 'bones' (identifiers, properties, inheritance, extra tables), while dedicated \Aggregate\*Appender\ classes (e.g., \AggregateOneToManyAppender\, \AggregateMapAppender\) graft relation metadata onto the aggregate. The system now supports complex mappings including one-to-one, one-to-many, many-to-many, many-to-one, element collections, and map relations, with specific support for polymorphism strategies and association tables.
orm/src/main/java/org/codefilarete/stalactite/engine/configurer/resolver · high confidence
New fluent query mapping and entity execution interfaces
The engine introduces a new fluent API for mapping SQL query results to Java beans, centered on the new BeanKeyQueryMapper and BeanPropertyQueryMapper interfaces which allow users to define root bean constructors and property setters via method references. Additionally, the persistence contract is refactored to separate read and write responsibilities through new EntityReadExecutor, EntityWriteExecutor, and EntityReadWriteExecutor interfaces, while EntityPersister now aggregates these capabilities. A new EntityCriteria interface provides a type-safe, chainable way to build query conditions using property accessors, and a DialectBuilder class simplifies database dialect configuration by wrapping vendor-specific settings.
core/src/main/java/org/codefilarete/stalactite/engine · high confidence
New result-set transformation and collection infrastructure
The result-handling package has been restructured to introduce a collector-like pattern for processing SQL results. A new Accumulator interface and Accumulators utility class allow queries to be collected into various Java collections (List, Set, Map, NavigableSet) with support for ordering and grouping. The previous single-result retrieval method has been replaced by this Accumulator mechanism, which consumes the entire ResultSet to build beans. Additionally, a BeanRelationFixer interface and ColumnConsumer/ColumnReader classes have been added to manage one-to-one and one-to-many bean relations and column-to-property mapping, while NoopResultSet and InMemoryResultSet provide base and test-friendly implementations for ResultSet handling.
sql/src/main/java/org/codefilarete/stalactite/sql/result · high confidence
New separate-fetch loading infrastructure for association tables
The \orm/src/main/java/org/codefilarete/stalactite/engine/configurer/resolver/separatefetch\ package now contains the core components for a two-phase separate-fetch strategy. This includes \AssociationTableLoader\ to load association records independently of the main aggregate query, \SeparateFetchQueryExecutor\ to efficiently execute the second-phase queries, and \SecondPhaseSelectListener\ to orchestrate the loading and 'sewing' of relations onto their owners. Supporting classes like \RelationStorage\, \IndexedRelationStorage\, and their \ThreadLocal\ wrappers manage the in-memory mapping of loaded relations during the second phase, ensuring the aggregate is fully populated without cartesian products.
orm/src/main/java/org/codefilarete/stalactite/engine/configurer/resolver/separatefetch · high confidence
One-to-one relation configuration refactored with unique constraints and polymorphism support
The one-to-one relation configuration logic has been consolidated into the dedicated \OneToOneRelationConfigurer\ class, which now manages the creation of \OneToOneOwnedBySourceConfigurer\ and \OneToOneOwnedByTargetConfigurer\ instances. This change introduces support for unique constraints on one-to-one relationships via the \UniqueConstraintNamingStrategy\, ensuring database integrity for unique associations. It also adds support for table-per-class polymorphism by conditionally skipping foreign key creation when the target entity uses this strategy. Additionally, the configuration now allows setting the reverse column by name, and the internal reflection handling has been updated to use \SerializablePropertyAccessor\ and \SerializablePropertyMutator\ for better type safety and performance.
orm/src/main/java/org/codefilarete/stalactite/engine/configurer/onetoone · high confidence
Polymorphic persister builders migrate to new DSL and builder infrastructure
The polymorphism configuration layer (single-table, join-table, and table-per-class builders) has been refactored to use the new \ConfiguredRelationalEntityPersister\ and \PersisterBuilderContext\ instead of the legacy \ConfiguredRelationalPersister\ and \PersisterRegistry\. This change removes the global persister registry from the build process, replaces \BeanMappingBuilder\ with \EmbeddableMappingBuilder\ for sub-entity mappings, and updates reflection access to use \PropertyAccessPoint\ instead of \ReversibleAccessor\. Additionally, select listeners are now explicitly propagated to sub-persisters via a \SelectListenerPropagator\ to ensure correct event handling during entity loading.
orm/src/main/java/org/codefilarete/stalactite/engine/configurer/polymorphism · high confidence
PostgreSQL adapter refactored to use vendor-specific database settings
The PostgreSQL adapter has been restructured to align with a new 'Vendor Settings' principle, replacing the previous dialect-centric approach. This change introduces \PostgreSQLDatabaseSettings\ to encapsulate PostgreSQL-specific configurations, including reserved keywords, type mappings, and SQL operations factories. The adapter now provides a dedicated \PostgreSQLDialectBuilder\ and registers a \PostgreSQL\_9\_6\_Entry\ via the ServiceLoader mechanism to automatically resolve the dialect for PostgreSQL 9.6 connections. This refactoring ensures that PostgreSQL-specific behaviors, such as auto-generated key handling and sequence selection, are correctly isolated within the vendor settings, preventing class overwrites when multiple adapters are present.
core-adapter/core-postgresql-adapter · high confidence
Redesigned entity mapping DSL with unified identifier policies and relation options
The entity mapping configuration has been restructured to introduce a cleaner, more consistent fluent API. The identifier mapping method has been renamed from \mapCompositeKey\ to \mapKey\, and the framework now supports a unified \IdentifierPolicy\ interface with specific implementations for database auto-increment, pooled HiLo sequences, database sequences, and already-assigned identifiers. Relation mapping has been enhanced with dedicated options interfaces for one-to-one, one-to-many, many-to-one, and many-to-many relationships, allowing for more granular control over join tables, column names, and bidirectional linking. Additionally, the configuration model now includes support for optimistic locking and inheritance strategies, providing a more robust foundation for defining entity persistence.
orm/src/main/java/org/codefilarete/stalactite/dsl/entity · high confidence
Redesigned fluent mapping DSL with new polymorphism and inheritance support
The ORM's fluent mapping API has been restructured to introduce a cleaner, intermediate metadata model for entity persistence configuration. This change adds support for single-table and table-per-class polymorphism via the new \PolymorphismPolicy\ interface and \FluentMappings\ entry points, allowing developers to define inheritance hierarchies more naturally. The API also introduces \ExtraTablePropertyOptions\ for storing properties on secondary tables joined on the primary key, and refactors inheritance configuration through \InheritanceOptions\ and \MappableSuperClassConfiguration\. Additionally, confusing join-table signatures have been renamed to \joiningTables()\ to clarify the distinction from other table options, and utility classes like \QueryEase\ have been renamed to \FluentQueries\ to better reflect their purpose.
orm/src/main/java/org/codefilarete/stalactite/dsl · high confidence
Refactored One-to-One Relationship Cascade Logic
The one-to-one relationship engine has been restructured to introduce distinct handling for relationships owned by the source versus those owned by the target. New classes, \OneToOneOwnedBySourceEngine\ and \OneToOneOwnedByTargetEngine\, replace the previous monolithic implementation, allowing for more precise cascade behavior. Specifically, the target-owned engine now uses a \ThreadLocal\ storage context to manage foreign key values during inserts and updates, ensuring correct persistence order and avoiding superfluous database selects. Additionally, generic signatures for column mappings have been updated to use wildcards (\Column\<T, ?\>\) to resolve casting issues and improve type compatibility.
orm/src/main/java/org/codefilarete/stalactite/engine/runtime/onetoone · high confidence
Refactored SQL binder registry to support composite types and decoupled read/write registries
The binder subsystem in core/src/main/java/org/codefilarete/stalactite/sql/statement/binder has been restructured to improve extensibility and type handling. A new ColumnBinderRegistry has been introduced to manage ParameterBinders per Column and Class, replacing previous logic that polluted the Dialect's ColumnBinderRegistry by using a copy instead. To support complex data structures, new binder classes (ComplexTypeBinder and DelegatingCompositeTypeBinder) allow mapping composite objects to single columns or multiple columns via converters and component binders. Additionally, the registry architecture is now split into distinct ResultSetReaderRegistry and PreparedStatementWriterRegistry interfaces, enabling separate management of database reading and writing behaviors.
core/src/main/java/org/codefilarete/stalactite/sql/statement/binder · high confidence
Refactored SQL generation to support prepared statements and extensible builders
The query builder module has been restructured to separate SQL string generation from parameter binding, introducing a new \ExpandableSQLAppender\ that handles named placeholders and collects values for later binding. This enables the generation of \PreparedSQL\ via the new \PreparableSQLBuilder\ interface, allowing safe execution of dynamic queries. The refactoring also introduces a factory-based architecture (e.g., \QuerySQLBuilderFactory\, \FromSQLBuilderFactory\) that allows users to override specific SQL rendering components, such as table/column naming via \DMLNameProvider\, to handle database-specific requirements like keyword quoting.
core/src/main/java/org/codefilarete/stalactite/query/builder · high confidence
Refactored SQL order builders to support reusable statements with named placeholders
The SQL generation logic for Insert, Update, and Delete operations has been restructured to introduce reusable prepared statements. New classes (ColumnVariable, PlaceholderVariable) and builders (InsertCommandBuilder, UpdateCommandBuilder, DeleteCommandBuilder) now generate statements that allow callers to bind values to named placeholders in the WHERE clause after the SQL is built. This enables the same statement object to be executed multiple times with different parameter values, improving efficiency for batch or repeated operations.
core/src/main/java/org/codefilarete/stalactite/sql/order · high confidence
Refactored SQL parameter binding with new binder infrastructure
The SQL statement binder package has been restructured to provide a more modular and robust approach to mapping Java types to JDBC parameters. This change introduces a new \ParameterBinder\ interface that unifies reading from \ResultSet\ and writing to \PreparedStatement\, supported by a new \LambdaParameterBinder\ for easier composition. Default bindings are now centralized in \DefaultParameterBinders\, covering primitives, \java.util.Date\, \java.time\ types (\LocalDate\, \LocalDateTime\, \LocalTime\, \ZoneId\), \UUID\, \Path\, \File\, and \BigDecimal\. New specific binders like \DateBinder\, \LocalDateBinder\, and \LocalTimeBinder\ handle type conversions explicitly. The system also adds support for enums via \NameEnumParameterBinder\ and \OrdinalEnumParameterBinder\, and introduces \CompositeTypeBinder\ for handling tuple-in operations. Null handling is managed by \NullAwareParameterBinder\ and related wrappers, while \InMemoryBlobSupport\ provides an in-memory implementation of \Blob\ for testing or specific use cases.
sql/src/main/java/org/codefilarete/stalactite/sql/statement/binder · high confidence
Refactored SQL statement generation and execution with column-indexed parameterization
The SQL statement layer has been refactored to use column-indexed parameterized statements (ColumnParameterizedSQL, ColumnParameterizedSelect) instead of generic prepared statements, allowing parameters to be bound by Column identity rather than positional indices. This change introduces a new DMLGenerator to construct INSERT, UPDATE, and DELETE statements, and a specialized PreparedUpdate class to handle the distinction between columns in the SET clause and the WHERE clause. Additionally, ReadOperationFactory and WriteOperationFactory are introduced to manage the creation of read and write operations, with support for configurable fetch sizes and row count validation.
core/src/main/java/org/codefilarete/stalactite/sql/statement · high confidence
Refactored Spring Data repository configuration infrastructure
The Spring Data integration module has been restructured to improve configuration extensibility and reduce coupling. A new \RepositoryConfigurationSourceWrapper\ and \EnableStalactiteRepositoriesRepositoryConfigurationSource\ have been introduced to wrap and adapt Spring Data's configuration source, specifically handling missing query lookup strategies to prevent runtime exceptions. The \StalactiteRepositoryConfigExtension\ has been updated to use this wrapper, ensuring that unsupported options in \@EnableStalactiteRepositories\ do not break repository scanning. Additionally, the \SpringDataPersistenceContextConfigurationBuilder\ now explicitly configures the \StalactitePlatformTransactionManager\ as the connection provider, and several configuration classes have been moved from the \spring-integration\ package to \spring-integration/spring-data\ to better align with the Spring Data module scope.
spring-integration/spring-data/src/main/java/org/codefilarete/stalactite/spring/repository/config · high confidence
Refactored embeddable mapping configuration and builder
The embeddable mapping logic has been reorganized into a dedicated package with new classes (EmbeddableLinkage, EmbeddableMapping, EmbeddableMappingBuilder, EmbeddableMappingConfiguration, Inset) that replace the previous BeanMappingBuilder. This change introduces an intermediate model for property and join metadata, improves handling of overridden columns from mapped superclasses, and aligns enum mapping with Hibernate behavior (using smallint for PostgreSQL). Users will see cleaner DSL support for column size and nullability, with conflicts raised if values are misaligned, and primitive properties now correctly generate non-nullable columns.
orm/src/main/java/org/codefilarete/stalactite/engine/configurer/builder/embeddable · medium confidence
Refactored entity loading engine to use a tree-based join structure and identity-based deduplication
The runtime load engine in the ORM has been restructured to use a new tree-based architecture (EntityJoinTree, EntityTreeInflater) for building and executing SQL queries. This change introduces identity-based deduplication of loaded entities using IdentityLinkedMap instead of relying on entity equals/hashCode, which prevents duplicate results and issues with cached identifiers. The new design also supports complex join scenarios, including polymorphic relations (single-table, join-table, table-per-class) and one-to-one/one-to-many relationships, by cloning tables and managing column aliases within the join tree.
orm/src/main/java/org/codefilarete/stalactite/engine/runtime/load · high confidence
Refactored entity mapping configuration and identifier handling
The engine's configuration layer has been restructured to improve modularity and support composite keys. New classes such as AbstractIdentification, AbstractRelationConfigurer, and FluentCompositeKeyMappingConfigurationSupport centralize identification logic, relation table lookups, and composite key mapping. The Fluent DSL now supports mapping composite keys and sub-entities with dedicated configuration builders. Internal contracts are better encapsulated, and naming strategies are consolidated into a dedicated configuration object to reduce boilerplate.
orm/src/main/java/org/codefilarete/stalactite/engine/configurer · high confidence
Refactored entity mapping configuration to use ReadWritePropertyAccessPoint and new linkage support classes
The entity mapping configuration engine has been refactored to replace the previous reflection accessors with the new ReadWritePropertyAccessPoint interface, simplifying property access and mutator logic. This change introduces several new internal support classes—CompositeKeyLinkageSupport, SingleKeyLinkageSupport, EntityDecoratedEmbeddableConfigurationSupport, and EntityFactoryProviderSupport—to better manage composite keys, embeddable configurations, and entity factory providers. Additionally, the FluentEntityMappingConfigurationSupport now leverages these new structures to handle entity mapping, inheritance, and relation options (such as OneToMany and ManyToMany) with improved type safety and cleaner separation of concerns.
orm/src/main/java/org/codefilarete/stalactite/engine/configurer/entity · high confidence
Refactored entity mapping model with new core classes and interfaces
The mapping module has been restructured to introduce a new intermediate model for entity persistence, replacing the previous strategy-based approach. This change introduces new core classes such as DefaultEntityMapping, EmbeddedClassMapping, and ComposedIdMapping to handle single and composite key identifiers, along with new interfaces like EntityMapping and IdMapping. The refactoring also adds support for element collection mapping via ColumnedCollectionMapping and ColumnedMapMapping, introduces readonly property handling, and replaces the old Row access with ColumnedRow for more precise data retrieval. These changes provide a cleaner, more type-safe foundation for entity-to-table mapping and improve the separation of concerns between configuration and runtime persistence.
core/src/main/java/org/codefilarete/stalactite/mapping · high confidence
Refactored identifier assembly to support composite keys and generic column types
The identifier assembly mechanism has been refactored to support composite primary keys and improve type safety. A new \IdentifierAssembler\ interface and \ComposedIdentifierAssembler\ abstract class have been introduced to handle multi-column keys, while \SingleIdentifierAssembler\ (renamed from \SimpleIdentifierAssembler\) handles single-column keys. The implementation now uses wildcard generics (\Column\<T, ?\>\) instead of raw \Object\ types to prevent casting issues and aligns with the new \ColumnedRow\ data access pattern. This change enables the mapping framework to correctly assemble and persist entities with composite identifiers.
core/src/main/java/org/codefilarete/stalactite/mapping/id/assembly · high confidence
Refactored identifier insertion managers and fixed ThreadLocal cleanup
The identifier insertion logic in the core mapping module has been restructured into distinct manager classes (AlreadyAssigned, BeforeInsert, JDBCGeneratedKeys, and CompositeKey) to handle different ID generation strategies. A critical fix was applied to CompositeKeyAlreadyAssignedIdentifierInsertionManager to ensure ThreadLocal state is cleared during error handling, preventing potential NullPointerExceptions. Additionally, the API for select operations now returns a Set to reflect the design constraint that results should not contain duplicates.
core/src/main/java/org/codefilarete/stalactite/mapping/id/manager · high confidence
Refactored many-to-many relation configuration to use new reflection accessors and explicit association table settings
The many-to-many relation configuration logic has been restructured to rely on the new ReadWritePropertyAccessPoint and SerializablePropertyAccessor/Mutator classes instead of the older ReversibleAccessor and ValueAccessPointByMethodReference. This change updates the internal configuration classes (ManyToManyAssociationConfiguration, ManyToManyRelation, ManyToManyRelationConfigurer) to support explicit association table naming and join column configuration via the MappedByConfiguration, and aligns the cycle configuration with the new ConfiguredRelationalEntityPersister interface.
orm/src/main/java/org/codefilarete/stalactite/engine/configurer/manytomany · high confidence
Refactored one-to-many relation configuration into dedicated classes
The one-to-many relation configuration logic has been moved from the general RelationConfigurer into a dedicated, autonomous package (org.codefilarete.stalactite.engine.configurer.onetomany). This change introduces new classes such as OneToManyRelationConfigurer, OneToManyConfigurerTemplate, and OneToManyAssociationConfiguration to handle the specific setup of one-to-many associations, including support for association tables and mapped reverse properties. This refactoring improves code organization and modularity by isolating the algorithm for one-to-many relations into its own components.
orm/src/main/java/org/codefilarete/stalactite/engine/configurer/onetomany · high confidence
Refactored one-to-one relation handling with separate ownership engines
The one-to-one relation resolution logic has been restructured to explicitly distinguish between relations owned by the source and those owned by the target. New classes, OneToOneOwnedBySourceEngine and OneToOneOwnedByTargetEngine, now manage the specific cascade and foreign-key maintenance behaviors for each ownership model, replacing the previous monolithic approach. The OneToOneResolver orchestrates this by selecting the appropriate engine based on the relation's ownership, ensuring that insert, update, and delete cascades are applied correctly according to which side holds the foreign key.
orm/src/main/java/org/codefilarete/stalactite/engine/configurer/resolver/onetoone · high confidence
Refactored persistence engine with dedicated executors and optimistic locking
The runtime persistence layer has been restructured to improve separation of concerns and reliability. CRUD operations are now handled by dedicated executors (InsertExecutor, UpdateExecutor, DeleteExecutor, SelectExecutor) rather than being embedded in the persister, allowing for more granular control over SQL generation and execution. A new optimistic locking mechanism using Multi-Version Concurrency Control (MVCC) has been introduced, which automatically manages version columns and reverts version upgrades on transaction rollback. Additionally, the persister now wraps all persistence operations with a listener collection, enabling consistent before/after hooks for insert, update, delete, and select actions.
core/src/main/java/org/codefilarete/stalactite/engine/runtime · high confidence
Refactored persistence listener architecture with granular event interfaces
The persistence listener system has been restructured to provide finer-grained control over database operations. New specific listener interfaces have been introduced for distinct actions: \PersistListener\ for general persistence, \InsertListener\ and \UpdateListener\ for specific write operations, and \DeleteListener\ and \DeleteByIdListener\ for removals. A new \SelectListener\ allows interception of read operations, featuring a \then()\ method to chain multiple listeners. These are aggregated by \PersisterListenerCollection\, which coordinates the execution of these events via \doWith...\ methods. Additionally, \UpdateListener\ now provides an \UpdatePayload\ helper to expose modified entity states and column values to listeners.
core/src/main/java/org/codefilarete/stalactite/engine/listener · high confidence
Refactored polymorphic relation handling with new resolver and appender classes
The ORM engine's polymorphism configuration has been reorganized to support more complex relation scenarios, including table-per-class-to-one and one-to-polymorphic-many associations. This change introduces new core classes in the polymorphism resolver package: \GraftableRelation\ to standardize relation metadata extraction, \PolymorphicSkeletonAppender\ to handle the appending of polymorphic structures for single-table, table-per-class, and join-table strategies, and \PolymorphicSkeletonResolver\ to create the appropriate \EntityReadWriteExecutor\ based on the polymorphism type. Additionally, the \PolymorphismResolver\ interface and its implementations (\SingleTableResolver\, \TablePerClassResolver\, \JoinTableResolver\) centralize the logic for resolving polymorphic entities and building sub-entity readers, improving code reuse and organization for polymorphic relation handling.
orm/src/main/java/org/codefilarete/stalactite/engine/configurer/resolver/polymorphism · high confidence
Refactored projection query execution to use SelectAdapter and simplified data retrieval
The projection query engine has been restructured to improve how select clauses are built and how projected values are retrieved. A new SelectAdapter interface and its SelectAdapterSupport implementation now handle the construction of the SQL SELECT clause, replacing previous direct manipulations. Additionally, the ProjectionQueryCriteriaSupport class has been updated to allow data retrieval from projected columns using their assigned aliases via ProjectionDataProvider, and to support building projected columns through entity property paths. This change also introduces a unified method signature for configuring select clauses, removing the previous selectionProjectionWhere signature and consolidating column addition logic.
orm/src/main/java/org/codefilarete/stalactite/engine/runtime/projection · high confidence
Refactored query API with explicit OrderBy and Limit support
The query API in the orm module has been refactored to replace Consumer callbacks with explicit OrderBy and Limit objects in the EntityFinder interface. This change introduces the ConfiguredEntityCriteria interface to define query inputs and updates the EntityFinder.select methods to accept sorting and pagination parameters directly, enabling derived query support for ordering and limiting results.
orm/src/main/java/org/codefilarete/stalactite/query · high confidence
Refactored query engine to extract column mapping and criteria support into dedicated classes
The query runtime logic has been restructured to improve maintainability and clarity. The responsibility for mapping aggregate property accessors to database columns has been moved from EntityCriteriaSupport into a new, dedicated AggregateAccessPointToColumnMapping class, which handles the traversal of the EntityJoinTree to build this mapping. EntityCriteriaSupport now delegates to this mapping and implements the RelationalEntityCriteria interface, while EntityQueryCriteriaSupport manages the execution flow, including the handling of collection-based criteria and in-memory sorting when SQL ordering is incompatible with collection joins. This separation clarifies the responsibilities of column resolution versus query execution and criteria building.
orm/src/main/java/org/codefilarete/stalactite/engine/runtime/query · high confidence
Refactored sub-entity mapping DSL with new reflection types and extended configuration options
The sub-entity mapping API has been reorganized into the \orm/src/main/java/org/codefilarete/stalactite/dsl/subentity\ package, moving classes like \FluentSubEntityMappingBuilder\ from the engine package. This change updates the fluent API to use \SerializablePropertyAccessor\ and \SerializablePropertyMutator\ instead of the previous \SerializableFunction\ and \SerializableBiConsumer\ types for property mapping. Additionally, the DSL now supports forcing column nullability (\nullable()\), declaring unique constraints (\unique()\), and setting column sizes (\columnSize()\). The \readConverter\ and \writeConverter\ methods have been generalized to accept data types different from the property type, and the \mapOneToMany\ method now returns a specific \FluentSubEntityMappingBuilderOneToManyOptions\ interface that includes support for join tables and indexed collections.
orm/src/main/java/org/codefilarete/stalactite/dsl/subentity · high confidence
Refined default SQL type mapping with precision, scale, and length support
The DDL generation logic now uses a new DefaultTypeMapping that aligns Java-to-SQL type conversions with Hibernate's defaults, including the addition of BigDecimal support mapped to decimal(precision, scale). The system now distinguishes between fixed-point sizes (precision and scale) and character lengths, allowing String columns to be generated with specific lengths (e.g., varchar(255) or varchar($l)) and numeric types to respect precision and scale constraints. This change ensures that generated schema definitions more accurately reflect the intended data constraints for strings and decimal numbers.
sql/src/main/java/org/codefilarete/stalactite/sql/ddl · high confidence
Restructured Fluent DSL for Entity Relations with Enhanced Configuration Options
The relation configuration API in the ORM has been reorganized to improve clarity and expand mapping capabilities. The fluent DSL interfaces (ManyToMany, OneToMany, OneToOne, ManyToOne) have been moved to a dedicated package and refactored to use SerializablePropertyAccessor and SerializablePropertyMutator instead of generic serializable functions, providing stronger typing for bidirectional relationships. New entity-specific options interfaces allow for more precise control: ManyToMany and OneToMany relations now support explicit association table configuration (joinTable, sourceJoinColumn, targetJoinColumn), ManyToOne relations allow custom foreign key column naming (columnName) and reverse link definition via Column objects, and OneToOne relations now support unique index generation (unique) and explicit reverse join column naming. Additionally, OneToMany relations have simplified ordering configuration and added cascading mode support.
orm/src/main/java/org/codefilarete/stalactite/dsl/relation · high confidence
Restructured persister configuration pipeline with new builder and identification steps
The ORM's entity mapping configuration has been reorganized into a modular pipeline within the \orm/src/main/java/org/codefilarete/stalactite/engine/configurer/builder\ package. A new \DefaultPersisterBuilder\ now orchestrates the creation of \EntityPersister\ instances, enforcing a strict check that prevents duplicate persisters for the same entity type. This builder delegates to a series of specialized steps: \IdentificationStep\ handles single and composite key resolution and inheritance constraints, \IdentifierManagerStep\ configures identifier generation policies (such as database-generated keys, sequences, or pre-assigned values), and \InheritanceMappingStep\ collects property mappings across inheritance hierarchies. Additionally, \AlreadyAssignedMarkerStep\ ensures entities with pre-assigned identifiers are correctly marked as persisted after database operations, while \BuildLifeCycleListener\ provides hooks for post-build configuration. This change replaces the previous monolithic \PersisterBuilderImpl\ with a more readable and testable structure.
orm/src/main/java/org/codefilarete/stalactite/engine/configurer/builder · high confidence
SQLite adapter added and database vendor packages reorganized
A new SQLite adapter has been introduced, providing specific parameter binders for binary streams and blobs, and mapping BigDecimal to text to accommodate SQLite's typing behavior. To prevent class conflicts when multiple database adapters are used, the SQL adapter packages for SQLite, Derby, H2, and MariaDB have been reorganized into dedicated sub-packages (e.g., \sql-derby-adapter\, \sql-h2-adapter\). Additionally, the MariaDB test infrastructure has been migrated from the embedded MariaDB4J library to Testcontainers, and Derby's type mapping has been updated to handle BigDecimal precision constraints.
(repo-wide) · high confidence
Simplified data access for projected columns via ColumnedRow
The result processing layer now uses a new ColumnedRow interface and its MapBasedColumnedRow implementation to read data from ResultSets. This change allows users to retrieve values from projected columns using their assigned aliases (e.g., 'count') directly, simplifying data access for end users who previously had to manage operators. The underlying iterator (ColumnedRowIterator) handles the mapping between Selectable columns and their aliases, ensuring that data retrieval is aligned with how RowTransformer and IdAssembler read data.
core/src/main/java/org/codefilarete/stalactite/sql/result · high confidence
Spring Data repository integration with transactional support and bean query overrides
The Spring Data integration now provides a dedicated repository factory and base implementation that supports transactional boundaries (read-only by default, write methods explicitly transactional) and includes a full \findAll\ method. It introduces a query lookup strategy that allows overriding derived queries via Spring beans (\@BeanQuery\) and supports native queries, while refactoring the factory bean to resolve entity persisters from the persistence context using a new internal adapter pattern.
spring-integration/spring-data/src/main/java/org/codefilarete/stalactite/spring/repository · high confidence
Support for ordered many-to-many relations with 1-based indexing
The ORM engine now supports ordered many-to-many relationships by introducing a new diffing mechanism in the \orm/src/main/java/org/codefilarete/stalactite/engine/diff\ package. This includes new classes (\AbstractDiff\, \Diff\, \IndexedDiff\, \State\) and a \CollectionDiffer\ that can detect additions, removals, and position changes in collections. A key behavioral change is that ordered collections now use 1-based indexing (starting from 1) instead of 0-based, ensuring correct persistence of element order.
orm/src/main/java/org/codefilarete/stalactite/engine/diff · high confidence
Test coverage
Added concurrency and integration tests for pooled identifier providers; Added integration tests for ManyToManyResolver; Added logging configuration for Spring Data tests; Added test infrastructure for external database integration testing; Added test logging configuration; Added test model classes for ORM engine; Added test model classes for composite key scenarios; Added test model classes for restaurant and review entities; Added test utilities for SQL dialect simulation and pair-set assertions; Added tests for AggregateResolver entity mapping and inheritance; Added tests for ColumnedRowIterator and MapBasedColumnedRow; Added tests for DMLGenerator SQL construction; Added tests for DSL resolver inheritance, relationship, and map metadata resolution; Added tests for ElementCollectionResolver; Added tests for JavaTypeToSqlTypeMapping behavior; Added tests for MapResolver map persistence features; Added tests for ORM engine configuration and mapping logic; Added tests for OneToOneResolver cascade and fetch behavior; Added tests for PersisterListenerCollection behavior; Added tests for PooledHiLoSequencePersister; Added tests for SQL query builder components; Added tests for SQL result processing components; Added tests for SQL statement binder components; Added tests for Select column aliasing and Union column registration; Added tests for Spring Data @BeanQuery override and lookup strategy; Added tests for Spring Data derived query projections and polymorphism; Added tests for Spring Data repository configuration and transaction management; Added tests for Stalactite Spring Boot auto-configuration; Added tests for TupleIn composite identifier handling; Added tests for UniqueConstraintNamingStrategy; Added tests for cycle detection in AbstractCycleLoader; Added tests for database sequence and pooled HiLo sequence identifier providers; Added tests for embeddable mapping configuration and column nullability; Added tests for engine naming strategies and embeddable mapping configurations; Added tests for engine persistence components and configuration; Added tests for identifier state management and persistence policies; Added tests for join-table polymorphism persistence and reading; Added tests for many-to-one relationship resolution and cascade behavior; Added tests for native query projections, pagination, and polymorphic mappings; Added tests for one-to-many relation resolution; Added tests for runtime persistence executors; Added tests for runtime query mapping and criteria support; Added tests for single-table polymorphism persistence and reading; Added tests for table-per-class polymorphism persistence and reading; Added tests for the DefaultPersisterBuilder and related mapping steps; Added unit and integration tests for SQL statement execution and parsing; Added unit tests for ColumnBinderRegistry and ComplexTypeBinder; Added unit tests for DDL generation components; Added unit tests for ORM engine runtime components; Added unit tests for SQL command builders; Added unit tests for SQL connection and transaction listener components; Added unit tests for Table structure operations; Added unit tests for cascade engine support classes; Updated runtime load tests to align with join node and mapping refactoring.
Dependencies
Maven project restructured into multi-module architecture with version 3.0.0-SNAPSHOT
The project has been reorganized from a single module into a multi-module Maven structure, introducing dedicated modules for core functionality, ORM, SQL operations, and database-specific adapters (Derby, H2, HSQLDB, MariaDB, MySQL, Oracle, PostgreSQL, SQLite). The build version has been updated to 3.0.0-SNAPSHOT, and the group ID has been changed to org.codefilarete.stalactite. This restructuring separates database driver dependencies into their own adapter modules and includes new Spring integration modules for autoconfiguration, data access, and transaction management.
(dependencies) · high confidence
Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 52 → 47 (-4.5)
- Rubric changed (rubric-2026.10.1 → rubric-2026.10.5) — scores are not directly comparable.
Lenses
- Code Health 69 → 69 (-0.0)
- Architecture 96 → 96 (+0.0)
- Maturity 74 → 48 (-26.2)
- Readiness 32 → 33 (+0.9)
- Security 89 → 89 (+0.0)
- Performance 61 → 61 (+0.0)
Resolved (25)
- Banned license: mysql:mysql-connector-java
- Dependency hygiene PARTLY measured — Maven build resolved part of the dependency graph, currency reported but not scored
- Duplicated block (10 lines × 2) (orm/src/main/java/org/codefilarete/stalactite/engine/runtime/jointable/JoinTablePolymorphismReader.java)
- Duplicated block (11 lines × 2) (orm/src/main/java/org/codefilarete/stalactite/engine/runtime/singletable/SingleTablePolymorphismEntityFinder.java)
- Duplicated block (14 lines × 2) (orm/src/main/java/org/codefilarete/stalactite/engine/configurer/resolver/polymorphism/tableperclass/TablePerClassAppender.java)
- Duplicated block (5 lines × 2) (orm/src/main/java/org/codefilarete/stalactite/engine/configurer/dslresolver/OneToManyMetadataResolver.java)
- Duplicated block (6 lines × 2) (orm/src/main/java/org/codefilarete/stalactite/engine/configurer/resolver/polymorphism/PolymorphicSkeletonAppender.java)
- Low cohesion: InternalProcessor (LCOM4 4) (orm/src/main/java/org/codefilarete/stalactite/engine/configurer/dslresolver/PropertyMappingResolver.java)
- Members sharing a duplicated core (4 members, 50+ identical tokens) (orm/src/main/java/org/codefilarete/stalactite/engine/configurer/dslresolver/ManyToManyMetadataResolver.java)
- Members sharing a duplicated core (5 members, 50+ identical tokens) (orm/src/main/java/org/codefilarete/stalactite/engine/runtime/jointable/JoinTablePolymorphismPersister.java)
- OneToManyOwnedByTargetHelper.determineForeignKeyColumns (cognitive 21) (orm/src/main/java/org/codefilarete/stalactite/engine/configurer/dslresolver/OneToManyMetadataResolver.java)
- OneToManyOwnedByTargetHelper.determineForeignKeyColumns (cyclomatic 16) (orm/src/main/java/org/codefilarete/stalactite/engine/configurer/dslresolver/OneToManyMetadataResolver.java)
- Outdated (test): net.bytebuddy:byte-buddy
- Outdated (test): net.bytebuddy:byte-buddy-agent
- Outdated (test): org.assertj:assertj-core
- Outdated (test): org.junit.jupiter:junit-jupiter
- Outdated (test): org.junit.jupiter:junit-jupiter-api
- Outdated (test): org.junit.jupiter:junit-jupiter-engine
- Outdated (test): org.junit.jupiter:junit-jupiter-params
- Outdated (test): org.junit.platform:junit-platform-commons
- …and 5 more
New (13)
- Dependency hygiene PARTLY measured — Maven/Gradle declarations read, no dependency graph resolved
- Duplicated block (10 lines × 3) (orm/src/main/java/org/codefilarete/stalactite/engine/runtime/jointable/JoinTablePolymorphismEntityFinder.java)
- Duplicated block (15 lines × 2) (orm/src/main/java/org/codefilarete/stalactite/engine/configurer/resolver/map/FetchedSeparatelyMapAppender.java)
- Duplicated block (6 lines × 2) (orm/src/main/java/org/codefilarete/stalactite/engine/configurer/resolver/polymorphism/PolymorphicSkeletonAppender.java)
- Duplicated block (8 lines × 2) (orm/src/main/java/org/codefilarete/stalactite/engine/configurer/resolver/map/JoinedMapAppender.java)
- Hotspot: orm/src/main/java/org/codefilarete/stalactite/engine/configurer/dslresolver/OneToManyMetadataResolver.java (orm/src/main/java/org/codefilarete/stalactite/engine/configurer/dslresolver/OneToManyMetadataResolver.java)
- Members sharing a duplicated core (4 members, 50+ identical tokens) (orm/src/main/java/org/codefilarete/stalactite/engine/configurer/dslresolver/ManyToManyMetadataResolver.java)
- Members sharing a duplicated core (5 members, 50+ identical tokens) (orm/src/main/java/org/codefilarete/stalactite/engine/runtime/jointable/JoinTablePolymorphismPersister.java)
- OneToManyOwnedByTargetHelper.createForeignKeyColumns (cognitive 21) (orm/src/main/java/org/codefilarete/stalactite/engine/configurer/dslresolver/OneToManyMetadataResolver.java)
- OneToManyOwnedByTargetHelper.createForeignKeyColumns (cyclomatic 16) (orm/src/main/java/org/codefilarete/stalactite/engine/configurer/dslresolver/OneToManyMetadataResolver.java)
- Split orm
- TodoComment (orm/src/main/java/org/codefilarete/stalactite/engine/runtime/tableperclass/TablePerClassPolymorphismPersister.java)
- TodoComment (orm/src/main/java/org/codefilarete/stalactite/engine/runtime/tableperclass/TablePerClassPolymorphismPersister.java)
Changes since last survey
- 3 commits — 3 feature/other, 0 fixes
By area
- orm/src — 3 commits
Notable commits
- change: Code cleanup
- change: First iteration of implementing table-per-class-to-one relation
- change: Sharing the AggregateOneToOneAppender.TablePerClassUnion with TablePerClassPolymorphismEntityFinder. Using this time to review the AbstractPolymorphicEntityFinder.persisterPerSubclass field usage to simplify logic of reading ids and selecting related subentities. This should prepare the Polymorphic-to-one feature (in particular table-per-class-to-one)
Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
codefilarete/stalactite was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.
About this page
- The score is its most recent published measurement, taken on 22 October 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit db416c3f97ed48ce40ebeca4150267795bdd1eb7 — the exact code this score is about.
- Scored under rubric-2026.10.5 — the same rubric and the same method as every other entry in this index.
- Measured by watchdog.canine.dev using codehealth-analyzer measure-2026.10.3+preprod-fddbc92cb8df.