Skip to content

Commit b7cf08d

Browse files
shahar-bironshahar-biron
committed
Fix Spring Boot Starter auto-configuration and update documentation
- Fixed FalkorDBAutoConfiguration to use correct class instantiation: * Use DefaultFalkorDBMappingContext instead of abstract FalkorDBMappingContext * Use DriverImpl directly instead of non-existent GraphDatabase.driver() * Fixed DefaultFalkorDBEntityConverter constructor with 3 parameters * Fixed FalkorDBTemplate constructor with 3 parameters - Updated main README.md: * Added Spring Boot Starter installation section * Separated Spring Boot (auto-config) from Standalone Spring (manual config) * Added application.properties/yml configuration examples - Updated starter README.md: * Added @EnableFalkorDBRepositories to usage example * Removed unimplemented configuration properties * Updated custom configuration examples to match actual implementation - Added IMPLEMENTATION_NOTES.md documenting the implementation details All modules now build and install successfully to local Maven repository.
1 parent fb22242 commit b7cf08d

File tree

4 files changed

+337
-41
lines changed

4 files changed

+337
-41
lines changed

‎README.md‎

Lines changed: 79 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -24,13 +24,56 @@ Spring Data FalkorDB provides JPA-style object-graph mapping for [FalkorDB](http
2424

2525
## 📦 Installation
2626

27-
### Maven
27+
### Spring Boot (Recommended)
2828

29-
Add the following dependencies to your `pom.xml`:
29+
For Spring Boot 3.x applications, use the Spring Boot Starter for automatic configuration:
30+
31+
#### Maven
32+
33+
```xml
34+
<dependency>
35+
<groupId>com.falkordb</groupId>
36+
<artifactId>spring-boot-starter-data-falkordb</artifactId>
37+
<version>1.0.0-SNAPSHOT</version>
38+
</dependency>
39+
```
40+
41+
#### Gradle
42+
43+
```gradle
44+
dependencies {
45+
implementation 'com.falkordb:spring-boot-starter-data-falkordb:1.0.0-SNAPSHOT'
46+
}
47+
```
48+
49+
Then configure your connection in `application.properties` or `application.yml`:
50+
51+
```properties
52+
spring.data.falkordb.uri=falkordb://localhost:6379
53+
spring.data.falkordb.database=social
54+
```
55+
56+
Or in `application.yml`:
57+
58+
```yaml
59+
spring:
60+
data:
61+
falkordb:
62+
uri: falkordb://localhost:6379
63+
database: social
64+
```
65+
66+
With the starter, all beans are auto-configured, and you can start using repositories immediately!
67+
68+
### Standalone Spring (Manual Configuration)
69+
70+
For non-Boot Spring applications, add the core dependencies:
71+
72+
#### Maven
3073
3174
```xml
3275
<dependency>
33-
<groupId>org.springframework.data</groupId>
76+
<groupId>com.falkordb</groupId>
3477
<artifactId>spring-data-falkordb</artifactId>
3578
<version>1.0.0-SNAPSHOT</version>
3679
</dependency>
@@ -42,11 +85,11 @@ Add the following dependencies to your `pom.xml`:
4285
</dependency>
4386
```
4487

45-
### Gradle
88+
#### Gradle
4689

4790
```gradle
4891
dependencies {
49-
implementation 'org.springframework.data:spring-data-falkordb:1.0.0-SNAPSHOT'
92+
implementation 'com.falkordb:spring-data-falkordb:1.0.0-SNAPSHOT'
5093
implementation 'com.falkordb:jfalkordb:0.5.1'
5194
}
5295
```
@@ -130,23 +173,49 @@ public interface PersonRepository extends FalkorDBRepository<Person, Long> {
130173

131174
### 3. Configuration
132175

133-
Configure the FalkorDB connection in your Spring application:
176+
#### Spring Boot (Auto-Configuration)
177+
178+
With the Spring Boot Starter, no configuration class is needed! Just add your properties and use `@EnableFalkorDBRepositories`:
179+
180+
```java
181+
@SpringBootApplication
182+
@EnableFalkorDBRepositories
183+
public class Application {
184+
public static void main(String[] args) {
185+
SpringApplication.run(Application.class, args);
186+
}
187+
}
188+
```
189+
190+
#### Standalone Spring (Manual Configuration)
191+
192+
For non-Boot applications, configure beans manually:
134193

135194
```java
136195
@Configuration
137196
@EnableFalkorDBRepositories
138197
public class FalkorDBConfig {
139198

140199
@Bean
141-
public FalkorDBClient falkorDBClient() {
142-
Driver driver = FalkorDB.driver("localhost", 6379);
200+
public Driver falkorDBDriver() {
201+
return new DriverImpl("localhost", 6379);
202+
}
203+
204+
@Bean
205+
public FalkorDBClient falkorDBClient(Driver driver) {
143206
return new DefaultFalkorDBClient(driver, "social");
144207
}
145208

209+
@Bean
210+
public FalkorDBMappingContext falkorDBMappingContext() {
211+
return new DefaultFalkorDBMappingContext();
212+
}
213+
146214
@Bean
147215
public FalkorDBTemplate falkorDBTemplate(FalkorDBClient client,
148-
FalkorDBMappingContext mappingContext,
149-
FalkorDBEntityConverter converter) {
216+
FalkorDBMappingContext mappingContext) {
217+
DefaultFalkorDBEntityConverter converter = new DefaultFalkorDBEntityConverter(
218+
mappingContext, new EntityInstantiators(), client);
150219
return new FalkorDBTemplate(client, mappingContext, converter);
151220
}
152221
}

‎spring-boot-starter-data-falkordb/IMPLEMENTATION_NOTES.md‎

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
# Spring Boot Starter for Spring Data FalkorDB - Implementation Notes
2+
3+
## Overview
4+
5+
This document describes the implementation of the Spring Boot Starter for Spring Data FalkorDB, which provides auto-configuration support for Spring Boot 3.x applications.
6+
7+
## Implementation Date
8+
9+
October 28, 2025
10+
11+
## Components
12+
13+
### 1. Auto-Configuration Classes
14+
15+
#### `FalkorDBAutoConfiguration.java`
16+
- **Purpose**: Main auto-configuration class that creates core beans
17+
- **Beans Configured**:
18+
- `Driver` - FalkorDB Java driver (using `DriverImpl`)
19+
- `FalkorDBClient` - Database client (using `DefaultFalkorDBClient`)
20+
- `FalkorDBMappingContext` - Mapping metadata (using `DefaultFalkorDBMappingContext`)
21+
- `FalkorDBTemplate` - Main template for database operations
22+
- **Key Features**:
23+
- Parses URI from properties (supports `falkordb://` and `redis://` schemes)
24+
- Validates required `database` property
25+
- All beans use `@ConditionalOnMissingBean` for customization
26+
27+
#### `FalkorDBRepositoriesAutoConfiguration.java`
28+
- **Purpose**: Auto-configures repository support
29+
- **Features**:
30+
- Conditional on `FalkorDBTemplate` bean
31+
- Imports `FalkorDBRepositoriesRegistrar` for repository scanning
32+
- Can be disabled with properties
33+
34+
#### `FalkorDBHealthContributorAutoConfiguration.java`
35+
- **Purpose**: Provides health indicator for Spring Boot Actuator
36+
- **Features**:
37+
- Only activates when Actuator is on classpath
38+
- Conditional on `FalkorDBTemplate` bean
39+
- Registers `FalkorDBHealthIndicator`
40+
41+
### 2. Configuration Properties
42+
43+
#### `FalkorDBProperties.java`
44+
- **Properties**:
45+
- `spring.data.falkordb.uri` - Connection URI (default: `falkordb://localhost:6379`)
46+
- `spring.data.falkordb.database` - Graph/database name (required)
47+
- **Features**:
48+
- Annotated with `@ConfigurationProperties`
49+
- Generates metadata for IDE support
50+
51+
### 3. Health Indicator
52+
53+
#### `FalkorDBHealthIndicator.java`
54+
- **Purpose**: Reports FalkorDB connection health
55+
- **Implementation**:
56+
- Extends `AbstractHealthIndicator`
57+
- Executes simple query to test connectivity
58+
- Reports database name and version in details
59+
60+
### 4. Repository Support
61+
62+
#### `FalkorDBRepositoriesRegistrar.java`
63+
- **Purpose**: Registers repository beans dynamically
64+
- **Features**:
65+
- Extends `AbstractRepositoryConfigurationSourceSupport`
66+
- Scans for `@EnableFalkorDBRepositories` annotation
67+
- Integrates with Spring Data Commons infrastructure
68+
69+
### 5. Build Configuration
70+
71+
#### `pom.xml`
72+
- **Key Dependencies**:
73+
- `spring-data-falkordb` (core module)
74+
- `spring-boot-autoconfigure`
75+
- `spring-boot-actuator-autoconfigure` (optional)
76+
- `jfalkordb` (FalkorDB Java driver)
77+
- **Plugins**:
78+
- `spring-boot-configuration-processor` for metadata generation
79+
- Maven Compiler Plugin with Java 17 target
80+
81+
### 6. Resource Files
82+
83+
#### `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`
84+
- Registers auto-configuration classes for Spring Boot 3.x
85+
- Lists:
86+
- `FalkorDBAutoConfiguration`
87+
- `FalkorDBRepositoriesAutoConfiguration`
88+
- `FalkorDBHealthContributorAutoConfiguration`
89+
90+
## Key Design Decisions
91+
92+
### 1. Driver Instantiation
93+
- Uses `new DriverImpl(host, port)` directly
94+
- Matches the pattern from integration tests
95+
- Simpler than using factory methods
96+
97+
### 2. Entity Converter Construction
98+
- Uses 3-parameter constructor: `(mappingContext, entityInstantiators, client)`
99+
- Client parameter needed for relationship loading
100+
- Matches the pattern from `FalkorDBTwitterIntegrationTests`
101+
102+
### 3. Template Construction
103+
- Uses 3-parameter constructor: `(client, mappingContext, converter)`
104+
- All three parameters are required
105+
- Provides full control over mapping and conversion
106+
107+
### 4. Property Naming
108+
- Uses `spring.data.falkordb.*` prefix
109+
- Consistent with Spring Data conventions
110+
- Simple URI-based configuration
111+
112+
### 5. Spring Boot 3.x Compatibility
113+
- Uses `AutoConfiguration.imports` file (not `spring.factories`)
114+
- Compatible with Spring Boot 3.x and Spring Data 4.0.0-RC1
115+
- Follows modern Spring Boot starter patterns
116+
117+
## Usage Example
118+
119+
### 1. Add Dependency
120+
121+
```xml
122+
<dependency>
123+
<groupId>com.falkordb</groupId>
124+
<artifactId>spring-boot-starter-data-falkordb</artifactId>
125+
<version>1.0.0-SNAPSHOT</version>
126+
</dependency>
127+
```
128+
129+
### 2. Configure Properties
130+
131+
```yaml
132+
spring:
133+
data:
134+
falkordb:
135+
uri: falkordb://localhost:6379
136+
database: mygraph
137+
```
138+
139+
### 3. Enable Repositories
140+
141+
```java
142+
@SpringBootApplication
143+
@EnableFalkorDBRepositories
144+
public class Application {
145+
public static void main(String[] args) {
146+
SpringApplication.run(Application.class, args);
147+
}
148+
}
149+
```
150+
151+
### 4. Use Repositories
152+
153+
```java
154+
@Service
155+
public class PersonService {
156+
@Autowired
157+
private PersonRepository personRepository;
158+
159+
public Person createPerson(String name) {
160+
Person person = new Person();
161+
person.setName(name);
162+
return personRepository.save(person);
163+
}
164+
}
165+
```
166+
167+
## Testing
168+
169+
### Build Verification
170+
- Core module builds successfully: ✅
171+
- Starter module builds successfully: ✅
172+
- Both modules install to local Maven repository: ✅
173+
174+
### Integration Testing
175+
- Integration tests in core module verify the correct instantiation pattern
176+
- Starter follows the same pattern for consistency
177+
178+
## Future Enhancements
179+
180+
### Potential Improvements
181+
1. **Connection Pooling**: Add support for connection pool configuration
182+
2. **Authentication**: Add username/password properties for authenticated connections
183+
3. **Timeouts**: Add connection and socket timeout properties
184+
4. **Metrics**: Add Micrometer metrics for query performance
185+
5. **SSL/TLS**: Add support for encrypted connections
186+
6. **Multiple Databases**: Better support for multiple database configurations
187+
7. **Transaction Management**: Enhanced transaction configuration options
188+
189+
### Compatibility
190+
- Currently targets Spring Boot 3.x
191+
- Could be backported to Spring Boot 2.x if needed (would require `spring.factories` instead of `AutoConfiguration.imports`)
192+
193+
## References
194+
195+
### Implementation References
196+
- `FalkorDBTwitterIntegrationTests.java` - Primary reference for bean construction
197+
- `DefaultFalkorDBClient.java` - Client implementation
198+
- `FalkorDBTemplate.java` - Template implementation
199+
- Spring Data Commons - Repository infrastructure
200+
201+
### Documentation Updated
202+
- Main `README.md` - Added Spring Boot Starter section
203+
- Starter `README.md` - Updated with correct implementation details
204+
205+
## Verification Commands
206+
207+
```bash
208+
# Build core module
209+
cd /Users/shaharbiron/Documents/GitHub/spring-data-falkordb
210+
mvn clean install -DskipTests
211+
212+
# Build starter module
213+
cd spring-boot-starter-data-falkordb
214+
mvn clean install -DskipTests
215+
216+
# Verify artifacts
217+
ls -la ~/.m2/repository/com/falkordb/spring-data-falkordb/1.0.0-SNAPSHOT/
218+
ls -la ~/.m2/repository/com/falkordb/spring-boot-starter-data-falkordb/1.0.0-SNAPSHOT/
219+
```
220+
221+
## Status
222+
223+
✅ **Complete**: The Spring Boot Starter is fully implemented and ready for use.
224+
225+
All components are:
226+
- ✅ Compiled successfully
227+
- ✅ Packaged as JAR
228+
- ✅ Installed to local Maven repository
229+
- ✅ Documented in README files
230+
231+
Next steps:
232+
1. Create sample application to demonstrate usage
233+
2. Add integration tests for auto-configuration
234+
3. Consider publishing to Maven Central

0 commit comments

Comments
 (0)