Skip to content

Commit 33a23f3

Browse files
zantvoortzantvoort
authored
Docusaurus versioning. (#71)
1 parent af0f995 commit 33a23f3

45 files changed

Lines changed: 18720 additions & 6 deletions

Some content is hidden

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

‎.github/workflows/release.yml‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -84,11 +84,6 @@ jobs:
8484
run: npx docusaurus docs:version ${{ steps.version.outputs.VERSION }}
8585
working-directory: website
8686

87-
- name: Update default version in config
88-
run: |
89-
sed -i "s/lastVersion: '.*'/lastVersion: '${{ steps.version.outputs.VERSION }}'/" docusaurus.config.ts
90-
working-directory: website
91-
9287
- name: Commit and push
9388
run: |
9489
git config user.name "github-actions[bot]"

‎website/docusaurus.config.ts‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,6 @@ const config: Config = {
2828
path: '../docs',
2929
routeBasePath: '/',
3030
sidebarPath: './sidebars.ts',
31-
lastVersion: '1.9.0',
3231
versions: {
3332
current: {
3433
label: 'Next',

‎website/versioned_docs/version-1.9.0/api-java.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
title: Java API Reference
3+
---
4+
5+
# Java API Reference
6+
7+
Storm's Java API is organized into a set of focused modules. Each module has a specific role, from the core ORM engine to Spring Boot auto-configuration. This page provides an overview of the module structure and links to detailed documentation for each concept.
8+
9+
## Module Overview
10+
11+
### storm-java21
12+
13+
The main Java API module. It provides the `ORMTemplate` entry point, repository interfaces, SQL Templates using Java's String Templates (preview feature), and the type-safe query DSL. This is the primary dependency for Java applications.
14+
15+
```xml
16+
<dependency>
17+
<groupId>st.orm</groupId>
18+
<artifactId>storm-java21</artifactId>
19+
<version>1.9.1</version>
20+
</dependency>
21+
```
22+
23+
**String Templates (Preview Feature):** The Java API uses JDK String Templates for SQL construction. String Templates are a preview feature in Java 21+, which means you must compile with `--enable-preview` and run with `--enable-preview`. The preview status means the syntax may change in future JDK releases, and Storm's Java API surface will adapt accordingly. The Kotlin API does not depend on any preview features and is fully stable.
24+
25+
To enable preview features in Maven:
26+
27+
```xml
28+
<plugin>
29+
<groupId>org.apache.maven.plugins</groupId>
30+
<artifactId>maven-compiler-plugin</artifactId>
31+
<configuration>
32+
<compilerArgs>
33+
<arg>--enable-preview</arg>
34+
</compilerArgs>
35+
</configuration>
36+
</plugin>
37+
```
38+
39+
### storm-spring
40+
41+
Spring Framework integration for Java. Provides `RepositoryBeanFactoryPostProcessor` for repository auto-discovery and injection, plus transaction integration. Add this module when you use Spring Framework without Spring Boot.
42+
43+
```xml
44+
<dependency>
45+
<groupId>st.orm</groupId>
46+
<artifactId>storm-spring</artifactId>
47+
<version>1.9.1</version>
48+
</dependency>
49+
```
50+
51+
See [Spring Integration](spring-integration.md) for configuration details.
52+
53+
### storm-spring-boot-starter
54+
55+
Spring Boot auto-configuration for Java. Automatically creates an `ORMTemplate` bean from the `DataSource`, discovers repositories, and binds `storm.*` properties from `application.yml`. This is the recommended dependency for Spring Boot applications.
56+
57+
```xml
58+
<dependency>
59+
<groupId>st.orm</groupId>
60+
<artifactId>storm-spring-boot-starter</artifactId>
61+
<version>1.9.1</version>
62+
</dependency>
63+
```
64+
65+
See [Spring Integration: Spring Boot Starter](spring-integration.md#spring-boot-starter) for what the starter provides and how to override its defaults.
66+
67+
## Key Classes
68+
69+
| Class | Description | Guide |
70+
|-------|-------------|-------|
71+
| `ORMTemplate` | The central entry point. Create with `ORMTemplate.of(dataSource)`. Provides access to entity/projection repositories and the SQL template query engine. | [Getting Started](getting-started.md) |
72+
| `EntityRepository<E, ID>` | Type-safe repository interface for CRUD operations on entities. Extend this interface and add custom query methods with default method bodies. | [Repositories](repositories.md) |
73+
| `ProjectionRepository<P, ID>` | Read-only repository for projections (subset of entity columns). | [Projections](projections.md) |
74+
| `Entity<ID>` | Marker interface for entity records. Implement this on your Java records to enable repository operations. | [Entities](entities.md) |
75+
| `Projection<ID>` | Marker interface for projection records. | [Projections](projections.md) |
76+
| `StormConfig` | Immutable configuration holder. Pass to `ORMTemplate.of()` to override defaults. | [Configuration](configuration.md) |
77+
78+
## Metamodel Generation
79+
80+
The `storm-metamodel-processor` annotation processor generates type-safe metamodel classes (e.g., `User_`) at compile time. These classes provide static references to entity fields for use in the query DSL, enabling compile-time checked queries.
81+
82+
```xml
83+
<dependency>
84+
<groupId>st.orm</groupId>
85+
<artifactId>storm-metamodel-processor</artifactId>
86+
<version>1.9.1</version>
87+
<scope>provided</scope>
88+
</dependency>
89+
```
90+
91+
See [Metamodel](metamodel.md) for setup and usage.
92+
93+
## Javadoc
94+
95+
The aggregated Javadoc covers all Java modules in the Storm framework:
96+
97+
[Browse the Javadoc](../api/java/index.html)

‎website/versioned_docs/version-1.9.0/api-kotlin.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
---
2+
title: Kotlin API Reference
3+
---
4+
5+
# Kotlin API Reference
6+
7+
Storm's Kotlin API is organized into a set of focused modules. Each module has a specific role, from the core ORM engine with coroutine support to Spring Boot auto-configuration and validation. This page provides an overview of the module structure and links to detailed documentation for each concept.
8+
9+
## Module Overview
10+
11+
### storm-kotlin
12+
13+
The main Kotlin API module. It provides the `ORMTemplate` interface, extension functions (`DataSource.orm`, `Connection.orm`), repository interfaces, coroutine support, and the type-safe query DSL. This is the primary dependency for Kotlin applications.
14+
15+
```kotlin
16+
// Gradle (Kotlin DSL)
17+
implementation("st.orm:storm-kotlin:1.9.1")
18+
```
19+
20+
```xml
21+
<!-- Maven -->
22+
<dependency>
23+
<groupId>st.orm</groupId>
24+
<artifactId>storm-kotlin</artifactId>
25+
<version>1.9.1</version>
26+
</dependency>
27+
```
28+
29+
The Kotlin API does not depend on any preview features. All APIs are stable and production-ready.
30+
31+
### storm-kotlin-spring
32+
33+
Spring Framework integration for Kotlin. Provides `RepositoryBeanFactoryPostProcessor` for repository auto-discovery and injection, `@EnableTransactionIntegration` for bridging Storm's programmatic transactions with Spring's `@Transactional`, and transaction-aware coroutine support. Add this module when you use Spring Framework without Spring Boot.
34+
35+
```kotlin
36+
implementation("st.orm:storm-kotlin-spring:1.9.1")
37+
```
38+
39+
See [Spring Integration](spring-integration.md) for configuration details.
40+
41+
### storm-kotlin-spring-boot-starter
42+
43+
Spring Boot auto-configuration for Kotlin. Automatically creates an `ORMTemplate` bean from the `DataSource`, discovers repositories, enables transaction integration, and binds `storm.*` properties from `application.yml`. This is the recommended dependency for Spring Boot applications.
44+
45+
```kotlin
46+
implementation("st.orm:storm-kotlin-spring-boot-starter:1.9.1")
47+
```
48+
49+
See [Spring Integration: Spring Boot Starter](spring-integration.md#spring-boot-starter) for what the starter provides and how to override its defaults.
50+
51+
### storm-kotlin-validator
52+
53+
Validation support for Kotlin entities. Provides integration with Kotlin validation libraries for entity constraint checking.
54+
55+
```kotlin
56+
implementation("st.orm:storm-kotlin-validator:1.9.1")
57+
```
58+
59+
## Key Classes and Functions
60+
61+
| Class/Function | Description | Guide |
62+
|----------------|-------------|-------|
63+
| `ORMTemplate` | The central entry point. Create with `dataSource.orm` or `ORMTemplate.of(dataSource)`. Provides access to entity/projection repositories and the SQL template query engine. | [Getting Started](getting-started.md) |
64+
| `EntityRepository<E, ID>` | Type-safe repository interface for CRUD operations on entities. Extend this interface and add custom query methods with default method bodies. | [Repositories](repositories.md) |
65+
| `ProjectionRepository<P, ID>` | Read-only repository for projections (subset of entity columns). | [Projections](projections.md) |
66+
| `Entity<ID>` | Marker interface for entity data classes. Implement this on your Kotlin data classes to enable repository operations. | [Entities](entities.md) |
67+
| `Projection<ID>` | Marker interface for projection data classes. | [Projections](projections.md) |
68+
| `DataSource.orm` | Extension property that creates an `ORMTemplate` from a `DataSource`. | [Getting Started](getting-started.md) |
69+
| `transaction { }` | Coroutine-aware programmatic transaction block. | [Transactions](transactions.md) |
70+
| `transactionBlocking { }` | Blocking variant of the programmatic transaction block. | [Transactions](transactions.md) |
71+
| `StormConfig` | Immutable configuration holder. Pass to `dataSource.orm(config)` to override defaults. | [Configuration](configuration.md) |
72+
73+
## Coroutine Support
74+
75+
Storm's Kotlin API provides first-class coroutine support. Query results can be consumed as `Flow<T>` for streaming, and the `transaction { }` block is a suspending function that integrates with structured concurrency. Storm leverages JVM virtual threads under the hood, so database operations do not block platform threads even when using JDBC (which is inherently synchronous).
76+
77+
```kotlin
78+
// Streaming with Flow
79+
val users: Flow<User> = orm.entity(User::class).selectAll()
80+
users.collect { processUser(it) }
81+
82+
// Suspending transaction
83+
transaction {
84+
orm insert User(name = "Alice")
85+
}
86+
```
87+
88+
## Metamodel Generation
89+
90+
The metamodel generates type-safe companion classes (e.g., `User_`) at compile time. These classes provide static references to entity fields for use in the query DSL, enabling compile-time checked queries.
91+
92+
There are two ways to configure metamodel generation for Kotlin projects, depending on your build tool:
93+
94+
- **Gradle with KSP:** Use `storm-metamodel-ksp`, which is a Kotlin Symbol Processing plugin.
95+
- **Maven with kapt:** Use `storm-metamodel-processor`, which is a standard Java annotation processor invoked through kapt.
96+
97+
Both generate the same metamodel classes; they are different build tool integrations.
98+
99+
**Gradle (Kotlin DSL) with KSP:**
100+
101+
```kotlin
102+
plugins {
103+
id("com.google.devtools.ksp") version "2.0.21-1.0.28"
104+
}
105+
106+
dependencies {
107+
ksp("st.orm:storm-metamodel-ksp:1.9.1")
108+
}
109+
```
110+
111+
**Maven with kapt:**
112+
113+
```xml
114+
<plugin>
115+
<groupId>org.jetbrains.kotlin</groupId>
116+
<artifactId>kotlin-maven-plugin</artifactId>
117+
<executions>
118+
<execution>
119+
<id>kapt</id>
120+
<goals><goal>kapt</goal></goals>
121+
<configuration>
122+
<annotationProcessorPaths>
123+
<path>
124+
<groupId>st.orm</groupId>
125+
<artifactId>storm-metamodel-processor</artifactId>
126+
<version>1.9.1</version>
127+
</path>
128+
</annotationProcessorPaths>
129+
</configuration>
130+
</execution>
131+
</executions>
132+
</plugin>
133+
```
134+
135+
See [Metamodel](metamodel.md) for setup and usage.
136+
137+
## KDoc
138+
139+
KDoc is generated per module using Dokka. Select a module below to browse its API documentation.
140+
141+
| Module | Description |
142+
|--------|-------------|
143+
| [storm-kotlin](../api/kotlin/storm-kotlin/index.html) | Kotlin API with coroutine support |
144+
| [storm-kotlin-spring](../api/kotlin/storm-kotlin-spring/index.html) | Spring Framework integration for Kotlin |
145+
| [storm-kotlin-spring-boot-starter](../api/kotlin/storm-kotlin-spring-boot-starter/index.html) | Spring Boot auto-configuration for Kotlin |
146+
| [storm-kotlin-validator](../api/kotlin/storm-kotlin-validator/index.html) | Kotlin validation support |
147+
| [storm-metamodel-ksp](../api/kotlin/storm-metamodel-ksp/index.html) | Kotlin Symbol Processing for metamodel generation |
148+
| [storm-kotlinx-serialization](../api/kotlin/storm-kotlinx-serialization/index.html) | Kotlinx Serialization support |

0 commit comments

Comments
 (0)