Skip to content

Commit c16b2dd

Browse files
dieppadieppa
committed
docs: target systems update
1 parent 09f93e6 commit c16b2dd

File tree

11 files changed

+191
-31
lines changed

11 files changed

+191
-31
lines changed

‎docs/changes/anatomy-and-structure.md‎

Lines changed: 21 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ The `id` must be unique across all Changes in your application.
2222
- Must be unique application-wide
2323
- Use descriptive names (e.g., `add-user-status`, not `change1`)
2424
- Cannot be modified once deployed
25+
____
2526

2627
### `order` - Execution sequence
2728
The `order` determines when the Change executes relative to others.
@@ -37,7 +38,7 @@ The `order` determines when the Change executes relative to others.
3738
- Minimum 4 digits recommended for future expansion
3839
- Determines execution order across all target systems
3940
- Cannot be changed once deployed
40-
41+
____
4142
### `author` - Responsibility tracking
4243
Identifies who is responsible for this change.
4344

@@ -53,18 +54,6 @@ Identifies who is responsible for this change.
5354

5455
## Optional properties
5556

56-
### `description` - Change explanation
57-
Briefly describes what the change does, especially useful for complex operations.
58-
59-
```java
60-
@Change(
61-
id = "optimize-user-queries",
62-
order = "0001",
63-
author = "performance-team",
64-
description = "Add composite index on user table to improve search performance"
65-
)
66-
```
67-
6857
### `transactional` - Transaction behavior
6958
Controls whether the change runs within a transaction (default: `true`).
7059

@@ -77,14 +66,14 @@ Controls whether the change runs within a transaction (default: `true`).
7766
)
7867
```
7968

80-
**When to set `transactional = false`:**
81-
- DDL operations (CREATE INDEX, ALTER TABLE)
82-
- Large bulk operations that exceed transaction limits
83-
- Cross-system changes spanning multiple databases
84-
- Operations that don't support transactions
85-
8669
**Important:** For non-transactional target systems (S3, Kafka, etc.), this flag has no effect.
8770

71+
:::tip
72+
For detailed information on transaction handling, see [Transactions](transactions.md).
73+
:::
74+
75+
----
76+
8877
### `recovery` - Failure handling strategy
8978
Controls how Flamingock handles execution failures (default: `MANUAL_INTERVENTION`).
9079

@@ -109,6 +98,19 @@ public class IdempotentChange {
10998

11099
For detailed information on recovery strategies, see [Safety and Recovery](../safety-and-recovery/introduction.md).
111100

101+
---
102+
### `description` - Change explanation
103+
Briefly describes what the change does, especially useful for complex operations.
104+
105+
```java
106+
@Change(
107+
id = "optimize-user-queries",
108+
order = "0001",
109+
author = "performance-team",
110+
description = "Add composite index on user table to improve search performance"
111+
)
112+
```
113+
112114
## Required annotations
113115

114116
### `@TargetSystem` - System specification

‎docs/flamingock-library-config/transactions.md‎ renamed to ‎docs/changes/transactions.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Transactions
3-
sidebar_position: 40
3+
sidebar_position: 3
44
---
55

66
# Transactions
@@ -25,7 +25,7 @@ These systems support native transaction capabilities:
2525
**When `transactional = false`**:
2626
- Execution runs without transaction
2727
- **On failure**: Safety through compensation logic (@Rollback)
28-
- Useful for DDL operations or large bulk operations that exceed transaction limits
28+
- Useful for DDL operations or any operation that requires not participating in a transaction
2929

3030
### ⚡ Non-transactional target systems
3131
**Examples**: Kafka, S3, REST APIs, file systems, message queues

‎docs/overview/core-concepts.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ Systems that support ACID transactions, such as MongoDB 4.0+, PostgreSQL, MySQL,
6868
### Non-transactional target systems
6969
Systems like Kafka, S3, REST APIs, or file systems that don't support transactions. For these systems, Flamingock relies on explicit rollback methods and careful change design to maintain consistency. Recovery strategies become particularly important for handling failures in non-transactional contexts.
7070

71-
For implementation details, see the [Transactions](../flamingock-library-config/transactions.md) section.
71+
For implementation details, see the [Transactions](../changes/transactions.md) section.
7272

7373

7474
## Stages

‎docs/resources/faq.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ Flamingock's behavior depends on your recovery strategy configuration:
6161
This intelligent failure handling prevents silent data corruption and provides operational control.
6262

6363
**How can I ensure changes are transactional?**
64-
If your database supports transactions (e.g. MongoDB ≥ 4.0 in replica set), you can enable them using [Flamingock’s transaction config](../flamingock-library-config/transactions.md).
64+
If your database supports transactions (e.g. MongoDB ≥ 4.0 in replica set), you can enable them using [Flamingock’s transaction config](../changes/transactions.md).
6565

6666
**Should I implement the @Rollback method in transactional environments?**
6767

‎docs/target-systems/couchbase-target-system.md‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,46 @@
22
title: Couchbase
33
sidebar_position: 5
44
---
5+
import Tabs from '@theme/Tabs';
6+
import TabItem from '@theme/TabItem';
57

68
# Couchbase Target System
79

810
The Couchbase target system (`CouchbaseTargetSystem`) enables Flamingock to apply changes to Couchbase databases using the official Couchbase Java SDK. As a transactional target system, it supports automatic rollback through Couchbase's transaction capabilities.
911

12+
## Version Compatibility
13+
14+
| Component | Version Requirement |
15+
|-----------|-------------------|
16+
| Couchbase Java Client | 3.6.0+ |
17+
18+
Couchbase Java Client 3.6.0+ is required and must be included in your project dependencies.
19+
20+
## Installation
21+
22+
Add the Couchbase Java Client dependency to your project (version 3.6.0+ required):
23+
24+
<Tabs groupId="gradle_maven">
25+
<TabItem value="gradle" label="Gradle" default>
26+
```kotlin
27+
implementation("com.couchbase.client:java-client:3.6.0")
28+
```
29+
</TabItem>
30+
<TabItem value="maven" label="Maven">
31+
```xml
32+
<dependency>
33+
<groupId>com.couchbase.client</groupId>
34+
<artifactId>java-client</artifactId>
35+
<version>3.6.0</version> <!-- 3.6.0+ supported -->
36+
</dependency>
37+
```
38+
</TabItem>
39+
</Tabs>
40+
1041
## Basic setup
1142

43+
Configure the target system:
44+
1245
```java
1346
CouchbaseTargetSystem couchbaseTarget = new CouchbaseTargetSystem("user-database", cluster, bucket);
1447
```
@@ -71,7 +104,7 @@ This architecture ensures explicit target system configuration while providing f
71104

72105
For a Change to leverage Couchbase's transactional capabilities, it must use the `AttemptContext` parameter. Flamingock uses the injected `Cluster` and `Bucket` dependencies to create and manage this context's lifecycle - creating the transaction context before execution, committing on success, and rolling back on failure.
73106

74-
> For detailed information on transaction handling, see [Transactions](../flamingock-library-config/transactions.md).
107+
> For detailed information on transaction handling, see [Transactions](../changes/transactions.md).
75108
76109
```java
77110
@TargetSystem("user-database")

‎docs/target-systems/default-target-system.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22
title: Default (Non-transactional)
33
sidebar_position: 6
44
---
5+
import Tabs from '@theme/Tabs';
6+
import TabItem from '@theme/TabItem';
57

68
# Default Target System
79

@@ -21,8 +23,14 @@ DefaultTargetSystem is the fallback choice when there's no specialized target sy
2123

2224
**Common systems using DefaultTargetSystem:** Kafka Schema Registry, message queues, object storage (S3), REST APIs, file systems, cache systems, feature flags, search engines
2325

26+
## Installation
27+
28+
No specific dependencies are required for DefaultTargetSystem. You can add any dependencies needed for your specific use case.
29+
2430
## Basic setup
2531

32+
Configure the target system:
33+
2634
```java
2735
DefaultTargetSystem schemaRegistry = new DefaultTargetSystem("kafka-schema-registry");
2836
```

‎docs/target-systems/dynamodb-target-system.md‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,46 @@
22
title: DynamoDB
33
sidebar_position: 4
44
---
5+
import Tabs from '@theme/Tabs';
6+
import TabItem from '@theme/TabItem';
57

68
# DynamoDB Target System
79

810
The DynamoDB target system (`DynamoDBTargetSystem`) enables Flamingock to apply changes to Amazon DynamoDB using the AWS SDK for Java. As a transactional target system, it supports automatic rollback through DynamoDB's transaction capabilities with `TransactWriteItems`.
911

12+
## Version Compatibility
13+
14+
| Component | Version Requirement |
15+
|-----------|-------------------|
16+
| AWS SDK DynamoDB Enhanced | 2.12.0+ |
17+
18+
AWS SDK DynamoDB Enhanced 2.12.0+ is required and must be included in your project dependencies.
19+
20+
## Installation
21+
22+
Add the AWS SDK DynamoDB Enhanced dependency to your project (version 2.12.0+ required):
23+
24+
<Tabs groupId="gradle_maven">
25+
<TabItem value="gradle" label="Gradle" default>
26+
```kotlin
27+
implementation("software.amazon.awssdk:dynamodb-enhanced:2.12.0")
28+
```
29+
</TabItem>
30+
<TabItem value="maven" label="Maven">
31+
```xml
32+
<dependency>
33+
<groupId>software.amazon.awssdk</groupId>
34+
<artifactId>dynamodb-enhanced</artifactId>
35+
<version>2.12.0</version> <!-- 2.12.0+ supported -->
36+
</dependency>
37+
```
38+
</TabItem>
39+
</Tabs>
40+
1041
## Basic setup
1142

43+
Configure the target system:
44+
1245
```java
1346
DynamoDBTargetSystem dynamoTarget = new DynamoDBTargetSystem("inventory-database", dynamoDbClient);
1447
```
@@ -68,7 +101,7 @@ This architecture ensures explicit target system configuration while providing f
68101

69102
For a Change to leverage DynamoDB's transactional capabilities, it must use the `TransactWriteItemsEnhancedRequest.Builder` parameter. Flamingock uses the injected `DynamoDbClient` dependency to create and manage this builder's lifecycle - creating it before execution and executing the transaction with all operations on success.
70103

71-
> For detailed information on transaction handling, see [Transactions](../flamingock-library-config/transactions.md).
104+
> For detailed information on transaction handling, see [Transactions](../changes/transactions.md).
72105
73106
```java
74107
@TargetSystem("inventory-database")

‎docs/target-systems/introduction.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ Every change is tied to a named target system, avoiding ambiguity and enabling c
2727

2828
This distinction is built into the target system definition.
2929

30-
> For detailed information on transaction handling, see [Transactions](../flamingock-library-config/transactions.md).
30+
> For detailed information on transaction handling, see [Transactions](../changes/transactions.md).
3131
3232
### Dependency isolation
3333

‎docs/target-systems/mongodb-springdata-target-system.md‎

Lines changed: 29 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22
title: MongoDB Spring Data
33
sidebar_position: 2
44
---
5+
import Tabs from '@theme/Tabs';
6+
import TabItem from '@theme/TabItem';
57

68
# MongoDB Spring Data Target System
79

@@ -11,12 +13,36 @@ The MongoDB Spring Data target system (`MongoSpringDataTargetSystem`) enables Fl
1113

1214
| Component | Version Requirement |
1315
|-----------|-------------------|
14-
| Spring Data MongoDB | 3.1.x+ |
16+
| Spring Data MongoDB | 3.1.x - 4.x |
17+
18+
Spring Data MongoDB versions from 3.1.x through 4.x are supported. Version 3.1.x+ is included in Spring Boot 2.4.3+.
19+
20+
## Installation
21+
22+
Add the Spring Data MongoDB dependency to your project (versions 3.1.x - 4.x supported):
23+
24+
<Tabs groupId="gradle_maven">
25+
<TabItem value="gradle" label="Gradle" default>
26+
```kotlin
27+
implementation("org.springframework.data:spring-data-mongodb:3.1.0")
28+
```
29+
</TabItem>
30+
<TabItem value="maven" label="Maven">
31+
```xml
32+
<dependency>
33+
<groupId>org.springframework.data</groupId>
34+
<artifactId>spring-data-mongodb</artifactId>
35+
<version>3.1.0</version> <!-- 3.1.x - 4.x supported -->
36+
</dependency>
37+
```
38+
</TabItem>
39+
</Tabs>
1540

16-
Spring Data MongoDB 3.1.x+ is included in Spring Boot 2.4.3+.
1741

1842
## Basic setup
1943

44+
Configure the target system:
45+
2046
```java
2147
MongoSpringDataTargetSystem mongoTarget = new MongoSpringDataTargetSystem("user-database", mongoTemplate);
2248
```
@@ -91,7 +117,7 @@ This architecture ensures explicit target system configuration while providing f
91117

92118
Spring Data MongoDB target system integrates with Spring's transaction management. When a Change is marked as transactional (the default), Flamingock uses the injected `MongoTemplate` dependency to handle transaction operations through Spring's infrastructure.
93119

94-
> For detailed information on transaction handling, see [Transactions](../flamingock-library-config/transactions.md).
120+
> For detailed information on transaction handling, see [Transactions](../changes/transactions.md).
95121
96122
```java
97123
@TargetSystem("user-database")

‎docs/target-systems/mongodb-target-system.md‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22
title: MongoDB Sync
33
sidebar_position: 1
44
---
5+
import Tabs from '@theme/Tabs';
6+
import TabItem from '@theme/TabItem';
57

68
# MongoDB Sync Target System
79

@@ -15,8 +17,31 @@ The MongoDB Sync target system (`MongoSyncTargetSystem`) enables Flamingock to a
1517

1618
MongoDB 4.0+ is required for transaction support.
1719

20+
## Installation
21+
22+
Add the MongoDB Java sync driver dependency to your project (version 4.0.0+ required):
23+
24+
<Tabs groupId="gradle_maven">
25+
<TabItem value="gradle" label="Gradle" default>
26+
```kotlin
27+
implementation("org.mongodb:mongodb-driver-sync:4.0.0")
28+
```
29+
</TabItem>
30+
<TabItem value="maven" label="Maven">
31+
```xml
32+
<dependency>
33+
<groupId>org.mongodb</groupId>
34+
<artifactId>mongodb-driver-sync</artifactId>
35+
<version>4.0.0</version> <!-- 4.0.0+ supported -->
36+
</dependency>
37+
```
38+
</TabItem>
39+
</Tabs>
40+
1841
## Basic setup
1942

43+
Configure the target system:
44+
2045
```java
2146
MongoSyncTargetSystem mongoTarget = new MongoSyncTargetSystem("user-database", mongoClient, "userDb");
2247
```
@@ -95,7 +120,7 @@ This architecture ensures explicit target system configuration while providing f
95120

96121
For a Change to leverage MongoDB's transactional capabilities, it must use the `ClientSession` parameter. Flamingock uses the injected `MongoClient` and `MongoDatabase` dependencies to create and manage this session's lifecycle - starting the transaction before execution, committing on success, and rolling back on failure.
97122

98-
> For detailed information on transaction handling, see [Transactions](../flamingock-library-config/transactions.md).
123+
> For detailed information on transaction handling, see [Transactions](../changes/transactions.md).
99124
100125
```java
101126
@TargetSystem("user-database")

0 commit comments

Comments
 (0)