Skip to content

Commit 1fde84d

Browse files
zantvoortzantvoort
authored
Feature/storm 60 (#61)
*Additions* - Add storm-bom module for centralized dependency version management - Add storm-test module with @stormtest JUnit 5 extension and StatementCapture - Add Spring Boot starter auto-configuration logic - Add StormConfig for centralized configuration - Add JMX metrics for dirty checking, entity cache, and template cache - Add entity lifecycle callbacks (EntityCallback<E>) for insert, update, upsert, and delete operations - Add polymorphic entity support - Add @uk support for unique key lookups and keyset pagination - Add schema validation - Add slice and keyset pagination logic with cursorless sliceBefore overloads and varargs orderByDescending - Add multi-column expression support for all operators on inline records - Add inline record flatten() for ORDER BY and GROUP BY expansion - Add Kotlin examples to foundation classes - Integrate Spotless Maven Plugin for automated code formatting (Java and Kotlin) *Improvements* - Split storm-jackson into storm-jackson2 (Jackson 2 / Spring Boot 3.x) and storm-jackson3 (Jackson 3 / Spring Boot 4+) - Move @SqlLog to foundation and process via proxy, replacing Spring AOP SqlLogger - Improve entity caching - Improve validation - Support entity-typed PK foreign key references in entity expansion - Support nullable detection for compound keys (@UK/@pk on inline records) - Propagate @persist from inline records to child fields - Improve test coverage and eliminate warnings *Fixes* - Fix template cache keying - Fix documentation errors *Documentation* - Comprehensive documentation updates across all major topics Relates to #60
1 parent 661fbf5 commit 1fde84d

610 files changed

Lines changed: 70408 additions & 7710 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.editorconfig‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
root = true
2+
3+
[*]
4+
indent_style = space
5+
indent_size = 4
6+
end_of_line = lf
7+
charset = utf-8
8+
trim_trailing_whitespace = true
9+
insert_final_newline = true
10+
11+
[*.{yml,yaml}]
12+
indent_size = 2
13+
14+
[*.md]
15+
trim_trailing_whitespace = false
16+
17+
[*.{kt,kts}]
18+
ktlint_standard_no-wildcard-imports = disabled
19+
ktlint_standard_function-naming = disabled
20+
ktlint_standard_value-parameter-comment = disabled
21+
ktlint_standard_value-argument-comment = disabled

‎.githooks/pre-push‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
#!/bin/sh
2+
echo "Running Spotless formatting check..."
3+
mvn spotless:check -q 2>&1
4+
if [ $? -ne 0 ]; then
5+
echo ""
6+
echo "Formatting check failed. Run 'mvn spotless:apply' to fix."
7+
exit 1
8+
fi

‎.github/workflows/ci.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
pull_request:
7+
branches: [ main ]
8+
9+
jobs:
10+
build:
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- name: Checkout repository
15+
uses: actions/checkout@v4
16+
17+
- name: Set up JDK 21
18+
uses: actions/setup-java@v4
19+
with:
20+
distribution: 'temurin'
21+
java-version: '21'
22+
cache: 'maven'
23+
24+
- name: Check formatting
25+
run: mvn spotless:check -B
26+
27+
- name: Build and test
28+
run: mvn verify -B
29+
30+
- name: Upload coverage to Codecov
31+
if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository
32+
uses: codecov/codecov-action@v4
33+
with:
34+
token: ${{ secrets.CODECOV_TOKEN }}
35+
flags: unittests
36+
fail_ci_if_error: false

‎.github/workflows/docs.yml‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
name: Documentation
2+
3+
on:
4+
push:
5+
branches: [main]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: write
10+
11+
concurrency:
12+
group: docs-deploy
13+
cancel-in-progress: true
14+
15+
jobs:
16+
deploy:
17+
runs-on: ubuntu-latest
18+
steps:
19+
- name: Checkout
20+
uses: actions/checkout@v4
21+
22+
- name: Set up JDK 21
23+
uses: actions/setup-java@v4
24+
with:
25+
java-version: '21'
26+
distribution: temurin
27+
cache: maven
28+
29+
- name: Set up Node.js
30+
uses: actions/setup-node@v4
31+
with:
32+
node-version: '22'
33+
cache: npm
34+
cache-dependency-path: website/package-lock.json
35+
36+
- name: Install website dependencies
37+
run: npm ci
38+
working-directory: website
39+
40+
- name: Build project (skip tests)
41+
run: mvn install -DskipTests -Dgpg.skip=true -q
42+
43+
- name: Generate Javadoc (aggregate)
44+
run: |
45+
mvn javadoc:aggregate -q \
46+
-Dmaven.javadoc.failOnError=false \
47+
-Dadditionaloption="--enable-preview --source 21"
48+
49+
- name: Generate KDoc (Dokka)
50+
run: |
51+
for module in storm-kotlin storm-kotlin-spring storm-kotlin-spring-boot-starter storm-kotlin-validator storm-metamodel-ksp storm-kotlinx-serialization; do
52+
if [ -d "$module" ]; then
53+
mvn dokka:dokka -pl "$module" -q -Dmaven.javadoc.failOnError=false || true
54+
fi
55+
done
56+
57+
- name: Copy Javadoc to website/static/api/java
58+
run: |
59+
mkdir -p website/static/api/java
60+
if [ -d target/site/apidocs ]; then
61+
cp -r target/site/apidocs/* website/static/api/java/
62+
fi
63+
64+
- name: Copy KDoc to website/static/api/kotlin
65+
run: |
66+
for module in storm-kotlin storm-kotlin-spring storm-kotlin-spring-boot-starter storm-kotlin-validator storm-metamodel-ksp storm-kotlinx-serialization; do
67+
if [ -d "$module/target/dokka" ]; then
68+
mkdir -p "website/static/api/kotlin/$module"
69+
cp -r "$module/target/dokka/"* "website/static/api/kotlin/$module/"
70+
fi
71+
done
72+
73+
- name: Build Docusaurus
74+
run: npm run build
75+
working-directory: website
76+
77+
- name: Deploy to GitHub Pages
78+
uses: peaceiris/actions-gh-pages@v4
79+
with:
80+
github_token: ${{ secrets.GITHUB_TOKEN }}
81+
publish_dir: ./website/build
82+
force_orphan: true

‎.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,3 +37,12 @@ build/
3737

3838
### Mac OS ###
3939
.DS_Store
40+
41+
### Maven Flatten Plugin ###
42+
.flattened-pom.xml
43+
44+
### Docusaurus ###
45+
website/node_modules/
46+
website/build/
47+
website/.docusaurus/
48+
website/static/api/

‎CONTRIBUTING.md‎

Lines changed: 44 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -32,19 +32,49 @@ mvn clean install
3232

3333
```
3434
storm-framework/
35-
├── storm-core/ # Core library (no preview dependencies)
36-
├── storm-java21/ # Java 21+ API (uses String Templates)
37-
├── storm-kotlin/ # Kotlin API
38-
├── storm-spring/ # Spring integration (Java)
39-
├── storm-kotlin-spring/ # Spring integration (Kotlin)
40-
├── storm-oracle/ # Oracle dialect
41-
├── storm-mysql/ # MySQL dialect
42-
├── storm-mariadb/ # MariaDB dialect
43-
├── storm-postgresql/ # PostgreSQL dialect
44-
├── storm-mssqlserver/ # MS SQL Server dialect
45-
├── storm-jackson/ # Jackson JSON support
46-
├── storm-kotlinx-serialization/ # Kotlinx serialization support
47-
└── storm-metamodel-processor/ # Annotation processor
35+
├── storm-bom/ # Bill of Materials (BOM) for version management
36+
├── storm-core/ # Core library (no preview dependencies)
37+
├── storm-java21/ # Java 21+ API (uses String Templates)
38+
├── storm-kotlin/ # Kotlin API
39+
├── storm-spring/ # Spring integration (Java)
40+
├── storm-kotlin-spring/ # Spring integration (Kotlin)
41+
├── storm-spring-boot-starter/ # Spring Boot Starter (Java)
42+
├── storm-kotlin-spring-boot-starter/ # Spring Boot Starter (Kotlin)
43+
├── storm-oracle/ # Oracle dialect
44+
├── storm-mysql/ # MySQL dialect
45+
├── storm-mariadb/ # MariaDB dialect
46+
├── storm-postgresql/ # PostgreSQL dialect
47+
├── storm-mssqlserver/ # MS SQL Server dialect
48+
├── storm-jackson/ # Jackson JSON support
49+
├── storm-kotlinx-serialization/ # Kotlinx serialization support
50+
└── storm-metamodel-processor/ # Annotation processor
51+
```
52+
53+
## Code Formatting
54+
55+
Storm uses [Spotless](https://github.com/diffplug/spotless) to enforce consistent code formatting across the project. Formatting is checked automatically in CI and can be enforced locally with a git pre-push hook.
56+
57+
- **Java** is formatted with [Palantir Java Format](https://github.com/palantir/palantir-java-format) (4-space indentation)
58+
- **Kotlin** is formatted with [ktlint](https://github.com/pinterest/ktlint) (Kotlin coding conventions)
59+
60+
### Auto-fix formatting
61+
62+
```bash
63+
mvn spotless:apply
64+
```
65+
66+
### Check formatting without modifying files
67+
68+
```bash
69+
mvn spotless:check
70+
```
71+
72+
### Set up the pre-push hook
73+
74+
To automatically check formatting before every push:
75+
76+
```bash
77+
git config core.hooksPath .githooks
4878
```
4979

5080
## Code Guidelines
@@ -53,7 +83,7 @@ storm-framework/
5383

5484
- Follow existing code style and conventions
5585
- Write clear, self-documenting code
56-
- Keep changes focused—one feature or fix per PR
86+
- Keep changes focused; one feature or fix per PR
5787
- Add tests for new functionality
5888

5989
### Kotlin

‎README.md‎

Lines changed: 45 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,14 @@
11
# ST/ORM
22

33
[![Maven Central](https://img.shields.io/maven-central/v/st.orm/storm-core.svg)](https://central.sonatype.com/namespace/st.orm)
4+
[![CI](https://github.com/storm-repo/storm-framework/actions/workflows/ci.yml/badge.svg)](https://github.com/storm-repo/storm-framework/actions/workflows/ci.yml)
5+
[![codecov](https://codecov.io/gh/storm-repo/storm-framework/graph/badge.svg)](https://codecov.io/gh/storm-repo/storm-framework)
46
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
7+
[![Docs](https://img.shields.io/badge/docs-storm--framework-blue)](https://storm-repo.github.io/storm-framework/)
58
[![Kotlin 2.0+](https://img.shields.io/badge/Kotlin-2.0%2B-purple)](https://kotlinlang.org/)
69
[![Java 21+](https://img.shields.io/badge/Java-21%2B-blue)](https://openjdk.org/projects/jdk/21/)
710

8-
**Storm** is a SQL Template and ORM framework designed for Kotlin 2.0+ and Java 21+, focusing on modernizing and simplifying database programming. By leveraging the latest features of Kotlin and Java, it enables developers to define entities and queries in a concise and readable manner, enhancing both productivity and code clarity.
11+
**Storm** is a modern, high-performance ORM for Kotlin 2.0+ and Java 21+, built around a powerful SQL template engine. It focuses on simplicity, type safety, and predictable performance through immutable models and compile-time metadata.
912

1013
**Key benefits:**
1114

@@ -126,12 +129,43 @@ List<User> users = orm.query(RAW."""
126129
127130
## Quick Start
128131

132+
### Dependency Management (BOM)
133+
134+
Storm provides a Bill of Materials (BOM) for centralized version management. Import the BOM once and omit version numbers from individual Storm dependencies.
135+
136+
**Maven:**
137+
138+
```xml
139+
<dependencyManagement>
140+
<dependencies>
141+
<dependency>
142+
<groupId>st.orm</groupId>
143+
<artifactId>storm-bom</artifactId>
144+
<version>1.9.0</version>
145+
<type>pom</type>
146+
<scope>import</scope>
147+
</dependency>
148+
</dependencies>
149+
</dependencyManagement>
150+
```
151+
152+
**Gradle (Kotlin DSL):**
153+
154+
```kotlin
155+
dependencies {
156+
implementation(platform("st.orm:storm-bom:1.9.0"))
157+
}
158+
```
159+
160+
With the BOM imported, add Storm modules without specifying versions:
161+
129162
### Kotlin
130163

131164
```kotlin
132165
dependencies {
133-
implementation("st.orm:storm-kotlin:1.8.2")
134-
runtimeOnly("st.orm:storm-core:1.8.2")
166+
implementation(platform("st.orm:storm-bom:1.9.0"))
167+
implementation("st.orm:storm-kotlin")
168+
runtimeOnly("st.orm:storm-core")
135169
}
136170
```
137171

@@ -141,18 +175,18 @@ dependencies {
141175
<dependency>
142176
<groupId>st.orm</groupId>
143177
<artifactId>storm-java21</artifactId>
144-
<version>1.8.2</version>
145178
</dependency>
146179
<dependency>
147180
<groupId>st.orm</groupId>
148181
<artifactId>storm-core</artifactId>
149-
<version>1.8.2</version>
150182
<scope>runtime</scope>
151183
</dependency>
152184
```
153185

154186
## Documentation
155187

188+
Full documentation is available at [storm-repo.github.io/storm-framework](https://storm-repo.github.io/storm-framework/).
189+
156190
### Core Concepts
157191

158192
Everything you need to build applications with Storm. Start with Getting Started and work through the topics as needed.
@@ -169,10 +203,14 @@ Everything you need to build applications with Storm. Start with Getting Started
169203
| [Refs](docs/refs.md) | Lazy loading and optimized references (7 min) |
170204
| [Batch & Streaming](docs/batch-streaming.md) | Bulk operations and Flow/Stream (5 min) |
171205
| [Upserts](docs/upserts.md) | Insert-or-update operations (6 min) |
206+
| [Polymorphism](docs/polymorphism.md) | Sealed type inheritance strategies (20 min) |
207+
| [Entity Lifecycle](docs/entity-lifecycle.md) | Callbacks for auditing, validation, and logging (8 min) |
172208
| [JSON Support](docs/json.md) | JSON columns and aggregation (6 min) |
173209
| [Transactions](docs/transactions.md) | Transaction management and propagation (22 min) |
174-
| [Spring Integration](docs/spring-integration.md) | Spring Boot configuration (6 min) |
210+
| [Spring Integration](docs/spring-integration.md) | Spring Boot Starter and auto-configuration (8 min) |
175211
| [Database Dialects](docs/dialects.md) | Database-specific support (5 min) |
212+
| [Testing](docs/testing.md) | JUnit 5 integration and statement capture (5 min) |
213+
| [Validation](docs/validation.md) | Record and schema validation (5 min) |
176214

177215
### Advanced Topics
178216

@@ -184,7 +222,7 @@ Deep dives into Storm's internals. You don't need these to be productive, but th
184222
| [Hydration](docs/hydration.md) | Result mapping to records (16 min) |
185223
| [Dirty Checking](docs/dirty-checking.md) | Update modes and change detection (19 min) |
186224
| [Entity Cache](docs/entity-cache.md) | Transaction-scoped caching and identity (10 min) |
187-
| [SQL Interceptors](docs/interceptors.md) | Query logging and modification (6 min) |
225+
| [SQL Logging](docs/sql-logging.md) | Declarative query logging with `@SqlLog` (6 min) |
188226
| [Configuration](docs/configuration.md) | System properties reference (7 min) |
189227

190228
### Resources

‎codecov.yml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
codecov:
2+
require_ci_to_pass: true
3+
4+
coverage:
5+
status:
6+
project:
7+
default:
8+
target: auto
9+
threshold: 5%
10+
patch:
11+
default:
12+
target: auto
13+
threshold: 10%
14+
informational: true
15+
16+
ignore:
17+
- "**/src/test/**"
18+
- "**/generated-sources/**"
19+
- "storm-bom/**"
20+
- "storm-metamodel-processor/**"
21+
- "storm-metamodel-ksp/**"

0 commit comments

Comments
 (0)