base version
This commit is contained in:
+39
@@ -0,0 +1,39 @@
|
||||
target/
|
||||
!.mvn/wrapper/maven-wrapper.jar
|
||||
!**/src/main/**/target/
|
||||
!**/src/test/**/target/
|
||||
.kotlin
|
||||
|
||||
### IntelliJ IDEA ###
|
||||
.idea/modules.xml
|
||||
.idea/jarRepositories.xml
|
||||
.idea/compiler.xml
|
||||
.idea/libraries/
|
||||
*.iws
|
||||
*.iml
|
||||
*.ipr
|
||||
|
||||
### Eclipse ###
|
||||
.apt_generated
|
||||
.classpath
|
||||
.factorypath
|
||||
.project
|
||||
.settings
|
||||
.springBeans
|
||||
.sts4-cache
|
||||
|
||||
### NetBeans ###
|
||||
/nbproject/private/
|
||||
/nbbuild/
|
||||
/dist/
|
||||
/nbdist/
|
||||
/.nb-gradle/
|
||||
build/
|
||||
!**/src/main/**/build/
|
||||
!**/src/test/**/build/
|
||||
|
||||
### VS Code ###
|
||||
.vscode/
|
||||
|
||||
### Mac OS ###
|
||||
.DS_Store
|
||||
Generated
+10
@@ -0,0 +1,10 @@
|
||||
# Default ignored files
|
||||
/shelf/
|
||||
/workspace.xml
|
||||
# Editor-based HTTP Client requests
|
||||
/httpRequests/
|
||||
# Ignored default folder with query files
|
||||
/queries/
|
||||
# Datasource local storage ignored files
|
||||
/dataSources/
|
||||
/dataSources.local.xml
|
||||
Generated
+13
@@ -0,0 +1,13 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project version="4">
|
||||
<component name="Encoding">
|
||||
<file url="file://$PROJECT_DIR$/clotho-core/src/main/java" charset="UTF-8" />
|
||||
<file url="file://$PROJECT_DIR$/clotho-core/src/main/resources" charset="UTF-8" />
|
||||
<file url="file://$PROJECT_DIR$/clotho-dev-app/src/main/java" charset="UTF-8" />
|
||||
<file url="file://$PROJECT_DIR$/clotho-dev-app/src/main/resources" charset="UTF-8" />
|
||||
<file url="file://$PROJECT_DIR$/clotho-spring-boot-starter/src/main/java" charset="UTF-8" />
|
||||
<file url="file://$PROJECT_DIR$/clotho-spring-boot-starter/src/main/resources" charset="UTF-8" />
|
||||
<file url="file://$PROJECT_DIR$/src/main/java" charset="UTF-8" />
|
||||
<file url="file://$PROJECT_DIR$/src/main/resources" charset="UTF-8" />
|
||||
</component>
|
||||
</project>
|
||||
Generated
+14
@@ -0,0 +1,14 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project version="4">
|
||||
<component name="ExternalStorageConfigurationManager" enabled="true" />
|
||||
<component name="MavenProjectsManager">
|
||||
<option name="originalFiles">
|
||||
<list>
|
||||
<option value="$PROJECT_DIR$/pom.xml" />
|
||||
</list>
|
||||
</option>
|
||||
</component>
|
||||
<component name="ProjectRootManager" version="2" languageLevel="JDK_21" default="true" project-jdk-name="21" project-jdk-type="JavaSDK">
|
||||
<output url="file://$PROJECT_DIR$/out" />
|
||||
</component>
|
||||
</project>
|
||||
Generated
+6
@@ -0,0 +1,6 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project version="4">
|
||||
<component name="VcsDirectoryMappings">
|
||||
<mapping directory="$PROJECT_DIR$" vcs="Git" />
|
||||
</component>
|
||||
</project>
|
||||
@@ -0,0 +1,241 @@
|
||||
# Clotho
|
||||
|
||||
A Java OGM (Object-Graph Mapper) for ArcadeDB, built on Apache TinkerPop/Gremlin.
|
||||
|
||||
Clotho is not a 1:1 node-to-object mapper. A "Clotho object" is a subgraph — a root vertex
|
||||
plus a declared set of edges and adjacent vertices spanning any number of hops. Complex graph
|
||||
traversals and analytics remain the developer's responsibility, written via `@Query` on
|
||||
repository interfaces. Clotho handles bounded object loading and persistence.
|
||||
|
||||
---
|
||||
|
||||
## Module Structure
|
||||
|
||||
```
|
||||
clotho/
|
||||
clotho-core/ # Zero Spring dependency. All mapping logic.
|
||||
clotho-spring-boot-starter/ # Autoconfigure, @Transactional bridge, Spring beans.
|
||||
clotho-dev-app/ # Minimal Spring Boot app for development testing against
|
||||
# a live ArcadeDB instance. Not a production artifact.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Three Tiers of Graph-to-Java Mapping
|
||||
|
||||
### 1. Vertex Type
|
||||
A single ArcadeDB vertex mapped to a Java class. Must extend `ClothoVertex`.
|
||||
|
||||
```java
|
||||
@VertexType("Employee")
|
||||
public class Employee extends ClothoVertex {
|
||||
@Property("name") String name;
|
||||
|
||||
@Include @Via("HAS_ADDRESS")
|
||||
Address address; // eagerly loaded as part of this object's boundary
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Edge Type
|
||||
A single ArcadeDB edge mapped to a Java class. Must extend `ClothoEdge`.
|
||||
|
||||
```java
|
||||
@EdgeType("WORKS_AT")
|
||||
public class WorksAt extends ClothoEdge {
|
||||
@OutVertex Employee employee;
|
||||
@InVertex Company company; // omit @InVertex for edge-only inclusion
|
||||
LocalDate startDate;
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Subgraph Type
|
||||
A composite Java class assembled from multiple vertices and edges via a `@Query` traversal.
|
||||
Has no ARID. Does NOT extend `ClothoVertex` or `ClothoEdge`.
|
||||
`save()` delegates to all component `ClothoEntity` fields individually.
|
||||
|
||||
```java
|
||||
@SubgraphType
|
||||
public class EmployeeProfile {
|
||||
Employee employee; // field name matches Gremlin as("employee")
|
||||
Manager manager;
|
||||
@Alias("dept") Department department;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Technology Stack
|
||||
|
||||
| Concern | Library |
|
||||
|---|---|
|
||||
| Language | Java 21 |
|
||||
| Build | Maven (multi-module) |
|
||||
| Graph connection | Apache TinkerPop 3.x — `DriverRemoteConnection` over WebSocket |
|
||||
| Null safety | JSpecify (`org.jspecify.annotations`) |
|
||||
| Boilerplate reduction | Lombok |
|
||||
| Testing | JUnit 5 |
|
||||
| Spring integration | Spring Boot 3.x autoconfigure |
|
||||
|
||||
---
|
||||
|
||||
## Key Design Decisions
|
||||
|
||||
- **Schema-first**: Clotho assumes the ArcadeDB schema already exists. No DDL generation.
|
||||
The developer manages the schema (e.g., using a Flyway-based migration tool).
|
||||
- **Optional lazy loading**: `@Include` fields default to `FetchType.EAGER` (always loaded).
|
||||
Declare `@Include(fetchType = FetchType.LAZY)` to skip a field during `populate()`. Lazy
|
||||
fields remain `null`/empty until the developer calls `session.loadField(vertex, "fieldName")`
|
||||
explicitly. No proxy or bytecode enhancement is used.
|
||||
- **Single-query boundary loading**: All `@Include` fields for a vertex are fetched in a single
|
||||
Gremlin `project()` traversal. This eliminates N+1 queries per object boundary and prevents
|
||||
race conditions from sequential round-trips. For nested boundaries, each vertex gets its own
|
||||
single-project query (one query per vertex, not one per field).
|
||||
- **Dirty tracking**: `ClothoEntity` tracks which fields were mutated via `notifyFieldChanged()`
|
||||
(called from manual setters). On save, `NEW` entities write all `@Property` fields; `MANAGED`
|
||||
entities write only dirty fields and skip the update entirely if nothing changed.
|
||||
`ClothoSession.close()` auto-saves all MANAGED entities (vertices and edges) that carry dirty fields.
|
||||
- **Optimistic locking**: Declare `@Version Long version` on an entity field. Clotho reads
|
||||
ArcadeDB's built-in `@version` property on load and includes a `.has("@version", version)`
|
||||
filter on every update. A version mismatch throws `OptimisticLockException`. Both vertices
|
||||
and edges support `@Version`.
|
||||
- **Edges are first-class citizens**: `ClothoEdge` entities participate in the same
|
||||
`EntityState` lifecycle, dirty tracking, `@Version` OCC, identity map caching, and
|
||||
auto-save-on-close as `ClothoVertex` entities. Edges can be loaded by ID via
|
||||
`session.load(EdgeType.class, id)`.
|
||||
- **Result mapping**: Clotho always instantiates the most specific registered class matching
|
||||
the vertex/edge label. Declared return types are upper bounds only.
|
||||
- **Inheritance**: Java class hierarchy is the primary mechanism. `additionalParents` on
|
||||
`@VertexType` handles ArcadeDB's multi-parent (diamond) inheritance where Java's single
|
||||
inheritance is insufficient.
|
||||
- **No automatic deletion**: Removing an element from an `@Include` collection does not
|
||||
delete it from the graph. Call `session.delete()` explicitly.
|
||||
|
||||
See `docs/` for detailed specifications.
|
||||
|
||||
---
|
||||
|
||||
## Package Structure
|
||||
|
||||
```
|
||||
com.binarygolem.clotho
|
||||
.core
|
||||
.model # ClothoEntity, ClothoVertex, ClothoEdge, ARID
|
||||
.annotation # All annotations (@VertexType, @EdgeType, @SubgraphType, etc.)
|
||||
.session # ClothoSession, ClothoSessionFactory
|
||||
.registry # TypeRegistry
|
||||
.mapping # ObjectMapper, SubgraphLoader, SubgraphPersistor, SubgraphTypeAssembler
|
||||
.query # QueryExecutor, @Query proxy infrastructure
|
||||
.exception # UnknownTypeException, ClothoException hierarchy
|
||||
.spring
|
||||
.config # ClothoAutoConfiguration
|
||||
.tx # Transaction bridge
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Coding Conventions
|
||||
|
||||
### Nullability
|
||||
Every parameter, return type, and field must carry `@NonNull` or `@Nullable` from JSpecify.
|
||||
Default assumption is `@NonNull`; annotate only what can be null.
|
||||
|
||||
```java
|
||||
import org.jspecify.annotations.NonNull;
|
||||
import org.jspecify.annotations.Nullable;
|
||||
```
|
||||
|
||||
### Lombok
|
||||
Use Lombok where it reduces noise without obscuring intent:
|
||||
- `@Getter` on domain classes
|
||||
- `@Builder` on factory/config classes
|
||||
- `@RequiredArgsConstructor` / `@AllArgsConstructor` on service classes
|
||||
- `@Value` is NOT compatible with Clotho-managed domain objects (requires mutable fields)
|
||||
|
||||
**`@Setter` restriction on entity classes:** Do NOT use Lombok `@Setter` on any field
|
||||
annotated with `@Property`, `@Include`, `@OutVertex`, `@InVertex`, or `@Version` on a
|
||||
`ClothoVertex` or `ClothoEdge` subclass. Write a manual setter that calls
|
||||
`notifyFieldChanged(fieldName)` so the session can track the change:
|
||||
|
||||
```java
|
||||
// Correct
|
||||
public void setName(String name) {
|
||||
this.name = name;
|
||||
notifyFieldChanged("name");
|
||||
}
|
||||
|
||||
// Wrong — dirty tracking does not fire
|
||||
@Setter String name;
|
||||
```
|
||||
|
||||
Lombok `@Setter` remains allowed only for framework-managed fields (`id`, `outVertexId`,
|
||||
`inVertexId`) because Clotho sets those itself and they are not part of dirty tracking.
|
||||
|
||||
### Comments
|
||||
Write no comments unless the WHY is non-obvious. One line maximum.
|
||||
Never write doc comments that restate what the method name already says.
|
||||
|
||||
### Naming
|
||||
- ArcadeDB type names (labels) use the `@VertexType` / `@EdgeType` annotation value.
|
||||
Class names need not match label names exactly.
|
||||
- Edge label constants: define as `public static final String LABEL = "WORKS_AT"` on the
|
||||
edge class to avoid magic strings at call sites.
|
||||
|
||||
---
|
||||
|
||||
## Development Setup
|
||||
|
||||
### Prerequisites
|
||||
- Java 21
|
||||
- Maven 3.9+
|
||||
- A running ArcadeDB instance (for integration tests and `clotho-dev-app`)
|
||||
|
||||
### Build
|
||||
```bash
|
||||
mvn clean install
|
||||
```
|
||||
|
||||
### Run `clotho-dev-app`
|
||||
```bash
|
||||
mvn -pl clotho-dev-app spring-boot:run
|
||||
```
|
||||
|
||||
### Connection (local ArcadeDB default)
|
||||
```properties
|
||||
clotho.gremlin.url=ws://localhost:8182/gremlin
|
||||
clotho.gremlin.username=root
|
||||
clotho.gremlin.password=playwithdata
|
||||
clotho.gremlin.traversal-source=g
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Status
|
||||
|
||||
| Phase | Description | Status |
|
||||
|---|---|---|
|
||||
| 1 | Project housekeeping — parent POM, module scaffold, package rename | Done |
|
||||
| 2 | Base types and annotations — `ARID`, `ClothoEntity`, `ClothoVertex`, `ClothoEdge`, all annotations, exception hierarchy | Done |
|
||||
| 3 | `clotho-dev-app` — Gremlin connection wiring, smoke test against live ArcadeDB | Done |
|
||||
| 4 | `TypeRegistry` — classpath scan, label→class map, hierarchy inference, `additionalParents`/`parentLabel` | Done |
|
||||
| 5 | `ElementMapper` — Gremlin `Vertex`/`Edge` → Java; always most-specific class by label | Done |
|
||||
| 6 | `SubgraphLoader` — traverse `@Include`/`@Via`, multi-hop, cycle detection, edge-only; `SubgraphTypeAssembler` | Done |
|
||||
| 7 | `SubgraphPersistor` — upsert, `@version` optimistic locking, cascade through boundary | Done |
|
||||
| 8 | `ClothoSession` / `ClothoSessionFactory` — identity map, `load`/`save`/`delete`/`query`, connection lifecycle | Done |
|
||||
| 9 | `ClothoRepository<T>` — abstract base class; `g()`, `execute()`, `findAll()`, `findById()`, etc.; dropped `@Query`/`@Param` | Done |
|
||||
| 10 | Spring Boot Starter — `ClothoAutoConfiguration`, `ClothoProperties`, `@ClothoRepository` bean scanning | Done |
|
||||
| 11 | Dirty tracking (`notifyFieldChanged`, `EntityState`), `SessionContext`, single-query `project()` loading, `@Version` OCC, `FetchType.LAZY`, `FieldMetadataCache`, expanded type coercion, `populateAll()` batch loading, auto-save on close, edge first-class parity | Done |
|
||||
| 12 | Transaction management — `openTransactionalSession()`, borrow counter, `rollback()`, `getCurrentSession()`, `ClothoTransactionManager`, Spring `@Transactional` bridge, `ClothoAutoConfiguration` tx bean | Done |
|
||||
|
||||
---
|
||||
|
||||
## Documentation Index
|
||||
|
||||
| Document | Contents |
|
||||
|---|---|
|
||||
| `docs/TYPE_SYSTEM.md` | `ClothoEntity` hierarchy, `@VertexType`, `@EdgeType`, `@SubgraphType`, inheritance, diamond inheritance, result mapping rule |
|
||||
| `docs/OBJECT_BOUNDARY.md` | `@Include`/`@Via`, multi-hop traversal, edge-only inclusion, cycle detection |
|
||||
| `docs/ANNOTATIONS.md` | Complete annotation reference with all attributes and examples |
|
||||
| `docs/QUERY_MODEL.md` | `@Query`, `@ClothoRepository`, `@SubgraphType` assembly, result mapping, parameter binding |
|
||||
| `docs/SPRING_INTEGRATION.md` | Autoconfigure, `@Transactional`, `application.properties` reference |
|
||||
| `docs/ARCHITECTURE.md` | Module breakdown, key components, data flow, session lifecycle |
|
||||
| `docs/TRANSACTIONS.md` | Transactional sessions, Spring `@Transactional`, nested propagation, `@Version` interaction, limitations |
|
||||
@@ -0,0 +1,61 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project xmlns="http://maven.apache.org/POM/4.0.0"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
|
||||
http://maven.apache.org/xsd/maven-4.0.0.xsd">
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
||||
<parent>
|
||||
<groupId>com.binarygolem.clotho</groupId>
|
||||
<artifactId>clotho-parent</artifactId>
|
||||
<version>0.1.0-SNAPSHOT</version>
|
||||
</parent>
|
||||
|
||||
<artifactId>clotho-core</artifactId>
|
||||
<name>Clotho Core</name>
|
||||
<description>Core OGM logic — zero Spring dependency</description>
|
||||
|
||||
<dependencies>
|
||||
|
||||
<!-- TinkerPop remote Gremlin client -->
|
||||
<dependency>
|
||||
<groupId>org.apache.tinkerpop</groupId>
|
||||
<artifactId>gremlin-driver</artifactId>
|
||||
</dependency>
|
||||
|
||||
<!-- Classpath scanning for TypeRegistry -->
|
||||
<dependency>
|
||||
<groupId>io.github.classgraph</groupId>
|
||||
<artifactId>classgraph</artifactId>
|
||||
</dependency>
|
||||
|
||||
<!-- Lombok (annotation processor only — not included in output jar) -->
|
||||
<dependency>
|
||||
<groupId>org.projectlombok</groupId>
|
||||
<artifactId>lombok</artifactId>
|
||||
<scope>provided</scope>
|
||||
</dependency>
|
||||
|
||||
<!-- Null annotations (compile + runtime for reflection-based checks) -->
|
||||
<dependency>
|
||||
<groupId>org.jspecify</groupId>
|
||||
<artifactId>jspecify</artifactId>
|
||||
</dependency>
|
||||
|
||||
<!-- Test: JUnit 5 -->
|
||||
<dependency>
|
||||
<groupId>org.junit.jupiter</groupId>
|
||||
<artifactId>junit-jupiter</artifactId>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
|
||||
<!-- Test: TinkerGraph — in-memory TinkerPop graph for unit tests (no real DB needed) -->
|
||||
<dependency>
|
||||
<groupId>org.apache.tinkerpop</groupId>
|
||||
<artifactId>tinkergraph-gremlin</artifactId>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
|
||||
</dependencies>
|
||||
|
||||
</project>
|
||||
@@ -0,0 +1,25 @@
|
||||
package com.binarygolem.clotho.annotation;
|
||||
|
||||
import java.lang.annotation.ElementType;
|
||||
import java.lang.annotation.Retention;
|
||||
import java.lang.annotation.RetentionPolicy;
|
||||
import java.lang.annotation.Target;
|
||||
|
||||
/**
|
||||
* On a {@code @SubgraphType} field: specifies the Gremlin {@code as()} alias
|
||||
* that this field is bound to when assembling from a {@code select()} result.
|
||||
*
|
||||
* <p>When omitted, the field name itself is used as the alias key.
|
||||
*
|
||||
* <pre>{@code
|
||||
* @Alias("dept")
|
||||
* Department department; // bound to .as("dept") in the Gremlin query
|
||||
* }</pre>
|
||||
*/
|
||||
@Target(ElementType.FIELD)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface Alias {
|
||||
|
||||
/** Gremlin {@code as()} alias to bind from. */
|
||||
String value();
|
||||
}
|
||||
@@ -0,0 +1,30 @@
|
||||
package com.binarygolem.clotho.annotation;
|
||||
|
||||
import java.lang.annotation.ElementType;
|
||||
import java.lang.annotation.Retention;
|
||||
import java.lang.annotation.RetentionPolicy;
|
||||
import java.lang.annotation.Target;
|
||||
|
||||
/**
|
||||
* Marks a {@link com.binarygolem.clotho.repository.ClothoRepository} subclass as a
|
||||
* Clotho-managed repository bean.
|
||||
*
|
||||
* <p>The {@code clotho-spring-boot-starter} scans for classes bearing this annotation
|
||||
* and registers them as Spring beans, injecting the shared {@code ClothoSessionFactory}.
|
||||
*
|
||||
* <pre>{@code
|
||||
* @ClothoRepository
|
||||
* public class EmployeeRepo extends ClothoRepository<Employee> {
|
||||
*
|
||||
* public EmployeeRepo(ClothoSessionFactory factory) { super(factory); }
|
||||
*
|
||||
* public List<Employee> findByDept(String dept) {
|
||||
* return execute(g().V().has("Employee", "dept", dept));
|
||||
* }
|
||||
* }
|
||||
* }</pre>
|
||||
*/
|
||||
@Target(ElementType.TYPE)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface ClothoRepository {
|
||||
}
|
||||
@@ -0,0 +1,29 @@
|
||||
package com.binarygolem.clotho.annotation;
|
||||
|
||||
import com.binarygolem.clotho.model.TraversalDirection;
|
||||
|
||||
import java.lang.annotation.ElementType;
|
||||
import java.lang.annotation.Retention;
|
||||
import java.lang.annotation.RetentionPolicy;
|
||||
import java.lang.annotation.Target;
|
||||
|
||||
/**
|
||||
* Specifies the edge traversal direction for an {@link Include} + {@link Via} field.
|
||||
*
|
||||
* <p>When omitted, the direction defaults to {@link TraversalDirection#OUT} or the
|
||||
* global default configured in {@code ClothoSessionFactory}.
|
||||
*
|
||||
* <pre>{@code
|
||||
* @Include @Via("ASSIGNED_TO") @Direction(IN)
|
||||
* List<Task> assignedTasks;
|
||||
*
|
||||
* @Include @Via("CONNECTED") @Direction(BOTH)
|
||||
* List<Node> neighbors;
|
||||
* }</pre>
|
||||
*/
|
||||
@Target(ElementType.FIELD)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface Direction {
|
||||
|
||||
TraversalDirection value() default TraversalDirection.OUT;
|
||||
}
|
||||
@@ -0,0 +1,23 @@
|
||||
package com.binarygolem.clotho.annotation;
|
||||
|
||||
import java.lang.annotation.ElementType;
|
||||
import java.lang.annotation.Retention;
|
||||
import java.lang.annotation.RetentionPolicy;
|
||||
import java.lang.annotation.Target;
|
||||
|
||||
/**
|
||||
* Declares a {@link com.binarygolem.clotho.model.ClothoEdge} subclass as a
|
||||
* Clotho-managed edge type. The annotated class is registered in the
|
||||
* {@code TypeRegistry} under the given ArcadeDB edge type name.
|
||||
*
|
||||
* <p>Convention: define a {@code public static final String LABEL = "..."}
|
||||
* constant on the edge class to allow call sites to reference the label without
|
||||
* using a magic string literal.
|
||||
*/
|
||||
@Target(ElementType.TYPE)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface EdgeType {
|
||||
|
||||
/** ArcadeDB edge type name — must match the schema exactly (case-sensitive). */
|
||||
String value();
|
||||
}
|
||||
@@ -0,0 +1,19 @@
|
||||
package com.binarygolem.clotho.annotation;
|
||||
|
||||
import java.lang.annotation.ElementType;
|
||||
import java.lang.annotation.Retention;
|
||||
import java.lang.annotation.RetentionPolicy;
|
||||
import java.lang.annotation.Target;
|
||||
|
||||
/**
|
||||
* On an {@code @EdgeType} class: marks the field holding the in-vertex (target)
|
||||
* of the edge. The field type must be a {@code @VertexType} class.
|
||||
*
|
||||
* <p>Omitting this annotation entirely on an edge class enables
|
||||
* <em>edge-only inclusion</em>: the edge and its properties are loaded but
|
||||
* the target vertex is never fetched from the database.
|
||||
*/
|
||||
@Target(ElementType.FIELD)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface InVertex {
|
||||
}
|
||||
@@ -0,0 +1,36 @@
|
||||
package com.binarygolem.clotho.annotation;
|
||||
|
||||
import com.binarygolem.clotho.model.FetchType;
|
||||
|
||||
import java.lang.annotation.ElementType;
|
||||
import java.lang.annotation.Retention;
|
||||
import java.lang.annotation.RetentionPolicy;
|
||||
import java.lang.annotation.Target;
|
||||
|
||||
/**
|
||||
* Marks a field as part of this object's load boundary.
|
||||
*
|
||||
* <p>Must always be paired with {@link Via}. The field type determines what is loaded:
|
||||
* <ul>
|
||||
* <li>A {@code @VertexType} class or {@code List<@VertexType>}: the edge is traversed
|
||||
* and the target vertex (and its own boundary) is loaded. Edge properties are
|
||||
* not accessible.</li>
|
||||
* <li>An {@code @EdgeType} class or {@code List<@EdgeType>}: the edge and its
|
||||
* properties are loaded. The target vertex is loaded only if the edge class
|
||||
* declares an {@link InVertex} field.</li>
|
||||
* </ul>
|
||||
*
|
||||
* <p>Inclusion is recursive: if a loaded vertex also declares {@code @Include} fields,
|
||||
* those are loaded as part of the same operation (cycle detection prevents infinite loops).
|
||||
* The developer is responsible for designing boundaries that do not load unbounded
|
||||
* portions of the graph.
|
||||
*
|
||||
* <p>Set {@link #fetchType()} to {@link FetchType#LAZY} to skip this field during
|
||||
* {@code SubgraphLoader.populate()}. Lazy fields remain {@code null} / empty until the
|
||||
* developer calls {@code session.loadField(vertex, "fieldName")} explicitly.
|
||||
*/
|
||||
@Target(ElementType.FIELD)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface Include {
|
||||
FetchType fetchType() default FetchType.EAGER;
|
||||
}
|
||||
@@ -0,0 +1,15 @@
|
||||
package com.binarygolem.clotho.annotation;
|
||||
|
||||
import java.lang.annotation.ElementType;
|
||||
import java.lang.annotation.Retention;
|
||||
import java.lang.annotation.RetentionPolicy;
|
||||
import java.lang.annotation.Target;
|
||||
|
||||
/**
|
||||
* On an {@code @EdgeType} class: marks the field holding the out-vertex (source)
|
||||
* of the edge. The field type must be a {@code @VertexType} class.
|
||||
*/
|
||||
@Target(ElementType.FIELD)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface OutVertex {
|
||||
}
|
||||
@@ -0,0 +1,25 @@
|
||||
package com.binarygolem.clotho.annotation;
|
||||
|
||||
import java.lang.annotation.ElementType;
|
||||
import java.lang.annotation.Retention;
|
||||
import java.lang.annotation.RetentionPolicy;
|
||||
import java.lang.annotation.Target;
|
||||
|
||||
/**
|
||||
* Maps a field to an ArcadeDB vertex or edge property by name.
|
||||
*
|
||||
* <p>Optional when the Java field name exactly matches the ArcadeDB property name.
|
||||
* Required when names differ.
|
||||
*
|
||||
* <pre>{@code
|
||||
* @Property("startDate") LocalDate start; // names differ — annotation required
|
||||
* LocalDate endDate; // names match — annotation optional
|
||||
* }</pre>
|
||||
*/
|
||||
@Target(ElementType.FIELD)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface Property {
|
||||
|
||||
/** ArcadeDB property name (case-sensitive). */
|
||||
String value();
|
||||
}
|
||||
@@ -0,0 +1,21 @@
|
||||
package com.binarygolem.clotho.annotation;
|
||||
|
||||
import java.lang.annotation.ElementType;
|
||||
import java.lang.annotation.Retention;
|
||||
import java.lang.annotation.RetentionPolicy;
|
||||
import java.lang.annotation.Target;
|
||||
|
||||
/**
|
||||
* Marks a field as the ArcadeDB record ID ({@link com.binarygolem.clotho.model.ARID}).
|
||||
*
|
||||
* <p>With the base-class approach ({@code ClothoVertex} / {@code ClothoEdge}),
|
||||
* the {@code id} field inherited from {@code ClothoEntity} is used automatically
|
||||
* and this annotation is typically not needed on subclass fields.
|
||||
*
|
||||
* <p>Use this annotation if you need a differently-named ID field or are
|
||||
* building a type that does not extend the standard base classes.
|
||||
*/
|
||||
@Target(ElementType.FIELD)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface RID {
|
||||
}
|
||||
@@ -0,0 +1,28 @@
|
||||
package com.binarygolem.clotho.annotation;
|
||||
|
||||
import java.lang.annotation.ElementType;
|
||||
import java.lang.annotation.Retention;
|
||||
import java.lang.annotation.RetentionPolicy;
|
||||
import java.lang.annotation.Target;
|
||||
|
||||
/**
|
||||
* Declares a composite type assembled from a Gremlin {@code select()} traversal.
|
||||
*
|
||||
* <p>A {@code @SubgraphType} class:
|
||||
* <ul>
|
||||
* <li>Does NOT extend {@link com.binarygolem.clotho.model.ClothoVertex} or
|
||||
* {@link com.binarygolem.clotho.model.ClothoEdge} — it holds them as fields.</li>
|
||||
* <li>Has no ArcadeDB record ID of its own.</li>
|
||||
* <li>Is assembled by {@code SubgraphTypeAssembler} from a {@code @Query} result
|
||||
* whose Gremlin traversal uses {@code select()} with named aliases.</li>
|
||||
* <li>Saving it via {@code session.save()} delegates to all contained
|
||||
* {@link com.binarygolem.clotho.model.ClothoEntity} fields individually.</li>
|
||||
* </ul>
|
||||
*
|
||||
* <p>Fields are bound by matching the field name (or {@code @Alias} value) to
|
||||
* the corresponding key in the Gremlin {@code select()} map.
|
||||
*/
|
||||
@Target(ElementType.TYPE)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface SubgraphType {
|
||||
}
|
||||
@@ -0,0 +1,27 @@
|
||||
package com.binarygolem.clotho.annotation;
|
||||
|
||||
import java.lang.annotation.ElementType;
|
||||
import java.lang.annotation.Retention;
|
||||
import java.lang.annotation.RetentionPolicy;
|
||||
import java.lang.annotation.Target;
|
||||
|
||||
/**
|
||||
* Enables application-managed optimistic locking on a vertex or edge class.
|
||||
*
|
||||
* <p>Declare one {@code @Version Long version} field on a {@link
|
||||
* com.binarygolem.clotho.model.ClothoVertex} or {@link
|
||||
* com.binarygolem.clotho.model.ClothoEdge} subclass. Clotho manages the counter
|
||||
* entirely: it is initialised to {@code 0} on create, read as a regular property
|
||||
* on load, and atomically checked-and-incremented on every update. A version mismatch
|
||||
* throws {@link com.binarygolem.clotho.exception.OptimisticLockException}.
|
||||
*
|
||||
* <p>The {@link #value()} attribute is the graph property name used to store the
|
||||
* counter. It must be a regular user-defined property — ArcadeDB's internal system
|
||||
* properties (those prefixed with {@code @}) are not accessible via the Gremlin
|
||||
* WebSocket interface.
|
||||
*/
|
||||
@Target(ElementType.FIELD)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface Version {
|
||||
String value() default "_version";
|
||||
}
|
||||
@@ -0,0 +1,37 @@
|
||||
package com.binarygolem.clotho.annotation;
|
||||
|
||||
import java.lang.annotation.ElementType;
|
||||
import java.lang.annotation.Retention;
|
||||
import java.lang.annotation.RetentionPolicy;
|
||||
import java.lang.annotation.Target;
|
||||
|
||||
/**
|
||||
* Declares a {@link com.binarygolem.clotho.model.ClothoVertex} subclass as a
|
||||
* Clotho-managed vertex type. The annotated class is registered in the
|
||||
* {@code TypeRegistry} under the given ArcadeDB type name.
|
||||
*
|
||||
* <p>For ArcadeDB's multi-parent (diamond) inheritance, list additional parent
|
||||
* type names in {@link #additionalParents()}. The Java class hierarchy covers
|
||||
* the primary parent; the annotation covers the rest.
|
||||
*/
|
||||
@Target(ElementType.TYPE)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface VertexType {
|
||||
|
||||
/** ArcadeDB vertex type name — must match the schema exactly (case-sensitive). */
|
||||
String value();
|
||||
|
||||
/**
|
||||
* Additional ArcadeDB parent type names beyond the Java class hierarchy.
|
||||
* Use when ArcadeDB has multi-parent inheritance that Java cannot represent
|
||||
* with a single {@code extends} clause.
|
||||
*/
|
||||
String[] additionalParents() default {};
|
||||
|
||||
/**
|
||||
* Explicit ArcadeDB parent type name for cases where the Java class does
|
||||
* not extend the corresponding Clotho parent class.
|
||||
* Takes precedence over Java hierarchy inference when set.
|
||||
*/
|
||||
String parentLabel() default "";
|
||||
}
|
||||
@@ -0,0 +1,27 @@
|
||||
package com.binarygolem.clotho.annotation;
|
||||
|
||||
import java.lang.annotation.ElementType;
|
||||
import java.lang.annotation.Retention;
|
||||
import java.lang.annotation.RetentionPolicy;
|
||||
import java.lang.annotation.Target;
|
||||
|
||||
/**
|
||||
* Specifies the ArcadeDB edge label to traverse for an {@link Include} field.
|
||||
* Required whenever {@code @Include} is used.
|
||||
*
|
||||
* <p>To avoid magic string literals, prefer referencing the {@code LABEL} constant
|
||||
* defined on the edge class:
|
||||
* <pre>{@code
|
||||
* @Include @Via(WorksAt.LABEL)
|
||||
* List<WorksAt> workHistory;
|
||||
* }</pre>
|
||||
*
|
||||
* @see Direction for controlling traversal direction (default: OUT)
|
||||
*/
|
||||
@Target(ElementType.FIELD)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface Via {
|
||||
|
||||
/** Edge label to traverse (case-sensitive). */
|
||||
String value();
|
||||
}
|
||||
@@ -0,0 +1,4 @@
|
||||
@NullMarked
|
||||
package com.binarygolem.clotho.annotation;
|
||||
|
||||
import org.jspecify.annotations.NullMarked;
|
||||
+18
@@ -0,0 +1,18 @@
|
||||
package com.binarygolem.clotho.exception;
|
||||
|
||||
/**
|
||||
* Thrown when Clotho detects a misconfiguration at startup or at the point
|
||||
* where a misconfigured type is first used — e.g., a class annotated with
|
||||
* {@code @VertexType} that does not extend {@code ClothoVertex}, or a field
|
||||
* annotated with {@code @Include} that is missing {@code @Via}.
|
||||
*/
|
||||
public class ClothoConfigurationException extends ClothoException {
|
||||
|
||||
public ClothoConfigurationException(String message) {
|
||||
super(message);
|
||||
}
|
||||
|
||||
public ClothoConfigurationException(String message, Throwable cause) {
|
||||
super(message, cause);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,13 @@
|
||||
package com.binarygolem.clotho.exception;
|
||||
|
||||
/** Base unchecked exception for all Clotho runtime errors. */
|
||||
public class ClothoException extends RuntimeException {
|
||||
|
||||
public ClothoException(String message) {
|
||||
super(message);
|
||||
}
|
||||
|
||||
public ClothoException(String message, Throwable cause) {
|
||||
super(message, cause);
|
||||
}
|
||||
}
|
||||
+23
@@ -0,0 +1,23 @@
|
||||
package com.binarygolem.clotho.exception;
|
||||
|
||||
import com.binarygolem.clotho.model.ARID;
|
||||
import lombok.Getter;
|
||||
|
||||
/**
|
||||
* Thrown when an update is rejected because the entity's {@code @Version} value no
|
||||
* longer matches the graph's current version — i.e., another writer has modified
|
||||
* the record since it was loaded.
|
||||
*/
|
||||
@Getter
|
||||
public class OptimisticLockException extends ClothoException {
|
||||
|
||||
private final ARID id;
|
||||
private final long expectedVersion;
|
||||
|
||||
public OptimisticLockException(ARID id, long expectedVersion) {
|
||||
super("Optimistic lock failure for " + id + " at version " + expectedVersion
|
||||
+ " — record was modified by another writer");
|
||||
this.id = id;
|
||||
this.expectedVersion = expectedVersion;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,22 @@
|
||||
package com.binarygolem.clotho.exception;
|
||||
|
||||
/**
|
||||
* Thrown when a Gremlin result carries a vertex or edge label that has no
|
||||
* registered Clotho Java class, and the configured
|
||||
* {@link com.binarygolem.clotho.model.UnknownTypeBehavior} is
|
||||
* {@code STRICT}.
|
||||
*/
|
||||
public class UnknownTypeException extends ClothoException {
|
||||
|
||||
private final String label;
|
||||
|
||||
public UnknownTypeException(String label) {
|
||||
super("No Clotho type registered for label: '" + label + "'");
|
||||
this.label = label;
|
||||
}
|
||||
|
||||
/** The unrecognised ArcadeDB type label. */
|
||||
public String getLabel() {
|
||||
return label;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,4 @@
|
||||
@NullMarked
|
||||
package com.binarygolem.clotho.exception;
|
||||
|
||||
import org.jspecify.annotations.NullMarked;
|
||||
@@ -0,0 +1,180 @@
|
||||
package com.binarygolem.clotho.mapping;
|
||||
|
||||
import com.binarygolem.clotho.annotation.Version;
|
||||
import com.binarygolem.clotho.exception.ClothoConfigurationException;
|
||||
import com.binarygolem.clotho.model.ARID;
|
||||
import com.binarygolem.clotho.model.ClothoEdge;
|
||||
import com.binarygolem.clotho.model.ClothoEntity;
|
||||
import com.binarygolem.clotho.model.ClothoVertex;
|
||||
import com.binarygolem.clotho.model.UnknownTypeBehavior;
|
||||
import com.binarygolem.clotho.registry.TypeRegistry;
|
||||
import org.apache.tinkerpop.gremlin.structure.Edge;
|
||||
import org.apache.tinkerpop.gremlin.structure.Element;
|
||||
import org.apache.tinkerpop.gremlin.structure.Vertex;
|
||||
import org.jspecify.annotations.Nullable;
|
||||
|
||||
import java.lang.reflect.Field;
|
||||
import java.time.Instant;
|
||||
import java.time.LocalDate;
|
||||
import java.time.LocalDateTime;
|
||||
import java.time.ZoneOffset;
|
||||
import java.util.HashSet;
|
||||
import java.util.Set;
|
||||
import java.util.logging.Logger;
|
||||
|
||||
/**
|
||||
* Maps TinkerPop {@link Vertex} and {@link Edge} instances to their most-specific
|
||||
* registered Clotho Java class using the {@link TypeRegistry}.
|
||||
*
|
||||
* <p>Field metadata is read from {@link FieldMetadataCache} — reflection is performed
|
||||
* once per class and reused on every subsequent mapping call.
|
||||
*
|
||||
* <p>Fields annotated with {@code @Property} are mapped by the annotation value.
|
||||
* Fields with no framework annotation and a simple (scalar) type are mapped by
|
||||
* field name. {@code @Version} fields are mapped using their declared property name
|
||||
* (default {@code "_version"}). Fields annotated with {@code @Include},
|
||||
* {@code @OutVertex}, or {@code @InVertex} are skipped — they are handled by
|
||||
* {@code SubgraphLoader}.
|
||||
*/
|
||||
public final class ElementMapper {
|
||||
|
||||
private static final Logger log = Logger.getLogger(ElementMapper.class.getName());
|
||||
|
||||
private final TypeRegistry registry;
|
||||
private final UnknownTypeBehavior unknownTypeBehavior;
|
||||
|
||||
public ElementMapper(TypeRegistry registry, UnknownTypeBehavior unknownTypeBehavior) {
|
||||
this.registry = registry;
|
||||
this.unknownTypeBehavior = unknownTypeBehavior;
|
||||
}
|
||||
|
||||
public ClothoVertex mapVertex(Vertex vertex) {
|
||||
Class<? extends ClothoVertex> targetClass =
|
||||
registry.resolveVertex(vertex.label(), unknownTypeBehavior);
|
||||
ClothoVertex instance = instantiate(targetClass);
|
||||
populate(vertex, instance);
|
||||
return instance;
|
||||
}
|
||||
|
||||
public ClothoEdge mapEdge(Edge edge) {
|
||||
Class<? extends ClothoEdge> targetClass =
|
||||
registry.resolveEdge(edge.label(), unknownTypeBehavior);
|
||||
ClothoEdge instance = instantiate(targetClass);
|
||||
populate(edge, instance);
|
||||
instance.setOutVertexId(ARID.of(edge.outVertex().id().toString()));
|
||||
instance.setInVertexId(ARID.of(edge.inVertex().id().toString()));
|
||||
return instance;
|
||||
}
|
||||
|
||||
private static void populate(Element element, ClothoEntity instance) {
|
||||
instance.setId(ARID.of(element.id().toString()));
|
||||
|
||||
FieldMetadataCache.ClassMetadata meta = FieldMetadataCache.get(instance.getClass());
|
||||
Set<String> mappedKeys = new HashSet<>();
|
||||
|
||||
// Map @Property and auto-mapped scalar fields
|
||||
for (Field field : meta.propertyFields()) {
|
||||
String propName = meta.fieldToPropertyName().get(field.getName());
|
||||
if (propName == null) continue;
|
||||
Object raw = readProperty(element, propName);
|
||||
if (raw == null) continue;
|
||||
mappedKeys.add(propName);
|
||||
setField(field, instance, coerce(raw, field.getType()));
|
||||
}
|
||||
|
||||
// Map @Version field
|
||||
Field versionField = meta.versionField();
|
||||
if (versionField != null) {
|
||||
String propName = versionField.getAnnotation(Version.class).value();
|
||||
Object raw = readProperty(element, propName);
|
||||
if (raw != null) {
|
||||
mappedKeys.add(propName);
|
||||
setField(versionField, instance, coerce(raw, versionField.getType()));
|
||||
}
|
||||
}
|
||||
|
||||
// Store any remaining unmapped properties as raw
|
||||
element.properties().forEachRemaining(p -> {
|
||||
if (!mappedKeys.contains(p.key())) {
|
||||
instance.setRawProperty(p.key(), p.value());
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
// --- Coercion ---
|
||||
|
||||
@Nullable
|
||||
static Object coerce(@Nullable Object value, Class<?> target) {
|
||||
if (value == null) return null;
|
||||
if (target.isInstance(value)) return value;
|
||||
|
||||
if (target == String.class) return value.toString();
|
||||
|
||||
if (value instanceof Number num) {
|
||||
if (target == int.class || target == Integer.class) return num.intValue();
|
||||
if (target == long.class || target == Long.class) return num.longValue();
|
||||
if (target == double.class || target == Double.class) return num.doubleValue();
|
||||
if (target == float.class || target == Float.class) return num.floatValue();
|
||||
if (target == short.class || target == Short.class) return num.shortValue();
|
||||
if (target == byte.class || target == Byte.class) return num.byteValue();
|
||||
if (target.isEnum()) return ordinalToEnum(target, num.intValue());
|
||||
if (target == LocalDateTime.class) return Instant.ofEpochMilli(num.longValue()).atZone(ZoneOffset.UTC).toLocalDateTime();
|
||||
if (target == LocalDate.class) return Instant.ofEpochMilli(num.longValue()).atZone(ZoneOffset.UTC).toLocalDate();
|
||||
if (target == Instant.class) return Instant.ofEpochMilli(num.longValue());
|
||||
}
|
||||
|
||||
if (value instanceof String str) {
|
||||
if (target.isEnum()) return nameToEnum(target, str);
|
||||
if (target == boolean.class || target == Boolean.class) return Boolean.parseBoolean(str);
|
||||
if (target == LocalDateTime.class) return LocalDateTime.parse(str);
|
||||
if (target == LocalDate.class) return LocalDate.parse(str);
|
||||
if (target == Instant.class) return Instant.parse(str);
|
||||
}
|
||||
|
||||
log.warning(() -> "Cannot coerce " + value.getClass().getName()
|
||||
+ " to " + target.getName() + " — returning value as-is");
|
||||
return value;
|
||||
}
|
||||
|
||||
@SuppressWarnings({"unchecked", "rawtypes"})
|
||||
private static Object ordinalToEnum(Class<?> target, int ordinal) {
|
||||
Object[] constants = target.getEnumConstants();
|
||||
if (ordinal >= 0 && ordinal < constants.length) return constants[ordinal];
|
||||
log.warning(() -> "Ordinal " + ordinal + " out of range for " + target.getName());
|
||||
return constants[0];
|
||||
}
|
||||
|
||||
@SuppressWarnings({"unchecked", "rawtypes"})
|
||||
private static Object nameToEnum(Class<?> target, String name) {
|
||||
return Enum.valueOf((Class<Enum>) target, name);
|
||||
}
|
||||
|
||||
// --- Reflection helpers ---
|
||||
|
||||
@Nullable
|
||||
private static Object readProperty(Element element, String key) {
|
||||
var prop = element.property(key);
|
||||
return prop.isPresent() ? prop.value() : null;
|
||||
}
|
||||
|
||||
private static void setField(Field field, Object instance, @Nullable Object value) {
|
||||
try {
|
||||
field.setAccessible(true);
|
||||
field.set(instance, value);
|
||||
} catch (IllegalAccessException e) {
|
||||
throw new ClothoConfigurationException(
|
||||
"Cannot set field '" + field.getName() + "' on " + instance.getClass().getName(), e);
|
||||
}
|
||||
}
|
||||
|
||||
private static <T> T instantiate(Class<T> clazz) {
|
||||
try {
|
||||
var ctor = clazz.getDeclaredConstructor();
|
||||
ctor.setAccessible(true);
|
||||
return ctor.newInstance();
|
||||
} catch (Exception e) {
|
||||
throw new ClothoConfigurationException(
|
||||
clazz.getName() + " must have a no-arg constructor for Clotho to instantiate it", e);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,132 @@
|
||||
package com.binarygolem.clotho.mapping;
|
||||
|
||||
import com.binarygolem.clotho.annotation.Include;
|
||||
import com.binarygolem.clotho.annotation.InVertex;
|
||||
import com.binarygolem.clotho.annotation.OutVertex;
|
||||
import com.binarygolem.clotho.annotation.Property;
|
||||
import com.binarygolem.clotho.annotation.RID;
|
||||
import com.binarygolem.clotho.annotation.Version;
|
||||
import com.binarygolem.clotho.model.ClothoEdge;
|
||||
import com.binarygolem.clotho.model.ClothoEntity;
|
||||
import com.binarygolem.clotho.model.FetchType;
|
||||
import org.jspecify.annotations.Nullable;
|
||||
|
||||
import java.lang.reflect.Field;
|
||||
import java.lang.reflect.Modifier;
|
||||
import java.util.ArrayList;
|
||||
import java.util.Collections;
|
||||
import java.util.LinkedHashMap;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.concurrent.ConcurrentHashMap;
|
||||
|
||||
/**
|
||||
* Per-class reflection cache for Clotho field metadata.
|
||||
*
|
||||
* <p>Reflection is performed once per class and the result stored in a
|
||||
* {@link ConcurrentHashMap}. All subsequent accesses return the cached
|
||||
* {@link ClassMetadata} without touching the reflection API.
|
||||
*
|
||||
* <p>Call {@link #get(Class)} to retrieve (or compute) the metadata for any class.
|
||||
*/
|
||||
public final class FieldMetadataCache {
|
||||
|
||||
/**
|
||||
* Cached metadata for a single Java class.
|
||||
*
|
||||
* @param allIncludeFields every {@code @Include} field (eager + lazy), in declaration order
|
||||
* @param eagerIncludeFields only {@code @Include(fetchType = EAGER)} fields
|
||||
* @param propertyFields fields that map to graph properties ({@code @Property} or
|
||||
* auto-mapped scalars); excludes {@code @Include}, {@code @OutVertex},
|
||||
* {@code @InVertex}, {@code @RID}, {@code @Version}, static, synthetic
|
||||
* @param edgeVertexFields {@code @OutVertex} and {@code @InVertex} fields (on edge classes)
|
||||
* @param versionField the {@code @Version}-annotated field, or {@code null}
|
||||
* @param fieldToPropertyName map from Java field name to graph property name, for all property
|
||||
* fields plus the version field
|
||||
*/
|
||||
public record ClassMetadata(
|
||||
List<Field> allIncludeFields,
|
||||
List<Field> eagerIncludeFields,
|
||||
List<Field> propertyFields,
|
||||
List<Field> edgeVertexFields,
|
||||
@Nullable Field versionField,
|
||||
Map<String, String> fieldToPropertyName
|
||||
) {}
|
||||
|
||||
private static final ConcurrentHashMap<Class<?>, ClassMetadata> cache = new ConcurrentHashMap<>();
|
||||
|
||||
public static ClassMetadata get(Class<?> clazz) {
|
||||
return cache.computeIfAbsent(clazz, FieldMetadataCache::compute);
|
||||
}
|
||||
|
||||
private static ClassMetadata compute(Class<?> clazz) {
|
||||
List<Field> allIncludes = new ArrayList<>();
|
||||
List<Field> eagerIncludes = new ArrayList<>();
|
||||
List<Field> properties = new ArrayList<>();
|
||||
List<Field> edgeVertices = new ArrayList<>();
|
||||
Field versionField = null;
|
||||
Map<String, String> fieldToPropertyName = new LinkedHashMap<>();
|
||||
|
||||
Class<?> cursor = clazz;
|
||||
while (cursor != null && cursor != ClothoEntity.class && cursor != Object.class) {
|
||||
for (Field f : cursor.getDeclaredFields()) {
|
||||
if (Modifier.isStatic(f.getModifiers()) || f.isSynthetic()) continue;
|
||||
|
||||
if (f.isAnnotationPresent(Include.class)) {
|
||||
allIncludes.add(f);
|
||||
if (f.getAnnotation(Include.class).fetchType() == FetchType.EAGER) {
|
||||
eagerIncludes.add(f);
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if (f.isAnnotationPresent(OutVertex.class) || f.isAnnotationPresent(InVertex.class)) {
|
||||
edgeVertices.add(f);
|
||||
continue;
|
||||
}
|
||||
if (f.isAnnotationPresent(RID.class)) continue;
|
||||
|
||||
if (f.isAnnotationPresent(Version.class)) {
|
||||
versionField = f;
|
||||
String propName = f.getAnnotation(Version.class).value();
|
||||
fieldToPropertyName.put(f.getName(), propName);
|
||||
continue;
|
||||
}
|
||||
|
||||
Property propAnnotation = f.getAnnotation(Property.class);
|
||||
if (propAnnotation != null) {
|
||||
properties.add(f);
|
||||
fieldToPropertyName.put(f.getName(), propAnnotation.value());
|
||||
} else if (isMappableType(f.getType())) {
|
||||
properties.add(f);
|
||||
fieldToPropertyName.put(f.getName(), f.getName());
|
||||
}
|
||||
}
|
||||
cursor = cursor.getSuperclass();
|
||||
}
|
||||
|
||||
// Walk parent of ClothoEdge too (ClothoEdge extends ClothoEntity; we stop at ClothoEntity
|
||||
// but edgeVertexFields live on the concrete edge class, already covered above).
|
||||
|
||||
return new ClassMetadata(
|
||||
Collections.unmodifiableList(allIncludes),
|
||||
Collections.unmodifiableList(eagerIncludes),
|
||||
Collections.unmodifiableList(properties),
|
||||
Collections.unmodifiableList(edgeVertices),
|
||||
versionField,
|
||||
Collections.unmodifiableMap(fieldToPropertyName)
|
||||
);
|
||||
}
|
||||
|
||||
static boolean isMappableType(Class<?> type) {
|
||||
return type.isPrimitive()
|
||||
|| type == String.class
|
||||
|| Number.class.isAssignableFrom(type)
|
||||
|| type == Boolean.class
|
||||
|| type == Character.class
|
||||
|| type.isEnum()
|
||||
|| java.time.temporal.Temporal.class.isAssignableFrom(type)
|
||||
|| type == java.util.UUID.class;
|
||||
}
|
||||
|
||||
private FieldMetadataCache() {}
|
||||
}
|
||||
@@ -0,0 +1,304 @@
|
||||
package com.binarygolem.clotho.mapping;
|
||||
|
||||
import com.binarygolem.clotho.annotation.Direction;
|
||||
import com.binarygolem.clotho.annotation.Include;
|
||||
import com.binarygolem.clotho.annotation.InVertex;
|
||||
import com.binarygolem.clotho.annotation.OutVertex;
|
||||
import com.binarygolem.clotho.annotation.Via;
|
||||
import com.binarygolem.clotho.exception.ClothoConfigurationException;
|
||||
import com.binarygolem.clotho.model.ARID;
|
||||
import com.binarygolem.clotho.model.ClothoEdge;
|
||||
import com.binarygolem.clotho.model.ClothoEntity;
|
||||
import com.binarygolem.clotho.model.ClothoVertex;
|
||||
import com.binarygolem.clotho.model.EntityState;
|
||||
import com.binarygolem.clotho.model.TraversalDirection;
|
||||
import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversal;
|
||||
import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversalSource;
|
||||
import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.__;
|
||||
import org.apache.tinkerpop.gremlin.structure.Edge;
|
||||
import org.apache.tinkerpop.gremlin.structure.T;
|
||||
import org.apache.tinkerpop.gremlin.structure.Vertex;
|
||||
import org.jspecify.annotations.Nullable;
|
||||
|
||||
import java.lang.reflect.Field;
|
||||
import java.lang.reflect.ParameterizedType;
|
||||
import java.lang.reflect.Type;
|
||||
import java.util.ArrayList;
|
||||
import java.util.Arrays;
|
||||
import java.util.HashSet;
|
||||
import java.util.LinkedHashMap;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* Populates {@code @Include} fields on a {@link ClothoVertex} by executing a single
|
||||
* Gremlin {@code project()} traversal that fetches all eagerly-declared includes
|
||||
* atomically. This eliminates N+1 queries per boundary and prevents the race
|
||||
* conditions that arise from sequential round-trips.
|
||||
*
|
||||
* <p>For nested boundaries (an included vertex that itself has {@code @Include} fields)
|
||||
* each vertex is loaded with its own single-project query — one query per vertex,
|
||||
* not one per field.
|
||||
*
|
||||
* <p>Fields declared with {@link com.binarygolem.clotho.model.FetchType#LAZY} are
|
||||
* skipped during {@link #populate(ClothoVertex)}. Use
|
||||
* {@link #populateSingleField(ClothoVertex, Field)} to load them on demand.
|
||||
*
|
||||
* <p>Cycle detection is performed via a visited-ARID set passed through the recursion.
|
||||
*/
|
||||
public final class SubgraphLoader {
|
||||
|
||||
private final GraphTraversalSource g;
|
||||
private final ElementMapper mapper;
|
||||
private final TraversalDirection defaultDirection;
|
||||
|
||||
public SubgraphLoader(GraphTraversalSource g, ElementMapper mapper,
|
||||
TraversalDirection defaultDirection) {
|
||||
this.g = g;
|
||||
this.mapper = mapper;
|
||||
this.defaultDirection = defaultDirection;
|
||||
}
|
||||
|
||||
// --- Public API ---
|
||||
|
||||
/** Populates all EAGER {@code @Include} fields on {@code vertex} and transitively included objects. */
|
||||
public void populate(ClothoVertex vertex) {
|
||||
populate(vertex, new HashSet<>());
|
||||
}
|
||||
|
||||
/**
|
||||
* Populates a single {@code @Include} field on demand (eager or lazy).
|
||||
* Used by {@link com.binarygolem.clotho.session.ClothoSession#loadField}.
|
||||
*/
|
||||
public void populateSingleField(ClothoVertex vertex, Field field) {
|
||||
populateSingleField(vertex, field, new HashSet<>());
|
||||
}
|
||||
|
||||
/**
|
||||
* Batch-populates EAGER {@code @Include} fields for a list of vertices.
|
||||
* Vertices are grouped by class; for each class one batch traversal per
|
||||
* {@code @Include} field covers all vertex IDs at once.
|
||||
* This is significantly more efficient than calling {@link #populate} per vertex
|
||||
* when loading large result sets from {@code findAll()} or {@code execute()}.
|
||||
*/
|
||||
public void populateAll(List<? extends ClothoVertex> vertices) {
|
||||
if (vertices.isEmpty()) return;
|
||||
Map<Class<?>, List<ClothoVertex>> byClass = new LinkedHashMap<>();
|
||||
for (ClothoVertex v : vertices) {
|
||||
byClass.computeIfAbsent(v.getClass(), k -> new ArrayList<>()).add(v);
|
||||
}
|
||||
for (Map.Entry<Class<?>, List<ClothoVertex>> entry : byClass.entrySet()) {
|
||||
populateAllOfClass(entry.getValue());
|
||||
}
|
||||
}
|
||||
|
||||
// --- Single-vertex population ---
|
||||
|
||||
private void populate(ClothoVertex vertex, Set<ARID> visited) {
|
||||
ARID id = vertex.getId();
|
||||
if (id == null) return;
|
||||
if (!visited.add(id)) return;
|
||||
|
||||
List<Field> eagerFields = FieldMetadataCache.get(vertex.getClass()).eagerIncludeFields();
|
||||
if (eagerFields.isEmpty()) return;
|
||||
|
||||
Map<String, Object> projected = projectVertex(id.asString(), eagerFields);
|
||||
if (projected == null) return;
|
||||
|
||||
for (Field field : eagerFields) {
|
||||
applyProjectedField(vertex, field, projected.get(field.getName()), visited);
|
||||
}
|
||||
}
|
||||
|
||||
// --- Single-field population ---
|
||||
|
||||
private void populateSingleField(ClothoVertex vertex, Field field, Set<ARID> visited) {
|
||||
ARID id = vertex.getId();
|
||||
if (id == null) return;
|
||||
|
||||
Map<String, Object> projected = projectVertex(id.asString(), List.of(field));
|
||||
if (projected == null) return;
|
||||
|
||||
applyProjectedField(vertex, field, projected.get(field.getName()), visited);
|
||||
}
|
||||
|
||||
// --- Batch population ---
|
||||
|
||||
@SuppressWarnings("unchecked")
|
||||
private void populateAllOfClass(List<ClothoVertex> vertices) {
|
||||
List<Field> eagerFields = FieldMetadataCache.get(vertices.get(0).getClass()).eagerIncludeFields();
|
||||
if (eagerFields.isEmpty()) return;
|
||||
|
||||
Map<String, ClothoVertex> byId = new LinkedHashMap<>();
|
||||
for (ClothoVertex v : vertices) {
|
||||
if (v.getId() != null) byId.put(v.getId().asString(), v);
|
||||
}
|
||||
if (byId.isEmpty()) return;
|
||||
|
||||
Object[] ids = byId.keySet().toArray();
|
||||
Set<ARID> visited = new HashSet<>();
|
||||
|
||||
for (Field field : eagerFields) {
|
||||
// One batch query per @Include field: group by vertex ID, fold results per vertex
|
||||
Map<Object, Object> batchResult = (Map<Object, Object>) g.V(ids)
|
||||
.group()
|
||||
.by(T.id)
|
||||
.by(buildByStep(field))
|
||||
.next();
|
||||
|
||||
for (Map.Entry<Object, Object> entry : batchResult.entrySet()) {
|
||||
String rawId = entry.getKey().toString();
|
||||
ClothoVertex vertex = byId.get(rawId);
|
||||
if (vertex == null) continue;
|
||||
applyProjectedField(vertex, field, entry.getValue(), visited);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// --- Projection ---
|
||||
|
||||
@SuppressWarnings("unchecked")
|
||||
private @Nullable Map<String, Object> projectVertex(String vertexId, List<Field> fields) {
|
||||
if (fields.isEmpty()) return Map.of();
|
||||
String[] keys = fields.stream().map(Field::getName).toArray(String[]::new);
|
||||
var traversal = g.V(vertexId).project(keys[0], Arrays.copyOfRange(keys, 1, keys.length));
|
||||
for (Field f : fields) {
|
||||
traversal = traversal.by(buildByStep(f));
|
||||
}
|
||||
return (Map<String, Object>) traversal.tryNext().orElse(null);
|
||||
}
|
||||
|
||||
/**
|
||||
* Builds the Gremlin {@code by()} step for a single {@code @Include} field.
|
||||
*
|
||||
* <p>For edge fields the projection includes the edge AND both adjacent full vertices
|
||||
* ({@code outV()}/{@code inV()} inside {@code project()} return vertices with all
|
||||
* their properties). This eliminates the separate {@code g.V(id)} call that
|
||||
* detached-edge traversals previously required.
|
||||
*/
|
||||
private GraphTraversal<?, ?> buildByStep(Field field) {
|
||||
Via via = field.getAnnotation(Via.class);
|
||||
if (via == null) {
|
||||
throw new ClothoConfigurationException(
|
||||
"@Include field '" + field.getName() + "' on "
|
||||
+ field.getDeclaringClass().getName() + " is missing @Via");
|
||||
}
|
||||
String label = via.value();
|
||||
TraversalDirection direction = resolveDirection(field);
|
||||
Class<?> elementType = resolveElementType(field);
|
||||
|
||||
if (ClothoEdge.class.isAssignableFrom(elementType)) {
|
||||
return switch (direction) {
|
||||
case OUT -> __.outE(label).project("edge", "outV", "inV")
|
||||
.by(__.identity()).by(__.outV()).by(__.inV()).fold();
|
||||
case IN -> __.inE(label).project("edge", "outV", "inV")
|
||||
.by(__.identity()).by(__.outV()).by(__.inV()).fold();
|
||||
case BOTH -> __.bothE(label).project("edge", "outV", "inV")
|
||||
.by(__.identity()).by(__.outV()).by(__.inV()).fold();
|
||||
};
|
||||
} else {
|
||||
return switch (direction) {
|
||||
case OUT -> __.out(label).fold();
|
||||
case IN -> __.in(label).fold();
|
||||
case BOTH -> __.both(label).fold();
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
// --- Applying projected results to entity fields ---
|
||||
|
||||
@SuppressWarnings("unchecked")
|
||||
private void applyProjectedField(ClothoVertex root, Field field,
|
||||
@Nullable Object projected, Set<ARID> visited) {
|
||||
List<?> items = projected instanceof List<?> l ? l : List.of();
|
||||
Class<?> elementType = resolveElementType(field);
|
||||
|
||||
if (ClothoEdge.class.isAssignableFrom(elementType)) {
|
||||
List<ClothoEdge> edges = new ArrayList<>();
|
||||
for (Object item : items) {
|
||||
edges.add(buildEdgeFromProjection((Map<String, Object>) item, root, visited));
|
||||
}
|
||||
setField(field, root, isList(field) ? edges : (edges.isEmpty() ? null : edges.get(0)));
|
||||
} else {
|
||||
List<ClothoVertex> loadedVertices = new ArrayList<>();
|
||||
for (Object item : items) {
|
||||
ClothoVertex mapped = mapper.mapVertex((Vertex) item);
|
||||
populate(mapped, visited);
|
||||
loadedVertices.add(mapped);
|
||||
}
|
||||
setField(field, root, isList(field) ? loadedVertices
|
||||
: (loadedVertices.isEmpty() ? null : loadedVertices.get(0)));
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Builds a {@link ClothoEdge} from a projection entry
|
||||
* {@code {"edge": Edge, "outV": Vertex, "inV": Vertex}}.
|
||||
* Both adjacent vertices are full (not detached) — they come from
|
||||
* {@code outV()}/{@code inV()} inside the projection step.
|
||||
*/
|
||||
private ClothoEdge buildEdgeFromProjection(Map<String, Object> entry,
|
||||
ClothoVertex root, Set<ARID> visited) {
|
||||
Edge rawEdge = (Edge) entry.get("edge");
|
||||
Vertex outVRaw = (Vertex) entry.get("outV");
|
||||
Vertex inVRaw = (Vertex) entry.get("inV");
|
||||
|
||||
ClothoEdge edge = mapper.mapEdge(rawEdge);
|
||||
edge.setState(EntityState.MANAGED);
|
||||
edge.clearDirtyFields();
|
||||
|
||||
ARID rootId = root.getId();
|
||||
for (Field evField : FieldMetadataCache.get(edge.getClass()).edgeVertexFields()) {
|
||||
if (evField.isAnnotationPresent(OutVertex.class)) {
|
||||
setField(evField, edge, sameOrMap(outVRaw, root, rootId, visited));
|
||||
} else if (evField.isAnnotationPresent(InVertex.class)) {
|
||||
setField(evField, edge, sameOrMap(inVRaw, root, rootId, visited));
|
||||
}
|
||||
}
|
||||
return edge;
|
||||
}
|
||||
|
||||
/** Returns {@code root} when the projected vertex is the same instance (by ARID), otherwise maps it. */
|
||||
private ClothoVertex sameOrMap(Vertex raw, ClothoVertex root,
|
||||
@Nullable ARID rootId, Set<ARID> visited) {
|
||||
ARID rawId = ARID.of(raw.id().toString());
|
||||
if (rawId.equals(rootId)) return root;
|
||||
ClothoVertex mapped = mapper.mapVertex(raw);
|
||||
populate(mapped, visited);
|
||||
return mapped;
|
||||
}
|
||||
|
||||
// --- Field type helpers ---
|
||||
|
||||
private TraversalDirection resolveDirection(Field field) {
|
||||
Direction annotation = field.getAnnotation(Direction.class);
|
||||
return annotation != null ? annotation.value() : defaultDirection;
|
||||
}
|
||||
|
||||
private static boolean isList(Field field) {
|
||||
return List.class.isAssignableFrom(field.getType());
|
||||
}
|
||||
|
||||
private static Class<?> resolveElementType(Field field) {
|
||||
if (!isList(field)) return field.getType();
|
||||
Type generic = field.getGenericType();
|
||||
if (generic instanceof ParameterizedType pt) {
|
||||
Type arg = pt.getActualTypeArguments()[0];
|
||||
if (arg instanceof Class<?> c) return c;
|
||||
}
|
||||
throw new ClothoConfigurationException(
|
||||
"Cannot determine element type of List field '" + field.getName() + "'");
|
||||
}
|
||||
|
||||
static void setField(Field field, Object instance, @Nullable Object value) {
|
||||
try {
|
||||
field.setAccessible(true);
|
||||
field.set(instance, value);
|
||||
} catch (IllegalAccessException e) {
|
||||
throw new ClothoConfigurationException(
|
||||
"Cannot set field '" + field.getName() + "' on "
|
||||
+ instance.getClass().getName(), e);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,512 @@
|
||||
package com.binarygolem.clotho.mapping;
|
||||
|
||||
import com.binarygolem.clotho.annotation.InVertex;
|
||||
import com.binarygolem.clotho.annotation.OutVertex;
|
||||
import com.binarygolem.clotho.annotation.SubgraphType;
|
||||
import com.binarygolem.clotho.exception.ClothoConfigurationException;
|
||||
import com.binarygolem.clotho.exception.ClothoException;
|
||||
import com.binarygolem.clotho.exception.OptimisticLockException;
|
||||
import com.binarygolem.clotho.model.ARID;
|
||||
import com.binarygolem.clotho.model.ClothoEdge;
|
||||
import com.binarygolem.clotho.model.ClothoEntity;
|
||||
import com.binarygolem.clotho.model.ClothoVertex;
|
||||
import com.binarygolem.clotho.model.EntityState;
|
||||
import com.binarygolem.clotho.model.TraversalDirection;
|
||||
import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversal;
|
||||
import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversalSource;
|
||||
import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.__;
|
||||
import org.apache.tinkerpop.gremlin.structure.Edge;
|
||||
import org.apache.tinkerpop.gremlin.structure.Vertex;
|
||||
import org.jspecify.annotations.Nullable;
|
||||
|
||||
import java.lang.annotation.Annotation;
|
||||
import java.lang.reflect.Field;
|
||||
import java.lang.reflect.Modifier;
|
||||
import java.util.ArrayList;
|
||||
import java.util.Collection;
|
||||
import java.util.Collections;
|
||||
import java.util.HashMap;
|
||||
import java.util.HashSet;
|
||||
import java.util.IdentityHashMap;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* Persists {@link ClothoVertex}, {@link ClothoEdge}, and {@code @SubgraphType} objects
|
||||
* to the graph database via Gremlin.
|
||||
*
|
||||
* <p>Persistence semantics:
|
||||
* <ul>
|
||||
* <li>{@link EntityState#NEW} or ARID {@code null} → create; returned ID is written back.</li>
|
||||
* <li>{@link EntityState#MANAGED} with dirty fields → update; only dirty fields are written.</li>
|
||||
* <li>{@link EntityState#MANAGED} with no dirty fields → skip (nothing changed).</li>
|
||||
* <li>{@code @Version} present → version filter added to update; mismatch throws
|
||||
* {@link OptimisticLockException}.</li>
|
||||
* <li>Cascade: after persisting a vertex, all {@code @Include} fields are persisted
|
||||
* recursively. An identity set prevents double-writes in the same call.</li>
|
||||
* <li>{@code @SubgraphType}: every {@link ClothoEntity} field is persisted.</li>
|
||||
* </ul>
|
||||
*
|
||||
* <p>Vertices and edges are treated identically — both participate in EntityState
|
||||
* lifecycle, dirty tracking, and {@code @Version} optimistic locking.
|
||||
*/
|
||||
public final class SubgraphPersistor {
|
||||
|
||||
private final GraphTraversalSource g;
|
||||
|
||||
public SubgraphPersistor(GraphTraversalSource g) {
|
||||
this.g = g;
|
||||
}
|
||||
|
||||
// --- Public API ---
|
||||
|
||||
/** Persists {@code vertex} and cascades through its {@code @Include} boundary. */
|
||||
public void persist(ClothoVertex vertex) {
|
||||
persistVertex(vertex, identitySet());
|
||||
}
|
||||
|
||||
/** Persists {@code edge} and its {@code @OutVertex}/{@code @InVertex} fields. */
|
||||
public void persist(ClothoEdge edge) {
|
||||
persistEdge(edge, identitySet());
|
||||
}
|
||||
|
||||
/**
|
||||
* Persists all {@link ClothoEntity} fields (and lists thereof) on a {@code @SubgraphType}.
|
||||
*
|
||||
* @throws ClothoConfigurationException if {@code subgraphType} lacks the annotation
|
||||
*/
|
||||
public void persist(Object subgraphType) {
|
||||
if (!subgraphType.getClass().isAnnotationPresent(SubgraphType.class)) {
|
||||
throw new ClothoConfigurationException(
|
||||
subgraphType.getClass().getName() + " is not annotated with @SubgraphType");
|
||||
}
|
||||
Set<ClothoEntity> visited = identitySet();
|
||||
for (ClothoEntity entity : collectEntityFields(subgraphType)) {
|
||||
if (entity instanceof ClothoVertex v) persistVertex(v, visited);
|
||||
else if (entity instanceof ClothoEdge e) persistEdge(e, visited);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Persists all dirty MANAGED entities as two Gremlin round-trips that together provide
|
||||
* all-or-nothing semantics for {@code @Version} conflicts:
|
||||
*
|
||||
* <ol>
|
||||
* <li><b>Version pre-flight</b> (one request): for every entity that carries a
|
||||
* {@code @Version} field, verify the expected version is still current. If any
|
||||
* version has changed, throw {@link OptimisticLockException} immediately — no
|
||||
* property has been written yet.</li>
|
||||
* <li><b>Batch update</b> (one request): write every dirty property across all
|
||||
* entities in a single {@code inject(0).union(...).iterate()} traversal. No
|
||||
* version filters inside — the pre-flight already guaranteed consistency.</li>
|
||||
* </ol>
|
||||
*
|
||||
* <p>The two-step approach means a narrow TOCTOU window exists between the check and
|
||||
* the write, but within that window a conflict would simply overwrite with the stale
|
||||
* value (the same risk as any non-transactional update). Eliminating the window
|
||||
* entirely requires native ArcadeDB transaction support, which is not available over
|
||||
* the Gremlin WebSocket interface.
|
||||
*/
|
||||
@SuppressWarnings({"unchecked", "rawtypes"})
|
||||
public void persistAllDirty(Collection<ClothoVertex> dirtyVertices,
|
||||
Collection<ClothoEdge> dirtyEdges) {
|
||||
// --- 1. Version pre-flight ---
|
||||
// Collect version expectations for all dirty @Version entities, then verify them in
|
||||
// one request. If any version is stale the exception is thrown here — before a single
|
||||
// property is written — giving true all-or-nothing semantics for version conflicts.
|
||||
List<VersionedExpectation> versionChecks = new ArrayList<>();
|
||||
for (ClothoVertex v : dirtyVertices) collectVersionExpectation(v, versionChecks);
|
||||
for (ClothoEdge e : dirtyEdges) collectVersionExpectation(e, versionChecks);
|
||||
|
||||
if (!versionChecks.isEmpty()) {
|
||||
long matched = (long) unionOf(g.inject(0),
|
||||
versionChecks.stream().map(VersionedExpectation::freshBranch).toList())
|
||||
.count().next();
|
||||
if (matched < versionChecks.size()) {
|
||||
// At least one version is stale. Re-run with fresh branches (traversals are
|
||||
// stateful and consumed after execution) to identify the specific conflict.
|
||||
Set<String> present = new HashSet<>(
|
||||
(List<String>) (List<?>) unionOf(g.inject(0),
|
||||
versionChecks.stream().map(VersionedExpectation::freshBranch).toList())
|
||||
.toList()
|
||||
);
|
||||
VersionedExpectation conflict = versionChecks.stream()
|
||||
.filter(c -> !present.contains(c.id().asString()))
|
||||
.findFirst().orElseThrow();
|
||||
throw new OptimisticLockException(conflict.id(), conflict.expectedVersion());
|
||||
}
|
||||
}
|
||||
|
||||
// --- 2. Batch update (no version filters — pre-flight already passed) ---
|
||||
// Build a lookup map so buildUpdateBranch can append the version+1 write for each entity.
|
||||
Map<ARID, VersionedExpectation> versionMap = new HashMap<>();
|
||||
for (VersionedExpectation ve : versionChecks) versionMap.put(ve.id(), ve);
|
||||
|
||||
List<GraphTraversal<?, ?>> updateBranches = new ArrayList<>();
|
||||
for (ClothoVertex v : dirtyVertices) buildUpdateBranch(v, true, updateBranches, versionMap);
|
||||
for (ClothoEdge e : dirtyEdges) buildUpdateBranch(e, false, updateBranches, versionMap);
|
||||
|
||||
if (!updateBranches.isEmpty()) {
|
||||
unionOf(g.inject(0), updateBranches).iterate();
|
||||
}
|
||||
|
||||
for (ClothoVertex v : dirtyVertices) { bumpVersionField(v, versionMap); v.clearDirtyFields(); }
|
||||
for (ClothoEdge e : dirtyEdges) { bumpVersionField(e, versionMap); e.clearDirtyFields(); }
|
||||
}
|
||||
|
||||
/**
|
||||
* Holds the data needed to verify one entity's expected {@code @Version} value.
|
||||
* {@link #freshBranch()} produces a new anonymous traversal each time — required
|
||||
* because Gremlin traversal objects are stateful and consumed after execution.
|
||||
*/
|
||||
private record VersionedExpectation(ARID id, long expectedVersion,
|
||||
String versionProp, boolean isVertex) {
|
||||
@SuppressWarnings({"unchecked", "rawtypes"})
|
||||
GraphTraversal<?, ?> freshBranch() {
|
||||
String idStr = id.asString();
|
||||
return (GraphTraversal<?, ?>)
|
||||
(isVertex ? __.V(idStr) : __.E(idStr)).has(versionProp, expectedVersion).constant(idStr);
|
||||
}
|
||||
}
|
||||
|
||||
/** Wraps raw-type {@code union()} call to avoid unchecked-warning noise at every call site. */
|
||||
@SuppressWarnings({"unchecked", "rawtypes"})
|
||||
private static GraphTraversal<?, ?> unionOf(GraphTraversal<?, ?> root,
|
||||
List<? extends GraphTraversal<?, ?>> branches) {
|
||||
return root.union(branches.toArray(GraphTraversal[]::new));
|
||||
}
|
||||
|
||||
/** Adds a {@link VersionedExpectation} for {@code entity} if it carries a {@code @Version} field. */
|
||||
private static void collectVersionExpectation(ClothoEntity entity, List<VersionedExpectation> checks) {
|
||||
if (entity.getDirtyFields().isEmpty()) return;
|
||||
Field vf = FieldMetadataCache.get(entity.getClass()).versionField();
|
||||
if (vf == null) return;
|
||||
Long ver = (Long) readField(vf, entity);
|
||||
if (ver == null) return;
|
||||
String vProp = vf.getAnnotation(com.binarygolem.clotho.annotation.Version.class).value();
|
||||
checks.add(new VersionedExpectation(entity.getId(), ver, vProp, entity instanceof ClothoVertex));
|
||||
}
|
||||
|
||||
/** Builds one anonymous update branch: writes dirty @Property fields and increments @Version. */
|
||||
@SuppressWarnings({"unchecked", "rawtypes"})
|
||||
private void buildUpdateBranch(ClothoEntity entity, boolean isVertex,
|
||||
List<GraphTraversal<?, ?>> branches,
|
||||
Map<ARID, VersionedExpectation> versionMap) {
|
||||
Set<String> dirty = entity.getDirtyFields();
|
||||
if (dirty.isEmpty()) return;
|
||||
|
||||
Map<String, String> fieldToProperty = FieldMetadataCache.get(entity.getClass()).fieldToPropertyName();
|
||||
List<PropertyEntry> dirtyEntries = collectAllPropertyEntries(entity).stream()
|
||||
.filter(pe -> dirty.contains(reverseMap(fieldToProperty, pe.name())))
|
||||
.toList();
|
||||
|
||||
VersionedExpectation ve = versionMap.get(entity.getId());
|
||||
if (dirtyEntries.isEmpty() && ve == null) return;
|
||||
|
||||
String idStr = entity.getId().asString();
|
||||
GraphTraversal t = isVertex ? __.V(idStr) : __.E(idStr);
|
||||
for (PropertyEntry pe : dirtyEntries) {
|
||||
if (pe.value() != null) t = t.property(pe.name(), pe.value());
|
||||
}
|
||||
if (ve != null) {
|
||||
t = t.property(ve.versionProp(), ve.expectedVersion() + 1);
|
||||
}
|
||||
branches.add(t);
|
||||
}
|
||||
|
||||
// --- Vertex persistence ---
|
||||
|
||||
private void persistVertex(ClothoVertex vertex, Set<ClothoEntity> visited) {
|
||||
if (!visited.add(vertex)) return;
|
||||
|
||||
if (vertex.getId() == null) {
|
||||
createVertex(vertex);
|
||||
vertex.setState(EntityState.MANAGED);
|
||||
} else if (vertex.getState() == EntityState.MANAGED) {
|
||||
Set<String> dirty = vertex.getDirtyFields();
|
||||
if (!dirty.isEmpty()) {
|
||||
updateEntity(vertex, dirty, g.V(vertex.getId().asString()));
|
||||
}
|
||||
} else {
|
||||
// ID is set but entity was not loaded through the session — full property write.
|
||||
writeAllProperties(vertex, g.V(vertex.getId().asString()));
|
||||
vertex.setState(EntityState.MANAGED);
|
||||
}
|
||||
|
||||
cascadeIncludes(vertex, visited);
|
||||
}
|
||||
|
||||
private void createVertex(ClothoVertex entity) {
|
||||
var traversal = g.addV(entity.getLabel());
|
||||
for (PropertyEntry pv : collectAllPropertyEntries(entity)) {
|
||||
if (pv.value() != null) traversal = traversal.property(pv.name(), pv.value());
|
||||
}
|
||||
Field vf = FieldMetadataCache.get(entity.getClass()).versionField();
|
||||
if (vf != null) {
|
||||
traversal = traversal.property(
|
||||
vf.getAnnotation(com.binarygolem.clotho.annotation.Version.class).value(), 0L);
|
||||
}
|
||||
Vertex created = traversal.next();
|
||||
entity.setId(ARID.of(created.id().toString()));
|
||||
if (vf != null) setField(vf, entity, 0L);
|
||||
entity.clearDirtyFields();
|
||||
}
|
||||
|
||||
// --- Edge persistence ---
|
||||
|
||||
private void persistEdge(ClothoEdge edge, Set<ClothoEntity> visited) {
|
||||
if (!visited.add(edge)) return;
|
||||
|
||||
if (edge.getId() == null) {
|
||||
createEdge(edge, visited);
|
||||
edge.setState(EntityState.MANAGED);
|
||||
} else if (edge.getState() == EntityState.MANAGED) {
|
||||
Set<String> dirty = edge.getDirtyFields();
|
||||
if (!dirty.isEmpty()) {
|
||||
updateEntity(edge, dirty, g.E(edge.getId().asString()));
|
||||
}
|
||||
} else {
|
||||
// ID is set but entity was not loaded through the session — full property write.
|
||||
writeAllProperties(edge, g.E(edge.getId().asString()));
|
||||
edge.setState(EntityState.MANAGED);
|
||||
}
|
||||
|
||||
// Cascade to @OutVertex / @InVertex loaded entities
|
||||
for (Field field : FieldMetadataCache.get(edge.getClass()).edgeVertexFields()) {
|
||||
Object value = readField(field, edge);
|
||||
if (value instanceof ClothoVertex v) persistVertex(v, visited);
|
||||
}
|
||||
}
|
||||
|
||||
private void createEdge(ClothoEdge entity, Set<ClothoEntity> visited) {
|
||||
ARID outId = resolveVertexId(entity, OutVertex.class, entity.getOutVertexId(), visited);
|
||||
ARID inId = resolveVertexId(entity, InVertex.class, entity.getInVertexId(), visited);
|
||||
|
||||
if (outId == null || inId == null) {
|
||||
throw new ClothoConfigurationException(
|
||||
"Cannot create edge '" + entity.getLabel()
|
||||
+ "': outVertexId and inVertexId must be resolvable");
|
||||
}
|
||||
|
||||
var traversal = g.addE(entity.getLabel())
|
||||
.from(__.V(outId.asString()))
|
||||
.to(__.V(inId.asString()));
|
||||
|
||||
for (PropertyEntry pv : collectAllPropertyEntries(entity)) {
|
||||
if (pv.value() != null) traversal = traversal.property(pv.name(), pv.value());
|
||||
}
|
||||
|
||||
Field vf = FieldMetadataCache.get(entity.getClass()).versionField();
|
||||
if (vf != null) {
|
||||
traversal = traversal.property(
|
||||
vf.getAnnotation(com.binarygolem.clotho.annotation.Version.class).value(), 0L);
|
||||
}
|
||||
|
||||
Edge created = traversal.next();
|
||||
entity.setId(ARID.of(created.id().toString()));
|
||||
if (vf != null) setField(vf, entity, 0L);
|
||||
entity.clearDirtyFields();
|
||||
}
|
||||
|
||||
// --- Full property write (entity has ID but was not loaded through session) ---
|
||||
|
||||
private void writeAllProperties(ClothoEntity entity, GraphTraversal<?, ?> start) {
|
||||
var t = start;
|
||||
for (PropertyEntry e : collectAllPropertyEntries(entity)) {
|
||||
if (e.value() != null) t = t.property(e.name(), e.value());
|
||||
}
|
||||
t.iterate();
|
||||
entity.clearDirtyFields();
|
||||
}
|
||||
|
||||
// --- Shared update with dirty-filter and OCC ---
|
||||
|
||||
/**
|
||||
* Updates only the dirty fields of {@code entity}, optionally guarded by {@code @Version}.
|
||||
* If a {@code @Version} field is present, the update is filtered by the expected version;
|
||||
* a mismatch throws {@link OptimisticLockException}. On success the version is
|
||||
* atomically incremented in the same traversal and the in-memory field is updated.
|
||||
*/
|
||||
private void updateEntity(ClothoEntity entity, Set<String> dirtyFieldNames,
|
||||
GraphTraversal<?, ?> start) {
|
||||
Map<String, String> fieldToProperty = FieldMetadataCache.get(entity.getClass()).fieldToPropertyName();
|
||||
|
||||
List<PropertyEntry> dirtyEntries = collectAllPropertyEntries(entity).stream()
|
||||
.filter(e -> dirtyFieldNames.contains(reverseMap(fieldToProperty, e.name())))
|
||||
.toList();
|
||||
|
||||
Field versionField = FieldMetadataCache.get(entity.getClass()).versionField();
|
||||
if (versionField != null) {
|
||||
Long version = (Long) readField(versionField, entity);
|
||||
if (version != null) {
|
||||
String vProp = versionField.getAnnotation(
|
||||
com.binarygolem.clotho.annotation.Version.class).value();
|
||||
var t = start.has(vProp, version);
|
||||
for (PropertyEntry e : dirtyEntries) {
|
||||
if (e.value() != null) t = t.property(e.name(), e.value());
|
||||
}
|
||||
t = t.property(vProp, version + 1);
|
||||
long matched = t.count().next();
|
||||
if (matched == 0) throw new OptimisticLockException(entity.getId(), version);
|
||||
setField(versionField, entity, version + 1);
|
||||
entity.clearDirtyFields();
|
||||
return;
|
||||
}
|
||||
}
|
||||
|
||||
var t = start;
|
||||
for (PropertyEntry e : dirtyEntries) {
|
||||
if (e.value() != null) t = t.property(e.name(), e.value());
|
||||
}
|
||||
if (!dirtyEntries.isEmpty()) t.iterate();
|
||||
entity.clearDirtyFields();
|
||||
}
|
||||
|
||||
/**
|
||||
* Given a property name, find the field name that maps to it.
|
||||
* Used to correlate dirty field names (Java field names) against PropertyEntry names (graph property names).
|
||||
*/
|
||||
private static String reverseMap(Map<String, String> fieldToProperty, String propertyName) {
|
||||
for (Map.Entry<String, String> entry : fieldToProperty.entrySet()) {
|
||||
if (entry.getValue().equals(propertyName)) return entry.getKey();
|
||||
}
|
||||
return propertyName;
|
||||
}
|
||||
|
||||
// --- Cascade ---
|
||||
|
||||
private void cascadeIncludes(ClothoVertex root, Set<ClothoEntity> visited) {
|
||||
for (Field field : FieldMetadataCache.get(root.getClass()).allIncludeFields()) {
|
||||
Object value = readField(field, root);
|
||||
if (value == null) continue;
|
||||
|
||||
TraversalDirection direction = resolveDirection(field);
|
||||
|
||||
if (value instanceof ClothoVertex v) {
|
||||
persistVertex(v, visited);
|
||||
} else if (value instanceof ClothoEdge e) {
|
||||
wireRootIntoEdge(e, root, direction);
|
||||
persistEdge(e, visited);
|
||||
} else if (value instanceof List<?> list) {
|
||||
for (Object item : list) {
|
||||
if (item instanceof ClothoVertex v) persistVertex(v, visited);
|
||||
else if (item instanceof ClothoEdge e) {
|
||||
wireRootIntoEdge(e, root, direction);
|
||||
persistEdge(e, visited);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private static void wireRootIntoEdge(ClothoEdge edge, ClothoVertex root,
|
||||
TraversalDirection direction) {
|
||||
ARID rootId = root.getId();
|
||||
if (rootId == null) return;
|
||||
switch (direction) {
|
||||
case OUT -> { if (edge.getOutVertexId() == null) edge.setOutVertexId(rootId); }
|
||||
case IN -> { if (edge.getInVertexId() == null) edge.setInVertexId(rootId); }
|
||||
case BOTH -> {}
|
||||
}
|
||||
}
|
||||
|
||||
private static TraversalDirection resolveDirection(Field field) {
|
||||
com.binarygolem.clotho.annotation.Direction annotation =
|
||||
field.getAnnotation(com.binarygolem.clotho.annotation.Direction.class);
|
||||
return annotation != null ? annotation.value() : TraversalDirection.OUT;
|
||||
}
|
||||
|
||||
// --- Vertex ID resolution for edge creation ---
|
||||
|
||||
@Nullable
|
||||
private ARID resolveVertexId(ClothoEdge edge,
|
||||
Class<? extends Annotation> sideAnnotation,
|
||||
@Nullable ARID stored,
|
||||
Set<ClothoEntity> visited) {
|
||||
if (stored != null) return stored;
|
||||
for (Field field : FieldMetadataCache.get(edge.getClass()).edgeVertexFields()) {
|
||||
if (!field.isAnnotationPresent(sideAnnotation)) continue;
|
||||
Object value = readField(field, edge);
|
||||
if (value instanceof ClothoVertex v) {
|
||||
if (v.getId() == null) persistVertex(v, visited);
|
||||
return v.getId();
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
// --- Property introspection ---
|
||||
|
||||
private record PropertyEntry(String name, @Nullable Object value) {}
|
||||
|
||||
private static List<PropertyEntry> collectAllPropertyEntries(ClothoEntity entity) {
|
||||
List<PropertyEntry> result = new ArrayList<>();
|
||||
for (Field field : FieldMetadataCache.get(entity.getClass()).propertyFields()) {
|
||||
String propName = FieldMetadataCache.get(entity.getClass())
|
||||
.fieldToPropertyName().get(field.getName());
|
||||
if (propName == null) continue;
|
||||
result.add(new PropertyEntry(propName, readField(field, entity)));
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
// --- SubgraphType entity collection ---
|
||||
|
||||
private static List<ClothoEntity> collectEntityFields(Object instance) {
|
||||
List<ClothoEntity> result = new ArrayList<>();
|
||||
Class<?> cursor = instance.getClass();
|
||||
while (cursor != null && cursor != Object.class) {
|
||||
for (Field field : cursor.getDeclaredFields()) {
|
||||
int mod = field.getModifiers();
|
||||
if (Modifier.isStatic(mod) || field.isSynthetic()) continue;
|
||||
Object value = readField(field, instance);
|
||||
if (value instanceof ClothoEntity entity) {
|
||||
result.add(entity);
|
||||
} else if (value instanceof List<?> list) {
|
||||
for (Object item : list) {
|
||||
if (item instanceof ClothoEntity entity) result.add(entity);
|
||||
}
|
||||
}
|
||||
}
|
||||
cursor = cursor.getSuperclass();
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
// --- Reflection helpers ---
|
||||
|
||||
@Nullable
|
||||
private static Object readField(Field field, Object instance) {
|
||||
try {
|
||||
field.setAccessible(true);
|
||||
return field.get(instance);
|
||||
} catch (IllegalAccessException e) {
|
||||
throw new ClothoException("Cannot read field '" + field.getName()
|
||||
+ "' on " + instance.getClass().getName(), e);
|
||||
}
|
||||
}
|
||||
|
||||
private static void setField(Field field, Object instance, Object value) {
|
||||
try {
|
||||
field.setAccessible(true);
|
||||
field.set(instance, value);
|
||||
} catch (IllegalAccessException e) {
|
||||
throw new ClothoException("Cannot set field '" + field.getName()
|
||||
+ "' on " + instance.getClass().getName(), e);
|
||||
}
|
||||
}
|
||||
|
||||
private static void bumpVersionField(ClothoEntity entity,
|
||||
Map<ARID, VersionedExpectation> versionMap) {
|
||||
VersionedExpectation ve = versionMap.get(entity.getId());
|
||||
if (ve == null) return;
|
||||
Field vf = FieldMetadataCache.get(entity.getClass()).versionField();
|
||||
if (vf == null) return;
|
||||
setField(vf, entity, ve.expectedVersion() + 1);
|
||||
}
|
||||
|
||||
private static Set<ClothoEntity> identitySet() {
|
||||
return Collections.newSetFromMap(new IdentityHashMap<>());
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,142 @@
|
||||
package com.binarygolem.clotho.mapping;
|
||||
|
||||
import com.binarygolem.clotho.annotation.Alias;
|
||||
import com.binarygolem.clotho.annotation.SubgraphType;
|
||||
import com.binarygolem.clotho.exception.ClothoConfigurationException;
|
||||
import com.binarygolem.clotho.model.ClothoVertex;
|
||||
import org.apache.tinkerpop.gremlin.structure.Edge;
|
||||
import org.apache.tinkerpop.gremlin.structure.Vertex;
|
||||
import org.jspecify.annotations.Nullable;
|
||||
|
||||
import java.lang.reflect.Field;
|
||||
import java.lang.reflect.Modifier;
|
||||
import java.lang.reflect.ParameterizedType;
|
||||
import java.lang.reflect.Type;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
|
||||
/**
|
||||
* Assembles a {@code @SubgraphType} instance from a Gremlin {@code select()} result map.
|
||||
*
|
||||
* <p>Each field on the subgraph type is matched to a map key by field name, or by the
|
||||
* value of an {@link Alias} annotation when present. Vertex values are mapped via
|
||||
* {@link ElementMapper} and their boundaries eagerly populated via {@link SubgraphLoader}.
|
||||
*/
|
||||
public final class SubgraphTypeAssembler {
|
||||
|
||||
private final ElementMapper mapper;
|
||||
private final SubgraphLoader loader;
|
||||
|
||||
public SubgraphTypeAssembler(ElementMapper mapper, SubgraphLoader loader) {
|
||||
this.mapper = mapper;
|
||||
this.loader = loader;
|
||||
}
|
||||
|
||||
/**
|
||||
* Assembles an instance of {@code type} from {@code selectResult}.
|
||||
*
|
||||
* @throws ClothoConfigurationException if {@code type} is not annotated with {@code @SubgraphType}
|
||||
*/
|
||||
public <T> T assemble(Class<T> type, Map<String, Object> selectResult) {
|
||||
if (!type.isAnnotationPresent(SubgraphType.class)) {
|
||||
throw new ClothoConfigurationException(
|
||||
type.getName() + " is not annotated with @SubgraphType");
|
||||
}
|
||||
|
||||
T instance = instantiate(type);
|
||||
|
||||
for (Field field : collectFields(type)) {
|
||||
String key = resolveKey(field);
|
||||
Object raw = selectResult.get(key);
|
||||
if (raw == null) continue;
|
||||
|
||||
Object mapped = mapValue(raw, field);
|
||||
setField(field, instance, mapped);
|
||||
}
|
||||
|
||||
return instance;
|
||||
}
|
||||
|
||||
private @Nullable Object mapValue(Object raw, Field field) {
|
||||
if (raw instanceof Vertex v) {
|
||||
ClothoVertex mapped = mapper.mapVertex(v);
|
||||
loader.populate(mapped);
|
||||
return mapped;
|
||||
}
|
||||
if (raw instanceof Edge e) {
|
||||
return mapper.mapEdge(e);
|
||||
}
|
||||
if (raw instanceof List<?> list) {
|
||||
Class<?> elementType = getListElementType(field);
|
||||
return list.stream()
|
||||
.map(item -> mapSingleValue(item, elementType))
|
||||
.toList();
|
||||
}
|
||||
return raw;
|
||||
}
|
||||
|
||||
private @Nullable Object mapSingleValue(Object raw, Class<?> elementType) {
|
||||
if (raw instanceof Vertex v) {
|
||||
ClothoVertex mapped = mapper.mapVertex(v);
|
||||
loader.populate(mapped);
|
||||
return mapped;
|
||||
}
|
||||
if (raw instanceof Edge e) {
|
||||
return mapper.mapEdge(e);
|
||||
}
|
||||
return raw;
|
||||
}
|
||||
|
||||
// --- Helpers ---
|
||||
|
||||
private static String resolveKey(Field field) {
|
||||
Alias alias = field.getAnnotation(Alias.class);
|
||||
return alias != null ? alias.value() : field.getName();
|
||||
}
|
||||
|
||||
private static List<Field> collectFields(Class<?> clazz) {
|
||||
List<Field> result = new ArrayList<>();
|
||||
Class<?> cursor = clazz;
|
||||
while (cursor != null && cursor != Object.class) {
|
||||
for (Field f : cursor.getDeclaredFields()) {
|
||||
int mod = f.getModifiers();
|
||||
if (!Modifier.isStatic(mod) && !f.isSynthetic()) result.add(f);
|
||||
}
|
||||
cursor = cursor.getSuperclass();
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
private static Class<?> getListElementType(Field field) {
|
||||
Type generic = field.getGenericType();
|
||||
if (generic instanceof ParameterizedType pt) {
|
||||
Type arg = pt.getActualTypeArguments()[0];
|
||||
if (arg instanceof Class<?> c) return c;
|
||||
}
|
||||
throw new ClothoConfigurationException(
|
||||
"Cannot determine element type of List field '" + field.getName() + "'");
|
||||
}
|
||||
|
||||
private static <T> T instantiate(Class<T> clazz) {
|
||||
try {
|
||||
var ctor = clazz.getDeclaredConstructor();
|
||||
ctor.setAccessible(true);
|
||||
return ctor.newInstance();
|
||||
} catch (Exception e) {
|
||||
throw new ClothoConfigurationException(
|
||||
clazz.getName() + " must have a no-arg constructor for Clotho to instantiate it", e);
|
||||
}
|
||||
}
|
||||
|
||||
private static void setField(Field field, Object instance, @Nullable Object value) {
|
||||
try {
|
||||
field.setAccessible(true);
|
||||
field.set(instance, value);
|
||||
} catch (IllegalAccessException e) {
|
||||
throw new ClothoConfigurationException(
|
||||
"Cannot set field '" + field.getName() + "' on "
|
||||
+ instance.getClass().getName(), e);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,4 @@
|
||||
@NullMarked
|
||||
package com.binarygolem.clotho.mapping;
|
||||
|
||||
import org.jspecify.annotations.NullMarked;
|
||||
@@ -0,0 +1,21 @@
|
||||
package com.binarygolem.clotho.model;
|
||||
|
||||
/**
|
||||
* Typed wrapper for an ArcadeDB record ID (e.g. {@code #10:0}).
|
||||
* Null ARID means the element has not yet been persisted.
|
||||
*/
|
||||
public record ARID(String value) {
|
||||
|
||||
public static ARID of(String value) {
|
||||
return new ARID(value);
|
||||
}
|
||||
|
||||
public String asString() {
|
||||
return value;
|
||||
}
|
||||
|
||||
@Override
|
||||
public String toString() {
|
||||
return value;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,26 @@
|
||||
package com.binarygolem.clotho.model;
|
||||
|
||||
import lombok.Getter;
|
||||
import lombok.Setter;
|
||||
import org.jspecify.annotations.Nullable;
|
||||
|
||||
/**
|
||||
* Base class for all Clotho-managed edge types.
|
||||
* Annotate concrete subclasses with {@code @EdgeType}.
|
||||
*
|
||||
* <p>Carries the ARIDs of the out-vertex and in-vertex so that edges are
|
||||
* always independently addressable, even when the adjacent vertices are
|
||||
* not loaded.
|
||||
*/
|
||||
public abstract class ClothoEdge extends ClothoEntity {
|
||||
|
||||
/** ARID of the vertex at the tail (source) of this edge. */
|
||||
@Getter
|
||||
@Setter
|
||||
private @Nullable ARID outVertexId;
|
||||
|
||||
/** ARID of the vertex at the head (target) of this edge. */
|
||||
@Getter
|
||||
@Setter
|
||||
private @Nullable ARID inVertexId;
|
||||
}
|
||||
@@ -0,0 +1,120 @@
|
||||
package com.binarygolem.clotho.model;
|
||||
|
||||
import com.binarygolem.clotho.annotation.EdgeType;
|
||||
import com.binarygolem.clotho.annotation.VertexType;
|
||||
import com.binarygolem.clotho.exception.ClothoConfigurationException;
|
||||
import lombok.Getter;
|
||||
import lombok.Setter;
|
||||
import org.jspecify.annotations.Nullable;
|
||||
|
||||
import java.util.Collections;
|
||||
import java.util.LinkedHashMap;
|
||||
import java.util.LinkedHashSet;
|
||||
import java.util.Map;
|
||||
import java.util.Set;
|
||||
|
||||
// NOPMD — EntityState is in the same package; explicit import needed by the compiler
|
||||
|
||||
/**
|
||||
* Base class for all Clotho-managed graph elements.
|
||||
* Carries identity ({@link ARID}), label, lifecycle state, dirty-field tracking,
|
||||
* and raw property access.
|
||||
*
|
||||
* <p>All {@code @VertexType} classes extend {@link ClothoVertex};
|
||||
* all {@code @EdgeType} classes extend {@link ClothoEdge}.
|
||||
*
|
||||
* <h3>Dirty tracking</h3>
|
||||
* Subclasses must call {@link #notifyFieldChanged(String)} from every manual setter
|
||||
* on tracked fields ({@code @Property}, {@code @Include}, {@code @OutVertex},
|
||||
* {@code @InVertex}). Do NOT use Lombok {@code @Setter} on those fields — write
|
||||
* the setter by hand. Notification is a no-op when the entity is not
|
||||
* {@link EntityState#MANAGED}, so calls during construction or hydration are safe.
|
||||
*/
|
||||
public abstract class ClothoEntity {
|
||||
|
||||
/** ArcadeDB record ID. Null until the element is persisted. */
|
||||
@Getter
|
||||
@Setter
|
||||
private @Nullable ARID id;
|
||||
|
||||
@Getter
|
||||
private EntityState state = EntityState.NEW;
|
||||
|
||||
private final Set<String> dirtyFields = new LinkedHashSet<>();
|
||||
|
||||
private final Map<String, @Nullable Object> rawProperties = new LinkedHashMap<>();
|
||||
|
||||
// --- Lifecycle (framework-internal: called from session and mapping layer) ---
|
||||
|
||||
public void setState(EntityState state) {
|
||||
this.state = state;
|
||||
}
|
||||
|
||||
public Set<String> getDirtyFields() {
|
||||
return Collections.unmodifiableSet(dirtyFields);
|
||||
}
|
||||
|
||||
public void clearDirtyFields() {
|
||||
dirtyFields.clear();
|
||||
}
|
||||
|
||||
// --- Dirty notification (public: called from entity subclass setters) ---
|
||||
|
||||
/**
|
||||
* Record that a tracked field has changed. Call this from every manual setter:
|
||||
*
|
||||
* <pre>{@code
|
||||
* public void setName(String name) {
|
||||
* this.name = name;
|
||||
* notifyFieldChanged("name");
|
||||
* }
|
||||
* }</pre>
|
||||
*
|
||||
* No-op when the entity is not {@link EntityState#MANAGED} (construction, hydration).
|
||||
*/
|
||||
public void notifyFieldChanged(String fieldName) {
|
||||
if (state == EntityState.MANAGED) {
|
||||
dirtyFields.add(fieldName);
|
||||
}
|
||||
}
|
||||
|
||||
// --- Label ---
|
||||
|
||||
/**
|
||||
* Returns the ArcadeDB type name declared on this class via
|
||||
* {@code @VertexType} or {@code @EdgeType}.
|
||||
*
|
||||
* @throws ClothoConfigurationException if neither annotation is present
|
||||
*/
|
||||
public String getLabel() {
|
||||
Class<?> cls = getClass();
|
||||
VertexType vt = cls.getAnnotation(VertexType.class);
|
||||
if (vt != null) return vt.value();
|
||||
EdgeType et = cls.getAnnotation(EdgeType.class);
|
||||
if (et != null) return et.value();
|
||||
throw new ClothoConfigurationException(
|
||||
cls.getName() + " is not annotated with @VertexType or @EdgeType");
|
||||
}
|
||||
|
||||
public boolean hasLabel(String label) {
|
||||
return getLabel().equals(label);
|
||||
}
|
||||
|
||||
// --- Raw properties ---
|
||||
|
||||
/**
|
||||
* Returns the raw value of a graph property not mapped to a typed field.
|
||||
* Returns {@code null} if the property is absent.
|
||||
*/
|
||||
public @Nullable Object getProperty(String key) {
|
||||
return rawProperties.get(key);
|
||||
}
|
||||
|
||||
/**
|
||||
* For Clotho framework use only — called by {@code ElementMapper} when
|
||||
* mapping a Gremlin element to this instance. Not part of the public API.
|
||||
*/
|
||||
public void setRawProperty(String key, @Nullable Object value) {
|
||||
rawProperties.put(key, value);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,13 @@
|
||||
package com.binarygolem.clotho.model;
|
||||
|
||||
/**
|
||||
* Base class for all Clotho-managed vertex types.
|
||||
* Annotate concrete subclasses with {@code @VertexType}.
|
||||
*
|
||||
* <p>An instance represents either a single vertex (properties only)
|
||||
* or a composite subgraph rooted at that vertex when {@code @Include}
|
||||
* fields are declared.
|
||||
*/
|
||||
public abstract class ClothoVertex extends ClothoEntity {
|
||||
// Vertex-specific behaviour added in later phases.
|
||||
}
|
||||
@@ -0,0 +1,17 @@
|
||||
package com.binarygolem.clotho.model;
|
||||
|
||||
/**
|
||||
* Lifecycle state of a {@link ClothoEntity}.
|
||||
*
|
||||
* <ul>
|
||||
* <li>{@link #NEW} — constructed in Java, never persisted to the graph.</li>
|
||||
* <li>{@link #MANAGED} — loaded from the graph or successfully saved at least once.
|
||||
* Dirty-field tracking is active in this state.</li>
|
||||
* <li>{@link #DETACHED} — removed from the graph via {@code session.delete()}.</li>
|
||||
* </ul>
|
||||
*/
|
||||
public enum EntityState {
|
||||
NEW,
|
||||
MANAGED,
|
||||
DETACHED
|
||||
}
|
||||
@@ -0,0 +1,17 @@
|
||||
package com.binarygolem.clotho.model;
|
||||
|
||||
/**
|
||||
* Controls when an {@code @Include} field is populated.
|
||||
*
|
||||
* <ul>
|
||||
* <li>{@link #EAGER} — populated immediately as part of {@code SubgraphLoader.populate()}.
|
||||
* This is the default.</li>
|
||||
* <li>{@link #LAZY} — skipped during {@code populate()}; remains {@code null} / empty
|
||||
* until the developer calls {@code session.loadField(vertex, "fieldName")}
|
||||
* explicitly.</li>
|
||||
* </ul>
|
||||
*/
|
||||
public enum FetchType {
|
||||
EAGER,
|
||||
LAZY
|
||||
}
|
||||
@@ -0,0 +1,8 @@
|
||||
package com.binarygolem.clotho.model;
|
||||
|
||||
/**
|
||||
* Concrete ClothoEdge used when {@code UnknownTypeBehavior.GENERIC} is active
|
||||
* and no registered type matches the edge label. Carries only raw properties.
|
||||
*/
|
||||
public final class GenericEdge extends ClothoEdge {
|
||||
}
|
||||
@@ -0,0 +1,8 @@
|
||||
package com.binarygolem.clotho.model;
|
||||
|
||||
/**
|
||||
* Concrete ClothoVertex used when {@code UnknownTypeBehavior.GENERIC} is active
|
||||
* and no registered type matches the vertex label. Carries only raw properties.
|
||||
*/
|
||||
public final class GenericVertex extends ClothoVertex {
|
||||
}
|
||||
@@ -0,0 +1,11 @@
|
||||
package com.binarygolem.clotho.model;
|
||||
|
||||
/** Edge traversal direction for {@code @Via} / {@code @Direction} declarations. */
|
||||
public enum TraversalDirection {
|
||||
/** Follow outgoing edges (default). */
|
||||
OUT,
|
||||
/** Follow incoming edges. */
|
||||
IN,
|
||||
/** Follow edges in both directions. */
|
||||
BOTH
|
||||
}
|
||||
@@ -0,0 +1,26 @@
|
||||
package com.binarygolem.clotho.model;
|
||||
|
||||
/**
|
||||
* Controls what happens when a Gremlin result carries a vertex or edge label
|
||||
* that has no registered Clotho Java class.
|
||||
*/
|
||||
public enum UnknownTypeBehavior {
|
||||
|
||||
/**
|
||||
* Throw {@link com.binarygolem.clotho.exception.UnknownTypeException}.
|
||||
* Recommended default — fail loudly rather than silently losing data.
|
||||
*/
|
||||
STRICT,
|
||||
|
||||
/**
|
||||
* Instantiate the closest registered ancestor in the Java type hierarchy.
|
||||
* Subtype-specific fields will be null; common ancestor fields are populated.
|
||||
*/
|
||||
NEAREST_ANCESTOR,
|
||||
|
||||
/**
|
||||
* Wrap the element in a plain {@link ClothoVertex} or {@link ClothoEdge}
|
||||
* with only raw property access available via {@code getProperty()}.
|
||||
*/
|
||||
GENERIC
|
||||
}
|
||||
@@ -0,0 +1,4 @@
|
||||
@NullMarked
|
||||
package com.binarygolem.clotho.model;
|
||||
|
||||
import org.jspecify.annotations.NullMarked;
|
||||
@@ -0,0 +1,239 @@
|
||||
package com.binarygolem.clotho.registry;
|
||||
|
||||
import com.binarygolem.clotho.annotation.EdgeType;
|
||||
import com.binarygolem.clotho.annotation.VertexType;
|
||||
import com.binarygolem.clotho.exception.ClothoConfigurationException;
|
||||
import com.binarygolem.clotho.exception.UnknownTypeException;
|
||||
import com.binarygolem.clotho.model.ClothoEdge;
|
||||
import com.binarygolem.clotho.model.ClothoVertex;
|
||||
import com.binarygolem.clotho.model.GenericEdge;
|
||||
import com.binarygolem.clotho.model.GenericVertex;
|
||||
import com.binarygolem.clotho.model.UnknownTypeBehavior;
|
||||
import io.github.classgraph.ClassGraph;
|
||||
import io.github.classgraph.ClassInfo;
|
||||
import io.github.classgraph.ScanResult;
|
||||
|
||||
import java.util.Arrays;
|
||||
import java.util.Collections;
|
||||
import java.util.LinkedHashMap;
|
||||
import java.util.LinkedHashSet;
|
||||
import java.util.Map;
|
||||
import java.util.Optional;
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* Holds the label-to-class mapping for all registered {@code @VertexType} and
|
||||
* {@code @EdgeType} classes. Built once at startup; immutable after construction.
|
||||
*
|
||||
* <p>Use {@link #builder()} for manual registration or {@link #scan(String...)}
|
||||
* for automatic classpath scanning.
|
||||
*/
|
||||
public final class TypeRegistry {
|
||||
|
||||
private final Map<String, Class<? extends ClothoVertex>> vertexTypes;
|
||||
private final Map<String, Class<? extends ClothoEdge>> edgeTypes;
|
||||
// label → declared ArcadeDB parent labels, derived from registered annotations
|
||||
private final Map<String, Set<String>> parentLabels;
|
||||
|
||||
private TypeRegistry(
|
||||
Map<String, Class<? extends ClothoVertex>> vertexTypes,
|
||||
Map<String, Class<? extends ClothoEdge>> edgeTypes,
|
||||
Map<String, Set<String>> parentLabels) {
|
||||
this.vertexTypes = Collections.unmodifiableMap(vertexTypes);
|
||||
this.edgeTypes = Collections.unmodifiableMap(edgeTypes);
|
||||
this.parentLabels = Collections.unmodifiableMap(parentLabels);
|
||||
}
|
||||
|
||||
// --- Lookup ---
|
||||
|
||||
public Optional<Class<? extends ClothoVertex>> findVertex(String label) {
|
||||
return Optional.ofNullable(vertexTypes.get(label));
|
||||
}
|
||||
|
||||
public Optional<Class<? extends ClothoEdge>> findEdge(String label) {
|
||||
return Optional.ofNullable(edgeTypes.get(label));
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolves a vertex label to a class, applying {@code behavior} when the
|
||||
* label is not registered.
|
||||
*
|
||||
* <p>{@code NEAREST_ANCESTOR} traverses the parent-label chain built from
|
||||
* registered annotations. For labels whose parentage is entirely unknown
|
||||
* (no registered class declares them as a parent), it falls back to
|
||||
* {@link GenericVertex}.
|
||||
*/
|
||||
public Class<? extends ClothoVertex> resolveVertex(String label, UnknownTypeBehavior behavior) {
|
||||
Class<? extends ClothoVertex> found = vertexTypes.get(label);
|
||||
if (found != null) return found;
|
||||
return switch (behavior) {
|
||||
case STRICT -> throw new UnknownTypeException(label);
|
||||
case NEAREST_ANCESTOR -> findNearestVertexAncestor(label).orElse(GenericVertex.class);
|
||||
case GENERIC -> GenericVertex.class;
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolves an edge label to a class, applying {@code behavior} when the
|
||||
* label is not registered.
|
||||
*/
|
||||
public Class<? extends ClothoEdge> resolveEdge(String label, UnknownTypeBehavior behavior) {
|
||||
Class<? extends ClothoEdge> found = edgeTypes.get(label);
|
||||
if (found != null) return found;
|
||||
return switch (behavior) {
|
||||
case STRICT -> throw new UnknownTypeException(label);
|
||||
case NEAREST_ANCESTOR -> findNearestEdgeAncestor(label).orElse(GenericEdge.class);
|
||||
case GENERIC -> GenericEdge.class;
|
||||
};
|
||||
}
|
||||
|
||||
private Optional<Class<? extends ClothoVertex>> findNearestVertexAncestor(String label) {
|
||||
for (String parent : parentLabels.getOrDefault(label, Set.of())) {
|
||||
Class<? extends ClothoVertex> registered = vertexTypes.get(parent);
|
||||
if (registered != null) return Optional.of(registered);
|
||||
Optional<Class<? extends ClothoVertex>> ancestor = findNearestVertexAncestor(parent);
|
||||
if (ancestor.isPresent()) return ancestor;
|
||||
}
|
||||
return Optional.empty();
|
||||
}
|
||||
|
||||
private Optional<Class<? extends ClothoEdge>> findNearestEdgeAncestor(String label) {
|
||||
for (String parent : parentLabels.getOrDefault(label, Set.of())) {
|
||||
Class<? extends ClothoEdge> registered = edgeTypes.get(parent);
|
||||
if (registered != null) return Optional.of(registered);
|
||||
Optional<Class<? extends ClothoEdge>> ancestor = findNearestEdgeAncestor(parent);
|
||||
if (ancestor.isPresent()) return ancestor;
|
||||
}
|
||||
return Optional.empty();
|
||||
}
|
||||
|
||||
// --- Introspection ---
|
||||
|
||||
public Set<String> vertexLabels() {
|
||||
return vertexTypes.keySet();
|
||||
}
|
||||
|
||||
public Set<String> edgeLabels() {
|
||||
return edgeTypes.keySet();
|
||||
}
|
||||
|
||||
// --- Factory ---
|
||||
|
||||
public static Builder builder() {
|
||||
return new Builder();
|
||||
}
|
||||
|
||||
/**
|
||||
* Scans the given packages for {@code @VertexType} and {@code @EdgeType}
|
||||
* classes and registers them.
|
||||
*
|
||||
* @throws ClothoConfigurationException if a class is annotated but does not
|
||||
* extend the correct base type, or if
|
||||
* two classes share the same label
|
||||
*/
|
||||
public static TypeRegistry scan(String... packages) {
|
||||
Builder builder = builder();
|
||||
try (ScanResult result = new ClassGraph()
|
||||
.enableClassInfo()
|
||||
.enableAnnotationInfo()
|
||||
.acceptPackages(packages)
|
||||
.scan()) {
|
||||
|
||||
for (ClassInfo info : result.getClassesWithAnnotation(VertexType.class)) {
|
||||
Class<?> clazz = info.loadClass();
|
||||
if (!ClothoVertex.class.isAssignableFrom(clazz)) {
|
||||
throw new ClothoConfigurationException(
|
||||
clazz.getName() + " is annotated @VertexType but does not extend ClothoVertex");
|
||||
}
|
||||
@SuppressWarnings("unchecked")
|
||||
Class<? extends ClothoVertex> vertexClass = (Class<? extends ClothoVertex>) clazz;
|
||||
builder.registerVertex(vertexClass);
|
||||
}
|
||||
|
||||
for (ClassInfo info : result.getClassesWithAnnotation(EdgeType.class)) {
|
||||
Class<?> clazz = info.loadClass();
|
||||
if (!ClothoEdge.class.isAssignableFrom(clazz)) {
|
||||
throw new ClothoConfigurationException(
|
||||
clazz.getName() + " is annotated @EdgeType but does not extend ClothoEdge");
|
||||
}
|
||||
@SuppressWarnings("unchecked")
|
||||
Class<? extends ClothoEdge> edgeClass = (Class<? extends ClothoEdge>) clazz;
|
||||
builder.registerEdge(edgeClass);
|
||||
}
|
||||
}
|
||||
return builder.build();
|
||||
}
|
||||
|
||||
// --- Builder ---
|
||||
|
||||
public static final class Builder {
|
||||
|
||||
private final Map<String, Class<? extends ClothoVertex>> vertexTypes = new LinkedHashMap<>();
|
||||
private final Map<String, Class<? extends ClothoEdge>> edgeTypes = new LinkedHashMap<>();
|
||||
private final Map<String, Set<String>> parentLabels = new LinkedHashMap<>();
|
||||
|
||||
public Builder registerVertex(Class<? extends ClothoVertex> clazz) {
|
||||
VertexType annotation = clazz.getAnnotation(VertexType.class);
|
||||
if (annotation == null) {
|
||||
throw new ClothoConfigurationException(
|
||||
clazz.getName() + " is not annotated with @VertexType");
|
||||
}
|
||||
String label = annotation.value();
|
||||
Class<? extends ClothoVertex> existing = vertexTypes.put(label, clazz);
|
||||
if (existing != null && !existing.equals(clazz)) {
|
||||
throw new ClothoConfigurationException(
|
||||
"Duplicate vertex label '" + label + "': "
|
||||
+ existing.getName() + " and " + clazz.getName());
|
||||
}
|
||||
recordVertexParents(label, clazz, annotation);
|
||||
return this;
|
||||
}
|
||||
|
||||
public Builder registerEdge(Class<? extends ClothoEdge> clazz) {
|
||||
EdgeType annotation = clazz.getAnnotation(EdgeType.class);
|
||||
if (annotation == null) {
|
||||
throw new ClothoConfigurationException(
|
||||
clazz.getName() + " is not annotated with @EdgeType");
|
||||
}
|
||||
String label = annotation.value();
|
||||
Class<? extends ClothoEdge> existing = edgeTypes.put(label, clazz);
|
||||
if (existing != null && !existing.equals(clazz)) {
|
||||
throw new ClothoConfigurationException(
|
||||
"Duplicate edge label '" + label + "': "
|
||||
+ existing.getName() + " and " + clazz.getName());
|
||||
}
|
||||
return this;
|
||||
}
|
||||
|
||||
private void recordVertexParents(String label, Class<? extends ClothoVertex> clazz,
|
||||
VertexType annotation) {
|
||||
Set<String> parents = new LinkedHashSet<>();
|
||||
|
||||
String explicit = annotation.parentLabel();
|
||||
if (!explicit.isEmpty()) {
|
||||
// parentLabel overrides Java hierarchy
|
||||
parents.add(explicit);
|
||||
} else {
|
||||
// Infer primary parent from Java superclass if it's also a @VertexType
|
||||
Class<?> superclass = clazz.getSuperclass();
|
||||
if (superclass != null) {
|
||||
VertexType superAnnotation = superclass.getAnnotation(VertexType.class);
|
||||
if (superAnnotation != null) {
|
||||
parents.add(superAnnotation.value());
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// additionalParents covers ArcadeDB multi-inheritance beyond the Java chain
|
||||
parents.addAll(Arrays.asList(annotation.additionalParents()));
|
||||
|
||||
if (!parents.isEmpty()) {
|
||||
parentLabels.put(label, Collections.unmodifiableSet(parents));
|
||||
}
|
||||
}
|
||||
|
||||
public TypeRegistry build() {
|
||||
return new TypeRegistry(vertexTypes, edgeTypes, parentLabels);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,4 @@
|
||||
@NullMarked
|
||||
package com.binarygolem.clotho.registry;
|
||||
|
||||
import org.jspecify.annotations.NullMarked;
|
||||
@@ -0,0 +1,379 @@
|
||||
package com.binarygolem.clotho.repository;
|
||||
|
||||
import com.binarygolem.clotho.annotation.EdgeType;
|
||||
import com.binarygolem.clotho.annotation.VertexType;
|
||||
import com.binarygolem.clotho.exception.ClothoConfigurationException;
|
||||
import com.binarygolem.clotho.exception.ClothoException;
|
||||
import com.binarygolem.clotho.mapping.ElementMapper;
|
||||
import com.binarygolem.clotho.mapping.SubgraphLoader;
|
||||
import com.binarygolem.clotho.mapping.SubgraphPersistor;
|
||||
import com.binarygolem.clotho.mapping.SubgraphTypeAssembler;
|
||||
import com.binarygolem.clotho.model.ARID;
|
||||
import com.binarygolem.clotho.model.ClothoEdge;
|
||||
import com.binarygolem.clotho.model.ClothoEntity;
|
||||
import com.binarygolem.clotho.model.ClothoVertex;
|
||||
import com.binarygolem.clotho.session.ClothoSession;
|
||||
import com.binarygolem.clotho.session.ClothoSessionFactory;
|
||||
import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversal;
|
||||
import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversalSource;
|
||||
import org.apache.tinkerpop.gremlin.structure.Edge;
|
||||
import org.apache.tinkerpop.gremlin.structure.Vertex;
|
||||
import org.jspecify.annotations.Nullable;
|
||||
|
||||
import java.lang.reflect.ParameterizedType;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.function.UnaryOperator;
|
||||
|
||||
/**
|
||||
* Abstract base class for Clotho repositories.
|
||||
*
|
||||
* <p>Subclass this to define query methods for a specific {@link ClothoEntity} type.
|
||||
* Call {@link #g()} to obtain the live {@link GraphTraversalSource} and build TinkerPop
|
||||
* Java DSL traversals, then pass them to {@link #execute}, {@link #executeSubgraph}, or
|
||||
* {@link #executeRaw}. No Gremlin strings; no annotation proxies.
|
||||
*
|
||||
* <pre>{@code
|
||||
* @ClothoRepository
|
||||
* public class EmployeeRepo extends ClothoRepository<Employee> {
|
||||
*
|
||||
* public EmployeeRepo(ClothoSessionFactory factory) { super(factory); }
|
||||
*
|
||||
* public List<Employee> findByDept(String dept) {
|
||||
* return execute(g().V().has("Employee", "dept", dept));
|
||||
* }
|
||||
*
|
||||
* public List<Employee> findSenior() {
|
||||
* return findAll(t -> t.has("level", "SENIOR"));
|
||||
* }
|
||||
*
|
||||
* public long countByDept(String dept) {
|
||||
* return this.<Long>executeRaw(
|
||||
* g().V().hasLabel("Employee").has("dept", dept).count()
|
||||
* ).get(0);
|
||||
* }
|
||||
* }
|
||||
* }</pre>
|
||||
*
|
||||
* <p>The type parameter {@code T} is inferred from the generic superclass declaration.
|
||||
* Use the two-argument constructor when the entity class cannot be inferred (e.g. when
|
||||
* a second level of generic inheritance is involved).
|
||||
*
|
||||
* <p>Repositories are stateless (thread-safe) after construction. A single instance
|
||||
* per application is typical; Spring Boot users obtain them as beans via
|
||||
* {@code ClothoAutoConfiguration}.
|
||||
*/
|
||||
public abstract class ClothoRepository<T extends ClothoEntity> {
|
||||
|
||||
protected final Class<T> entityClass;
|
||||
|
||||
private final GraphTraversalSource g;
|
||||
private final ElementMapper mapper;
|
||||
private final SubgraphLoader loader;
|
||||
private final SubgraphPersistor persistor;
|
||||
private final SubgraphTypeAssembler assembler;
|
||||
|
||||
/**
|
||||
* Primary constructor. Infers the entity class {@code T} from the generic superclass
|
||||
* declaration ({@code class EmployeeRepo extends ClothoRepository<Employee>}).
|
||||
*
|
||||
* @throws ClothoConfigurationException if the generic type cannot be inferred
|
||||
*/
|
||||
@SuppressWarnings("unchecked")
|
||||
protected ClothoRepository(ClothoSessionFactory factory) {
|
||||
this.g = factory.traversal();
|
||||
this.mapper = factory.mapper();
|
||||
this.loader = factory.loader();
|
||||
this.persistor = factory.persistor();
|
||||
this.assembler = factory.assembler();
|
||||
try {
|
||||
ParameterizedType pt = (ParameterizedType) getClass().getGenericSuperclass();
|
||||
this.entityClass = (Class<T>) pt.getActualTypeArguments()[0];
|
||||
} catch (ClassCastException | ArrayIndexOutOfBoundsException e) {
|
||||
throw new ClothoConfigurationException(
|
||||
getClass().getName()
|
||||
+ " cannot infer entity type from generic superclass."
|
||||
+ " Use ClothoRepository(factory, Class<T>) instead.", e);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Fallback constructor for cases where the generic entity type cannot be inferred
|
||||
* automatically (e.g. multi-level generic inheritance).
|
||||
*/
|
||||
protected ClothoRepository(ClothoSessionFactory factory, Class<T> entityClass) {
|
||||
this.g = factory.traversal();
|
||||
this.mapper = factory.mapper();
|
||||
this.loader = factory.loader();
|
||||
this.persistor = factory.persistor();
|
||||
this.assembler = factory.assembler();
|
||||
this.entityClass = entityClass;
|
||||
}
|
||||
|
||||
// --- Traversal access ---
|
||||
|
||||
/**
|
||||
* Returns the live {@link GraphTraversalSource}.
|
||||
* Use this to build traversals inside repository methods:
|
||||
* <pre>{@code return execute(g().V().has("Employee", "dept", dept)); }</pre>
|
||||
*/
|
||||
protected GraphTraversalSource g() {
|
||||
return g;
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the base traversal for all entities of this repository's type.
|
||||
* Vertex repositories return {@code g().V().hasLabel(label)};
|
||||
* edge repositories return {@code g().E().hasLabel(label)}.
|
||||
*/
|
||||
protected GraphTraversal<?, ?> allEntities() {
|
||||
String label = getLabel();
|
||||
if (ClothoVertex.class.isAssignableFrom(entityClass)) {
|
||||
return g().V().hasLabel(label);
|
||||
}
|
||||
return g().E().hasLabel(label);
|
||||
}
|
||||
|
||||
// --- Execute ---
|
||||
|
||||
/**
|
||||
* Executes a traversal that produces vertices or edges, maps each result to its
|
||||
* most-specific registered Clotho type, and (for vertices) batch-populates all
|
||||
* {@code @Include} boundaries in a single set of Gremlin traversals.
|
||||
*/
|
||||
@SuppressWarnings("unchecked")
|
||||
public List<T> execute(GraphTraversal<?, ?> traversal) {
|
||||
List<?> raw = traversal.toList();
|
||||
|
||||
if (ClothoVertex.class.isAssignableFrom(entityClass)) {
|
||||
List<ClothoVertex> vertices = raw.stream()
|
||||
.filter(Vertex.class::isInstance)
|
||||
.map(item -> mapper.mapVertex((Vertex) item))
|
||||
.toList();
|
||||
loader.populateAll(vertices);
|
||||
return (List<T>) vertices;
|
||||
}
|
||||
|
||||
return raw.stream().map(item -> {
|
||||
if (item instanceof Vertex v) return (T) mapper.mapVertex(v);
|
||||
if (item instanceof Edge e) return (T) mapper.mapEdge(e);
|
||||
throw new ClothoException(
|
||||
"execute() expected Vertex or Edge results but got: "
|
||||
+ item.getClass().getName());
|
||||
}).toList();
|
||||
}
|
||||
|
||||
/**
|
||||
* Applies {@code filter} to {@code base} then executes the result.
|
||||
*
|
||||
* <pre>{@code
|
||||
* // Caller passes a filter that extends the base traversal:
|
||||
* findAll(t -> t.has("level", "SENIOR").has("dept", dept))
|
||||
* }</pre>
|
||||
*/
|
||||
public List<T> execute(GraphTraversal<?, ?> base, UnaryOperator<GraphTraversal<?, ?>> filter) {
|
||||
return execute(filter.apply(base));
|
||||
}
|
||||
|
||||
/**
|
||||
* Like {@link #execute(GraphTraversal)} but integrates with the session's identity map.
|
||||
* Vertices already cached by the session are returned as-is (same Java instance, tracked).
|
||||
* New vertices are populated and registered as MANAGED.
|
||||
*
|
||||
* <p>This guarantees that for any ARID there is exactly one Java instance per session —
|
||||
* mutations on returned objects are always tracked and auto-saved on close.
|
||||
*/
|
||||
@SuppressWarnings("unchecked")
|
||||
public List<T> execute(ClothoSession session, GraphTraversal<?, ?> traversal) {
|
||||
List<?> raw = traversal.toList();
|
||||
|
||||
if (ClothoVertex.class.isAssignableFrom(entityClass)) {
|
||||
List<ClothoVertex> result = new ArrayList<>();
|
||||
List<ClothoVertex> toPopulate = new ArrayList<>();
|
||||
|
||||
for (Object item : raw) {
|
||||
if (!(item instanceof Vertex v)) continue;
|
||||
ClothoVertex mapped = mapper.mapVertex(v);
|
||||
ARID id = mapped.getId();
|
||||
@Nullable ClothoVertex cached = id != null ? session.getCached(id) : null;
|
||||
if (cached != null) {
|
||||
result.add(cached);
|
||||
} else {
|
||||
result.add(mapped);
|
||||
toPopulate.add(mapped);
|
||||
}
|
||||
}
|
||||
|
||||
loader.populateAll(toPopulate);
|
||||
toPopulate.forEach(session::register);
|
||||
return (List<T>) result;
|
||||
}
|
||||
|
||||
return raw.stream().map(item -> {
|
||||
if (item instanceof Vertex v) return (T) mapper.mapVertex(v);
|
||||
if (item instanceof Edge e) return (T) mapper.mapEdge(e);
|
||||
throw new ClothoException(
|
||||
"execute() expected Vertex or Edge results but got: "
|
||||
+ item.getClass().getName());
|
||||
}).toList();
|
||||
}
|
||||
|
||||
/**
|
||||
* Convenience overload — applies {@code filter} first, then delegates to
|
||||
* {@link #execute(ClothoSession, GraphTraversal)}.
|
||||
*/
|
||||
public List<T> execute(ClothoSession session, GraphTraversal<?, ?> base,
|
||||
UnaryOperator<GraphTraversal<?, ?>> filter) {
|
||||
return execute(session, filter.apply(base));
|
||||
}
|
||||
|
||||
/**
|
||||
* Executes a {@code select()}-producing traversal and assembles each row into an
|
||||
* instance of {@code subgraphType} via {@link SubgraphTypeAssembler}.
|
||||
*
|
||||
* <pre>{@code
|
||||
* executeSubgraph(EmployeeProfile.class,
|
||||
* g().V().has("Employee","id",id).as("employee")
|
||||
* .out("MANAGED_BY").as("manager")
|
||||
* .select("employee","manager"))
|
||||
* }</pre>
|
||||
*/
|
||||
@SuppressWarnings("unchecked")
|
||||
public <S> List<S> executeSubgraph(Class<S> subgraphType, GraphTraversal<?, ?> traversal) {
|
||||
return traversal.toList().stream()
|
||||
.map(item -> {
|
||||
if (item instanceof Map<?, ?> m) {
|
||||
return assembler.assemble(subgraphType, (Map<String, Object>) m);
|
||||
}
|
||||
throw new ClothoException(
|
||||
"executeSubgraph() expected Map results but got: "
|
||||
+ item.getClass().getName());
|
||||
})
|
||||
.toList();
|
||||
}
|
||||
|
||||
/**
|
||||
* Executes a traversal and returns the raw results without any Clotho mapping.
|
||||
* Use for scalar results such as counts, property values, or aggregations.
|
||||
*
|
||||
* <pre>{@code
|
||||
* long total = this.<Long>executeRaw(g().V().hasLabel("Employee").count()).get(0);
|
||||
* }</pre>
|
||||
*/
|
||||
@SuppressWarnings("unchecked")
|
||||
public <R> List<R> executeRaw(GraphTraversal<?, ?> traversal) {
|
||||
return (List<R>) traversal.toList();
|
||||
}
|
||||
|
||||
// --- Built-in operations ---
|
||||
|
||||
/** Returns all entities of this repository's type, with boundaries populated. */
|
||||
public List<T> findAll() {
|
||||
return execute(allEntities());
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns all entities matching the given filter, applied to the base
|
||||
* {@link #allEntities()} traversal.
|
||||
*/
|
||||
public List<T> findAll(UnaryOperator<GraphTraversal<?, ?>> filter) {
|
||||
return execute(allEntities(), filter);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the entity with the given ARID, or {@code null} if not found.
|
||||
* For vertices the {@code @Include} boundary is eagerly populated.
|
||||
*/
|
||||
@SuppressWarnings("unchecked")
|
||||
public @Nullable T findById(ARID id) {
|
||||
if (ClothoVertex.class.isAssignableFrom(entityClass)) {
|
||||
return g().V(id.asString()).tryNext()
|
||||
.map(v -> {
|
||||
ClothoVertex vertex = mapper.mapVertex(v);
|
||||
loader.populate(vertex);
|
||||
return (T) vertex;
|
||||
})
|
||||
.orElse(null);
|
||||
}
|
||||
return g().E(id.asString()).tryNext()
|
||||
.map(e -> (T) mapper.mapEdge(e))
|
||||
.orElse(null);
|
||||
}
|
||||
|
||||
/** Returns the total count of entities of this repository's type. */
|
||||
public long count() {
|
||||
return (long) allEntities().count().next();
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the count of entities matching the given filter, applied to
|
||||
* the base {@link #allEntities()} traversal.
|
||||
*/
|
||||
public long count(UnaryOperator<GraphTraversal<?, ?>> filter) {
|
||||
return (long) filter.apply(allEntities()).count().next();
|
||||
}
|
||||
|
||||
/** Returns a page of entities sorted in traversal order. */
|
||||
public List<T> findWithPagination(long offset, long limit) {
|
||||
return execute(allEntities().range(offset, offset + limit));
|
||||
}
|
||||
|
||||
/** Returns a filtered page of entities. */
|
||||
public List<T> findWithPagination(UnaryOperator<GraphTraversal<?, ?>> filter,
|
||||
long offset, long limit) {
|
||||
return execute(filter.apply(allEntities()).range(offset, offset + limit));
|
||||
}
|
||||
|
||||
// --- Persistence ---
|
||||
|
||||
/**
|
||||
* Persists the entity (create if ARID is null; update otherwise).
|
||||
* For vertices, cascades through {@code @Include} boundaries.
|
||||
*/
|
||||
public void save(T entity) {
|
||||
if (entity instanceof ClothoVertex v) {
|
||||
persistor.persist(v);
|
||||
} else if (entity instanceof ClothoEdge e) {
|
||||
persistor.persist(e);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Removes the entity from the graph.
|
||||
*
|
||||
* @throws ClothoException if the entity has no ARID
|
||||
*/
|
||||
public void delete(T entity) {
|
||||
ARID id = entity.getId();
|
||||
if (id == null) {
|
||||
throw new ClothoException(
|
||||
"Cannot delete unpersisted entity: " + entity.getClass().getName());
|
||||
}
|
||||
delete(id);
|
||||
}
|
||||
|
||||
/** Removes the entity with the given ARID from the graph. */
|
||||
public void delete(ARID id) {
|
||||
if (ClothoVertex.class.isAssignableFrom(entityClass)) {
|
||||
g().V(id.asString()).drop().iterate();
|
||||
} else {
|
||||
g().E(id.asString()).drop().iterate();
|
||||
}
|
||||
}
|
||||
|
||||
// --- Introspection ---
|
||||
|
||||
public Class<T> getEntityClass() {
|
||||
return entityClass;
|
||||
}
|
||||
|
||||
private String getLabel() {
|
||||
VertexType vt = entityClass.getAnnotation(VertexType.class);
|
||||
if (vt != null) return vt.value();
|
||||
EdgeType et = entityClass.getAnnotation(EdgeType.class);
|
||||
if (et != null) return et.value();
|
||||
throw new ClothoConfigurationException(
|
||||
entityClass.getName() + " has no @VertexType or @EdgeType annotation");
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,4 @@
|
||||
@NullMarked
|
||||
package com.binarygolem.clotho.repository;
|
||||
|
||||
import org.jspecify.annotations.NullMarked;
|
||||
@@ -0,0 +1,357 @@
|
||||
package com.binarygolem.clotho.session;
|
||||
|
||||
import com.binarygolem.clotho.exception.ClothoConfigurationException;
|
||||
import com.binarygolem.clotho.exception.ClothoException;
|
||||
import com.binarygolem.clotho.mapping.ElementMapper;
|
||||
import com.binarygolem.clotho.mapping.FieldMetadataCache;
|
||||
import com.binarygolem.clotho.mapping.SubgraphLoader;
|
||||
import com.binarygolem.clotho.mapping.SubgraphPersistor;
|
||||
import com.binarygolem.clotho.mapping.SubgraphTypeAssembler;
|
||||
import com.binarygolem.clotho.model.ARID;
|
||||
import com.binarygolem.clotho.model.ClothoEdge;
|
||||
import com.binarygolem.clotho.model.ClothoEntity;
|
||||
import com.binarygolem.clotho.model.ClothoVertex;
|
||||
import com.binarygolem.clotho.model.EntityState;
|
||||
import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversalSource;
|
||||
import org.jspecify.annotations.Nullable;
|
||||
|
||||
import java.lang.reflect.Field;
|
||||
import java.util.LinkedHashMap;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
|
||||
/**
|
||||
* A unit of work against the graph. Provides load/save/delete operations and
|
||||
* maintains a per-session identity map so that the same vertex or edge ARID
|
||||
* always resolves to the same Java instance within the session.
|
||||
*
|
||||
* <p>Obtain sessions from {@link ClothoSessionFactory#openSession()} or
|
||||
* {@link ClothoSessionFactory#openTransactionalSession()}.
|
||||
*
|
||||
* <p>Non-transactional sessions: {@link #close()} auto-saves dirty managed entities,
|
||||
* clears the identity map, and unbinds the thread-local {@link SessionContext}.
|
||||
*
|
||||
* <p>Transactional sessions: all graph operations execute within a single ArcadeDB
|
||||
* transaction. {@link #close()} auto-saves then commits; any exception during auto-save
|
||||
* triggers a rollback. Call {@link #rollback()} explicitly to abort without saving.
|
||||
*
|
||||
* <p>When {@link ClothoSessionFactory#openSession()} is called while a session is already
|
||||
* bound to the current thread (e.g., inside a {@code @Transactional} method), it returns
|
||||
* the existing session with a borrow count incremented. {@link #close()} on a borrowed
|
||||
* session is a no-op until all borrows are returned.
|
||||
*
|
||||
* <p>Sessions are NOT thread-safe. Use one session per thread / virtual thread.
|
||||
*/
|
||||
public class ClothoSession implements AutoCloseable {
|
||||
|
||||
private final GraphTraversalSource g;
|
||||
private final ElementMapper mapper;
|
||||
private final SubgraphLoader loader;
|
||||
private final SubgraphPersistor persistor;
|
||||
private final SubgraphTypeAssembler assembler;
|
||||
private final boolean transactional;
|
||||
private final boolean txSupported;
|
||||
|
||||
/** Decremented on each close(); real close only fires when it reaches 0. */
|
||||
private int openCount = 1;
|
||||
|
||||
private final Map<ARID, ClothoVertex> vertexCache = new LinkedHashMap<>();
|
||||
private final Map<ARID, ClothoEdge> edgeCache = new LinkedHashMap<>();
|
||||
|
||||
ClothoSession(GraphTraversalSource g, ElementMapper mapper,
|
||||
SubgraphLoader loader, SubgraphPersistor persistor,
|
||||
SubgraphTypeAssembler assembler,
|
||||
boolean transactional, boolean txSupported) {
|
||||
this.g = g;
|
||||
this.mapper = mapper;
|
||||
this.loader = loader;
|
||||
this.persistor = persistor;
|
||||
this.assembler = assembler;
|
||||
this.transactional = transactional;
|
||||
this.txSupported = txSupported;
|
||||
SessionContext.bind(this);
|
||||
}
|
||||
|
||||
// --- Load ---
|
||||
|
||||
/**
|
||||
* Loads the vertex with the given ID and eagerly populates its {@code @Include}
|
||||
* boundary. Returns the session-cached instance if already loaded.
|
||||
*
|
||||
* @throws ClothoException if no vertex with the given ID exists in the graph
|
||||
* @throws ClassCastException if the loaded vertex type is not assignable to {@code type}
|
||||
*/
|
||||
public <T extends ClothoVertex> T load(Class<T> type, ARID id) {
|
||||
@Nullable ClothoVertex cached = vertexCache.get(id);
|
||||
if (cached != null) {
|
||||
return type.cast(cached);
|
||||
}
|
||||
|
||||
ClothoVertex vertex = g.V(id.asString()).tryNext()
|
||||
.map(mapper::mapVertex)
|
||||
.orElseThrow(() -> new ClothoException("No vertex found with id: " + id));
|
||||
|
||||
loader.populate(vertex);
|
||||
markManaged(vertex);
|
||||
vertexCache.put(vertex.getId(), vertex);
|
||||
|
||||
return type.cast(vertex);
|
||||
}
|
||||
|
||||
/**
|
||||
* Loads the edge with the given ID. Returns the session-cached instance if already loaded.
|
||||
*
|
||||
* @throws ClothoException if no edge with the given ID exists in the graph
|
||||
* @throws ClassCastException if the loaded edge type is not assignable to {@code type}
|
||||
*/
|
||||
public <T extends ClothoEdge> T loadEdge(Class<T> type, ARID id) {
|
||||
@Nullable ClothoEdge cached = edgeCache.get(id);
|
||||
if (cached != null) {
|
||||
return type.cast(cached);
|
||||
}
|
||||
|
||||
ClothoEdge edge = g.E(id.asString()).tryNext()
|
||||
.map(mapper::mapEdge)
|
||||
.orElseThrow(() -> new ClothoException("No edge found with id: " + id));
|
||||
|
||||
markManaged(edge);
|
||||
edgeCache.put(edge.getId(), edge);
|
||||
|
||||
return type.cast(edge);
|
||||
}
|
||||
|
||||
// --- Save ---
|
||||
|
||||
/**
|
||||
* Persists a vertex and cascades through its {@code @Include} boundary.
|
||||
* Creates the vertex if its ARID is null; for managed vertices only dirty fields
|
||||
* are written. Adds the vertex to the session identity map.
|
||||
*/
|
||||
public void save(ClothoVertex vertex) {
|
||||
persistor.persist(vertex);
|
||||
markManaged(vertex);
|
||||
ARID id = vertex.getId();
|
||||
if (id != null) {
|
||||
vertexCache.put(id, vertex);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Persists an edge. Creates it if its ARID is null; for managed edges only dirty
|
||||
* fields are written.
|
||||
*/
|
||||
public void save(ClothoEdge edge) {
|
||||
persistor.persist(edge);
|
||||
markManaged(edge);
|
||||
ARID id = edge.getId();
|
||||
if (id != null) {
|
||||
edgeCache.put(id, edge);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Persists all {@link ClothoEntity} fields of a {@code @SubgraphType} instance.
|
||||
* The subgraph type itself has no ARID and is not cached.
|
||||
*/
|
||||
public void save(Object subgraphType) {
|
||||
persistor.persist(subgraphType);
|
||||
}
|
||||
|
||||
// --- Delete ---
|
||||
|
||||
/**
|
||||
* Removes the entity from the graph and evicts it from the session identity map.
|
||||
*
|
||||
* @throws ClothoException if the entity has no ARID (was never persisted)
|
||||
*/
|
||||
public void delete(ClothoEntity entity) {
|
||||
ARID id = entity.getId();
|
||||
if (id == null) {
|
||||
throw new ClothoException(
|
||||
"Cannot delete unpersisted entity: " + entity.getClass().getName());
|
||||
}
|
||||
if (entity instanceof ClothoVertex) {
|
||||
g.V(id.asString()).drop().iterate();
|
||||
vertexCache.remove(id);
|
||||
} else if (entity instanceof ClothoEdge) {
|
||||
g.E(id.asString()).drop().iterate();
|
||||
edgeCache.remove(id);
|
||||
}
|
||||
entity.setState(EntityState.DETACHED);
|
||||
}
|
||||
|
||||
// --- Lazy field loading ---
|
||||
|
||||
/**
|
||||
* Populates a single {@code @Include} field on demand — intended for fields
|
||||
* declared with {@link com.binarygolem.clotho.model.FetchType#LAZY} but usable
|
||||
* on any {@code @Include} field to force a refresh.
|
||||
*
|
||||
* @throws ClothoConfigurationException if no {@code @Include} field with the given
|
||||
* name exists on the vertex's class
|
||||
*/
|
||||
public void loadField(ClothoVertex vertex, String fieldName) {
|
||||
Field field = FieldMetadataCache.get(vertex.getClass()).allIncludeFields().stream()
|
||||
.filter(f -> f.getName().equals(fieldName))
|
||||
.findFirst()
|
||||
.orElseThrow(() -> new ClothoConfigurationException(
|
||||
"No @Include field '" + fieldName + "' on "
|
||||
+ vertex.getClass().getName()));
|
||||
loader.populateSingleField(vertex, field);
|
||||
}
|
||||
|
||||
// --- Assemble ---
|
||||
|
||||
/**
|
||||
* Assembles a {@code @SubgraphType} from a Gremlin {@code select()} result map.
|
||||
*/
|
||||
public <T> T assemble(Class<T> type, Map<String, Object> selectResult) {
|
||||
return assembler.assemble(type, selectResult);
|
||||
}
|
||||
|
||||
// --- Advanced ---
|
||||
|
||||
/**
|
||||
* Returns the underlying {@link GraphTraversalSource} for use by repositories
|
||||
* and advanced callers who need direct traversal access.
|
||||
* For transactional sessions this is the transaction-bound source.
|
||||
*/
|
||||
public GraphTraversalSource traversal() {
|
||||
return g;
|
||||
}
|
||||
|
||||
/** Returns {@code true} if this session was opened with transaction support. */
|
||||
public boolean isTransactional() {
|
||||
return transactional;
|
||||
}
|
||||
|
||||
/**
|
||||
* Evicts all loaded objects from the session identity map without touching the database.
|
||||
* Forces a fresh graph fetch on the next {@link #load} call for any previously-loaded ID.
|
||||
* Does NOT flush dirty fields — call {@link #save} explicitly before clearing if needed.
|
||||
*/
|
||||
public void clearCache() {
|
||||
vertexCache.clear();
|
||||
edgeCache.clear();
|
||||
}
|
||||
|
||||
/**
|
||||
* Rolls back the current transaction (if transactional), discards all pending changes,
|
||||
* clears the identity map, and unbinds this session from the current thread.
|
||||
* Safe to call on non-transactional sessions — pending changes are simply discarded.
|
||||
*/
|
||||
public void rollback() {
|
||||
openCount = 0;
|
||||
if (transactional && txSupported) {
|
||||
try { g.tx().rollback(); } catch (Exception ignored) {}
|
||||
}
|
||||
clearCache();
|
||||
SessionContext.unbind();
|
||||
}
|
||||
|
||||
/**
|
||||
* Auto-saves dirty managed entities, optionally commits the transaction, then
|
||||
* clears the identity map and unbinds this session from the current thread.
|
||||
*
|
||||
* <p>When this session is borrowed (obtained via {@link ClothoSessionFactory#openSession()}
|
||||
* while another session is already active), close() is a no-op until all borrows
|
||||
* are returned — the outermost owner does the real flush and commit.
|
||||
*
|
||||
* <p>If auto-save throws and this session is transactional, a rollback is attempted
|
||||
* before re-throwing.
|
||||
*/
|
||||
@Override
|
||||
public void close() {
|
||||
if (--openCount > 0) return;
|
||||
try {
|
||||
autoSave();
|
||||
if (transactional && txSupported) g.tx().commit();
|
||||
} catch (RuntimeException e) {
|
||||
if (transactional && txSupported) {
|
||||
try { g.tx().rollback(); } catch (Exception ignored) {}
|
||||
}
|
||||
throw e;
|
||||
} finally {
|
||||
clearCache();
|
||||
SessionContext.unbind();
|
||||
}
|
||||
}
|
||||
|
||||
// --- Registration ---
|
||||
|
||||
/**
|
||||
* Returns the cached vertex for {@code id} if one exists in this session's identity
|
||||
* map, or {@code null} if it has not been loaded yet.
|
||||
*/
|
||||
public @Nullable ClothoVertex getCached(ARID id) {
|
||||
return vertexCache.get(id);
|
||||
}
|
||||
|
||||
/**
|
||||
* Registers an already-hydrated vertex (and all entities reachable through its
|
||||
* {@code @Include} boundary) into this session's identity map as MANAGED.
|
||||
* After this call, dirty-field tracking and auto-save-on-close apply to the
|
||||
* vertex and every edge/adjacent vertex loaded with it.
|
||||
*
|
||||
* <p>Entities already cached by this session are skipped, so calling register()
|
||||
* on a graph with shared references is safe and cycle-free.
|
||||
*/
|
||||
public void register(ClothoVertex vertex) {
|
||||
if (vertex.getId() == null || vertexCache.containsKey(vertex.getId())) return;
|
||||
markManaged(vertex);
|
||||
vertexCache.put(vertex.getId(), vertex);
|
||||
|
||||
for (Field field : FieldMetadataCache.get(vertex.getClass()).allIncludeFields()) {
|
||||
Object value = readField(field, vertex);
|
||||
if (value instanceof List<?> list) {
|
||||
for (Object item : list) {
|
||||
if (item instanceof ClothoEdge e) registerEdge(e);
|
||||
else if (item instanceof ClothoVertex v) register(v);
|
||||
}
|
||||
} else if (value instanceof ClothoEdge e) registerEdge(e);
|
||||
else if (value instanceof ClothoVertex v) register(v);
|
||||
}
|
||||
}
|
||||
|
||||
private void registerEdge(ClothoEdge edge) {
|
||||
if (edge.getId() == null || edgeCache.containsKey(edge.getId())) return;
|
||||
markManaged(edge);
|
||||
edgeCache.put(edge.getId(), edge);
|
||||
|
||||
for (Field field : FieldMetadataCache.get(edge.getClass()).edgeVertexFields()) {
|
||||
Object value = readField(field, edge);
|
||||
if (value instanceof ClothoVertex v) register(v);
|
||||
}
|
||||
}
|
||||
|
||||
private static @Nullable Object readField(Field field, Object target) {
|
||||
try {
|
||||
field.setAccessible(true);
|
||||
return field.get(target);
|
||||
} catch (IllegalAccessException e) {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
// --- Internal ---
|
||||
|
||||
/** Increments the borrow count so the next close() call is a no-op. */
|
||||
void borrow() {
|
||||
openCount++;
|
||||
}
|
||||
|
||||
private void autoSave() {
|
||||
List<ClothoVertex> dirtyVertices = vertexCache.values().stream()
|
||||
.filter(v -> v.getState() == EntityState.MANAGED && !v.getDirtyFields().isEmpty())
|
||||
.toList();
|
||||
List<ClothoEdge> dirtyEdges = edgeCache.values().stream()
|
||||
.filter(e -> e.getState() == EntityState.MANAGED && !e.getDirtyFields().isEmpty())
|
||||
.toList();
|
||||
persistor.persistAllDirty(dirtyVertices, dirtyEdges);
|
||||
}
|
||||
|
||||
private static void markManaged(ClothoEntity entity) {
|
||||
entity.setState(EntityState.MANAGED);
|
||||
entity.clearDirtyFields();
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,174 @@
|
||||
package com.binarygolem.clotho.session;
|
||||
|
||||
import com.binarygolem.clotho.exception.ClothoException;
|
||||
import com.binarygolem.clotho.mapping.ElementMapper;
|
||||
import com.binarygolem.clotho.mapping.SubgraphLoader;
|
||||
import com.binarygolem.clotho.mapping.SubgraphPersistor;
|
||||
import com.binarygolem.clotho.mapping.SubgraphTypeAssembler;
|
||||
import com.binarygolem.clotho.model.TraversalDirection;
|
||||
import com.binarygolem.clotho.model.UnknownTypeBehavior;
|
||||
import com.binarygolem.clotho.registry.TypeRegistry;
|
||||
import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversalSource;
|
||||
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* Creates {@link ClothoSession} instances and provides shared stateless components to
|
||||
* {@link com.binarygolem.clotho.repository.ClothoRepository} subclasses.
|
||||
*
|
||||
* <p>Construct once at application startup via {@link #builder()}. Shared components
|
||||
* (mapper, loader, persistor, assembler) are created once and reused across all sessions
|
||||
* and repositories — they are all stateless after construction.
|
||||
*
|
||||
* <p>The factory does NOT manage the {@link GraphTraversalSource} lifecycle. The caller
|
||||
* is responsible for closing the connection at shutdown. Spring Boot users obtain the
|
||||
* factory as a bean via {@code ClothoAutoConfiguration}.
|
||||
*/
|
||||
public final class ClothoSessionFactory {
|
||||
|
||||
private final GraphTraversalSource g;
|
||||
private final TypeRegistry registry;
|
||||
private final UnknownTypeBehavior unknownTypeBehavior;
|
||||
private final TraversalDirection defaultDirection;
|
||||
|
||||
// Stateless components shared by all sessions and repositories
|
||||
private final ElementMapper mapper;
|
||||
private final SubgraphLoader loader;
|
||||
private final SubgraphPersistor persistor;
|
||||
private final SubgraphTypeAssembler assembler;
|
||||
|
||||
/** False when the graph rejects g.tx() calls (e.g. OrientDB with orient-transactional=false). */
|
||||
private final boolean graphSupportsTransactions;
|
||||
|
||||
private ClothoSessionFactory(GraphTraversalSource g, TypeRegistry registry,
|
||||
UnknownTypeBehavior unknownTypeBehavior,
|
||||
TraversalDirection defaultDirection) {
|
||||
this.g = g;
|
||||
this.registry = registry;
|
||||
this.unknownTypeBehavior = unknownTypeBehavior;
|
||||
this.defaultDirection = defaultDirection;
|
||||
this.mapper = new ElementMapper(registry, unknownTypeBehavior);
|
||||
this.loader = new SubgraphLoader(g, mapper, defaultDirection);
|
||||
this.persistor = new SubgraphPersistor(g);
|
||||
this.assembler = new SubgraphTypeAssembler(mapper, loader);
|
||||
this.graphSupportsTransactions = probeTransactionSupport(g);
|
||||
}
|
||||
|
||||
private static boolean probeTransactionSupport(GraphTraversalSource g) {
|
||||
// Verify basic connectivity first — propagates loudly if the server is unreachable.
|
||||
g.inject(0).toList();
|
||||
// If the server is reachable, any tx failure means the graph doesn't support transactions.
|
||||
try {
|
||||
g.tx().commit();
|
||||
return true;
|
||||
} catch (Exception ignored) {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
// --- Public API ---
|
||||
|
||||
/**
|
||||
* Opens a session. If a session is already bound to the current thread (e.g. the caller
|
||||
* is inside a {@code @Transactional} method), the existing session is borrowed and returned —
|
||||
* its {@code close()} is a no-op until all borrows are returned.
|
||||
*/
|
||||
public ClothoSession openSession() {
|
||||
ClothoSession existing = SessionContext.get();
|
||||
if (existing != null) {
|
||||
existing.borrow();
|
||||
return existing;
|
||||
}
|
||||
return new ClothoSession(g, mapper, loader, persistor, assembler, false, false);
|
||||
}
|
||||
|
||||
/**
|
||||
* Opens a session with transactional intent. Marks the session so that
|
||||
* {@link ClothoSession#close()} calls {@code g.tx().commit()} after the batch
|
||||
* auto-save, and {@link ClothoSession#rollback()} calls {@code g.tx().rollback()}.
|
||||
*
|
||||
* <p>With ArcadeDB over the Gremlin WebSocket interface, {@code g.tx().begin()}
|
||||
* returns a transaction-bound source but subsequent operations on it fail. For this
|
||||
* reason the session uses the same base {@link GraphTraversalSource} as non-transactional
|
||||
* sessions. The practical effect is that each Gremlin request is auto-committed by
|
||||
* ArcadeDB immediately. The auto-save batch at {@code close()} is still a single
|
||||
* request and therefore atomic as far as ArcadeDB is concerned.
|
||||
*
|
||||
* <p>The API is preserved so that {@link ClothoTransactionManager} wires correctly
|
||||
* into Spring {@code @Transactional}, and borrow semantics (nested
|
||||
* {@link #openSession()} calls returning the same session) still apply.
|
||||
*
|
||||
* <p>Prefer this via Spring's {@code @Transactional} and {@link ClothoTransactionManager}
|
||||
* rather than calling it directly.
|
||||
*/
|
||||
public ClothoSession openTransactionalSession() {
|
||||
return new ClothoSession(g, mapper, loader, persistor, assembler, true, graphSupportsTransactions);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the session currently bound to this thread.
|
||||
*
|
||||
* @throws ClothoException if no session is bound — call only within a {@code @Transactional}
|
||||
* method or an explicit {@code openSession()} block
|
||||
*/
|
||||
public ClothoSession getCurrentSession() {
|
||||
ClothoSession session = SessionContext.get();
|
||||
if (session == null) {
|
||||
throw new ClothoException(
|
||||
"No active Clotho session — call getCurrentSession() only within a @Transactional method");
|
||||
}
|
||||
return session;
|
||||
}
|
||||
|
||||
/** Returns the underlying traversal source. */
|
||||
public GraphTraversalSource traversal() {
|
||||
return g;
|
||||
}
|
||||
|
||||
// --- Component accessors: used by ClothoRepository ---
|
||||
|
||||
public ElementMapper mapper() { return mapper; }
|
||||
public SubgraphLoader loader() { return loader; }
|
||||
public SubgraphPersistor persistor() { return persistor; }
|
||||
public SubgraphTypeAssembler assembler() { return assembler; }
|
||||
|
||||
// --- Builder ---
|
||||
|
||||
public static Builder builder() {
|
||||
return new Builder();
|
||||
}
|
||||
|
||||
public static final class Builder {
|
||||
|
||||
private GraphTraversalSource g;
|
||||
private TypeRegistry registry;
|
||||
private UnknownTypeBehavior unknownTypeBehavior = UnknownTypeBehavior.STRICT;
|
||||
private TraversalDirection defaultDirection = TraversalDirection.OUT;
|
||||
|
||||
public Builder g(GraphTraversalSource g) {
|
||||
this.g = g;
|
||||
return this;
|
||||
}
|
||||
|
||||
public Builder registry(TypeRegistry registry) {
|
||||
this.registry = registry;
|
||||
return this;
|
||||
}
|
||||
|
||||
public Builder unknownTypeBehavior(UnknownTypeBehavior unknownTypeBehavior) {
|
||||
this.unknownTypeBehavior = unknownTypeBehavior;
|
||||
return this;
|
||||
}
|
||||
|
||||
public Builder defaultDirection(TraversalDirection defaultDirection) {
|
||||
this.defaultDirection = defaultDirection;
|
||||
return this;
|
||||
}
|
||||
|
||||
public ClothoSessionFactory build() {
|
||||
Objects.requireNonNull(g, "g (GraphTraversalSource) is required");
|
||||
Objects.requireNonNull(registry, "registry (TypeRegistry) is required");
|
||||
return new ClothoSessionFactory(g, registry, unknownTypeBehavior, defaultDirection);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,30 @@
|
||||
package com.binarygolem.clotho.session;
|
||||
|
||||
import org.jspecify.annotations.Nullable;
|
||||
|
||||
/**
|
||||
* Holds the {@link ClothoSession} bound to the current thread.
|
||||
*
|
||||
* <p>{@code bind} and {@code unbind} are package-private — only {@link ClothoSession}
|
||||
* calls them. {@link #get()} is public so that {@link
|
||||
* com.binarygolem.clotho.model.ClothoEntity#notifyFieldChanged} can reach the
|
||||
* active session without holding a direct reference.
|
||||
*/
|
||||
public final class SessionContext {
|
||||
|
||||
private static final ThreadLocal<ClothoSession> current = new ThreadLocal<>();
|
||||
|
||||
static void bind(ClothoSession session) {
|
||||
current.set(session);
|
||||
}
|
||||
|
||||
static void unbind() {
|
||||
current.remove();
|
||||
}
|
||||
|
||||
public static @Nullable ClothoSession get() {
|
||||
return current.get();
|
||||
}
|
||||
|
||||
private SessionContext() {}
|
||||
}
|
||||
@@ -0,0 +1,4 @@
|
||||
@NullMarked
|
||||
package com.binarygolem.clotho.session;
|
||||
|
||||
import org.jspecify.annotations.NullMarked;
|
||||
@@ -0,0 +1,6 @@
|
||||
package com.binarygolem.clotho.fixture;
|
||||
|
||||
import com.binarygolem.clotho.annotation.VertexType;
|
||||
|
||||
@VertexType("Employee")
|
||||
public class ScanEmployee extends ScanPerson {}
|
||||
@@ -0,0 +1,7 @@
|
||||
package com.binarygolem.clotho.fixture;
|
||||
|
||||
import com.binarygolem.clotho.annotation.VertexType;
|
||||
import com.binarygolem.clotho.model.ClothoVertex;
|
||||
|
||||
@VertexType("Person")
|
||||
public class ScanPerson extends ClothoVertex {}
|
||||
@@ -0,0 +1,7 @@
|
||||
package com.binarygolem.clotho.fixture;
|
||||
|
||||
import com.binarygolem.clotho.annotation.EdgeType;
|
||||
import com.binarygolem.clotho.model.ClothoEdge;
|
||||
|
||||
@EdgeType("WORKS_AT")
|
||||
public class ScanWorksAt extends ClothoEdge {}
|
||||
@@ -0,0 +1,213 @@
|
||||
package com.binarygolem.clotho.mapping;
|
||||
|
||||
import com.binarygolem.clotho.annotation.EdgeType;
|
||||
import com.binarygolem.clotho.annotation.Include;
|
||||
import com.binarygolem.clotho.annotation.Property;
|
||||
import com.binarygolem.clotho.annotation.VertexType;
|
||||
import com.binarygolem.clotho.annotation.Via;
|
||||
import com.binarygolem.clotho.exception.UnknownTypeException;
|
||||
import com.binarygolem.clotho.model.ClothoEdge;
|
||||
import com.binarygolem.clotho.model.ClothoVertex;
|
||||
import com.binarygolem.clotho.model.GenericVertex;
|
||||
import com.binarygolem.clotho.model.UnknownTypeBehavior;
|
||||
import com.binarygolem.clotho.registry.TypeRegistry;
|
||||
import org.apache.tinkerpop.gremlin.structure.Graph;
|
||||
import org.apache.tinkerpop.gremlin.structure.T;
|
||||
import org.apache.tinkerpop.gremlin.structure.Vertex;
|
||||
import org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerGraph;
|
||||
import org.junit.jupiter.api.BeforeEach;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
import static org.junit.jupiter.api.Assertions.*;
|
||||
|
||||
class ElementMapperTest {
|
||||
|
||||
// --- Fixture types ---
|
||||
|
||||
@VertexType("Employee")
|
||||
static class Employee extends ClothoVertex {
|
||||
@Property("name") String name;
|
||||
@Property("dept") String department;
|
||||
int age; // mapped by field name (simple type)
|
||||
@Include @Via("HAS_ADDRESS")
|
||||
Object address; // must be skipped
|
||||
}
|
||||
|
||||
@VertexType("HourlyEmployee")
|
||||
static class HourlyEmployee extends Employee {
|
||||
@Property("hourlyRate") double hourlyRate;
|
||||
}
|
||||
|
||||
@EdgeType("WORKS_AT")
|
||||
static class WorksAt extends ClothoEdge {
|
||||
@Property("role") String role;
|
||||
}
|
||||
|
||||
enum Status { ACTIVE, INACTIVE }
|
||||
|
||||
@VertexType("Contract")
|
||||
static class Contract extends ClothoVertex {
|
||||
Status status;
|
||||
long count;
|
||||
}
|
||||
|
||||
// --- Setup ---
|
||||
|
||||
private Graph graph;
|
||||
private TypeRegistry registry;
|
||||
private ElementMapper mapper;
|
||||
|
||||
@BeforeEach
|
||||
void setUp() {
|
||||
graph = TinkerGraph.open();
|
||||
registry = TypeRegistry.builder()
|
||||
.registerVertex(Employee.class)
|
||||
.registerVertex(HourlyEmployee.class)
|
||||
.registerVertex(Contract.class)
|
||||
.registerEdge(WorksAt.class)
|
||||
.build();
|
||||
mapper = new ElementMapper(registry, UnknownTypeBehavior.STRICT);
|
||||
}
|
||||
|
||||
// --- Vertex mapping ---
|
||||
|
||||
@Test
|
||||
void mapsAnnotatedPropertyFields() {
|
||||
Vertex v = graph.addVertex(T.label, "Employee", "name", "Alice", "dept", "Engineering");
|
||||
|
||||
Employee emp = (Employee) mapper.mapVertex(v);
|
||||
|
||||
assertEquals("Alice", emp.name);
|
||||
assertEquals("Engineering", emp.department);
|
||||
}
|
||||
|
||||
@Test
|
||||
void mapsFieldByNameWhenNoPropertyAnnotation() {
|
||||
Vertex v = graph.addVertex(T.label, "Employee", "name", "Bob", "age", 30);
|
||||
|
||||
Employee emp = (Employee) mapper.mapVertex(v);
|
||||
|
||||
assertEquals(30, emp.age);
|
||||
}
|
||||
|
||||
@Test
|
||||
void skipsIncludeAnnotatedFields() {
|
||||
Vertex v = graph.addVertex(T.label, "Employee", "name", "Carol", "address", "ignored");
|
||||
|
||||
Employee emp = (Employee) mapper.mapVertex(v);
|
||||
|
||||
// address field must not be populated by the ElementMapper — SubgraphLoader does it
|
||||
assertNull(emp.address);
|
||||
// "address" should end up in raw properties since the field was skipped
|
||||
assertEquals("ignored", emp.getProperty("address"));
|
||||
}
|
||||
|
||||
@Test
|
||||
void setsAridFromElementId() {
|
||||
Vertex v = graph.addVertex(T.label, "Employee");
|
||||
|
||||
Employee emp = (Employee) mapper.mapVertex(v);
|
||||
|
||||
assertNotNull(emp.getId());
|
||||
assertEquals(v.id().toString(), emp.getId().asString());
|
||||
}
|
||||
|
||||
@Test
|
||||
void storesUnmappedPropertiesAsRaw() {
|
||||
Vertex v = graph.addVertex(T.label, "Employee", "name", "Dan", "unmapped", "extra");
|
||||
|
||||
Employee emp = (Employee) mapper.mapVertex(v);
|
||||
|
||||
assertEquals("extra", emp.getProperty("unmapped"));
|
||||
}
|
||||
|
||||
@Test
|
||||
void returnsMostSpecificSubtype() {
|
||||
Vertex v = graph.addVertex(T.label, "HourlyEmployee", "name", "Eve", "hourlyRate", 25.5);
|
||||
|
||||
ClothoVertex result = mapper.mapVertex(v);
|
||||
|
||||
assertInstanceOf(HourlyEmployee.class, result);
|
||||
assertEquals(25.5, ((HourlyEmployee) result).hourlyRate);
|
||||
}
|
||||
|
||||
@Test
|
||||
void mapsInheritedFields() {
|
||||
Vertex v = graph.addVertex(T.label, "HourlyEmployee", "name", "Frank", "dept", "Sales", "hourlyRate", 20.0);
|
||||
|
||||
HourlyEmployee emp = (HourlyEmployee) mapper.mapVertex(v);
|
||||
|
||||
assertEquals("Frank", emp.name);
|
||||
assertEquals("Sales", emp.department);
|
||||
assertEquals(20.0, emp.hourlyRate);
|
||||
}
|
||||
|
||||
// --- Type coercion ---
|
||||
|
||||
@Test
|
||||
void coercesIntegerToLong() {
|
||||
// TinkerGraph stores 42 as Integer; Contract.count is long
|
||||
Vertex v = graph.addVertex(T.label, "Contract", "count", 42);
|
||||
|
||||
Contract c = (Contract) mapper.mapVertex(v);
|
||||
|
||||
assertEquals(42L, c.count);
|
||||
}
|
||||
|
||||
@Test
|
||||
void coercesStringToEnum() {
|
||||
Vertex v = graph.addVertex(T.label, "Contract", "status", "ACTIVE");
|
||||
|
||||
Contract c = (Contract) mapper.mapVertex(v);
|
||||
|
||||
assertEquals(Status.ACTIVE, c.status);
|
||||
}
|
||||
|
||||
// --- Edge mapping ---
|
||||
|
||||
@Test
|
||||
void mapsEdgePropertiesAndVertexIds() {
|
||||
Vertex out = graph.addVertex(T.label, "Employee");
|
||||
Vertex in = graph.addVertex(T.label, "Company");
|
||||
var edge = out.addEdge("WORKS_AT", in, "role", "Engineer");
|
||||
|
||||
WorksAt w = (WorksAt) mapper.mapEdge(edge);
|
||||
|
||||
assertEquals("Engineer", w.role);
|
||||
assertNotNull(w.getOutVertexId());
|
||||
assertNotNull(w.getInVertexId());
|
||||
assertEquals(out.id().toString(), w.getOutVertexId().asString());
|
||||
assertEquals(in.id().toString(), w.getInVertexId().asString());
|
||||
}
|
||||
|
||||
@Test
|
||||
void setsEdgeArid() {
|
||||
Vertex out = graph.addVertex(T.label, "Employee");
|
||||
Vertex in = graph.addVertex(T.label, "Company");
|
||||
var edge = out.addEdge("WORKS_AT", in);
|
||||
|
||||
WorksAt w = (WorksAt) mapper.mapEdge(edge);
|
||||
|
||||
assertNotNull(w.getId());
|
||||
}
|
||||
|
||||
// --- UnknownTypeBehavior ---
|
||||
|
||||
@Test
|
||||
void strictThrowsForUnknownLabel() {
|
||||
Vertex v = graph.addVertex(T.label, "Unknown");
|
||||
|
||||
assertThrows(UnknownTypeException.class, () -> mapper.mapVertex(v));
|
||||
}
|
||||
|
||||
@Test
|
||||
void genericReturnsGenericVertex() {
|
||||
ElementMapper genericMapper = new ElementMapper(registry, UnknownTypeBehavior.GENERIC);
|
||||
Vertex v = graph.addVertex(T.label, "Unknown", "key", "value");
|
||||
|
||||
ClothoVertex result = genericMapper.mapVertex(v);
|
||||
|
||||
assertInstanceOf(GenericVertex.class, result);
|
||||
assertEquals("value", result.getProperty("key"));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,246 @@
|
||||
package com.binarygolem.clotho.mapping;
|
||||
|
||||
import com.binarygolem.clotho.annotation.Direction;
|
||||
import com.binarygolem.clotho.annotation.EdgeType;
|
||||
import com.binarygolem.clotho.annotation.Include;
|
||||
import com.binarygolem.clotho.annotation.InVertex;
|
||||
import com.binarygolem.clotho.annotation.OutVertex;
|
||||
import com.binarygolem.clotho.annotation.Property;
|
||||
import com.binarygolem.clotho.annotation.VertexType;
|
||||
import com.binarygolem.clotho.annotation.Via;
|
||||
import com.binarygolem.clotho.exception.ClothoConfigurationException;
|
||||
import com.binarygolem.clotho.model.ClothoEdge;
|
||||
import com.binarygolem.clotho.model.ClothoVertex;
|
||||
import com.binarygolem.clotho.model.TraversalDirection;
|
||||
import com.binarygolem.clotho.model.UnknownTypeBehavior;
|
||||
import com.binarygolem.clotho.registry.TypeRegistry;
|
||||
import org.apache.commons.configuration2.BaseConfiguration;
|
||||
import org.apache.commons.configuration2.Configuration;
|
||||
import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversalSource;
|
||||
import org.apache.tinkerpop.gremlin.structure.Graph;
|
||||
import org.apache.tinkerpop.gremlin.structure.T;
|
||||
import org.apache.tinkerpop.gremlin.structure.Vertex;
|
||||
import org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerGraph;
|
||||
import org.junit.jupiter.api.BeforeEach;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
import java.util.List;
|
||||
|
||||
import static org.junit.jupiter.api.Assertions.*;
|
||||
|
||||
class SubgraphLoaderTest {
|
||||
|
||||
// --- Fixture types ---
|
||||
|
||||
@VertexType("Employee")
|
||||
static class Employee extends ClothoVertex {
|
||||
@Property("name") String name;
|
||||
|
||||
@Include @Via("HAS_ADDRESS")
|
||||
Address address;
|
||||
|
||||
@Include @Via("TAGGED_WITH")
|
||||
List<Tag> tags;
|
||||
|
||||
@Include @Via("MANAGED_BY") @Direction(TraversalDirection.IN)
|
||||
List<Employee> reports;
|
||||
}
|
||||
|
||||
@VertexType("Address")
|
||||
static class Address extends ClothoVertex {
|
||||
@Property("street") String street;
|
||||
}
|
||||
|
||||
@VertexType("Tag")
|
||||
static class Tag extends ClothoVertex {
|
||||
@Property("value") String value;
|
||||
}
|
||||
|
||||
@EdgeType("WORKS_AT")
|
||||
static class WorksAt extends ClothoEdge {
|
||||
@Property("role") String role;
|
||||
@OutVertex Employee employee;
|
||||
@InVertex Company company;
|
||||
}
|
||||
|
||||
@VertexType("Bad")
|
||||
static class BadVertex extends ClothoVertex {
|
||||
@Include // missing @Via — triggers validation error in SubgraphLoader
|
||||
Address address;
|
||||
}
|
||||
|
||||
@VertexType("Company")
|
||||
static class Company extends ClothoVertex {
|
||||
@Property("name") String name;
|
||||
|
||||
@Include @Via("WORKS_AT") @Direction(TraversalDirection.IN)
|
||||
List<WorksAt> staff;
|
||||
}
|
||||
|
||||
// --- Setup ---
|
||||
|
||||
private Graph graph;
|
||||
private GraphTraversalSource g;
|
||||
private TypeRegistry registry;
|
||||
private ElementMapper mapper;
|
||||
private SubgraphLoader loader;
|
||||
|
||||
@BeforeEach
|
||||
void setUp() {
|
||||
Configuration conf = new BaseConfiguration();
|
||||
conf.setProperty(TinkerGraph.GREMLIN_TINKERGRAPH_VERTEX_ID_MANAGER, "ANY");
|
||||
conf.setProperty(TinkerGraph.GREMLIN_TINKERGRAPH_EDGE_ID_MANAGER, "ANY");
|
||||
graph = TinkerGraph.open(conf);
|
||||
g = graph.traversal();
|
||||
|
||||
registry = TypeRegistry.builder()
|
||||
.registerVertex(Employee.class)
|
||||
.registerVertex(Address.class)
|
||||
.registerVertex(Tag.class)
|
||||
.registerVertex(Company.class)
|
||||
.registerEdge(WorksAt.class)
|
||||
.build();
|
||||
mapper = new ElementMapper(registry, UnknownTypeBehavior.STRICT);
|
||||
loader = new SubgraphLoader(g, mapper, TraversalDirection.OUT);
|
||||
}
|
||||
|
||||
// --- Single vertex @Include field ---
|
||||
|
||||
@Test
|
||||
void loadsSingleVertexIncludeField() {
|
||||
Vertex empV = graph.addVertex(T.id, "emp-1", T.label, "Employee", "name", "Alice");
|
||||
Vertex addrV = graph.addVertex(T.id, "addr-1", T.label, "Address", "street", "1 Main St");
|
||||
empV.addEdge("HAS_ADDRESS", addrV);
|
||||
|
||||
Employee emp = (Employee) mapper.mapVertex(empV);
|
||||
loader.populate(emp);
|
||||
|
||||
assertNotNull(emp.address);
|
||||
assertEquals("1 Main St", emp.address.street);
|
||||
}
|
||||
|
||||
@Test
|
||||
void setsNullWhenNoEdgeExistsForSingleField() {
|
||||
Vertex empV = graph.addVertex(T.id, "emp-2", T.label, "Employee", "name", "Bob");
|
||||
|
||||
Employee emp = (Employee) mapper.mapVertex(empV);
|
||||
loader.populate(emp);
|
||||
|
||||
assertNull(emp.address);
|
||||
}
|
||||
|
||||
// --- List vertex @Include field ---
|
||||
|
||||
@Test
|
||||
void loadsListVertexIncludeField() {
|
||||
Vertex empV = graph.addVertex(T.id, "emp-3", T.label, "Employee", "name", "Carol");
|
||||
Vertex tag1 = graph.addVertex(T.id, "tag-1", T.label, "Tag", "value", "java");
|
||||
Vertex tag2 = graph.addVertex(T.id, "tag-2", T.label, "Tag", "value", "graph");
|
||||
empV.addEdge("TAGGED_WITH", tag1);
|
||||
empV.addEdge("TAGGED_WITH", tag2);
|
||||
|
||||
Employee emp = (Employee) mapper.mapVertex(empV);
|
||||
loader.populate(emp);
|
||||
|
||||
assertEquals(2, emp.tags.size());
|
||||
assertTrue(emp.tags.stream().map(t -> t.value).toList().containsAll(List.of("java", "graph")));
|
||||
}
|
||||
|
||||
@Test
|
||||
void setsEmptyListWhenNoEdgesExist() {
|
||||
Vertex empV = graph.addVertex(T.id, "emp-4", T.label, "Employee", "name", "Dan");
|
||||
|
||||
Employee emp = (Employee) mapper.mapVertex(empV);
|
||||
loader.populate(emp);
|
||||
|
||||
assertNotNull(emp.tags);
|
||||
assertTrue(emp.tags.isEmpty());
|
||||
}
|
||||
|
||||
// --- Edge @Include field with @OutVertex / @InVertex ---
|
||||
|
||||
@Test
|
||||
void loadsEdgeFieldWithAdjacentVertices() {
|
||||
Vertex empV = graph.addVertex(T.id, "emp-5", T.label, "Employee", "name", "Eve");
|
||||
Vertex coV = graph.addVertex(T.id, "co-1", T.label, "Company", "name", "Acme");
|
||||
empV.addEdge("WORKS_AT", coV, "role", "Engineer");
|
||||
|
||||
Company company = (Company) mapper.mapVertex(coV);
|
||||
loader.populate(company);
|
||||
|
||||
assertEquals(1, company.staff.size());
|
||||
WorksAt edge = company.staff.get(0);
|
||||
assertEquals("Engineer", edge.role);
|
||||
assertNotNull(edge.employee);
|
||||
assertEquals("Eve", edge.employee.name);
|
||||
assertNotNull(edge.company);
|
||||
assertEquals("Acme", edge.company.name);
|
||||
}
|
||||
|
||||
// --- Direction ---
|
||||
|
||||
@Test
|
||||
void loadsInDirectionField() {
|
||||
Vertex manager = graph.addVertex(T.id, "mgr-1", T.label, "Employee", "name", "Grace");
|
||||
Vertex report = graph.addVertex(T.id, "rep-1", T.label, "Employee", "name", "Hank");
|
||||
report.addEdge("MANAGED_BY", manager);
|
||||
|
||||
Employee mgr = (Employee) mapper.mapVertex(manager);
|
||||
loader.populate(mgr);
|
||||
|
||||
assertEquals(1, mgr.reports.size());
|
||||
assertEquals("Hank", mgr.reports.get(0).name);
|
||||
}
|
||||
|
||||
// --- Multi-hop ---
|
||||
|
||||
@Test
|
||||
void loadsMultiHopBoundary() {
|
||||
Vertex empV = graph.addVertex(T.id, "emp-6", T.label, "Employee", "name", "Ivy");
|
||||
Vertex addrV = graph.addVertex(T.id, "addr-2", T.label, "Address", "street", "2 Oak Ave");
|
||||
empV.addEdge("HAS_ADDRESS", addrV);
|
||||
Vertex tag = graph.addVertex(T.id, "tag-3", T.label, "Tag", "value", "remote");
|
||||
empV.addEdge("TAGGED_WITH", tag);
|
||||
|
||||
Employee emp = (Employee) mapper.mapVertex(empV);
|
||||
loader.populate(emp);
|
||||
|
||||
assertNotNull(emp.address);
|
||||
assertEquals("2 Oak Ave", emp.address.street);
|
||||
assertEquals(1, emp.tags.size());
|
||||
assertEquals("remote", emp.tags.get(0).value);
|
||||
}
|
||||
|
||||
// --- Cycle detection ---
|
||||
|
||||
@Test
|
||||
void doesNotLoopOnCyclicIncludes() {
|
||||
// Employee A manages Employee B who manages Employee A
|
||||
Vertex empA = graph.addVertex(T.id, "emp-a", T.label, "Employee", "name", "A");
|
||||
Vertex empB = graph.addVertex(T.id, "emp-b", T.label, "Employee", "name", "B");
|
||||
empB.addEdge("MANAGED_BY", empA); // B is managed by A
|
||||
empA.addEdge("MANAGED_BY", empB); // A is managed by B (cycle)
|
||||
|
||||
Employee a = (Employee) mapper.mapVertex(empA);
|
||||
assertDoesNotThrow(() -> loader.populate(a));
|
||||
|
||||
// A.reports contains B; B.reports contains A but stops there
|
||||
assertEquals(1, a.reports.size());
|
||||
assertEquals("B", a.reports.get(0).name);
|
||||
// B.reports should be populated but A won't be recursed again
|
||||
assertNotNull(a.reports.get(0).reports);
|
||||
}
|
||||
|
||||
// --- Validation ---
|
||||
|
||||
@Test
|
||||
void throwsWhenViaIsMissing() {
|
||||
Vertex v = graph.addVertex(T.id, "bad-1", T.label, "Bad");
|
||||
TypeRegistry reg = TypeRegistry.builder().registerVertex(BadVertex.class).build();
|
||||
ElementMapper m = new ElementMapper(reg, UnknownTypeBehavior.STRICT);
|
||||
SubgraphLoader sl = new SubgraphLoader(g, m, TraversalDirection.OUT);
|
||||
|
||||
BadVertex bad = (BadVertex) m.mapVertex(v);
|
||||
assertThrows(ClothoConfigurationException.class, () -> sl.populate(bad));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,491 @@
|
||||
package com.binarygolem.clotho.mapping;
|
||||
|
||||
import com.binarygolem.clotho.annotation.EdgeType;
|
||||
import com.binarygolem.clotho.annotation.Include;
|
||||
import com.binarygolem.clotho.annotation.InVertex;
|
||||
import com.binarygolem.clotho.annotation.OutVertex;
|
||||
import com.binarygolem.clotho.annotation.Property;
|
||||
import com.binarygolem.clotho.annotation.SubgraphType;
|
||||
import com.binarygolem.clotho.annotation.VertexType;
|
||||
import com.binarygolem.clotho.annotation.Via;
|
||||
import com.binarygolem.clotho.exception.ClothoConfigurationException;
|
||||
import com.binarygolem.clotho.model.ARID;
|
||||
import com.binarygolem.clotho.model.ClothoEdge;
|
||||
import com.binarygolem.clotho.model.ClothoVertex;
|
||||
import org.apache.commons.configuration2.BaseConfiguration;
|
||||
import org.apache.commons.configuration2.Configuration;
|
||||
import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversalSource;
|
||||
import org.apache.tinkerpop.gremlin.structure.Graph;
|
||||
import org.apache.tinkerpop.gremlin.structure.T;
|
||||
import org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerGraph;
|
||||
import org.junit.jupiter.api.BeforeEach;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
import com.binarygolem.clotho.annotation.Version;
|
||||
import com.binarygolem.clotho.exception.OptimisticLockException;
|
||||
import com.binarygolem.clotho.model.EntityState;
|
||||
|
||||
import java.util.List;
|
||||
|
||||
import static org.junit.jupiter.api.Assertions.*;
|
||||
|
||||
class SubgraphPersistorTest {
|
||||
|
||||
// --- Fixture types ---
|
||||
|
||||
@VertexType("Employee")
|
||||
static class Employee extends ClothoVertex {
|
||||
@Property("name") String name;
|
||||
|
||||
@Include @Via("HAS_ADDRESS")
|
||||
Address address;
|
||||
|
||||
@Include @Via("WORKS_AT")
|
||||
List<WorksAt> workHistory;
|
||||
}
|
||||
|
||||
@VertexType("Address")
|
||||
static class Address extends ClothoVertex {
|
||||
@Property("street") String street;
|
||||
}
|
||||
|
||||
@VertexType("Company")
|
||||
static class Company extends ClothoVertex {
|
||||
@Property("name") String name;
|
||||
}
|
||||
|
||||
@EdgeType("WORKS_AT")
|
||||
static class WorksAt extends ClothoEdge {
|
||||
@Property("role") String role;
|
||||
@OutVertex Employee employee;
|
||||
@InVertex Company company;
|
||||
}
|
||||
|
||||
@SubgraphType
|
||||
static class EmployeeProfile {
|
||||
Employee employee;
|
||||
Address address;
|
||||
}
|
||||
|
||||
static class NotSubgraphType {}
|
||||
|
||||
@VertexType("VersionedItem")
|
||||
static class VersionedItem extends ClothoVertex {
|
||||
@Property("label") String label;
|
||||
@Version Long version;
|
||||
|
||||
public void setLabel(String v) { this.label = v; notifyFieldChanged("label"); }
|
||||
}
|
||||
|
||||
// --- Setup ---
|
||||
|
||||
private Graph graph;
|
||||
private GraphTraversalSource g;
|
||||
private SubgraphPersistor persistor;
|
||||
|
||||
@BeforeEach
|
||||
void setUp() {
|
||||
Configuration conf = new BaseConfiguration();
|
||||
conf.setProperty(TinkerGraph.GREMLIN_TINKERGRAPH_VERTEX_ID_MANAGER, "ANY");
|
||||
conf.setProperty(TinkerGraph.GREMLIN_TINKERGRAPH_EDGE_ID_MANAGER, "ANY");
|
||||
graph = TinkerGraph.open(conf);
|
||||
g = graph.traversal();
|
||||
persistor = new SubgraphPersistor(g);
|
||||
}
|
||||
|
||||
// --- Vertex create ---
|
||||
|
||||
@Test
|
||||
void createsNewVertexAndSetsArid() {
|
||||
Employee emp = new Employee();
|
||||
emp.name = "Alice";
|
||||
|
||||
persistor.persist(emp);
|
||||
|
||||
assertNotNull(emp.getId());
|
||||
assertEquals(1L, g.V().hasLabel("Employee").has("name", "Alice").count().next());
|
||||
}
|
||||
|
||||
@Test
|
||||
void createsVertexWithoutProperties() {
|
||||
Employee emp = new Employee();
|
||||
|
||||
persistor.persist(emp);
|
||||
|
||||
assertNotNull(emp.getId());
|
||||
assertEquals(1L, g.V().hasLabel("Employee").count().next());
|
||||
}
|
||||
|
||||
// --- Vertex update ---
|
||||
|
||||
@Test
|
||||
void updatesExistingVertex() {
|
||||
graph.addVertex(T.id, "emp-1", T.label, "Employee", "name", "OldName");
|
||||
|
||||
Employee emp = new Employee();
|
||||
emp.setId(ARID.of("emp-1"));
|
||||
emp.name = "NewName";
|
||||
|
||||
persistor.persist(emp);
|
||||
|
||||
String stored = (String) g.V("emp-1").values("name").next();
|
||||
assertEquals("NewName", stored);
|
||||
}
|
||||
|
||||
// --- Edge create ---
|
||||
|
||||
@Test
|
||||
void createsNewEdgeUsingStoredVertexIds() {
|
||||
graph.addVertex(T.id, "emp-1", T.label, "Employee", "name", "Bob");
|
||||
graph.addVertex(T.id, "co-1", T.label, "Company", "name", "Acme");
|
||||
|
||||
WorksAt edge = new WorksAt();
|
||||
edge.setOutVertexId(ARID.of("emp-1"));
|
||||
edge.setInVertexId(ARID.of("co-1"));
|
||||
edge.role = "Engineer";
|
||||
|
||||
persistor.persist(edge);
|
||||
|
||||
assertNotNull(edge.getId());
|
||||
assertEquals(1L, g.E().hasLabel("WORKS_AT").has("role", "Engineer").count().next());
|
||||
}
|
||||
|
||||
@Test
|
||||
void createsNewEdgeUsingOutInVertexFields() {
|
||||
// Vertices already exist; edge references them via @OutVertex/@InVertex fields
|
||||
// (outVertexId/inVertexId are null — persisting should resolve them from the fields)
|
||||
graph.addVertex(T.id, "emp-field-1", T.label, "Employee", "name", "Carol");
|
||||
graph.addVertex(T.id, "co-field-1", T.label, "Company", "name", "Corp");
|
||||
|
||||
Employee emp = new Employee();
|
||||
emp.setId(ARID.of("emp-field-1"));
|
||||
|
||||
Company co = new Company();
|
||||
co.setId(ARID.of("co-field-1"));
|
||||
|
||||
WorksAt edge = new WorksAt();
|
||||
edge.employee = emp; // @OutVertex — ARID resolved from here
|
||||
edge.company = co; // @InVertex — ARID resolved from here
|
||||
edge.role = "Manager";
|
||||
|
||||
persistor.persist(edge);
|
||||
|
||||
assertNotNull(edge.getId());
|
||||
assertEquals(1L, g.E().hasLabel("WORKS_AT").has("role", "Manager").count().next());
|
||||
}
|
||||
|
||||
// --- Edge update ---
|
||||
|
||||
@Test
|
||||
void updatesExistingEdge() {
|
||||
var empV = graph.addVertex(T.id, "emp-2", T.label, "Employee");
|
||||
var coV = graph.addVertex(T.id, "co-2", T.label, "Company");
|
||||
// Explicit String ID so the edge can be looked up by string ARID later
|
||||
var e = empV.addEdge("WORKS_AT", coV, T.id, "e-update-1", "role", "OldRole");
|
||||
String edgeId = e.id().toString();
|
||||
|
||||
WorksAt edge = new WorksAt();
|
||||
edge.setId(ARID.of(edgeId));
|
||||
edge.role = "NewRole";
|
||||
|
||||
persistor.persist(edge);
|
||||
|
||||
String stored = (String) g.E(edgeId).values("role").next();
|
||||
assertEquals("NewRole", stored);
|
||||
}
|
||||
|
||||
// --- Cascade through @Include ---
|
||||
|
||||
@Test
|
||||
void cascadesPersistsIncludedVertex() {
|
||||
Employee emp = new Employee();
|
||||
emp.name = "Dan";
|
||||
Address addr = new Address();
|
||||
addr.street = "1 Main St";
|
||||
emp.address = addr;
|
||||
|
||||
persistor.persist(emp);
|
||||
|
||||
assertNotNull(emp.getId());
|
||||
assertNotNull(addr.getId());
|
||||
assertEquals(1L, g.V().hasLabel("Address").has("street", "1 Main St").count().next());
|
||||
}
|
||||
|
||||
@Test
|
||||
void cascadesPersistsIncludedEdgeList() {
|
||||
// Use an existing emp with a String ID so g.V(id) round-trips correctly in TinkerGraph.
|
||||
// (Auto-generated TinkerGraph IDs are Long; String lookup fails. Production ArcadeDB uses String RIDs.)
|
||||
graph.addVertex(T.id, "emp-cascade", T.label, "Employee", "name", "Eve");
|
||||
graph.addVertex(T.id, "co-3", T.label, "Company", "name", "Initech");
|
||||
|
||||
Employee emp = new Employee();
|
||||
emp.setId(ARID.of("emp-cascade"));
|
||||
emp.name = "Eve";
|
||||
|
||||
WorksAt edge = new WorksAt();
|
||||
edge.setInVertexId(ARID.of("co-3"));
|
||||
edge.role = "Dev";
|
||||
// outVertexId is null — wireRootIntoEdge should supply emp's ARID
|
||||
emp.workHistory = List.of(edge);
|
||||
|
||||
persistor.persist(emp);
|
||||
|
||||
assertNotNull(edge.getId());
|
||||
assertEquals(emp.getId(), edge.getOutVertexId());
|
||||
assertEquals(1L, g.E().hasLabel("WORKS_AT").has("role", "Dev").count().next());
|
||||
}
|
||||
|
||||
// --- Identity set prevents double-persist ---
|
||||
|
||||
@Test
|
||||
void doesNotPersistSameObjectTwice() {
|
||||
Address shared = new Address();
|
||||
shared.street = "Shared St";
|
||||
|
||||
Employee emp1 = new Employee();
|
||||
emp1.name = "Frank";
|
||||
emp1.address = shared;
|
||||
|
||||
Employee emp2 = new Employee();
|
||||
emp2.name = "Grace";
|
||||
emp2.address = shared; // same object reference
|
||||
|
||||
persistor.persist(emp1);
|
||||
// Now manually add emp2's address as the same shared object
|
||||
// Simulate a second persist call sharing the same address
|
||||
persistor.persist(emp2);
|
||||
|
||||
// shared address should appear exactly once in the graph
|
||||
// (emp2's persist uses a new identity set so shared gets persisted again — that's OK)
|
||||
// But within a single persist(emp1) call, the identity set is shared across the cascade
|
||||
assertEquals(1L, g.V().hasLabel("Address").has("street", "Shared St").count().next()
|
||||
+ g.V().hasLabel("Address").has("street", "Shared St").count().next() - 1);
|
||||
}
|
||||
|
||||
@Test
|
||||
void singlePersistCallDeduplicatesSharedObject() {
|
||||
Address shared = new Address();
|
||||
shared.street = "42 Loop Rd";
|
||||
shared.setId(ARID.of("addr-x"));
|
||||
|
||||
graph.addVertex(T.id, "addr-x", T.label, "Address", "street", "42 Loop Rd");
|
||||
|
||||
Employee emp = new Employee();
|
||||
emp.name = "Hank";
|
||||
emp.address = shared;
|
||||
|
||||
// persist(emp) should visit shared once even if the cascade tried to reach it multiple times
|
||||
// Here we just verify it doesn't throw and the ID is still set correctly
|
||||
assertDoesNotThrow(() -> persistor.persist(emp));
|
||||
}
|
||||
|
||||
// --- @SubgraphType ---
|
||||
|
||||
@Test
|
||||
void persistsSubgraphTypeDelegatingToEntityFields() {
|
||||
Employee emp = new Employee();
|
||||
emp.name = "Ivy";
|
||||
Address addr = new Address();
|
||||
addr.street = "99 Graph Blvd";
|
||||
|
||||
EmployeeProfile profile = new EmployeeProfile();
|
||||
profile.employee = emp;
|
||||
profile.address = addr;
|
||||
|
||||
persistor.persist(profile);
|
||||
|
||||
assertNotNull(emp.getId());
|
||||
assertNotNull(addr.getId());
|
||||
assertEquals(1L, g.V().hasLabel("Employee").has("name", "Ivy").count().next());
|
||||
assertEquals(1L, g.V().hasLabel("Address").has("street", "99 Graph Blvd").count().next());
|
||||
}
|
||||
|
||||
@Test
|
||||
void throwsWhenPersistingNonSubgraphType() {
|
||||
assertThrows(ClothoConfigurationException.class,
|
||||
() -> persistor.persist(new NotSubgraphType()));
|
||||
}
|
||||
|
||||
// --- Missing vertex IDs for edge ---
|
||||
|
||||
@Test
|
||||
void throwsWhenEdgeHasNoResolvableOutVertex() {
|
||||
WorksAt edge = new WorksAt();
|
||||
// No outVertexId, no @OutVertex field value, no @InVertex field value
|
||||
assertThrows(ClothoConfigurationException.class, () -> persistor.persist(edge));
|
||||
}
|
||||
|
||||
// --- persistAllDirty (batch update) ---
|
||||
|
||||
@Test
|
||||
void persistAllDirty_updatesAllDirtyVerticesInSingleCall() {
|
||||
graph.addVertex(T.id, "e-1", T.label, "Employee", "name", "Alice");
|
||||
graph.addVertex(T.id, "e-2", T.label, "Employee", "name", "Bob");
|
||||
|
||||
Employee alice = new Employee();
|
||||
alice.setId(ARID.of("e-1"));
|
||||
alice.name = "Alice Updated";
|
||||
alice.setState(EntityState.MANAGED);
|
||||
alice.notifyFieldChanged("name");
|
||||
|
||||
Employee bob = new Employee();
|
||||
bob.setId(ARID.of("e-2"));
|
||||
bob.name = "Bob Updated";
|
||||
bob.setState(EntityState.MANAGED);
|
||||
bob.notifyFieldChanged("name");
|
||||
|
||||
persistor.persistAllDirty(List.of(alice, bob), List.of());
|
||||
|
||||
assertEquals("Alice Updated", g.V("e-1").values("name").next());
|
||||
assertEquals("Bob Updated", g.V("e-2").values("name").next());
|
||||
assertTrue(alice.getDirtyFields().isEmpty(), "dirty fields must be cleared after batch");
|
||||
assertTrue(bob.getDirtyFields().isEmpty());
|
||||
}
|
||||
|
||||
@Test
|
||||
void persistAllDirty_updatesVertexAndEdgeTogether() {
|
||||
var empV = graph.addVertex(T.id, "e-3", T.label, "Employee", "name", "Carol");
|
||||
var coV = graph.addVertex(T.id, "c-1", T.label, "Company");
|
||||
empV.addEdge("WORKS_AT", coV, T.id, "wa-1", "role", "Dev");
|
||||
|
||||
Employee carol = new Employee();
|
||||
carol.setId(ARID.of("e-3"));
|
||||
carol.name = "Carol Updated";
|
||||
carol.setState(EntityState.MANAGED);
|
||||
carol.notifyFieldChanged("name");
|
||||
|
||||
WorksAt edge = new WorksAt();
|
||||
edge.setId(ARID.of("wa-1"));
|
||||
edge.role = "Senior Dev";
|
||||
edge.setState(EntityState.MANAGED);
|
||||
edge.notifyFieldChanged("role");
|
||||
|
||||
persistor.persistAllDirty(List.of(carol), List.of(edge));
|
||||
|
||||
assertEquals("Carol Updated", g.V("e-3").values("name").next());
|
||||
assertEquals("Senior Dev", g.E("wa-1").values("role").next());
|
||||
}
|
||||
|
||||
@Test
|
||||
void persistAllDirty_emptyInputIsNoOp() {
|
||||
assertDoesNotThrow(() -> persistor.persistAllDirty(List.of(), List.of()));
|
||||
}
|
||||
|
||||
@Test
|
||||
void persistAllDirty_skipsEntitiesWithNoDirtyFields() {
|
||||
graph.addVertex(T.id, "e-4", T.label, "Employee", "name", "Dave");
|
||||
|
||||
Employee dave = new Employee();
|
||||
dave.setId(ARID.of("e-4"));
|
||||
dave.name = "Should Not Change";
|
||||
dave.setState(EntityState.MANAGED);
|
||||
// No notifyFieldChanged() — getDirtyFields() is empty
|
||||
|
||||
persistor.persistAllDirty(List.of(dave), List.of());
|
||||
|
||||
assertEquals("Dave", g.V("e-4").values("name").next(), "unchanged name must not be overwritten");
|
||||
}
|
||||
|
||||
// --- @Version OCC ---
|
||||
|
||||
@Test
|
||||
void create_initializesVersionToZero() {
|
||||
VersionedItem item = new VersionedItem();
|
||||
item.label = "first";
|
||||
|
||||
persistor.persist(item);
|
||||
|
||||
assertNotNull(item.getId());
|
||||
assertEquals(0L, item.version);
|
||||
// Use label-based lookup — auto-assigned TinkerGraph IDs are Longs, not Strings
|
||||
Long storedVersion = (Long) g.V().hasLabel("VersionedItem").values("_version").next();
|
||||
assertEquals(0L, storedVersion);
|
||||
}
|
||||
|
||||
@Test
|
||||
void update_incrementsVersionAtomically() {
|
||||
graph.addVertex(T.id, "vi-1", T.label, "VersionedItem", "label", "original", "_version", 0L);
|
||||
|
||||
VersionedItem item = new VersionedItem();
|
||||
item.setId(ARID.of("vi-1"));
|
||||
item.version = 0L;
|
||||
item.setState(EntityState.MANAGED);
|
||||
item.setLabel("updated");
|
||||
|
||||
persistor.persist(item);
|
||||
|
||||
assertEquals("updated", g.V("vi-1").values("label").next());
|
||||
assertEquals(1L, g.V("vi-1").values("_version").next());
|
||||
assertEquals(1L, item.version, "in-memory version must be bumped after successful update");
|
||||
}
|
||||
|
||||
@Test
|
||||
void update_throwsOptimisticLockExceptionOnVersionMismatch() {
|
||||
// Graph has version 5 but entity was loaded with version 3
|
||||
graph.addVertex(T.id, "vi-2", T.label, "VersionedItem", "label", "stale", "_version", 5L);
|
||||
|
||||
VersionedItem item = new VersionedItem();
|
||||
item.setId(ARID.of("vi-2"));
|
||||
item.version = 3L;
|
||||
item.setState(EntityState.MANAGED);
|
||||
item.setLabel("conflict");
|
||||
|
||||
assertThrows(OptimisticLockException.class, () -> persistor.persist(item));
|
||||
// Original value must be unchanged in graph
|
||||
assertEquals("stale", g.V("vi-2").values("label").next());
|
||||
assertEquals(5L, g.V("vi-2").values("_version").next());
|
||||
}
|
||||
|
||||
@Test
|
||||
void persistAllDirty_throwsBeforeAnyWriteOnVersionConflict() {
|
||||
graph.addVertex(T.id, "vi-3", T.label, "VersionedItem", "label", "A", "_version", 2L);
|
||||
graph.addVertex(T.id, "vi-4", T.label, "VersionedItem", "label", "B", "_version", 0L);
|
||||
|
||||
VersionedItem a = new VersionedItem();
|
||||
a.setId(ARID.of("vi-3"));
|
||||
a.version = 1L; // stale — graph has 2
|
||||
a.setState(EntityState.MANAGED);
|
||||
a.setLabel("A-updated");
|
||||
|
||||
VersionedItem b = new VersionedItem();
|
||||
b.setId(ARID.of("vi-4"));
|
||||
b.version = 0L; // correct
|
||||
b.setState(EntityState.MANAGED);
|
||||
b.setLabel("B-updated");
|
||||
|
||||
assertThrows(OptimisticLockException.class,
|
||||
() -> persistor.persistAllDirty(List.of(a, b), List.of()));
|
||||
|
||||
// Neither entity should have been written (pre-flight throws before any write)
|
||||
assertEquals("A", g.V("vi-3").values("label").next(), "stale entity must not be written");
|
||||
assertEquals("B", g.V("vi-4").values("label").next(), "clean entity must also not be written");
|
||||
}
|
||||
|
||||
@Test
|
||||
void persistAllDirty_incrementsVersionsOnSuccess() {
|
||||
graph.addVertex(T.id, "vi-5", T.label, "VersionedItem", "label", "X", "_version", 1L);
|
||||
graph.addVertex(T.id, "vi-6", T.label, "VersionedItem", "label", "Y", "_version", 3L);
|
||||
|
||||
VersionedItem x = new VersionedItem();
|
||||
x.setId(ARID.of("vi-5"));
|
||||
x.version = 1L;
|
||||
x.setState(EntityState.MANAGED);
|
||||
x.setLabel("X-updated");
|
||||
|
||||
VersionedItem y = new VersionedItem();
|
||||
y.setId(ARID.of("vi-6"));
|
||||
y.version = 3L;
|
||||
y.setState(EntityState.MANAGED);
|
||||
y.setLabel("Y-updated");
|
||||
|
||||
persistor.persistAllDirty(List.of(x, y), List.of());
|
||||
|
||||
assertEquals("X-updated", g.V("vi-5").values("label").next());
|
||||
assertEquals(2L, g.V("vi-5").values("_version").next());
|
||||
assertEquals(2L, x.version, "in-memory version must be bumped");
|
||||
|
||||
assertEquals("Y-updated", g.V("vi-6").values("label").next());
|
||||
assertEquals(4L, g.V("vi-6").values("_version").next());
|
||||
assertEquals(4L, y.version);
|
||||
}
|
||||
}
|
||||
+160
@@ -0,0 +1,160 @@
|
||||
package com.binarygolem.clotho.mapping;
|
||||
|
||||
import com.binarygolem.clotho.annotation.Alias;
|
||||
import com.binarygolem.clotho.annotation.Property;
|
||||
import com.binarygolem.clotho.annotation.SubgraphType;
|
||||
import com.binarygolem.clotho.annotation.VertexType;
|
||||
import com.binarygolem.clotho.exception.ClothoConfigurationException;
|
||||
import com.binarygolem.clotho.model.ClothoVertex;
|
||||
import com.binarygolem.clotho.model.TraversalDirection;
|
||||
import com.binarygolem.clotho.model.UnknownTypeBehavior;
|
||||
import com.binarygolem.clotho.registry.TypeRegistry;
|
||||
import org.apache.commons.configuration2.BaseConfiguration;
|
||||
import org.apache.commons.configuration2.Configuration;
|
||||
import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversalSource;
|
||||
import org.apache.tinkerpop.gremlin.structure.Graph;
|
||||
import org.apache.tinkerpop.gremlin.structure.T;
|
||||
import org.apache.tinkerpop.gremlin.structure.Vertex;
|
||||
import org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerGraph;
|
||||
import org.junit.jupiter.api.BeforeEach;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
|
||||
import static org.junit.jupiter.api.Assertions.*;
|
||||
|
||||
class SubgraphTypeAssemblerTest {
|
||||
|
||||
// --- Fixture types ---
|
||||
|
||||
static class NotASubgraphType {}
|
||||
|
||||
@VertexType("Employee")
|
||||
static class Employee extends ClothoVertex {
|
||||
@Property("name") String name;
|
||||
}
|
||||
|
||||
@VertexType("Department")
|
||||
static class Department extends ClothoVertex {
|
||||
@Property("deptName") String deptName;
|
||||
}
|
||||
|
||||
@SubgraphType
|
||||
static class EmployeeProfile {
|
||||
Employee employee;
|
||||
@Alias("dept")
|
||||
Department department;
|
||||
List<Employee> colleagues;
|
||||
}
|
||||
|
||||
// --- Setup ---
|
||||
|
||||
private Graph graph;
|
||||
private GraphTraversalSource g;
|
||||
private TypeRegistry registry;
|
||||
private ElementMapper mapper;
|
||||
private SubgraphLoader loader;
|
||||
private SubgraphTypeAssembler assembler;
|
||||
|
||||
@BeforeEach
|
||||
void setUp() {
|
||||
Configuration conf = new BaseConfiguration();
|
||||
conf.setProperty(TinkerGraph.GREMLIN_TINKERGRAPH_VERTEX_ID_MANAGER, "ANY");
|
||||
conf.setProperty(TinkerGraph.GREMLIN_TINKERGRAPH_EDGE_ID_MANAGER, "ANY");
|
||||
graph = TinkerGraph.open(conf);
|
||||
g = graph.traversal();
|
||||
|
||||
registry = TypeRegistry.builder()
|
||||
.registerVertex(Employee.class)
|
||||
.registerVertex(Department.class)
|
||||
.build();
|
||||
mapper = new ElementMapper(registry, UnknownTypeBehavior.STRICT);
|
||||
loader = new SubgraphLoader(g, mapper, TraversalDirection.OUT);
|
||||
assembler = new SubgraphTypeAssembler(mapper, loader);
|
||||
}
|
||||
|
||||
// --- Field-name matching ---
|
||||
|
||||
@Test
|
||||
void assemblsVertexByFieldName() {
|
||||
Vertex empV = graph.addVertex(T.id, "emp-1", T.label, "Employee", "name", "Alice");
|
||||
Map<String, Object> result = Map.of("employee", empV);
|
||||
|
||||
EmployeeProfile profile = assembler.assemble(EmployeeProfile.class, result);
|
||||
|
||||
assertNotNull(profile.employee);
|
||||
assertEquals("Alice", profile.employee.name);
|
||||
}
|
||||
|
||||
// --- @Alias override ---
|
||||
|
||||
@Test
|
||||
void assemblsVertexByAlias() {
|
||||
Vertex deptV = graph.addVertex(T.id, "dept-1", T.label, "Department", "deptName", "Engineering");
|
||||
Map<String, Object> result = Map.of("dept", deptV);
|
||||
|
||||
EmployeeProfile profile = assembler.assemble(EmployeeProfile.class, result);
|
||||
|
||||
assertNotNull(profile.department);
|
||||
assertEquals("Engineering", profile.department.deptName);
|
||||
}
|
||||
|
||||
// --- Missing key ---
|
||||
|
||||
@Test
|
||||
void leavesFieldNullWhenKeyAbsent() {
|
||||
Vertex empV = graph.addVertex(T.id, "emp-2", T.label, "Employee", "name", "Bob");
|
||||
Map<String, Object> result = Map.of("employee", empV);
|
||||
// "dept" key absent
|
||||
|
||||
EmployeeProfile profile = assembler.assemble(EmployeeProfile.class, result);
|
||||
|
||||
assertNull(profile.department);
|
||||
}
|
||||
|
||||
// --- List value ---
|
||||
|
||||
@Test
|
||||
void assemblsListOfVertices() {
|
||||
Vertex c1 = graph.addVertex(T.id, "c-1", T.label, "Employee", "name", "Carol");
|
||||
Vertex c2 = graph.addVertex(T.id, "c-2", T.label, "Employee", "name", "Dan");
|
||||
Map<String, Object> result = Map.of("colleagues", List.of(c1, c2));
|
||||
|
||||
EmployeeProfile profile = assembler.assemble(EmployeeProfile.class, result);
|
||||
|
||||
assertEquals(2, profile.colleagues.size());
|
||||
assertTrue(profile.colleagues.stream().map(e -> e.name).toList()
|
||||
.containsAll(List.of("Carol", "Dan")));
|
||||
}
|
||||
|
||||
// --- Validation ---
|
||||
|
||||
@Test
|
||||
void throwsWhenClassLacksSubgraphTypeAnnotation() {
|
||||
assertThrows(ClothoConfigurationException.class,
|
||||
() -> assembler.assemble(NotASubgraphType.class, Map.of()));
|
||||
}
|
||||
|
||||
// --- Full round-trip ---
|
||||
|
||||
@Test
|
||||
void assemblesAllFieldsFromSelectResult() {
|
||||
Vertex empV = graph.addVertex(T.id, "emp-3", T.label, "Employee", "name", "Eve");
|
||||
Vertex deptV = graph.addVertex(T.id, "dept-2", T.label, "Department", "deptName", "Research");
|
||||
Vertex c1 = graph.addVertex(T.id, "c-3", T.label, "Employee", "name", "Frank");
|
||||
|
||||
Map<String, Object> result = Map.of(
|
||||
"employee", empV,
|
||||
"dept", deptV,
|
||||
"colleagues", List.of(c1)
|
||||
);
|
||||
|
||||
EmployeeProfile profile = assembler.assemble(EmployeeProfile.class, result);
|
||||
|
||||
assertEquals("Eve", profile.employee.name);
|
||||
assertEquals("Research", profile.department.deptName);
|
||||
assertEquals(1, profile.colleagues.size());
|
||||
assertEquals("Frank", profile.colleagues.get(0).name);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,240 @@
|
||||
package com.binarygolem.clotho.registry;
|
||||
|
||||
import com.binarygolem.clotho.annotation.EdgeType;
|
||||
import com.binarygolem.clotho.annotation.VertexType;
|
||||
import com.binarygolem.clotho.exception.ClothoConfigurationException;
|
||||
import com.binarygolem.clotho.exception.UnknownTypeException;
|
||||
import com.binarygolem.clotho.model.ClothoEdge;
|
||||
import com.binarygolem.clotho.model.ClothoVertex;
|
||||
import com.binarygolem.clotho.model.GenericEdge;
|
||||
import com.binarygolem.clotho.model.GenericVertex;
|
||||
import com.binarygolem.clotho.model.UnknownTypeBehavior;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
import static org.junit.jupiter.api.Assertions.*;
|
||||
|
||||
class TypeRegistryTest {
|
||||
|
||||
// --- Sample types ---
|
||||
|
||||
@VertexType("Person")
|
||||
static class Person extends ClothoVertex {}
|
||||
|
||||
@VertexType("Employee")
|
||||
static class Employee extends Person {}
|
||||
|
||||
@VertexType("HourlyEmployee")
|
||||
static class HourlyEmployee extends Employee {}
|
||||
|
||||
// parentLabel escape hatch: Java doesn't extend Employee but ArcadeDB does
|
||||
@VertexType(value = "OffSiteEmployee", parentLabel = "Employee")
|
||||
static class OffSiteEmployee extends ClothoVertex {}
|
||||
|
||||
// Diamond: in ArcadeDB ContractEmployee extends both Employee and Contractor
|
||||
@VertexType("Contractor")
|
||||
static class Contractor extends Person {}
|
||||
|
||||
@VertexType(value = "ContractEmployee", additionalParents = {"Contractor"})
|
||||
static class ContractEmployee extends Employee {}
|
||||
|
||||
@EdgeType("WORKS_AT")
|
||||
static class WorksAt extends ClothoEdge {}
|
||||
|
||||
// --- Basic registration and lookup ---
|
||||
|
||||
@Test
|
||||
void registersVertexByLabel() {
|
||||
TypeRegistry registry = TypeRegistry.builder()
|
||||
.registerVertex(Employee.class)
|
||||
.build();
|
||||
|
||||
assertEquals(Employee.class, registry.findVertex("Employee").orElseThrow());
|
||||
}
|
||||
|
||||
@Test
|
||||
void registersEdgeByLabel() {
|
||||
TypeRegistry registry = TypeRegistry.builder()
|
||||
.registerEdge(WorksAt.class)
|
||||
.build();
|
||||
|
||||
assertEquals(WorksAt.class, registry.findEdge("WORKS_AT").orElseThrow());
|
||||
}
|
||||
|
||||
@Test
|
||||
void returnsEmptyForUnknownLabel() {
|
||||
TypeRegistry registry = TypeRegistry.builder().build();
|
||||
|
||||
assertTrue(registry.findVertex("Nobody").isEmpty());
|
||||
assertTrue(registry.findEdge("NOBODY").isEmpty());
|
||||
}
|
||||
|
||||
@Test
|
||||
void exposesRegisteredLabels() {
|
||||
TypeRegistry registry = TypeRegistry.builder()
|
||||
.registerVertex(Person.class)
|
||||
.registerVertex(Employee.class)
|
||||
.registerEdge(WorksAt.class)
|
||||
.build();
|
||||
|
||||
assertTrue(registry.vertexLabels().containsAll(java.util.Set.of("Person", "Employee")));
|
||||
assertTrue(registry.edgeLabels().contains("WORKS_AT"));
|
||||
}
|
||||
|
||||
// --- UnknownTypeBehavior ---
|
||||
|
||||
@Test
|
||||
void strictThrowsOnUnknownVertex() {
|
||||
TypeRegistry registry = TypeRegistry.builder().build();
|
||||
|
||||
assertThrows(UnknownTypeException.class,
|
||||
() -> registry.resolveVertex("Ghost", UnknownTypeBehavior.STRICT));
|
||||
}
|
||||
|
||||
@Test
|
||||
void strictThrowsOnUnknownEdge() {
|
||||
TypeRegistry registry = TypeRegistry.builder().build();
|
||||
|
||||
assertThrows(UnknownTypeException.class,
|
||||
() -> registry.resolveEdge("GHOST", UnknownTypeBehavior.STRICT));
|
||||
}
|
||||
|
||||
@Test
|
||||
void genericReturnsGenericVertex() {
|
||||
TypeRegistry registry = TypeRegistry.builder().build();
|
||||
|
||||
assertEquals(GenericVertex.class,
|
||||
registry.resolveVertex("Unknown", UnknownTypeBehavior.GENERIC));
|
||||
}
|
||||
|
||||
@Test
|
||||
void genericReturnsGenericEdge() {
|
||||
TypeRegistry registry = TypeRegistry.builder().build();
|
||||
|
||||
assertEquals(GenericEdge.class,
|
||||
registry.resolveEdge("UNKNOWN", UnknownTypeBehavior.GENERIC));
|
||||
}
|
||||
|
||||
// --- NEAREST_ANCESTOR via Java hierarchy ---
|
||||
|
||||
@Test
|
||||
void nearestAncestorFindsDirectParent() {
|
||||
// HourlyEmployee → Employee → Person; only Person and Employee registered
|
||||
TypeRegistry registry = TypeRegistry.builder()
|
||||
.registerVertex(Person.class)
|
||||
.registerVertex(Employee.class)
|
||||
.registerVertex(HourlyEmployee.class)
|
||||
.build();
|
||||
|
||||
// HourlyEmployee IS registered, should return it directly
|
||||
assertEquals(HourlyEmployee.class,
|
||||
registry.resolveVertex("HourlyEmployee", UnknownTypeBehavior.NEAREST_ANCESTOR));
|
||||
}
|
||||
|
||||
@Test
|
||||
void nearestAncestorFindsAncestorForUnregisteredLabel() {
|
||||
// Register Person and Employee but NOT HourlyEmployee.
|
||||
// Simulate "HourlyEmployee" arriving from DB without a Java class.
|
||||
// TypeRegistry can only resolve this if it knows the label's parents —
|
||||
// which requires the label to be in the registered hierarchy.
|
||||
// For a fully unknown label, NEAREST_ANCESTOR falls back to GenericVertex.
|
||||
TypeRegistry registry = TypeRegistry.builder()
|
||||
.registerVertex(Person.class)
|
||||
.registerVertex(Employee.class)
|
||||
.build();
|
||||
|
||||
assertEquals(GenericVertex.class,
|
||||
registry.resolveVertex("HourlyEmployee", UnknownTypeBehavior.NEAREST_ANCESTOR));
|
||||
}
|
||||
|
||||
// --- parentLabel escape hatch ---
|
||||
|
||||
@Test
|
||||
void parentLabelOverridesJavaHierarchy() {
|
||||
TypeRegistry registry = TypeRegistry.builder()
|
||||
.registerVertex(Employee.class)
|
||||
.registerVertex(OffSiteEmployee.class) // Java: ClothoVertex, ArcadeDB: Employee
|
||||
.build();
|
||||
|
||||
// OffSiteEmployee declares parentLabel = "Employee", so its ancestor is Employee
|
||||
Class<? extends ClothoVertex> resolved =
|
||||
registry.resolveVertex("OffSiteEmployee", UnknownTypeBehavior.NEAREST_ANCESTOR);
|
||||
assertEquals(OffSiteEmployee.class, resolved);
|
||||
}
|
||||
|
||||
// --- additionalParents (diamond inheritance) ---
|
||||
|
||||
@Test
|
||||
void additionalParentsAreRecorded() {
|
||||
TypeRegistry registry = TypeRegistry.builder()
|
||||
.registerVertex(Person.class)
|
||||
.registerVertex(Employee.class)
|
||||
.registerVertex(Contractor.class)
|
||||
.registerVertex(ContractEmployee.class)
|
||||
.build();
|
||||
|
||||
// ContractEmployee is registered — resolves directly
|
||||
assertEquals(ContractEmployee.class,
|
||||
registry.resolveVertex("ContractEmployee", UnknownTypeBehavior.NEAREST_ANCESTOR));
|
||||
}
|
||||
|
||||
// --- Validation ---
|
||||
|
||||
@Test
|
||||
void duplicateLabelThrows() {
|
||||
@VertexType("Employee")
|
||||
class AnotherEmployee extends ClothoVertex {}
|
||||
|
||||
TypeRegistry.Builder builder = TypeRegistry.builder()
|
||||
.registerVertex(Employee.class);
|
||||
|
||||
assertThrows(ClothoConfigurationException.class,
|
||||
() -> builder.registerVertex(AnotherEmployee.class));
|
||||
}
|
||||
|
||||
@Test
|
||||
void missingAnnotationOnVertexThrows() {
|
||||
class Unannotated extends ClothoVertex {}
|
||||
|
||||
assertThrows(ClothoConfigurationException.class,
|
||||
() -> TypeRegistry.builder().registerVertex(Unannotated.class));
|
||||
}
|
||||
|
||||
@Test
|
||||
void missingAnnotationOnEdgeThrows() {
|
||||
class Unannotated extends ClothoEdge {}
|
||||
|
||||
assertThrows(ClothoConfigurationException.class,
|
||||
() -> TypeRegistry.builder().registerEdge(Unannotated.class));
|
||||
}
|
||||
|
||||
@Test
|
||||
void unknownTypeExceptionCarriesLabel() {
|
||||
TypeRegistry registry = TypeRegistry.builder().build();
|
||||
|
||||
UnknownTypeException ex = assertThrows(UnknownTypeException.class,
|
||||
() -> registry.resolveVertex("Missing", UnknownTypeBehavior.STRICT));
|
||||
assertEquals("Missing", ex.getLabel());
|
||||
}
|
||||
|
||||
// --- Classpath scan ---
|
||||
|
||||
@Test
|
||||
void scanFindsAnnotatedClassesInPackage() {
|
||||
TypeRegistry registry = TypeRegistry.scan("com.binarygolem.clotho.fixture");
|
||||
|
||||
assertTrue(registry.vertexLabels().contains("Person"));
|
||||
assertTrue(registry.vertexLabels().contains("Employee"));
|
||||
assertTrue(registry.edgeLabels().contains("WORKS_AT"));
|
||||
}
|
||||
|
||||
@Test
|
||||
void scanInfersJavaHierarchyFromFixtures() {
|
||||
// ScanEmployee extends ScanPerson (@VertexType("Person")), so Employee's parent
|
||||
// should be inferred as "Person" without any explicit parentLabel.
|
||||
TypeRegistry registry = TypeRegistry.scan("com.binarygolem.clotho.fixture");
|
||||
|
||||
// Employee is registered directly, so it resolves to itself
|
||||
assertEquals(com.binarygolem.clotho.fixture.ScanEmployee.class,
|
||||
registry.resolveVertex("Employee", UnknownTypeBehavior.NEAREST_ANCESTOR));
|
||||
}
|
||||
}
|
||||
+422
@@ -0,0 +1,422 @@
|
||||
package com.binarygolem.clotho.repository;
|
||||
|
||||
import com.binarygolem.clotho.annotation.EdgeType;
|
||||
import com.binarygolem.clotho.annotation.InVertex;
|
||||
import com.binarygolem.clotho.annotation.OutVertex;
|
||||
import com.binarygolem.clotho.annotation.Property;
|
||||
import com.binarygolem.clotho.annotation.SubgraphType;
|
||||
import com.binarygolem.clotho.annotation.VertexType;
|
||||
import com.binarygolem.clotho.exception.ClothoException;
|
||||
import com.binarygolem.clotho.model.ARID;
|
||||
import com.binarygolem.clotho.model.ClothoEdge;
|
||||
import com.binarygolem.clotho.model.ClothoVertex;
|
||||
import com.binarygolem.clotho.model.EntityState;
|
||||
import com.binarygolem.clotho.model.TraversalDirection;
|
||||
import com.binarygolem.clotho.model.UnknownTypeBehavior;
|
||||
import com.binarygolem.clotho.registry.TypeRegistry;
|
||||
import com.binarygolem.clotho.session.ClothoSession;
|
||||
import com.binarygolem.clotho.session.ClothoSessionFactory;
|
||||
import org.apache.commons.configuration2.BaseConfiguration;
|
||||
import org.apache.commons.configuration2.Configuration;
|
||||
import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversalSource;
|
||||
import org.apache.tinkerpop.gremlin.structure.Graph;
|
||||
import org.apache.tinkerpop.gremlin.structure.T;
|
||||
import org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerGraph;
|
||||
import org.junit.jupiter.api.BeforeEach;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
import java.util.List;
|
||||
|
||||
import static org.junit.jupiter.api.Assertions.*;
|
||||
|
||||
class ClothoRepositoryTest {
|
||||
|
||||
// --- Fixture types ---
|
||||
|
||||
@VertexType("Employee")
|
||||
static class Employee extends ClothoVertex {
|
||||
@Property("name") String name;
|
||||
@Property("dept") String dept;
|
||||
|
||||
void setName(String name) {
|
||||
this.name = name;
|
||||
notifyFieldChanged("name");
|
||||
}
|
||||
}
|
||||
|
||||
@VertexType("Company")
|
||||
static class Company extends ClothoVertex {
|
||||
@Property("name") String name;
|
||||
}
|
||||
|
||||
@EdgeType("WORKS_AT")
|
||||
static class WorksAt extends ClothoEdge {
|
||||
@Property("role") String role;
|
||||
@OutVertex Employee employee;
|
||||
@InVertex Company company;
|
||||
}
|
||||
|
||||
@SubgraphType
|
||||
static class EmployeeCompanyPair {
|
||||
Employee employee;
|
||||
Company company;
|
||||
}
|
||||
|
||||
// --- Concrete repository ---
|
||||
|
||||
static class EmployeeRepo extends ClothoRepository<Employee> {
|
||||
EmployeeRepo(ClothoSessionFactory factory) { super(factory); }
|
||||
|
||||
List<Employee> findByDept(String dept) {
|
||||
return execute(g().V().has("Employee", "dept", dept));
|
||||
}
|
||||
|
||||
List<Employee> findSenior() {
|
||||
return findAll(t -> t.has("dept", "Engineering"));
|
||||
}
|
||||
|
||||
long countByDept(String dept) {
|
||||
return this.<Long>executeRaw(
|
||||
g().V().hasLabel("Employee").has("dept", dept).count()
|
||||
).get(0);
|
||||
}
|
||||
|
||||
List<EmployeeCompanyPair> loadPairs(String employeeId) {
|
||||
return executeSubgraph(EmployeeCompanyPair.class,
|
||||
g().V(employeeId).as("employee")
|
||||
.out("WORKS_AT").as("company")
|
||||
.select("employee", "company")
|
||||
);
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
static class WorksAtRepo extends ClothoRepository<WorksAt> {
|
||||
WorksAtRepo(ClothoSessionFactory factory) { super(factory); }
|
||||
}
|
||||
|
||||
// --- Setup ---
|
||||
|
||||
private Graph graph;
|
||||
private GraphTraversalSource g;
|
||||
private ClothoSessionFactory factory;
|
||||
private EmployeeRepo employeeRepo;
|
||||
private WorksAtRepo edgeRepo;
|
||||
|
||||
@BeforeEach
|
||||
void setUp() {
|
||||
Configuration conf = new BaseConfiguration();
|
||||
conf.setProperty(TinkerGraph.GREMLIN_TINKERGRAPH_VERTEX_ID_MANAGER, "ANY");
|
||||
conf.setProperty(TinkerGraph.GREMLIN_TINKERGRAPH_EDGE_ID_MANAGER, "ANY");
|
||||
graph = TinkerGraph.open(conf);
|
||||
g = graph.traversal();
|
||||
|
||||
TypeRegistry registry = TypeRegistry.builder()
|
||||
.registerVertex(Employee.class)
|
||||
.registerVertex(Company.class)
|
||||
.registerEdge(WorksAt.class)
|
||||
.build();
|
||||
|
||||
factory = ClothoSessionFactory.builder()
|
||||
.g(g)
|
||||
.registry(registry)
|
||||
.unknownTypeBehavior(UnknownTypeBehavior.STRICT)
|
||||
.defaultDirection(TraversalDirection.OUT)
|
||||
.build();
|
||||
|
||||
employeeRepo = new EmployeeRepo(factory);
|
||||
edgeRepo = new WorksAtRepo(factory);
|
||||
}
|
||||
|
||||
// --- execute ---
|
||||
|
||||
@Test
|
||||
void executeReturnsMatchingVertices() {
|
||||
graph.addVertex(T.id, "e-1", T.label, "Employee", "name", "Alice", "dept", "Engineering");
|
||||
graph.addVertex(T.id, "e-2", T.label, "Employee", "name", "Bob", "dept", "Marketing");
|
||||
|
||||
List<Employee> result = employeeRepo.findByDept("Engineering");
|
||||
|
||||
assertEquals(1, result.size());
|
||||
assertEquals("Alice", result.get(0).name);
|
||||
}
|
||||
|
||||
@Test
|
||||
void executeWithFilterAppliesFilter() {
|
||||
graph.addVertex(T.id, "e-3", T.label, "Employee", "name", "Carol", "dept", "Engineering");
|
||||
graph.addVertex(T.id, "e-4", T.label, "Employee", "name", "Dave", "dept", "HR");
|
||||
|
||||
List<Employee> result = employeeRepo.findSenior();
|
||||
|
||||
assertEquals(1, result.size());
|
||||
assertEquals("Carol", result.get(0).name);
|
||||
}
|
||||
|
||||
@Test
|
||||
void executeReturnsEmptyListWhenNoMatch() {
|
||||
graph.addVertex(T.id, "e-5", T.label, "Employee", "name", "Eve", "dept", "Sales");
|
||||
|
||||
List<Employee> result = employeeRepo.findByDept("Nonexistent");
|
||||
|
||||
assertTrue(result.isEmpty());
|
||||
}
|
||||
|
||||
// --- executeRaw ---
|
||||
|
||||
@Test
|
||||
void executeRawReturnsScalarCount() {
|
||||
graph.addVertex(T.id, "e-6", T.label, "Employee", "name", "Frank", "dept", "Engineering");
|
||||
graph.addVertex(T.id, "e-7", T.label, "Employee", "name", "Grace", "dept", "Engineering");
|
||||
graph.addVertex(T.id, "e-8", T.label, "Employee", "name", "Hank", "dept", "Marketing");
|
||||
|
||||
long count = employeeRepo.countByDept("Engineering");
|
||||
|
||||
assertEquals(2L, count);
|
||||
}
|
||||
|
||||
// --- executeSubgraph ---
|
||||
|
||||
@Test
|
||||
void executeSubgraphAssemblesSubgraphType() {
|
||||
var empV = graph.addVertex(T.id, "e-9", T.label, "Employee", "name", "Ivy");
|
||||
var coV = graph.addVertex(T.id, "c-1", T.label, "Company", "name", "Acme");
|
||||
empV.addEdge("WORKS_AT", coV);
|
||||
|
||||
List<EmployeeCompanyPair> pairs = employeeRepo.loadPairs("e-9");
|
||||
|
||||
assertEquals(1, pairs.size());
|
||||
assertEquals("Ivy", pairs.get(0).employee.name);
|
||||
assertEquals("Acme", pairs.get(0).company.name);
|
||||
}
|
||||
|
||||
// --- findAll ---
|
||||
|
||||
@Test
|
||||
void findAllReturnsAllEntities() {
|
||||
graph.addVertex(T.id, "e-10", T.label, "Employee", "name", "Jack");
|
||||
graph.addVertex(T.id, "e-11", T.label, "Employee", "name", "Kate");
|
||||
|
||||
List<Employee> all = employeeRepo.findAll();
|
||||
|
||||
assertEquals(2, all.size());
|
||||
}
|
||||
|
||||
@Test
|
||||
void findAllWithFilterReturnsFiltered() {
|
||||
graph.addVertex(T.id, "e-12", T.label, "Employee", "name", "Leo", "dept", "Engineering");
|
||||
graph.addVertex(T.id, "e-13", T.label, "Employee", "name", "Mia", "dept", "Engineering");
|
||||
graph.addVertex(T.id, "e-14", T.label, "Employee", "name", "Nick", "dept", "Marketing");
|
||||
|
||||
List<Employee> result = employeeRepo.findAll(t -> t.has("dept", "Engineering"));
|
||||
|
||||
assertEquals(2, result.size());
|
||||
}
|
||||
|
||||
// --- findById ---
|
||||
|
||||
@Test
|
||||
void findByIdReturnsEntity() {
|
||||
graph.addVertex(T.id, "e-15", T.label, "Employee", "name", "Olivia");
|
||||
|
||||
Employee found = employeeRepo.findById(ARID.of("e-15"));
|
||||
|
||||
assertNotNull(found);
|
||||
assertEquals("Olivia", found.name);
|
||||
}
|
||||
|
||||
@Test
|
||||
void findByIdReturnsNullWhenNotFound() {
|
||||
assertNull(employeeRepo.findById(ARID.of("does-not-exist")));
|
||||
}
|
||||
|
||||
// --- count ---
|
||||
|
||||
@Test
|
||||
void countReturnsTotal() {
|
||||
graph.addVertex(T.id, "e-16", T.label, "Employee", "name", "Pat");
|
||||
graph.addVertex(T.id, "e-17", T.label, "Employee", "name", "Quinn");
|
||||
|
||||
assertEquals(2L, employeeRepo.count());
|
||||
}
|
||||
|
||||
@Test
|
||||
void countWithFilterReturnsFilteredTotal() {
|
||||
graph.addVertex(T.id, "e-18", T.label, "Employee", "name", "Ray", "dept", "Engineering");
|
||||
graph.addVertex(T.id, "e-19", T.label, "Employee", "name", "Sara", "dept", "HR");
|
||||
|
||||
long count = employeeRepo.count(t -> t.has("dept", "Engineering"));
|
||||
|
||||
assertEquals(1L, count);
|
||||
}
|
||||
|
||||
// --- findWithPagination ---
|
||||
|
||||
@Test
|
||||
void findWithPaginationReturnsPage() {
|
||||
graph.addVertex(T.id, "e-20", T.label, "Employee", "name", "Tina");
|
||||
graph.addVertex(T.id, "e-21", T.label, "Employee", "name", "Uma");
|
||||
graph.addVertex(T.id, "e-22", T.label, "Employee", "name", "Vince");
|
||||
|
||||
List<Employee> page = employeeRepo.findWithPagination(0, 2);
|
||||
|
||||
assertEquals(2, page.size());
|
||||
}
|
||||
|
||||
// --- save ---
|
||||
|
||||
@Test
|
||||
void saveCreatesNewVertex() {
|
||||
Employee emp = new Employee();
|
||||
emp.name = "Wendy";
|
||||
emp.dept = "Finance";
|
||||
|
||||
employeeRepo.save(emp);
|
||||
|
||||
assertNotNull(emp.getId());
|
||||
assertEquals(1L, g.V().hasLabel("Employee").has("name", "Wendy").count().next());
|
||||
}
|
||||
|
||||
@Test
|
||||
void saveUpdatesExistingVertex() {
|
||||
graph.addVertex(T.id, "e-23", T.label, "Employee", "name", "OldName");
|
||||
|
||||
Employee emp = new Employee();
|
||||
emp.setId(ARID.of("e-23"));
|
||||
emp.name = "NewName";
|
||||
|
||||
employeeRepo.save(emp);
|
||||
|
||||
assertEquals("NewName", g.V("e-23").values("name").next());
|
||||
}
|
||||
|
||||
// --- delete ---
|
||||
|
||||
@Test
|
||||
void deleteRemovesEntityFromGraph() {
|
||||
graph.addVertex(T.id, "e-24", T.label, "Employee", "name", "Xavier");
|
||||
|
||||
Employee emp = new Employee();
|
||||
emp.setId(ARID.of("e-24"));
|
||||
|
||||
employeeRepo.delete(emp);
|
||||
|
||||
assertEquals(0L, g.V("e-24").count().next());
|
||||
}
|
||||
|
||||
@Test
|
||||
void deleteByAridRemovesFromGraph() {
|
||||
graph.addVertex(T.id, "e-25", T.label, "Employee", "name", "Yara");
|
||||
|
||||
employeeRepo.delete(ARID.of("e-25"));
|
||||
|
||||
assertEquals(0L, g.V("e-25").count().next());
|
||||
}
|
||||
|
||||
@Test
|
||||
void deleteThrowsWhenEntityHasNoId() {
|
||||
Employee emp = new Employee();
|
||||
assertThrows(ClothoException.class, () -> employeeRepo.delete(emp));
|
||||
}
|
||||
|
||||
// --- entity class inference ---
|
||||
|
||||
@Test
|
||||
void entityClassIsCorrectlyInferred() {
|
||||
assertEquals(Employee.class, employeeRepo.getEntityClass());
|
||||
}
|
||||
|
||||
@Test
|
||||
void edgeRepositoryInfersEdgeClass() {
|
||||
assertEquals(WorksAt.class, edgeRepo.getEntityClass());
|
||||
}
|
||||
|
||||
// --- edge repository ---
|
||||
|
||||
@Test
|
||||
void edgeRepositoryFindAll() {
|
||||
var empV = graph.addVertex(T.id, "e-26", T.label, "Employee");
|
||||
var coV = graph.addVertex(T.id, "c-2", T.label, "Company");
|
||||
empV.addEdge("WORKS_AT", coV, T.id, "wa-1", "role", "Dev");
|
||||
|
||||
List<WorksAt> edges = edgeRepo.findAll();
|
||||
|
||||
assertEquals(1, edges.size());
|
||||
assertEquals("Dev", edges.get(0).role);
|
||||
}
|
||||
|
||||
// --- execute with session ---
|
||||
|
||||
@Test
|
||||
void execute_withSession_returnsManaged() {
|
||||
graph.addVertex(T.id, "e-30", T.label, "Employee", "name", "Zara", "dept", "Engineering");
|
||||
|
||||
try (ClothoSession session = factory.openSession()) {
|
||||
List<Employee> results = employeeRepo.execute(session,
|
||||
g.V().has("Employee", "name", "Zara"));
|
||||
|
||||
assertEquals(1, results.size());
|
||||
assertEquals(EntityState.MANAGED, results.get(0).getState());
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
void execute_withSession_dirtyTrackingFires() {
|
||||
graph.addVertex(T.id, "e-31", T.label, "Employee", "name", "Aaron", "dept", "Engineering");
|
||||
|
||||
try (ClothoSession session = factory.openSession()) {
|
||||
List<Employee> results = employeeRepo.execute(session,
|
||||
g.V().has("Employee", "name", "Aaron"));
|
||||
|
||||
Employee emp = results.get(0);
|
||||
emp.setName("Aaron Updated");
|
||||
|
||||
assertFalse(emp.getDirtyFields().isEmpty());
|
||||
assertTrue(emp.getDirtyFields().contains("name"));
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
void execute_withSession_registersAllResults() {
|
||||
graph.addVertex(T.id, "e-32", T.label, "Employee", "name", "Beth", "dept", "HR");
|
||||
graph.addVertex(T.id, "e-33", T.label, "Employee", "name", "Carl", "dept", "HR");
|
||||
graph.addVertex(T.id, "e-34", T.label, "Employee", "name", "Dana", "dept", "IT");
|
||||
|
||||
try (ClothoSession session = factory.openSession()) {
|
||||
List<Employee> hrStaff = employeeRepo.execute(session,
|
||||
employeeRepo.g().V().has("Employee", "dept", "HR"));
|
||||
|
||||
assertEquals(2, hrStaff.size());
|
||||
assertTrue(hrStaff.stream().allMatch(e -> e.getState() == EntityState.MANAGED));
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
void execute_withSession_returnsCachedInstanceForDuplicateVertex() {
|
||||
graph.addVertex(T.id, "e-40", T.label, "Employee", "name", "Zoe", "dept", "Engineering");
|
||||
|
||||
try (ClothoSession session = factory.openSession()) {
|
||||
Employee loaded = session.load(Employee.class, ARID.of("e-40"));
|
||||
|
||||
List<Employee> results = employeeRepo.execute(session,
|
||||
g.V().has("Employee", "dept", "Engineering"));
|
||||
|
||||
assertEquals(1, results.size());
|
||||
assertSame(loaded, results.get(0));
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
void execute_withSession_filterOverload_returnsManaged() {
|
||||
graph.addVertex(T.id, "e-35", T.label, "Employee", "name", "Eve", "dept", "Finance");
|
||||
graph.addVertex(T.id, "e-36", T.label, "Employee", "name", "Frank", "dept", "Engineering");
|
||||
|
||||
try (ClothoSession session = factory.openSession()) {
|
||||
List<Employee> results = employeeRepo.execute(session,
|
||||
employeeRepo.allEntities(), t -> t.has("dept", "Finance"));
|
||||
|
||||
assertEquals(1, results.size());
|
||||
assertEquals(EntityState.MANAGED, results.get(0).getState());
|
||||
assertEquals("Eve", results.get(0).name);
|
||||
}
|
||||
}
|
||||
}
|
||||
+74
@@ -0,0 +1,74 @@
|
||||
package com.binarygolem.clotho.session;
|
||||
|
||||
import com.binarygolem.clotho.model.TraversalDirection;
|
||||
import com.binarygolem.clotho.model.UnknownTypeBehavior;
|
||||
import com.binarygolem.clotho.registry.TypeRegistry;
|
||||
import org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerGraph;
|
||||
import org.junit.jupiter.api.AfterEach;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
import static org.junit.jupiter.api.Assertions.*;
|
||||
|
||||
class ClothoSessionFactoryTest {
|
||||
|
||||
@AfterEach
|
||||
void tearDown() {
|
||||
ClothoSession bound = SessionContext.get();
|
||||
if (bound != null) bound.rollback();
|
||||
}
|
||||
|
||||
@Test
|
||||
void openSessionReturnsSession() {
|
||||
ClothoSessionFactory factory = ClothoSessionFactory.builder()
|
||||
.g(TinkerGraph.open().traversal())
|
||||
.registry(TypeRegistry.builder().build())
|
||||
.build();
|
||||
|
||||
assertNotNull(factory.openSession());
|
||||
}
|
||||
|
||||
@Test
|
||||
void openSession_whenNoSessionBound_createsNewSession() {
|
||||
ClothoSessionFactory factory = ClothoSessionFactory.builder()
|
||||
.g(TinkerGraph.open().traversal())
|
||||
.registry(TypeRegistry.builder().build())
|
||||
.build();
|
||||
|
||||
ClothoSession session = factory.openSession();
|
||||
assertNotNull(session);
|
||||
assertFalse(session.isTransactional());
|
||||
}
|
||||
|
||||
@Test
|
||||
void openSession_whenSessionAlreadyBound_returnsSameInstance() {
|
||||
ClothoSessionFactory factory = ClothoSessionFactory.builder()
|
||||
.g(TinkerGraph.open().traversal())
|
||||
.registry(TypeRegistry.builder().build())
|
||||
.build();
|
||||
|
||||
ClothoSession a = factory.openSession();
|
||||
ClothoSession b = factory.openSession();
|
||||
assertSame(a, b, "openSession() must borrow the existing session when one is already bound");
|
||||
b.close(); // decrement borrow count (a is still open)
|
||||
}
|
||||
|
||||
@Test
|
||||
void defaultsApplyWhenNotExplicitlySet() {
|
||||
assertDoesNotThrow(() -> ClothoSessionFactory.builder()
|
||||
.g(TinkerGraph.open().traversal())
|
||||
.registry(TypeRegistry.builder().build())
|
||||
.build()
|
||||
.openSession());
|
||||
}
|
||||
|
||||
@Test
|
||||
void explicitConfigIsAccepted() {
|
||||
assertDoesNotThrow(() -> ClothoSessionFactory.builder()
|
||||
.g(TinkerGraph.open().traversal())
|
||||
.registry(TypeRegistry.builder().build())
|
||||
.unknownTypeBehavior(UnknownTypeBehavior.GENERIC)
|
||||
.defaultDirection(TraversalDirection.IN)
|
||||
.build()
|
||||
.openSession());
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,263 @@
|
||||
package com.binarygolem.clotho.session;
|
||||
|
||||
import com.binarygolem.clotho.annotation.EdgeType;
|
||||
import com.binarygolem.clotho.annotation.InVertex;
|
||||
import com.binarygolem.clotho.annotation.OutVertex;
|
||||
import com.binarygolem.clotho.annotation.Property;
|
||||
import com.binarygolem.clotho.annotation.SubgraphType;
|
||||
import com.binarygolem.clotho.annotation.VertexType;
|
||||
import com.binarygolem.clotho.exception.ClothoException;
|
||||
import com.binarygolem.clotho.model.ARID;
|
||||
import com.binarygolem.clotho.model.ClothoEdge;
|
||||
import com.binarygolem.clotho.model.ClothoVertex;
|
||||
import com.binarygolem.clotho.model.TraversalDirection;
|
||||
import com.binarygolem.clotho.model.UnknownTypeBehavior;
|
||||
import com.binarygolem.clotho.registry.TypeRegistry;
|
||||
import org.apache.commons.configuration2.BaseConfiguration;
|
||||
import org.apache.commons.configuration2.Configuration;
|
||||
import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversalSource;
|
||||
import org.apache.tinkerpop.gremlin.structure.Graph;
|
||||
import org.apache.tinkerpop.gremlin.structure.T;
|
||||
import org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerGraph;
|
||||
import org.junit.jupiter.api.AfterEach;
|
||||
import org.junit.jupiter.api.BeforeEach;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
import java.util.HashMap;
|
||||
import java.util.Map;
|
||||
|
||||
import static org.junit.jupiter.api.Assertions.*;
|
||||
|
||||
class ClothoSessionTest {
|
||||
|
||||
// --- Fixture types ---
|
||||
|
||||
@VertexType("Person")
|
||||
static class Person extends ClothoVertex {
|
||||
@Property("name") String name;
|
||||
}
|
||||
|
||||
@VertexType("Company")
|
||||
static class Company extends ClothoVertex {
|
||||
@Property("name") String name;
|
||||
}
|
||||
|
||||
@EdgeType("WORKS_AT")
|
||||
static class WorksAt extends ClothoEdge {
|
||||
@Property("role") String role;
|
||||
@OutVertex Person person;
|
||||
@InVertex Company company;
|
||||
}
|
||||
|
||||
@SubgraphType
|
||||
static class PersonProfile {
|
||||
Person person;
|
||||
Company company;
|
||||
}
|
||||
|
||||
// --- Setup ---
|
||||
|
||||
private Graph graph;
|
||||
private GraphTraversalSource g;
|
||||
private ClothoSession session;
|
||||
|
||||
@AfterEach
|
||||
void tearDown() {
|
||||
if (session != null && SessionContext.get() != null) {
|
||||
session.rollback();
|
||||
}
|
||||
}
|
||||
|
||||
@BeforeEach
|
||||
void setUp() {
|
||||
Configuration conf = new BaseConfiguration();
|
||||
conf.setProperty(TinkerGraph.GREMLIN_TINKERGRAPH_VERTEX_ID_MANAGER, "ANY");
|
||||
conf.setProperty(TinkerGraph.GREMLIN_TINKERGRAPH_EDGE_ID_MANAGER, "ANY");
|
||||
graph = TinkerGraph.open(conf);
|
||||
g = graph.traversal();
|
||||
|
||||
TypeRegistry registry = TypeRegistry.builder()
|
||||
.registerVertex(Person.class)
|
||||
.registerVertex(Company.class)
|
||||
.registerEdge(WorksAt.class)
|
||||
.build();
|
||||
|
||||
session = ClothoSessionFactory.builder()
|
||||
.g(g)
|
||||
.registry(registry)
|
||||
.unknownTypeBehavior(UnknownTypeBehavior.STRICT)
|
||||
.defaultDirection(TraversalDirection.OUT)
|
||||
.build()
|
||||
.openSession();
|
||||
}
|
||||
|
||||
// --- load ---
|
||||
|
||||
@Test
|
||||
void loadsVertexById() {
|
||||
graph.addVertex(T.id, "p-1", T.label, "Person", "name", "Alice");
|
||||
|
||||
Person person = session.load(Person.class, ARID.of("p-1"));
|
||||
|
||||
assertNotNull(person);
|
||||
assertEquals("Alice", person.name);
|
||||
assertEquals(ARID.of("p-1"), person.getId());
|
||||
}
|
||||
|
||||
@Test
|
||||
void returnsCachedInstanceOnSecondLoad() {
|
||||
graph.addVertex(T.id, "p-2", T.label, "Person", "name", "Bob");
|
||||
|
||||
Person first = session.load(Person.class, ARID.of("p-2"));
|
||||
Person second = session.load(Person.class, ARID.of("p-2"));
|
||||
|
||||
assertSame(first, second);
|
||||
}
|
||||
|
||||
@Test
|
||||
void throwsWhenVertexNotFound() {
|
||||
assertThrows(ClothoException.class,
|
||||
() -> session.load(Person.class, ARID.of("no-such-id")));
|
||||
}
|
||||
|
||||
// --- save vertex ---
|
||||
|
||||
@Test
|
||||
void savePersistsNewVertex() {
|
||||
Person person = new Person();
|
||||
person.name = "Carol";
|
||||
|
||||
session.save(person);
|
||||
|
||||
assertNotNull(person.getId());
|
||||
assertEquals(1L, g.V().hasLabel("Person").has("name", "Carol").count().next());
|
||||
}
|
||||
|
||||
@Test
|
||||
void saveUpdatesExistingVertex() {
|
||||
graph.addVertex(T.id, "p-3", T.label, "Person", "name", "OldName");
|
||||
|
||||
Person person = new Person();
|
||||
person.setId(ARID.of("p-3"));
|
||||
person.name = "NewName";
|
||||
|
||||
session.save(person);
|
||||
|
||||
assertEquals("NewName", g.V("p-3").values("name").next());
|
||||
}
|
||||
|
||||
@Test
|
||||
void saveVertexAddsToIdentityMap() {
|
||||
Person person = new Person();
|
||||
person.name = "Dan";
|
||||
|
||||
session.save(person);
|
||||
|
||||
// load() should return the same Java object from the identity map
|
||||
Person fromCache = session.load(Person.class, person.getId());
|
||||
assertSame(person, fromCache);
|
||||
}
|
||||
|
||||
// --- save edge ---
|
||||
|
||||
@Test
|
||||
void savePersistsNewEdge() {
|
||||
graph.addVertex(T.id, "p-4", T.label, "Person");
|
||||
graph.addVertex(T.id, "c-1", T.label, "Company");
|
||||
|
||||
WorksAt edge = new WorksAt();
|
||||
edge.setOutVertexId(ARID.of("p-4"));
|
||||
edge.setInVertexId(ARID.of("c-1"));
|
||||
edge.role = "Engineer";
|
||||
|
||||
session.save(edge);
|
||||
|
||||
assertNotNull(edge.getId());
|
||||
assertEquals(1L, g.E().hasLabel("WORKS_AT").has("role", "Engineer").count().next());
|
||||
}
|
||||
|
||||
// --- save @SubgraphType ---
|
||||
|
||||
@Test
|
||||
void saveDelegatesToSubgraphTypeFields() {
|
||||
Person person = new Person();
|
||||
person.name = "Eve";
|
||||
Company company = new Company();
|
||||
company.name = "Acme";
|
||||
|
||||
PersonProfile profile = new PersonProfile();
|
||||
profile.person = person;
|
||||
profile.company = company;
|
||||
|
||||
session.save(profile);
|
||||
|
||||
assertNotNull(person.getId());
|
||||
assertNotNull(company.getId());
|
||||
assertEquals(1L, g.V().hasLabel("Person").has("name", "Eve").count().next());
|
||||
assertEquals(1L, g.V().hasLabel("Company").has("name", "Acme").count().next());
|
||||
}
|
||||
|
||||
// --- delete ---
|
||||
|
||||
@Test
|
||||
void deletesVertexFromGraph() {
|
||||
graph.addVertex(T.id, "p-5", T.label, "Person", "name", "Frank");
|
||||
|
||||
Person person = session.load(Person.class, ARID.of("p-5"));
|
||||
session.delete(person);
|
||||
|
||||
assertEquals(0L, g.V("p-5").count().next());
|
||||
}
|
||||
|
||||
@Test
|
||||
void deleteEvictsFromIdentityMap() {
|
||||
graph.addVertex(T.id, "p-6", T.label, "Person", "name", "Grace");
|
||||
|
||||
Person person = session.load(Person.class, ARID.of("p-6"));
|
||||
session.delete(person);
|
||||
|
||||
// Re-add the vertex with a different name; reload must hit the graph, not stale cache
|
||||
graph.addVertex(T.id, "p-6", T.label, "Person", "name", "Grace2");
|
||||
Person reloaded = session.load(Person.class, ARID.of("p-6"));
|
||||
assertEquals("Grace2", reloaded.name);
|
||||
}
|
||||
|
||||
@Test
|
||||
void deleteThrowsWhenEntityHasNoId() {
|
||||
Person person = new Person();
|
||||
assertThrows(ClothoException.class, () -> session.delete(person));
|
||||
}
|
||||
|
||||
// --- clearCache ---
|
||||
|
||||
@Test
|
||||
void clearCacheForcesFreshLoad() {
|
||||
graph.addVertex(T.id, "p-7", T.label, "Person", "name", "Hank");
|
||||
|
||||
Person first = session.load(Person.class, ARID.of("p-7"));
|
||||
session.clearCache();
|
||||
Person second = session.load(Person.class, ARID.of("p-7"));
|
||||
|
||||
assertNotSame(first, second);
|
||||
assertEquals("Hank", second.name);
|
||||
}
|
||||
|
||||
// --- assemble ---
|
||||
|
||||
@Test
|
||||
void assemblesSubgraphTypeFromMap() {
|
||||
var empV = graph.addVertex(T.id, "p-8", T.label, "Person", "name", "Ivy");
|
||||
var coV = graph.addVertex(T.id, "c-2", T.label, "Company", "name", "Corp");
|
||||
|
||||
Map<String, Object> result = new HashMap<>();
|
||||
result.put("person", empV);
|
||||
result.put("company", coV);
|
||||
|
||||
PersonProfile profile = session.assemble(PersonProfile.class, result);
|
||||
|
||||
assertNotNull(profile.person);
|
||||
assertEquals("Ivy", profile.person.name);
|
||||
assertNotNull(profile.company);
|
||||
assertEquals("Corp", profile.company.name);
|
||||
}
|
||||
}
|
||||
+181
@@ -0,0 +1,181 @@
|
||||
package com.binarygolem.clotho.session;
|
||||
|
||||
import com.binarygolem.clotho.annotation.Property;
|
||||
import com.binarygolem.clotho.annotation.VertexType;
|
||||
import com.binarygolem.clotho.exception.ClothoException;
|
||||
import com.binarygolem.clotho.model.ARID;
|
||||
import com.binarygolem.clotho.model.ClothoVertex;
|
||||
import com.binarygolem.clotho.model.TraversalDirection;
|
||||
import com.binarygolem.clotho.model.UnknownTypeBehavior;
|
||||
import com.binarygolem.clotho.registry.TypeRegistry;
|
||||
import org.apache.commons.configuration2.BaseConfiguration;
|
||||
import org.apache.commons.configuration2.Configuration;
|
||||
import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversalSource;
|
||||
import org.apache.tinkerpop.gremlin.structure.Graph;
|
||||
import org.apache.tinkerpop.gremlin.structure.T;
|
||||
import org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerGraph;
|
||||
import org.junit.jupiter.api.AfterEach;
|
||||
import org.junit.jupiter.api.BeforeEach;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
import static org.junit.jupiter.api.Assertions.*;
|
||||
import static org.junit.jupiter.api.Assumptions.assumeTrue;
|
||||
|
||||
class ClothoSessionTransactionTest {
|
||||
|
||||
@VertexType("Widget")
|
||||
static class Widget extends ClothoVertex {
|
||||
@Property("label") String label;
|
||||
|
||||
void setLabel(String label) {
|
||||
this.label = label;
|
||||
notifyFieldChanged("label");
|
||||
}
|
||||
}
|
||||
|
||||
private Graph graph;
|
||||
private GraphTraversalSource g;
|
||||
private ClothoSessionFactory factory;
|
||||
private boolean graphSupportsTransactions;
|
||||
|
||||
@AfterEach
|
||||
void tearDown() {
|
||||
ClothoSession bound = SessionContext.get();
|
||||
if (bound != null) bound.rollback();
|
||||
}
|
||||
|
||||
@BeforeEach
|
||||
void setUp() {
|
||||
Configuration conf = new BaseConfiguration();
|
||||
conf.setProperty(TinkerGraph.GREMLIN_TINKERGRAPH_VERTEX_ID_MANAGER, "ANY");
|
||||
graph = TinkerGraph.open(conf);
|
||||
g = graph.traversal();
|
||||
|
||||
TypeRegistry registry = TypeRegistry.builder()
|
||||
.registerVertex(Widget.class)
|
||||
.build();
|
||||
|
||||
factory = ClothoSessionFactory.builder()
|
||||
.g(g)
|
||||
.registry(registry)
|
||||
.unknownTypeBehavior(UnknownTypeBehavior.STRICT)
|
||||
.defaultDirection(TraversalDirection.OUT)
|
||||
.build();
|
||||
graphSupportsTransactions = graph.features().graph().supportsTransactions();
|
||||
}
|
||||
|
||||
// --- isTransactional ---
|
||||
|
||||
@Test
|
||||
void openSession_isNotTransactional() {
|
||||
try (ClothoSession session = factory.openSession()) {
|
||||
assertFalse(session.isTransactional());
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
void openTransactionalSession_isTransactional() {
|
||||
assumeTrue(graphSupportsTransactions, "graph does not support transactions");
|
||||
ClothoSession session = factory.openTransactionalSession();
|
||||
assertTrue(session.isTransactional());
|
||||
session.rollback();
|
||||
}
|
||||
|
||||
// --- borrow / close ---
|
||||
|
||||
@Test
|
||||
void openSession_whenSessionAlreadyBound_returnsSameInstance() {
|
||||
try (ClothoSession outer = factory.openSession()) {
|
||||
ClothoSession inner = factory.openSession();
|
||||
assertSame(outer, inner);
|
||||
inner.close(); // no-op: borrow count still > 0
|
||||
assertNotNull(SessionContext.get(), "session must still be bound after borrowed close");
|
||||
} // outer close: real flush
|
||||
assertNull(SessionContext.get(), "session must be unbound after final close");
|
||||
}
|
||||
|
||||
@Test
|
||||
void borrowedSession_closeIsNoOpUntilAllBorrowsReturned() {
|
||||
graph.addVertex(T.id, "w-1", T.label, "Widget", "label", "original");
|
||||
|
||||
try (ClothoSession outer = factory.openSession()) {
|
||||
Widget w = outer.load(Widget.class, ARID.of("w-1"));
|
||||
w.setLabel("modified");
|
||||
|
||||
ClothoSession borrowed = factory.openSession();
|
||||
assertSame(outer, borrowed);
|
||||
borrowed.close(); // borrow close — must NOT flush
|
||||
|
||||
// Dirty field must still be present (flush not yet triggered)
|
||||
assertFalse(w.getDirtyFields().isEmpty());
|
||||
}
|
||||
// Real close: auto-save fires, persists "modified"
|
||||
assertEquals("modified", g.V("w-1").values("label").next());
|
||||
}
|
||||
|
||||
// --- rollback ---
|
||||
|
||||
@Test
|
||||
void rollback_unbindsSession() {
|
||||
ClothoSession session = factory.openSession();
|
||||
assertNotNull(SessionContext.get());
|
||||
session.rollback();
|
||||
assertNull(SessionContext.get());
|
||||
}
|
||||
|
||||
@Test
|
||||
void rollback_preventsAutoSave() {
|
||||
graph.addVertex(T.id, "w-2", T.label, "Widget", "label", "before");
|
||||
|
||||
ClothoSession session = factory.openSession();
|
||||
Widget w = session.load(Widget.class, ARID.of("w-2"));
|
||||
w.setLabel("after");
|
||||
session.rollback(); // discard without saving
|
||||
|
||||
assertEquals("before", g.V("w-2").values("label").next());
|
||||
}
|
||||
|
||||
// --- getCurrentSession ---
|
||||
|
||||
@Test
|
||||
void getCurrentSession_throwsWhenNoSessionBound() {
|
||||
assertNull(SessionContext.get(), "precondition: no session before test");
|
||||
assertThrows(ClothoException.class, () -> factory.getCurrentSession());
|
||||
}
|
||||
|
||||
@Test
|
||||
void getCurrentSession_returnsBoundSession() {
|
||||
try (ClothoSession session = factory.openSession()) {
|
||||
assertSame(session, factory.getCurrentSession());
|
||||
}
|
||||
}
|
||||
|
||||
// --- transactional session ---
|
||||
|
||||
@Test
|
||||
void transactionalSession_closeSavesChanges() {
|
||||
assumeTrue(graphSupportsTransactions, "graph does not support transactions");
|
||||
Widget w = new Widget();
|
||||
w.setLabel("saved-tx");
|
||||
|
||||
ClothoSession session = factory.openTransactionalSession();
|
||||
session.save(w);
|
||||
session.close();
|
||||
|
||||
assertNotNull(w.getId());
|
||||
assertEquals(1L, g.V().hasLabel("Widget").has("label", "saved-tx").count().next());
|
||||
}
|
||||
|
||||
@Test
|
||||
void transactionalSession_rollbackDiscardsSave() {
|
||||
assumeTrue(graphSupportsTransactions, "graph does not support transactions");
|
||||
Widget w = new Widget();
|
||||
w.setLabel("not-saved");
|
||||
|
||||
ClothoSession session = factory.openTransactionalSession();
|
||||
session.save(w);
|
||||
session.rollback();
|
||||
|
||||
assertNull(SessionContext.get());
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,95 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project xmlns="http://maven.apache.org/POM/4.0.0"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
|
||||
http://maven.apache.org/xsd/maven-4.0.0.xsd">
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
||||
<parent>
|
||||
<groupId>com.binarygolem.clotho</groupId>
|
||||
<artifactId>clotho-parent</artifactId>
|
||||
<version>0.1.0-SNAPSHOT</version>
|
||||
</parent>
|
||||
|
||||
<artifactId>clotho-dev-app</artifactId>
|
||||
<name>Clotho Dev App</name>
|
||||
<description>
|
||||
Development sandbox — connects to a live ArcadeDB instance for manual and
|
||||
exploratory testing during library development. Not a production artifact.
|
||||
</description>
|
||||
|
||||
<dependencies>
|
||||
|
||||
<dependency>
|
||||
<groupId>com.binarygolem.clotho</groupId>
|
||||
<artifactId>clotho-spring-boot-starter</artifactId>
|
||||
</dependency>
|
||||
|
||||
<!-- Spring Boot baseline: context, logging, autoconfigure -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter</artifactId>
|
||||
</dependency>
|
||||
|
||||
<dependency>
|
||||
<groupId>org.projectlombok</groupId>
|
||||
<artifactId>lombok</artifactId>
|
||||
<scope>provided</scope>
|
||||
</dependency>
|
||||
|
||||
<dependency>
|
||||
<groupId>org.jspecify</groupId>
|
||||
<artifactId>jspecify</artifactId>
|
||||
</dependency>
|
||||
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-configuration-processor</artifactId>
|
||||
<optional>true</optional>
|
||||
</dependency>
|
||||
|
||||
<!-- Test -->
|
||||
<dependency>
|
||||
<groupId>org.junit.jupiter</groupId>
|
||||
<artifactId>junit-jupiter</artifactId>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-test</artifactId>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
|
||||
</dependencies>
|
||||
|
||||
<build>
|
||||
<plugins>
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-compiler-plugin</artifactId>
|
||||
<configuration>
|
||||
<annotationProcessorPaths>
|
||||
<path>
|
||||
<groupId>org.projectlombok</groupId>
|
||||
<artifactId>lombok</artifactId>
|
||||
<version>${lombok.version}</version>
|
||||
</path>
|
||||
</annotationProcessorPaths>
|
||||
</configuration>
|
||||
</plugin>
|
||||
<plugin>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-maven-plugin</artifactId>
|
||||
<executions>
|
||||
<execution>
|
||||
<goals>
|
||||
<goal>repackage</goal>
|
||||
</goals>
|
||||
</execution>
|
||||
</executions>
|
||||
</plugin>
|
||||
</plugins>
|
||||
</build>
|
||||
|
||||
</project>
|
||||
@@ -0,0 +1,12 @@
|
||||
package com.binarygolem.clotho.dev;
|
||||
|
||||
import org.springframework.boot.SpringApplication;
|
||||
import org.springframework.boot.autoconfigure.SpringBootApplication;
|
||||
|
||||
@SpringBootApplication
|
||||
public class ClothoDevApp {
|
||||
|
||||
public static void main(String[] args) {
|
||||
SpringApplication.run(ClothoDevApp.class, args);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,25 @@
|
||||
package com.binarygolem.clotho.dev;
|
||||
|
||||
import lombok.RequiredArgsConstructor;
|
||||
import lombok.extern.slf4j.Slf4j;
|
||||
import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversalSource;
|
||||
import org.springframework.boot.ApplicationArguments;
|
||||
import org.springframework.boot.ApplicationRunner;
|
||||
import org.springframework.core.annotation.Order;
|
||||
import org.springframework.stereotype.Component;
|
||||
|
||||
@Slf4j
|
||||
@Component
|
||||
@Order(1)
|
||||
@RequiredArgsConstructor
|
||||
public class ConnectionSmokeTest implements ApplicationRunner {
|
||||
|
||||
private final GraphTraversalSource traversalSource;
|
||||
|
||||
@Override
|
||||
public void run(ApplicationArguments args) {
|
||||
log.info("Testing Gremlin connection...");
|
||||
long count = traversalSource.V().count().next();
|
||||
log.info("Connection OK — total vertex count: {}", count);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,39 @@
|
||||
package com.binarygolem.clotho.dev;
|
||||
|
||||
import org.apache.tinkerpop.gremlin.driver.Cluster;
|
||||
import org.apache.tinkerpop.gremlin.driver.remote.DriverRemoteConnection;
|
||||
import org.apache.tinkerpop.gremlin.process.traversal.AnonymousTraversalSource;
|
||||
import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversalSource;
|
||||
import org.apache.tinkerpop.gremlin.util.ser.GraphSONMessageSerializerV3;
|
||||
import org.springframework.boot.context.properties.EnableConfigurationProperties;
|
||||
import org.springframework.context.annotation.Bean;
|
||||
import org.springframework.context.annotation.Configuration;
|
||||
|
||||
import java.net.URI;
|
||||
|
||||
@Configuration
|
||||
@EnableConfigurationProperties(GremlinProperties.class)
|
||||
public class GremlinConfig {
|
||||
|
||||
@Bean(destroyMethod = "close")
|
||||
public Cluster gremlinCluster(GremlinProperties props) {
|
||||
URI uri = URI.create(props.getUrl());
|
||||
int port = uri.getPort() > 0 ? uri.getPort() : 8182;
|
||||
return Cluster.build()
|
||||
.addContactPoint(uri.getHost())
|
||||
.port(port)
|
||||
.credentials(props.getUsername(), props.getPassword())
|
||||
.serializer(new GraphSONMessageSerializerV3())
|
||||
.create();
|
||||
}
|
||||
|
||||
@Bean
|
||||
public DriverRemoteConnection remoteConnection(Cluster cluster, GremlinProperties props) {
|
||||
return DriverRemoteConnection.using(cluster, props.getTraversalSource());
|
||||
}
|
||||
|
||||
@Bean(destroyMethod = "close")
|
||||
public GraphTraversalSource traversalSource(DriverRemoteConnection connection) {
|
||||
return AnonymousTraversalSource.traversal().withRemote(connection);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
package com.binarygolem.clotho.dev;
|
||||
|
||||
import lombok.Data;
|
||||
import org.springframework.boot.context.properties.ConfigurationProperties;
|
||||
|
||||
@ConfigurationProperties("clotho.gremlin")
|
||||
@Data
|
||||
public class GremlinProperties {
|
||||
|
||||
private String url = "";
|
||||
private String username = "";
|
||||
private String password = "";
|
||||
private String traversalSource = "g";
|
||||
}
|
||||
@@ -0,0 +1,301 @@
|
||||
package com.binarygolem.clotho.dev.demo;
|
||||
|
||||
import com.binarygolem.clotho.dev.demo.model.Company;
|
||||
import com.binarygolem.clotho.dev.demo.model.Person;
|
||||
import com.binarygolem.clotho.dev.demo.model.WorksAt;
|
||||
import com.binarygolem.clotho.dev.demo.repository.PersonRepository;
|
||||
import com.binarygolem.clotho.model.ARID;
|
||||
import com.binarygolem.clotho.session.ClothoSession;
|
||||
import com.binarygolem.clotho.session.ClothoSessionFactory;
|
||||
import lombok.RequiredArgsConstructor;
|
||||
import lombok.extern.slf4j.Slf4j;
|
||||
import org.jspecify.annotations.Nullable;
|
||||
import org.springframework.boot.ApplicationArguments;
|
||||
import org.springframework.boot.ApplicationRunner;
|
||||
import org.springframework.core.annotation.Order;
|
||||
import org.springframework.stereotype.Component;
|
||||
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* Demonstrates core Clotho features against a live ArcadeDB instance.
|
||||
*
|
||||
* <p>Requires these ArcadeDB types to exist before running:
|
||||
* <pre>
|
||||
* CREATE VERTEX TYPE Person;
|
||||
* CREATE PROPERTY Person.name STRING;
|
||||
* CREATE PROPERTY Person.email STRING;
|
||||
* CREATE PROPERTY Person.age INTEGER;
|
||||
*
|
||||
* CREATE VERTEX TYPE Company;
|
||||
* CREATE PROPERTY Company.name STRING;
|
||||
* CREATE PROPERTY Company.industry STRING;
|
||||
*
|
||||
* CREATE EDGE TYPE WORKS_AT;
|
||||
* CREATE PROPERTY WORKS_AT.role STRING;
|
||||
* CREATE PROPERTY WORKS_AT.startYear INTEGER;
|
||||
* </pre>
|
||||
*
|
||||
* <p>All demo data is cleaned up after the run regardless of success or failure.
|
||||
*/
|
||||
@Slf4j
|
||||
@Component
|
||||
@Order(2)
|
||||
@RequiredArgsConstructor
|
||||
public class FeatureDemo implements ApplicationRunner {
|
||||
|
||||
private final ClothoSessionFactory sessionFactory;
|
||||
private final PersonRepository personRepository;
|
||||
|
||||
@Override
|
||||
public void run(ApplicationArguments args) {
|
||||
log.info("");
|
||||
log.info("══════════════════════════════════════");
|
||||
log.info(" Clotho Feature Demo ");
|
||||
log.info("══════════════════════════════════════");
|
||||
|
||||
@Nullable ARID personId = null;
|
||||
@Nullable ARID bobId = null;
|
||||
@Nullable ARID charlieId = null;
|
||||
@Nullable ARID companyId = null;
|
||||
|
||||
try {
|
||||
// ── 1. Create entities (session cascades: person → edge → company) ──
|
||||
log.info("");
|
||||
log.info("1. Creating entities");
|
||||
|
||||
try (ClothoSession session = sessionFactory.openSession()) {
|
||||
Company acme = new Company();
|
||||
acme.setName("Acme Corp");
|
||||
acme.setIndustry("Technology");
|
||||
|
||||
Person alice = new Person();
|
||||
alice.setName("Alice Smith");
|
||||
alice.setEmail("alice@example.com");
|
||||
alice.setAge(32);
|
||||
WorksAt aliceJob = new WorksAt();
|
||||
aliceJob.setCompany(acme);
|
||||
aliceJob.setRole("Senior Engineer");
|
||||
aliceJob.setStartYear(2020);
|
||||
alice.setJobs(List.of(aliceJob));
|
||||
|
||||
Person bob = new Person();
|
||||
bob.setName("Bob Jones");
|
||||
bob.setEmail("bob@example.com");
|
||||
bob.setAge(28);
|
||||
WorksAt bobJob = new WorksAt();
|
||||
bobJob.setCompany(acme);
|
||||
bobJob.setRole("Engineer");
|
||||
bobJob.setStartYear(2022);
|
||||
bob.setJobs(List.of(bobJob));
|
||||
|
||||
Person charlie = new Person();
|
||||
charlie.setName("Charlie Lee");
|
||||
charlie.setEmail("charlie@example.com");
|
||||
charlie.setAge(41);
|
||||
WorksAt charlieJob = new WorksAt();
|
||||
charlieJob.setCompany(acme);
|
||||
charlieJob.setRole("Engineering Manager");
|
||||
charlieJob.setStartYear(2018);
|
||||
charlie.setJobs(List.of(charlieJob));
|
||||
|
||||
session.save(alice);
|
||||
session.save(bob);
|
||||
session.save(charlie);
|
||||
|
||||
personId = alice.getId();
|
||||
bobId = bob.getId();
|
||||
charlieId = charlie.getId();
|
||||
companyId = acme.getId();
|
||||
|
||||
log.info(" ✓ Company {} → {}", acme.getName(), acme.getId());
|
||||
log.info(" ✓ Person {} ({}) → {}", alice.getName(), aliceJob.getRole(), alice.getId());
|
||||
log.info(" ✓ Person {} ({}) → {}", bob.getName(), bobJob.getRole(), bob.getId());
|
||||
log.info(" ✓ Person {} ({}) → {}", charlie.getName(), charlieJob.getRole(), charlie.getId());
|
||||
}
|
||||
|
||||
// ── 2. Load by ID — @Include boundary auto-populated in a single query ──
|
||||
log.info("");
|
||||
log.info("2. Loading by ID (@Include populated atomically)");
|
||||
|
||||
try (ClothoSession session = sessionFactory.openSession()) {
|
||||
Person alice = session.load(Person.class, personId);
|
||||
List<WorksAt> jobs = alice.getJobs();
|
||||
|
||||
log.info(" ✓ Loaded: {} (age {}), {} job(s)", alice.getName(), alice.getAge(),
|
||||
jobs == null ? 0 : jobs.size());
|
||||
|
||||
if (jobs != null && !jobs.isEmpty()) {
|
||||
WorksAt job = jobs.get(0);
|
||||
String companyName = job.getCompany() != null ? job.getCompany().getName() : "?";
|
||||
log.info(" └─ {} at {} (since {})", job.getRole(), companyName, job.getStartYear());
|
||||
}
|
||||
}
|
||||
|
||||
// ── 3. Dirty tracking — only modified fields are written ──
|
||||
log.info("");
|
||||
log.info("3. Dirty tracking (partial update)");
|
||||
|
||||
try (ClothoSession session = sessionFactory.openSession()) {
|
||||
Person alice = session.load(Person.class, personId);
|
||||
alice.setEmail("alice.smith@example.com"); // dirty: email
|
||||
alice.setAge(33); // dirty: age
|
||||
// name is unchanged — not written
|
||||
session.save(alice);
|
||||
log.info(" ✓ Saved 2 dirty fields (email, age); name not touched");
|
||||
}
|
||||
|
||||
try (ClothoSession session = sessionFactory.openSession()) {
|
||||
Person alice = session.load(Person.class, personId);
|
||||
log.info(" ✓ Verified: email={}, age={}", alice.getEmail(), alice.getAge());
|
||||
}
|
||||
|
||||
// ── 4. Auto-save on session close ──
|
||||
log.info("");
|
||||
log.info("4. Auto-save on session close");
|
||||
|
||||
try (ClothoSession session = sessionFactory.openSession()) {
|
||||
Person alice = session.load(Person.class, personId);
|
||||
alice.setAge(34);
|
||||
// no explicit save() — session.close() persists dirty MANAGED entities
|
||||
}
|
||||
|
||||
try (ClothoSession session = sessionFactory.openSession()) {
|
||||
Person alice = session.load(Person.class, personId);
|
||||
log.info(" ✓ Age auto-saved on close: {}", alice.getAge());
|
||||
}
|
||||
|
||||
// ── 5. Repository queries ──
|
||||
log.info("");
|
||||
log.info("5. Repository queries");
|
||||
|
||||
List<Person> byName = personRepository.findByName("Alice Smith");
|
||||
log.info(" ✓ findByName(\"Alice Smith\"): {} result(s)", byName.size());
|
||||
|
||||
List<Person> byAge = personRepository.findByAgeGreaterThan(30);
|
||||
log.info(" ✓ findByAgeGreaterThan(30): {} result(s)", byAge.size());
|
||||
|
||||
List<Person> employed = personRepository.findEmployed();
|
||||
log.info(" ✓ findEmployed(): {} result(s)", employed.size());
|
||||
|
||||
long total = personRepository.count();
|
||||
log.info(" ✓ count(): {} total Person(s) in graph", total);
|
||||
|
||||
// ── 6. Ad-hoc traversal + session-aware execute ──
|
||||
log.info("");
|
||||
log.info("6. Ad-hoc traversal: findCoworkers() with session-aware execute");
|
||||
log.info(" (traverses WORKS_AT not declared as @Include — results are MANAGED)");
|
||||
|
||||
@Nullable ARID firstCoworkerId = null;
|
||||
|
||||
try (ClothoSession session = sessionFactory.openSession()) {
|
||||
Person alice = session.load(Person.class, personId);
|
||||
// session-aware overload: returned entities are MANAGED in this session
|
||||
List<Person> coworkers = personRepository.findCoworkers(alice, session);
|
||||
log.info(" ✓ Alice's co-workers at Acme Corp: {} found", coworkers.size());
|
||||
for (Person cw : coworkers) {
|
||||
String role = cw.getJobs() != null && !cw.getJobs().isEmpty()
|
||||
? cw.getJobs().get(0).getRole() : "?";
|
||||
log.info(" └─ {} ({})", cw.getName(), role);
|
||||
}
|
||||
if (!coworkers.isEmpty()) {
|
||||
firstCoworkerId = coworkers.get(0).getId();
|
||||
coworkers.get(0).setEmail("updated-by-demo@example.com");
|
||||
// no explicit save() — dirty tracking fires; auto-saved on session close
|
||||
}
|
||||
} // ← session.close() auto-saves the dirty co-worker here
|
||||
|
||||
if (firstCoworkerId != null) {
|
||||
try (ClothoSession session = sessionFactory.openSession()) {
|
||||
Person cw = session.load(Person.class, firstCoworkerId);
|
||||
log.info(" ✓ Co-worker email auto-saved on close: {}", cw.getEmail());
|
||||
}
|
||||
}
|
||||
|
||||
// ── 7. Transactional session ──
|
||||
log.info("");
|
||||
log.info("7. Transactional session (atomic multi-step write)");
|
||||
|
||||
ARID txPersonId = null;
|
||||
try (ClothoSession session = sessionFactory.openTransactionalSession()) {
|
||||
Company startupCo = new Company();
|
||||
startupCo.setName("StartupCo");
|
||||
startupCo.setIndustry("FinTech");
|
||||
|
||||
Person diana = new Person();
|
||||
diana.setName("Diana Prince");
|
||||
diana.setEmail("diana@startupco.io");
|
||||
diana.setAge(29);
|
||||
|
||||
// openSession() inside a transactional session borrows the same session
|
||||
ClothoSession borrowed = sessionFactory.openSession();
|
||||
log.info(" openSession() inside @Transactional returns same session? {}",
|
||||
borrowed == session ? "yes" : "no");
|
||||
borrowed.close(); // borrow close — no-op
|
||||
|
||||
session.save(diana);
|
||||
txPersonId = diana.getId();
|
||||
log.info(" ✓ Diana created: {} → {}", diana.getName(), diana.getId());
|
||||
log.info(" ✓ (company would be linked here; session commits on close)");
|
||||
} // ← tx.commit() fires here
|
||||
|
||||
if (txPersonId != null) {
|
||||
try (ClothoSession session = sessionFactory.openSession()) {
|
||||
Person diana = session.load(Person.class, txPersonId);
|
||||
log.info(" ✓ Verified commit: {} loaded after tx close", diana.getName());
|
||||
session.delete(diana);
|
||||
}
|
||||
}
|
||||
|
||||
} catch (Exception e) {
|
||||
log.error("Demo failed — check that the required ArcadeDB schema exists", e);
|
||||
log.error("Required types: Person, Company, WORKS_AT (see FeatureDemo Javadoc)");
|
||||
|
||||
} finally {
|
||||
cleanup(personId, bobId, charlieId, companyId);
|
||||
}
|
||||
}
|
||||
|
||||
private void cleanup(@Nullable ARID personId, @Nullable ARID bobId,
|
||||
@Nullable ARID charlieId, @Nullable ARID companyId) {
|
||||
log.info("");
|
||||
log.info("Cleaning up demo data");
|
||||
try {
|
||||
// Delete all persons in one traversal. Sequential per-session deletes cause OrientDB's
|
||||
// Gremlin Server to cache the Company vertex at its initial @version and then fail the
|
||||
// MVCC check when cascade-deleting later edges bumps the DB version above the cached one.
|
||||
// A single g.V(...).drop() request loads Company once and applies all cascades atomically.
|
||||
List<Object> personIds = new ArrayList<>();
|
||||
if (personId != null) personIds.add(personId.asString());
|
||||
if (bobId != null) personIds.add(bobId.asString());
|
||||
if (charlieId != null) personIds.add(charlieId.asString());
|
||||
if (!personIds.isEmpty()) {
|
||||
sessionFactory.traversal().V(personIds.toArray()).drop().iterate();
|
||||
log.info(" ✓ Deleted {} Person(s) (+ incident WORKS_AT edge(s))", personIds.size());
|
||||
}
|
||||
if (companyId != null) {
|
||||
try {
|
||||
sessionFactory.traversal().V(companyId.asString()).drop().iterate();
|
||||
log.info(" ✓ Deleted Company");
|
||||
} catch (Exception e) {
|
||||
// OrientDB cascade-deletes the Company when the last incident WORKS_AT edge is
|
||||
// removed by the person bulk-drop above — treat "not found" as already gone.
|
||||
if (e.getMessage() != null && e.getMessage().contains("was not found")) {
|
||||
log.info(" ✓ Company already removed (cascade)");
|
||||
} else {
|
||||
throw e;
|
||||
}
|
||||
}
|
||||
}
|
||||
} catch (Exception e) {
|
||||
log.warn("Cleanup failed — demo data may remain in the graph: {}", e.getMessage());
|
||||
}
|
||||
|
||||
log.info("");
|
||||
log.info("══════════════════════════════════════");
|
||||
log.info(" Demo complete ");
|
||||
log.info("══════════════════════════════════════");
|
||||
log.info("");
|
||||
}
|
||||
}
|
||||
+103
@@ -0,0 +1,103 @@
|
||||
package com.binarygolem.clotho.dev.demo;
|
||||
|
||||
import com.binarygolem.clotho.session.ClothoSessionFactory;
|
||||
import lombok.RequiredArgsConstructor;
|
||||
import lombok.extern.slf4j.Slf4j;
|
||||
import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversalSource;
|
||||
import org.apache.tinkerpop.gremlin.structure.Vertex;
|
||||
import org.springframework.boot.ApplicationArguments;
|
||||
import org.springframework.boot.ApplicationRunner;
|
||||
import org.springframework.core.annotation.Order;
|
||||
import org.springframework.stereotype.Component;
|
||||
|
||||
/**
|
||||
* Confirms that Clotho's application-managed {@code @Version} OCC mechanism works
|
||||
* against a live ArcadeDB instance.
|
||||
*
|
||||
* <p>ArcadeDB's internal {@code @version} property is not accessible via the Gremlin
|
||||
* WebSocket interface. Clotho therefore manages the version counter itself as a regular
|
||||
* graph property (default: {@code "_version"}). This probe verifies that the Gremlin
|
||||
* filter step {@code .has("_version", expectedValue)} works correctly with ArcadeDB for
|
||||
* regular properties — the foundation of the pre-flight conflict check.
|
||||
*/
|
||||
@Slf4j
|
||||
@Component
|
||||
@Order(3)
|
||||
@RequiredArgsConstructor
|
||||
public class VersionConflictProbe implements ApplicationRunner {
|
||||
|
||||
private final ClothoSessionFactory sessionFactory;
|
||||
|
||||
@Override
|
||||
public void run(ApplicationArguments args) {
|
||||
log.info("");
|
||||
log.info("══════════════════════════════════════════════════════");
|
||||
log.info(" Clotho @Version OCC Mechanism Smoke Test ");
|
||||
log.info("══════════════════════════════════════════════════════");
|
||||
|
||||
GraphTraversalSource g = sessionFactory.traversal();
|
||||
String probeId = null;
|
||||
|
||||
try {
|
||||
// Create a vertex with an initial _version=0 (mimics what Clotho does on persist)
|
||||
Vertex v = g.addV("Person")
|
||||
.property("name", "OccProbe")
|
||||
.property("_version", 0L)
|
||||
.next();
|
||||
probeId = v.id().toString();
|
||||
log.info(" Probe vertex created: {}", probeId);
|
||||
|
||||
// ── Part 1: does .has("_version", value) actually filter? ──
|
||||
log.info("");
|
||||
log.info("Part 1: _version filter works with regular properties");
|
||||
|
||||
long matchCorrect = g.V(probeId).has("_version", 0L).count().next();
|
||||
long matchWrong = g.V(probeId).has("_version", 99L).count().next();
|
||||
log.info(" .has('_version', 0L) → {}", matchCorrect);
|
||||
log.info(" .has('_version', 99L) → {}", matchWrong);
|
||||
boolean filterWorks = matchCorrect == 1 && matchWrong == 0;
|
||||
log.info(" → Filter functional? → {}", filterWorks ? "YES ✓" : "NO ✗");
|
||||
|
||||
// ── Part 2: pre-flight check + atomic version-increment update ──
|
||||
log.info("");
|
||||
log.info("Part 2: check-and-increment update (Clotho's write step)");
|
||||
|
||||
// This is what Clotho's updateEntity() does: filter by version, write dirty props,
|
||||
// increment version — all in one traversal.
|
||||
long updated = g.V(probeId)
|
||||
.has("_version", 0L)
|
||||
.property("name", "OccProbe-v1")
|
||||
.property("_version", 1L)
|
||||
.count().next();
|
||||
log.info(" Update with correct version (0→1): matched={}", updated);
|
||||
|
||||
// Try stale update — version is now 1, so filtering by 0 must return 0
|
||||
long stale = g.V(probeId)
|
||||
.has("_version", 0L)
|
||||
.property("name", "MUST-NOT-BE-WRITTEN")
|
||||
.count().next();
|
||||
log.info(" Update with stale version (0 after bump): matched={}", stale);
|
||||
|
||||
String finalName = (String) g.V(probeId).values("name").next();
|
||||
Long finalVer = (Long) g.V(probeId).values("_version").next();
|
||||
log.info(" Final name: {} (expected: OccProbe-v1)", finalName);
|
||||
log.info(" Final _version: {} (expected: 1)", finalVer);
|
||||
|
||||
boolean occWorks = updated == 1 && stale == 0
|
||||
&& "OccProbe-v1".equals(finalName) && Long.valueOf(1L).equals(finalVer);
|
||||
log.info(" → Application-managed OCC works? → {}", occWorks ? "YES ✓" : "NO ✗");
|
||||
|
||||
} catch (Exception e) {
|
||||
log.error("Probe failed unexpectedly", e);
|
||||
} finally {
|
||||
if (probeId != null) {
|
||||
try { g.V(probeId).drop().iterate(); } catch (Exception ignored) {}
|
||||
}
|
||||
log.info("");
|
||||
log.info("══════════════════════════════════════════════════════");
|
||||
log.info(" Probe complete ");
|
||||
log.info("══════════════════════════════════════════════════════");
|
||||
log.info("");
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,38 @@
|
||||
package com.binarygolem.clotho.dev.demo.model;
|
||||
|
||||
import com.binarygolem.clotho.annotation.Property;
|
||||
import com.binarygolem.clotho.annotation.VertexType;
|
||||
import com.binarygolem.clotho.model.ClothoVertex;
|
||||
import lombok.Getter;
|
||||
import org.jspecify.annotations.Nullable;
|
||||
|
||||
/**
|
||||
* ArcadeDB type: {@code Company}.
|
||||
*
|
||||
* <p>Required schema:
|
||||
* <pre>
|
||||
* CREATE VERTEX TYPE Company;
|
||||
* CREATE PROPERTY Company.name STRING;
|
||||
* CREATE PROPERTY Company.industry STRING;
|
||||
* </pre>
|
||||
*/
|
||||
@VertexType("Company")
|
||||
@Getter
|
||||
public class Company extends ClothoVertex {
|
||||
|
||||
@Property("name")
|
||||
private @Nullable String name;
|
||||
|
||||
@Property("industry")
|
||||
private @Nullable String industry;
|
||||
|
||||
public void setName(@Nullable String name) {
|
||||
this.name = name;
|
||||
notifyFieldChanged("name");
|
||||
}
|
||||
|
||||
public void setIndustry(@Nullable String industry) {
|
||||
this.industry = industry;
|
||||
notifyFieldChanged("industry");
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,60 @@
|
||||
package com.binarygolem.clotho.dev.demo.model;
|
||||
|
||||
import com.binarygolem.clotho.annotation.Include;
|
||||
import com.binarygolem.clotho.annotation.Property;
|
||||
import com.binarygolem.clotho.annotation.VertexType;
|
||||
import com.binarygolem.clotho.annotation.Via;
|
||||
import com.binarygolem.clotho.model.ClothoVertex;
|
||||
import lombok.Getter;
|
||||
import org.jspecify.annotations.Nullable;
|
||||
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* ArcadeDB type: {@code Person}.
|
||||
*
|
||||
* <p>Required schema:
|
||||
* <pre>
|
||||
* CREATE VERTEX TYPE Person;
|
||||
* CREATE PROPERTY Person.name STRING;
|
||||
* CREATE PROPERTY Person.email STRING;
|
||||
* CREATE PROPERTY Person.age INTEGER;
|
||||
* </pre>
|
||||
*/
|
||||
@VertexType("Person")
|
||||
@Getter
|
||||
public class Person extends ClothoVertex {
|
||||
|
||||
@Property("name")
|
||||
private @Nullable String name;
|
||||
|
||||
@Property("email")
|
||||
private @Nullable String email;
|
||||
|
||||
@Property("age")
|
||||
private @Nullable Integer age;
|
||||
|
||||
@Include
|
||||
@Via("WORKS_AT")
|
||||
private @Nullable List<WorksAt> jobs;
|
||||
|
||||
public void setName(@Nullable String name) {
|
||||
this.name = name;
|
||||
notifyFieldChanged("name");
|
||||
}
|
||||
|
||||
public void setEmail(@Nullable String email) {
|
||||
this.email = email;
|
||||
notifyFieldChanged("email");
|
||||
}
|
||||
|
||||
public void setAge(@Nullable Integer age) {
|
||||
this.age = age;
|
||||
notifyFieldChanged("age");
|
||||
}
|
||||
|
||||
public void setJobs(@Nullable List<WorksAt> jobs) {
|
||||
this.jobs = jobs;
|
||||
notifyFieldChanged("jobs");
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,56 @@
|
||||
package com.binarygolem.clotho.dev.demo.model;
|
||||
|
||||
import com.binarygolem.clotho.annotation.EdgeType;
|
||||
import com.binarygolem.clotho.annotation.InVertex;
|
||||
import com.binarygolem.clotho.annotation.OutVertex;
|
||||
import com.binarygolem.clotho.annotation.Property;
|
||||
import com.binarygolem.clotho.model.ClothoEdge;
|
||||
import lombok.Getter;
|
||||
import org.jspecify.annotations.Nullable;
|
||||
|
||||
/**
|
||||
* ArcadeDB type: {@code WORKS_AT}.
|
||||
*
|
||||
* <p>Required schema:
|
||||
* <pre>
|
||||
* CREATE EDGE TYPE WORKS_AT;
|
||||
* CREATE PROPERTY WORKS_AT.role STRING;
|
||||
* CREATE PROPERTY WORKS_AT.startYear INTEGER;
|
||||
* </pre>
|
||||
*/
|
||||
@EdgeType("WORKS_AT")
|
||||
@Getter
|
||||
public class WorksAt extends ClothoEdge {
|
||||
|
||||
@Property("role")
|
||||
private @Nullable String role;
|
||||
|
||||
@Property("startYear")
|
||||
private @Nullable Integer startYear;
|
||||
|
||||
@OutVertex
|
||||
private @Nullable Person person;
|
||||
|
||||
@InVertex
|
||||
private @Nullable Company company;
|
||||
|
||||
public void setRole(@Nullable String role) {
|
||||
this.role = role;
|
||||
notifyFieldChanged("role");
|
||||
}
|
||||
|
||||
public void setStartYear(@Nullable Integer startYear) {
|
||||
this.startYear = startYear;
|
||||
notifyFieldChanged("startYear");
|
||||
}
|
||||
|
||||
public void setPerson(@Nullable Person person) {
|
||||
this.person = person;
|
||||
notifyFieldChanged("person");
|
||||
}
|
||||
|
||||
public void setCompany(@Nullable Company company) {
|
||||
this.company = company;
|
||||
notifyFieldChanged("company");
|
||||
}
|
||||
}
|
||||
+61
@@ -0,0 +1,61 @@
|
||||
package com.binarygolem.clotho.dev.demo.repository;
|
||||
|
||||
import com.binarygolem.clotho.dev.demo.model.Person;
|
||||
import com.binarygolem.clotho.repository.ClothoRepository;
|
||||
import com.binarygolem.clotho.session.ClothoSession;
|
||||
import com.binarygolem.clotho.session.ClothoSessionFactory;
|
||||
import org.apache.tinkerpop.gremlin.process.traversal.P;
|
||||
import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.__;
|
||||
|
||||
import java.util.List;
|
||||
|
||||
@com.binarygolem.clotho.annotation.ClothoRepository
|
||||
public class PersonRepository extends ClothoRepository<Person> {
|
||||
|
||||
public PersonRepository(ClothoSessionFactory factory) {
|
||||
super(factory);
|
||||
}
|
||||
|
||||
public List<Person> findByName(String name) {
|
||||
return execute(g().V().has("Person", "name", name));
|
||||
}
|
||||
|
||||
public List<Person> findByAgeGreaterThan(int minAge) {
|
||||
return execute(allEntities(), t -> t.has("age", P.gt(minAge)));
|
||||
}
|
||||
|
||||
/** Returns all people who have at least one outgoing WORKS_AT edge. */
|
||||
public List<Person> findEmployed() {
|
||||
return execute(allEntities(), t -> t.where(__.outE("WORKS_AT")));
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns co-workers as detached (untracked) entities — suitable for read-only use.
|
||||
*
|
||||
* <p>Traverses WORKS_AT edges that are not declared as {@code @Include} on
|
||||
* {@code Person}, demonstrating that repository methods can freely cross any
|
||||
* edge in the graph regardless of object-boundary declarations.
|
||||
*/
|
||||
public List<Person> findCoworkers(Person person) {
|
||||
return execute(
|
||||
g().V(person.getId().asString()).as("self")
|
||||
.out("WORKS_AT") // Person → Company
|
||||
.in("WORKS_AT") // Company → all Persons at that company
|
||||
.where(P.neq("self"))
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns co-workers registered into {@code session} as MANAGED entities.
|
||||
* Dirty-field changes on the returned objects are tracked and auto-saved when
|
||||
* the session closes — no explicit {@code save()} needed.
|
||||
*/
|
||||
public List<Person> findCoworkers(Person person, ClothoSession session) {
|
||||
return execute(session,
|
||||
g().V(person.getId().asString()).as("self")
|
||||
.out("WORKS_AT")
|
||||
.in("WORKS_AT")
|
||||
.where(P.neq("self"))
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,4 @@
|
||||
@NullMarked
|
||||
package com.binarygolem.clotho.dev;
|
||||
|
||||
import org.jspecify.annotations.NullMarked;
|
||||
@@ -0,0 +1,14 @@
|
||||
spring.application.name=clotho-dev-app
|
||||
|
||||
# OrientDB Gremlin endpoint (no auth — Gremlin Server configured without authentication)
|
||||
clotho.gremlin.url=ws://localhost:8182/gremlin
|
||||
clotho.gremlin.username=
|
||||
clotho.gremlin.password=
|
||||
clotho.gremlin.traversal-source=g
|
||||
|
||||
# Clotho behaviour
|
||||
clotho.default-direction=OUT
|
||||
clotho.unknown-type-behavior=STRICT
|
||||
|
||||
# Packages to scan for @VertexType / @EdgeType / @ClothoRepository
|
||||
clotho.packages=com.binarygolem.clotho.dev
|
||||
@@ -0,0 +1,105 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project xmlns="http://maven.apache.org/POM/4.0.0"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
|
||||
http://maven.apache.org/xsd/maven-4.0.0.xsd">
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
||||
<parent>
|
||||
<groupId>com.binarygolem.clotho</groupId>
|
||||
<artifactId>clotho-parent</artifactId>
|
||||
<version>0.1.0-SNAPSHOT</version>
|
||||
</parent>
|
||||
|
||||
<artifactId>clotho-spring-boot-starter</artifactId>
|
||||
<name>Clotho Spring Boot Starter</name>
|
||||
<description>Spring Boot autoconfiguration and @Transactional bridge for Clotho</description>
|
||||
|
||||
<dependencies>
|
||||
|
||||
<!-- Clotho core -->
|
||||
<dependency>
|
||||
<groupId>com.binarygolem.clotho</groupId>
|
||||
<artifactId>clotho-core</artifactId>
|
||||
</dependency>
|
||||
|
||||
<!-- Spring Boot autoconfiguration infrastructure -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-autoconfigure</artifactId>
|
||||
</dependency>
|
||||
|
||||
<!-- Transaction management (arrives transitively but pinned to prevent version drift) -->
|
||||
<dependency>
|
||||
<groupId>org.springframework</groupId>
|
||||
<artifactId>spring-tx</artifactId>
|
||||
</dependency>
|
||||
|
||||
<!-- Generates META-INF/spring-configuration-metadata.json for IDE support -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-configuration-processor</artifactId>
|
||||
<optional>true</optional>
|
||||
</dependency>
|
||||
|
||||
<dependency>
|
||||
<groupId>org.projectlombok</groupId>
|
||||
<artifactId>lombok</artifactId>
|
||||
<scope>provided</scope>
|
||||
</dependency>
|
||||
|
||||
<dependency>
|
||||
<groupId>org.jspecify</groupId>
|
||||
<artifactId>jspecify</artifactId>
|
||||
</dependency>
|
||||
|
||||
<!-- Test -->
|
||||
<dependency>
|
||||
<groupId>org.junit.jupiter</groupId>
|
||||
<artifactId>junit-jupiter</artifactId>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-test</artifactId>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
|
||||
<dependency>
|
||||
<groupId>org.springframework</groupId>
|
||||
<artifactId>spring-test</artifactId>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
|
||||
<!-- Test: in-memory TinkerGraph — avoids needing a real ArcadeDB in tests -->
|
||||
<dependency>
|
||||
<groupId>org.apache.tinkerpop</groupId>
|
||||
<artifactId>tinkergraph-gremlin</artifactId>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
|
||||
<!-- Test: ApplicationContextRunner -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-test-autoconfigure</artifactId>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
|
||||
<!-- Test: AssertJ — required by ApplicationContextRunner -->
|
||||
<dependency>
|
||||
<groupId>org.assertj</groupId>
|
||||
<artifactId>assertj-core</artifactId>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
|
||||
<!-- Test: Mockito for ClothoTransactionManagerTest -->
|
||||
<dependency>
|
||||
<groupId>org.mockito</groupId>
|
||||
<artifactId>mockito-core</artifactId>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
|
||||
</dependencies>
|
||||
|
||||
</project>
|
||||
+105
@@ -0,0 +1,105 @@
|
||||
package com.binarygolem.clotho.spring.config;
|
||||
|
||||
import com.binarygolem.clotho.registry.TypeRegistry;
|
||||
import com.binarygolem.clotho.session.ClothoSessionFactory;
|
||||
import com.binarygolem.clotho.spring.repository.ClothoRepositoryRegistrar;
|
||||
import com.binarygolem.clotho.spring.tx.ClothoTransactionManager;
|
||||
import org.apache.tinkerpop.gremlin.driver.Cluster;
|
||||
import org.apache.tinkerpop.gremlin.driver.remote.DriverRemoteConnection;
|
||||
import org.apache.tinkerpop.gremlin.process.traversal.AnonymousTraversalSource;
|
||||
import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversalSource;
|
||||
import org.apache.tinkerpop.gremlin.util.ser.GraphSONMessageSerializerV3;
|
||||
import org.springframework.boot.autoconfigure.AutoConfiguration;
|
||||
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
|
||||
import org.springframework.boot.context.properties.EnableConfigurationProperties;
|
||||
import org.springframework.context.annotation.Bean;
|
||||
import org.springframework.context.annotation.Import;
|
||||
import org.springframework.transaction.PlatformTransactionManager;
|
||||
|
||||
import java.net.URI;
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* Autoconfigures the Clotho OGM layer for Spring Boot.
|
||||
*
|
||||
* <p>Creates a Gremlin {@link Cluster}, {@link DriverRemoteConnection},
|
||||
* {@link GraphTraversalSource}, {@link TypeRegistry}, and {@link ClothoSessionFactory}
|
||||
* from {@code clotho.*} properties. All beans are conditional on missing; override any
|
||||
* bean in your own {@code @Configuration} to customise.
|
||||
*
|
||||
* <p>Also imports {@link ClothoRepositoryRegistrar}, which scans {@code clotho.packages}
|
||||
* for {@code @ClothoRepository}-annotated {@link com.binarygolem.clotho.repository.ClothoRepository}
|
||||
* subclasses and registers them as Spring beans.
|
||||
*/
|
||||
@AutoConfiguration
|
||||
@EnableConfigurationProperties(ClothoProperties.class)
|
||||
@Import(ClothoRepositoryRegistrar.class)
|
||||
public class ClothoAutoConfiguration {
|
||||
|
||||
/**
|
||||
* Gremlin cluster connecting to the configured server.
|
||||
* Override this bean to use a custom cluster configuration.
|
||||
*/
|
||||
@Bean(destroyMethod = "close")
|
||||
@ConditionalOnMissingBean
|
||||
public Cluster clothoGremlinCluster(ClothoProperties props) {
|
||||
ClothoProperties.Gremlin gremlin = props.getGremlin();
|
||||
URI uri = URI.create(gremlin.getUrl());
|
||||
int port = uri.getPort() > 0 ? uri.getPort() : 8182;
|
||||
return Cluster.build()
|
||||
.addContactPoint(uri.getHost())
|
||||
.port(port)
|
||||
.credentials(gremlin.getUsername(), gremlin.getPassword())
|
||||
.serializer(new GraphSONMessageSerializerV3())
|
||||
.create();
|
||||
}
|
||||
|
||||
@Bean
|
||||
@ConditionalOnMissingBean
|
||||
public DriverRemoteConnection clothoRemoteConnection(Cluster cluster, ClothoProperties props) {
|
||||
return DriverRemoteConnection.using(cluster, props.getGremlin().getTraversalSource());
|
||||
}
|
||||
|
||||
/**
|
||||
* Live {@link GraphTraversalSource} backed by the remote Gremlin server.
|
||||
* Override with a TinkerGraph-backed source in tests.
|
||||
*/
|
||||
@Bean(destroyMethod = "close")
|
||||
@ConditionalOnMissingBean
|
||||
public GraphTraversalSource clothoTraversalSource(DriverRemoteConnection connection) {
|
||||
return AnonymousTraversalSource.traversal().withRemote(connection);
|
||||
}
|
||||
|
||||
/**
|
||||
* {@link TypeRegistry} populated by scanning {@code clotho.packages}.
|
||||
* Registers no types when no packages are configured.
|
||||
*/
|
||||
@Bean
|
||||
@ConditionalOnMissingBean
|
||||
public TypeRegistry clothoTypeRegistry(ClothoProperties props) {
|
||||
List<String> packages = props.getPackages();
|
||||
if (packages.isEmpty()) {
|
||||
return TypeRegistry.builder().build();
|
||||
}
|
||||
return TypeRegistry.scan(packages.toArray(String[]::new));
|
||||
}
|
||||
|
||||
@Bean
|
||||
@ConditionalOnMissingBean
|
||||
public ClothoSessionFactory clothoSessionFactory(GraphTraversalSource g,
|
||||
TypeRegistry registry,
|
||||
ClothoProperties props) {
|
||||
return ClothoSessionFactory.builder()
|
||||
.g(g)
|
||||
.registry(registry)
|
||||
.unknownTypeBehavior(props.getUnknownTypeBehavior())
|
||||
.defaultDirection(props.getDefaultDirection())
|
||||
.build();
|
||||
}
|
||||
|
||||
@Bean
|
||||
@ConditionalOnMissingBean(PlatformTransactionManager.class)
|
||||
public ClothoTransactionManager clothoTransactionManager(ClothoSessionFactory factory) {
|
||||
return new ClothoTransactionManager(factory);
|
||||
}
|
||||
}
|
||||
+45
@@ -0,0 +1,45 @@
|
||||
package com.binarygolem.clotho.spring.config;
|
||||
|
||||
import com.binarygolem.clotho.model.TraversalDirection;
|
||||
import com.binarygolem.clotho.model.UnknownTypeBehavior;
|
||||
import lombok.Data;
|
||||
import org.springframework.boot.context.properties.ConfigurationProperties;
|
||||
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* Binds {@code clotho.*} properties from {@code application.properties} or YAML.
|
||||
*
|
||||
* <pre>{@code
|
||||
* clotho.gremlin.url=ws://localhost:8182/gremlin
|
||||
* clotho.gremlin.username=root
|
||||
* clotho.gremlin.password=secret
|
||||
* clotho.gremlin.traversal-source=g
|
||||
* clotho.default-direction=OUT
|
||||
* clotho.unknown-type-behavior=STRICT
|
||||
* clotho.packages=com.example.domain,com.example.graph
|
||||
* }</pre>
|
||||
*/
|
||||
@ConfigurationProperties("clotho")
|
||||
@Data
|
||||
public class ClothoProperties {
|
||||
|
||||
private Gremlin gremlin = new Gremlin();
|
||||
private TraversalDirection defaultDirection = TraversalDirection.OUT;
|
||||
private UnknownTypeBehavior unknownTypeBehavior = UnknownTypeBehavior.STRICT;
|
||||
|
||||
/**
|
||||
* Base packages to scan for {@code @VertexType}, {@code @EdgeType}, and
|
||||
* {@code @ClothoRepository} classes.
|
||||
*/
|
||||
private List<String> packages = new ArrayList<>();
|
||||
|
||||
@Data
|
||||
public static class Gremlin {
|
||||
private String url = "ws://localhost:8182/gremlin";
|
||||
private String username = "";
|
||||
private String password = "";
|
||||
private String traversalSource = "g";
|
||||
}
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
@NullMarked
|
||||
package com.binarygolem.clotho.spring.config;
|
||||
|
||||
import org.jspecify.annotations.NullMarked;
|
||||
+91
@@ -0,0 +1,91 @@
|
||||
package com.binarygolem.clotho.spring.repository;
|
||||
|
||||
import com.binarygolem.clotho.repository.ClothoRepository;
|
||||
import org.springframework.beans.BeansException;
|
||||
import org.springframework.beans.factory.config.ConfigurableListableBeanFactory;
|
||||
import org.springframework.beans.factory.config.RuntimeBeanReference;
|
||||
import org.springframework.beans.factory.support.BeanDefinitionRegistry;
|
||||
import org.springframework.beans.factory.support.BeanDefinitionRegistryPostProcessor;
|
||||
import org.springframework.beans.factory.support.GenericBeanDefinition;
|
||||
import org.springframework.boot.context.properties.bind.Bindable;
|
||||
import org.springframework.boot.context.properties.bind.Binder;
|
||||
import org.springframework.context.EnvironmentAware;
|
||||
import org.springframework.context.annotation.ClassPathScanningCandidateComponentProvider;
|
||||
import org.springframework.core.annotation.AnnotationUtils;
|
||||
import org.springframework.core.env.Environment;
|
||||
import org.springframework.core.type.filter.AnnotationTypeFilter;
|
||||
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* Scans {@code clotho.packages} for classes annotated with
|
||||
* {@link com.binarygolem.clotho.annotation.ClothoRepository @ClothoRepository}
|
||||
* that extend {@link ClothoRepository}, and registers each as a singleton Spring bean.
|
||||
*
|
||||
* <p>Each registered bean receives the shared {@code clothoSessionFactory} bean
|
||||
* as its constructor argument; Spring resolves the dependency at context refresh time.
|
||||
*/
|
||||
public class ClothoRepositoryRegistrar
|
||||
implements BeanDefinitionRegistryPostProcessor, EnvironmentAware {
|
||||
|
||||
private Environment environment;
|
||||
|
||||
@Override
|
||||
public void setEnvironment(Environment environment) {
|
||||
this.environment = environment;
|
||||
}
|
||||
|
||||
@Override
|
||||
public void postProcessBeanDefinitionRegistry(BeanDefinitionRegistry registry) throws BeansException {
|
||||
List<String> packages = Binder.get(environment)
|
||||
.bind("clotho.packages", Bindable.listOf(String.class))
|
||||
.orElse(List.of());
|
||||
|
||||
if (packages.isEmpty()) {
|
||||
return;
|
||||
}
|
||||
|
||||
ClassPathScanningCandidateComponentProvider scanner = buildScanner();
|
||||
|
||||
for (String pkg : packages) {
|
||||
for (var candidate : scanner.findCandidateComponents(pkg)) {
|
||||
String className = candidate.getBeanClassName();
|
||||
if (className == null) continue;
|
||||
|
||||
Class<?> cls;
|
||||
try {
|
||||
cls = Class.forName(className);
|
||||
} catch (ClassNotFoundException e) {
|
||||
continue;
|
||||
}
|
||||
|
||||
if (!ClothoRepository.class.isAssignableFrom(cls)) continue;
|
||||
|
||||
GenericBeanDefinition bd = new GenericBeanDefinition();
|
||||
bd.setBeanClass(cls);
|
||||
bd.getConstructorArgumentValues()
|
||||
.addGenericArgumentValue(new RuntimeBeanReference("clothoSessionFactory"));
|
||||
bd.setLazyInit(false);
|
||||
|
||||
registry.registerBeanDefinition(beanName(cls), bd);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@Override
|
||||
public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) throws BeansException {
|
||||
// no-op
|
||||
}
|
||||
|
||||
private ClassPathScanningCandidateComponentProvider buildScanner() {
|
||||
var scanner = new ClassPathScanningCandidateComponentProvider(false);
|
||||
scanner.addIncludeFilter(new AnnotationTypeFilter(
|
||||
com.binarygolem.clotho.annotation.ClothoRepository.class));
|
||||
return scanner;
|
||||
}
|
||||
|
||||
private static String beanName(Class<?> cls) {
|
||||
String name = cls.getSimpleName();
|
||||
return Character.toLowerCase(name.charAt(0)) + name.substring(1);
|
||||
}
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
@NullMarked
|
||||
package com.binarygolem.clotho.spring.repository;
|
||||
|
||||
import org.jspecify.annotations.NullMarked;
|
||||
+54
@@ -0,0 +1,54 @@
|
||||
package com.binarygolem.clotho.spring.tx;
|
||||
|
||||
import com.binarygolem.clotho.session.ClothoSession;
|
||||
import com.binarygolem.clotho.session.ClothoSessionFactory;
|
||||
import com.binarygolem.clotho.session.SessionContext;
|
||||
import org.jspecify.annotations.Nullable;
|
||||
import org.springframework.transaction.PlatformTransactionManager;
|
||||
import org.springframework.transaction.TransactionDefinition;
|
||||
import org.springframework.transaction.TransactionStatus;
|
||||
import org.springframework.transaction.support.DefaultTransactionStatus;
|
||||
|
||||
/**
|
||||
* Integrates Clotho transactional sessions with Spring's {@code @Transactional} mechanism.
|
||||
*
|
||||
* <p>Register as a bean (done automatically by {@code ClothoAutoConfiguration}) and annotate
|
||||
* service methods with {@code @Transactional}. Spring calls {@link #getTransaction},
|
||||
* {@link #commit}, and {@link #rollback}; application code calls
|
||||
* {@link ClothoSessionFactory#openSession()} or {@link ClothoSessionFactory#getCurrentSession()}
|
||||
* to obtain the session bound to the transaction.
|
||||
*
|
||||
* <p>Nested {@code @Transactional} methods join the outer transaction — no new session or
|
||||
* commit is created for the inner method.
|
||||
*/
|
||||
public class ClothoTransactionManager implements PlatformTransactionManager {
|
||||
|
||||
private final ClothoSessionFactory sessionFactory;
|
||||
|
||||
public ClothoTransactionManager(ClothoSessionFactory sessionFactory) {
|
||||
this.sessionFactory = sessionFactory;
|
||||
}
|
||||
|
||||
@Override
|
||||
public TransactionStatus getTransaction(@Nullable TransactionDefinition definition) {
|
||||
ClothoSession existing = SessionContext.get();
|
||||
if (existing != null) {
|
||||
return new DefaultTransactionStatus(existing, false, false, false, false, null);
|
||||
}
|
||||
ClothoSession session = sessionFactory.openTransactionalSession();
|
||||
return new DefaultTransactionStatus(session, true, true, false, false, null);
|
||||
}
|
||||
|
||||
@Override
|
||||
public void commit(TransactionStatus status) {
|
||||
if (!status.isNewTransaction()) return;
|
||||
ClothoSession session = (ClothoSession) ((DefaultTransactionStatus) status).getTransaction();
|
||||
session.close();
|
||||
}
|
||||
|
||||
@Override
|
||||
public void rollback(TransactionStatus status) {
|
||||
ClothoSession session = (ClothoSession) ((DefaultTransactionStatus) status).getTransaction();
|
||||
session.rollback();
|
||||
}
|
||||
}
|
||||
+2
@@ -0,0 +1,2 @@
|
||||
/** Spring transaction management bridge for Clotho. */
|
||||
package com.binarygolem.clotho.spring.tx;
|
||||
+1
@@ -0,0 +1 @@
|
||||
com.binarygolem.clotho.spring.config.ClothoAutoConfiguration
|
||||
+118
@@ -0,0 +1,118 @@
|
||||
package com.binarygolem.clotho.spring.config;
|
||||
|
||||
import com.binarygolem.clotho.annotation.VertexType;
|
||||
import com.binarygolem.clotho.model.ClothoVertex;
|
||||
import com.binarygolem.clotho.model.TraversalDirection;
|
||||
import com.binarygolem.clotho.model.UnknownTypeBehavior;
|
||||
import com.binarygolem.clotho.registry.TypeRegistry;
|
||||
import com.binarygolem.clotho.session.ClothoSessionFactory;
|
||||
import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversalSource;
|
||||
import org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerGraph;
|
||||
import org.junit.jupiter.api.Test;
|
||||
import org.springframework.boot.autoconfigure.AutoConfigurations;
|
||||
import org.springframework.boot.test.context.runner.ApplicationContextRunner;
|
||||
|
||||
import static org.junit.jupiter.api.Assertions.*;
|
||||
|
||||
class ClothoAutoConfigurationTest {
|
||||
|
||||
// --- Fixtures ---
|
||||
|
||||
@VertexType("Widget")
|
||||
static class Widget extends ClothoVertex {}
|
||||
|
||||
@com.binarygolem.clotho.annotation.ClothoRepository
|
||||
static class WidgetRepo extends com.binarygolem.clotho.repository.ClothoRepository<Widget> {
|
||||
WidgetRepo(ClothoSessionFactory factory) { super(factory); }
|
||||
}
|
||||
|
||||
// --- Context runner ---
|
||||
|
||||
private final ApplicationContextRunner contextRunner = new ApplicationContextRunner()
|
||||
.withConfiguration(AutoConfigurations.of(ClothoAutoConfiguration.class));
|
||||
|
||||
/** Provides a TinkerGraph traversal source so no real ArcadeDB is needed. */
|
||||
private ApplicationContextRunner withTinkerGraph(ApplicationContextRunner runner) {
|
||||
return runner
|
||||
.withBean("clothoTraversalSource", GraphTraversalSource.class,
|
||||
() -> TinkerGraph.open().traversal())
|
||||
.withBean("clothoTypeRegistry", TypeRegistry.class,
|
||||
() -> TypeRegistry.builder().build());
|
||||
}
|
||||
|
||||
// --- Tests ---
|
||||
|
||||
@Test
|
||||
void sessionFactoryBeanIsCreated() {
|
||||
withTinkerGraph(contextRunner).run(ctx -> {
|
||||
assertNull(ctx.getStartupFailure(),
|
||||
() -> ctx.getStartupFailure().getMessage());
|
||||
assertNotNull(ctx.getBean(ClothoSessionFactory.class));
|
||||
});
|
||||
}
|
||||
|
||||
@Test
|
||||
void sessionFactoryBacksOffWhenUserProvides() {
|
||||
ClothoSessionFactory existing = ClothoSessionFactory.builder()
|
||||
.g(TinkerGraph.open().traversal())
|
||||
.registry(TypeRegistry.builder().build())
|
||||
.build();
|
||||
withTinkerGraph(contextRunner)
|
||||
.withBean(ClothoSessionFactory.class, () -> existing)
|
||||
.run(ctx -> {
|
||||
assertNull(ctx.getStartupFailure());
|
||||
assertSame(existing, ctx.getBean(ClothoSessionFactory.class));
|
||||
});
|
||||
}
|
||||
|
||||
@Test
|
||||
void propertiesDefaultsApply() {
|
||||
withTinkerGraph(contextRunner).run(ctx -> {
|
||||
assertNull(ctx.getStartupFailure());
|
||||
ClothoProperties props = ctx.getBean(ClothoProperties.class);
|
||||
assertEquals(TraversalDirection.OUT, props.getDefaultDirection());
|
||||
assertEquals(UnknownTypeBehavior.STRICT, props.getUnknownTypeBehavior());
|
||||
assertTrue(props.getPackages().isEmpty());
|
||||
});
|
||||
}
|
||||
|
||||
@Test
|
||||
void propertiesOverridesApply() {
|
||||
withTinkerGraph(contextRunner)
|
||||
.withPropertyValues(
|
||||
"clotho.default-direction=IN",
|
||||
"clotho.unknown-type-behavior=GENERIC"
|
||||
)
|
||||
.run(ctx -> {
|
||||
assertNull(ctx.getStartupFailure());
|
||||
ClothoProperties props = ctx.getBean(ClothoProperties.class);
|
||||
assertEquals(TraversalDirection.IN, props.getDefaultDirection());
|
||||
assertEquals(UnknownTypeBehavior.GENERIC, props.getUnknownTypeBehavior());
|
||||
});
|
||||
}
|
||||
|
||||
@Test
|
||||
void repositoryIsRegisteredWhenPackageConfigured() {
|
||||
withTinkerGraph(contextRunner)
|
||||
.withPropertyValues(
|
||||
"clotho.packages=com.binarygolem.clotho.spring.config"
|
||||
)
|
||||
.run(ctx -> {
|
||||
assertNull(ctx.getStartupFailure(),
|
||||
() -> ctx.getStartupFailure() != null
|
||||
? ctx.getStartupFailure().getMessage() : "");
|
||||
assertTrue(ctx.containsBean("widgetRepo"),
|
||||
"WidgetRepo should be registered as 'widgetRepo'");
|
||||
assertNotNull(ctx.getBean(WidgetRepo.class));
|
||||
});
|
||||
}
|
||||
|
||||
@Test
|
||||
void noRepositoriesRegisteredWhenNoPackagesConfigured() {
|
||||
withTinkerGraph(contextRunner).run(ctx -> {
|
||||
assertNull(ctx.getStartupFailure());
|
||||
assertTrue(ctx.getBeansOfType(
|
||||
com.binarygolem.clotho.repository.ClothoRepository.class).isEmpty());
|
||||
});
|
||||
}
|
||||
}
|
||||
+119
@@ -0,0 +1,119 @@
|
||||
package com.binarygolem.clotho.spring.tx;
|
||||
|
||||
import com.binarygolem.clotho.session.ClothoSession;
|
||||
import com.binarygolem.clotho.session.ClothoSessionFactory;
|
||||
import com.binarygolem.clotho.session.SessionContext;
|
||||
import org.junit.jupiter.api.AfterEach;
|
||||
import org.junit.jupiter.api.Test;
|
||||
import org.springframework.transaction.TransactionStatus;
|
||||
import org.springframework.transaction.support.DefaultTransactionDefinition;
|
||||
|
||||
import static org.junit.jupiter.api.Assertions.*;
|
||||
import static org.mockito.Mockito.*;
|
||||
|
||||
class ClothoTransactionManagerTest {
|
||||
|
||||
private final ClothoSessionFactory factory = mock(ClothoSessionFactory.class);
|
||||
private final ClothoTransactionManager manager = new ClothoTransactionManager(factory);
|
||||
|
||||
@AfterEach
|
||||
void clearThreadLocal() {
|
||||
// Ensure no session bleeds between tests
|
||||
ClothoSession bound = SessionContext.get();
|
||||
if (bound != null) bound.rollback();
|
||||
}
|
||||
|
||||
// --- getTransaction ---
|
||||
|
||||
@Test
|
||||
void getTransaction_opensNewTransactionalSession_whenNoBoundSession() {
|
||||
ClothoSession session = mock(ClothoSession.class);
|
||||
when(factory.openTransactionalSession()).thenReturn(session);
|
||||
// SessionContext has no bound session — simulate by not calling any bind
|
||||
|
||||
TransactionStatus status = manager.getTransaction(new DefaultTransactionDefinition());
|
||||
|
||||
assertTrue(status.isNewTransaction());
|
||||
verify(factory).openTransactionalSession();
|
||||
}
|
||||
|
||||
@Test
|
||||
void getTransaction_joinsExistingSession_whenSessionAlreadyBound() {
|
||||
// We need an actual session bound to the thread; use a spy-friendly stub
|
||||
ClothoSession existing = mock(ClothoSession.class);
|
||||
// Bind it manually via reflection helper (package-private) isn't available;
|
||||
// instead, call openTransactionalSession mock, get a status, then check a second call
|
||||
when(factory.openTransactionalSession()).thenReturn(existing);
|
||||
|
||||
// First transaction binds the session (simulate by capturing what the manager does)
|
||||
// We can't bind via SessionContext directly (package-private), so we test the
|
||||
// second getTransaction() call by verifying isNewTransaction is false when
|
||||
// openTransactionalSession() has been called and SessionContext already has a value.
|
||||
// The real behaviour is tested end-to-end in ClothoSessionTransactionTest.
|
||||
// Here we verify: when SessionContext.get() returns non-null, isNewTransaction is false.
|
||||
// We cannot inject into SessionContext from outside the package — so we test the
|
||||
// manager with a real session bound:
|
||||
when(factory.openTransactionalSession()).thenReturn(mock(ClothoSession.class));
|
||||
|
||||
// Outer: binds a session
|
||||
TransactionStatus outer = manager.getTransaction(new DefaultTransactionDefinition());
|
||||
assertTrue(outer.isNewTransaction());
|
||||
// manager.commit() to clean up at end of test — but SessionContext needs to be
|
||||
// populated by a real ClothoSession. Since the mock doesn't call bind, we can't
|
||||
// test the join path purely with mocks. So we verify by calling commit() / rollback()
|
||||
// correctly; the join test is covered in the integration-style session test.
|
||||
manager.rollback(outer);
|
||||
}
|
||||
|
||||
// --- commit ---
|
||||
|
||||
@Test
|
||||
void commit_closesSessionOnNewTransaction() {
|
||||
ClothoSession session = mock(ClothoSession.class);
|
||||
when(factory.openTransactionalSession()).thenReturn(session);
|
||||
|
||||
TransactionStatus status = manager.getTransaction(new DefaultTransactionDefinition());
|
||||
// isNewTransaction == true (no prior bound session since mock doesn't call bind)
|
||||
manager.commit(status);
|
||||
|
||||
verify(session).close();
|
||||
}
|
||||
|
||||
@Test
|
||||
void commit_doesNotCloseSessionOnNestedTransaction() {
|
||||
// Build a status where isNewTransaction == false
|
||||
ClothoSession session = mock(ClothoSession.class);
|
||||
org.springframework.transaction.support.DefaultTransactionStatus nestedStatus =
|
||||
new org.springframework.transaction.support.DefaultTransactionStatus(
|
||||
session, false, false, false, false, null);
|
||||
|
||||
manager.commit(nestedStatus);
|
||||
|
||||
verify(session, never()).close();
|
||||
}
|
||||
|
||||
// --- rollback ---
|
||||
|
||||
@Test
|
||||
void rollback_callsSessionRollback() {
|
||||
ClothoSession session = mock(ClothoSession.class);
|
||||
when(factory.openTransactionalSession()).thenReturn(session);
|
||||
|
||||
TransactionStatus status = manager.getTransaction(new DefaultTransactionDefinition());
|
||||
manager.rollback(status);
|
||||
|
||||
verify(session).rollback();
|
||||
}
|
||||
|
||||
@Test
|
||||
void rollback_callsSessionRollback_onNestedTransaction() {
|
||||
ClothoSession session = mock(ClothoSession.class);
|
||||
org.springframework.transaction.support.DefaultTransactionStatus nestedStatus =
|
||||
new org.springframework.transaction.support.DefaultTransactionStatus(
|
||||
session, false, false, false, false, null);
|
||||
|
||||
manager.rollback(nestedStatus);
|
||||
|
||||
verify(session).rollback();
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,341 @@
|
||||
# Annotation Reference
|
||||
|
||||
## Class-Level Annotations
|
||||
|
||||
---
|
||||
|
||||
### `@VertexType`
|
||||
|
||||
Declares a class as a Clotho-managed vertex type. The class must extend `ClothoVertex`.
|
||||
|
||||
```java
|
||||
@Target(ElementType.TYPE)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface VertexType {
|
||||
String value(); // ArcadeDB vertex type name (required)
|
||||
String[] additionalParents() // ArcadeDB parent type names beyond Java hierarchy
|
||||
default {}; // Use for diamond inheritance
|
||||
String parentLabel() // Explicit ArcadeDB parent when Java hierarchy diverges
|
||||
default "";
|
||||
}
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
```java
|
||||
// Simple
|
||||
@VertexType("Employee")
|
||||
public class Employee extends ClothoVertex { }
|
||||
|
||||
// Abstract type
|
||||
@VertexType("Person")
|
||||
public abstract class Person extends ClothoVertex { }
|
||||
|
||||
// Diamond inheritance
|
||||
@VertexType(value = "ContractEmployee", additionalParents = {"Contractor"})
|
||||
public class ContractEmployee extends Employee { }
|
||||
|
||||
// Divergent Java/ArcadeDB hierarchy
|
||||
@VertexType(value = "ExternalWorker", parentLabel = "Employee")
|
||||
public class ExternalWorker extends ClothoVertex { }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `@EdgeType`
|
||||
|
||||
Declares a class as a Clotho-managed edge type. The class must extend `ClothoEdge`.
|
||||
|
||||
```java
|
||||
@Target(ElementType.TYPE)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface EdgeType {
|
||||
String value(); // ArcadeDB edge type name (required)
|
||||
}
|
||||
```
|
||||
|
||||
**Example:**
|
||||
|
||||
```java
|
||||
@EdgeType("WORKS_AT")
|
||||
public class WorksAt extends ClothoEdge {
|
||||
public static final String LABEL = "WORKS_AT";
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
Convention: define `LABEL` as a constant on the edge class to avoid magic strings at call
|
||||
sites when referencing the label in `@Via`.
|
||||
|
||||
---
|
||||
|
||||
### `@SubgraphType`
|
||||
|
||||
Declares a composite type assembled from a Gremlin `select()` traversal. Must NOT extend
|
||||
`ClothoVertex` or `ClothoEdge`. Has no ARID.
|
||||
|
||||
```java
|
||||
@Target(ElementType.TYPE)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface SubgraphType {
|
||||
}
|
||||
```
|
||||
|
||||
**Example:**
|
||||
|
||||
```java
|
||||
@SubgraphType
|
||||
public class EmployeeProfile {
|
||||
Employee employee;
|
||||
Manager manager;
|
||||
@Alias("dept") Department department;
|
||||
List<WorksAt> workHistory;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Field-Level Annotations
|
||||
|
||||
---
|
||||
|
||||
### `@RID`
|
||||
|
||||
Marks the field that holds the element's `ARID`. Inherited from `ClothoEntity`; generally
|
||||
not needed unless overriding the base class field.
|
||||
|
||||
```java
|
||||
@Target(ElementType.FIELD)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface RID {
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `@Property`
|
||||
|
||||
Maps a field to an ArcadeDB vertex or edge property. Optional when the field name exactly
|
||||
matches the property name.
|
||||
|
||||
```java
|
||||
@Target(ElementType.FIELD)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface Property {
|
||||
String value(); // ArcadeDB property name
|
||||
}
|
||||
```
|
||||
|
||||
**Example:**
|
||||
|
||||
```java
|
||||
@Property("startDate") LocalDate start; // field name differs from property name
|
||||
LocalDate endDate; // no annotation needed; names match
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `@Include`
|
||||
|
||||
Marks a field as part of this object's eager-load boundary. Always paired with `@Via`.
|
||||
The field type must be a `@VertexType` class, an `@EdgeType` class, or a `List<>` of either.
|
||||
|
||||
```java
|
||||
@Target(ElementType.FIELD)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface Include {
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `@Via`
|
||||
|
||||
Specifies the ArcadeDB edge label to traverse for an `@Include` field.
|
||||
|
||||
```java
|
||||
@Target(ElementType.FIELD)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface Via {
|
||||
String value(); // Edge label (required)
|
||||
}
|
||||
```
|
||||
|
||||
**Strongly preferred pattern** — use the edge class's `LABEL` constant:
|
||||
|
||||
```java
|
||||
@Include @Via(WorksAt.LABEL)
|
||||
List<WorksAt> workHistory;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `@Direction`
|
||||
|
||||
Specifies which edge direction to follow for an `@Include` + `@Via` traversal.
|
||||
Defaults to `OUT` (or the global configured default).
|
||||
|
||||
```java
|
||||
@Target(ElementType.FIELD)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface Direction {
|
||||
Direction value() default Direction.OUT;
|
||||
}
|
||||
|
||||
public enum Direction { OUT, IN, BOTH }
|
||||
```
|
||||
|
||||
**Example:**
|
||||
|
||||
```java
|
||||
@Include @Via("ASSIGNED_TO") @Direction(Direction.IN)
|
||||
List<Task> assignedTasks;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `@OutVertex`
|
||||
|
||||
On an `@EdgeType` class: marks the field holding the out-vertex (source) of the edge.
|
||||
The field type must be a `@VertexType` class.
|
||||
|
||||
```java
|
||||
@Target(ElementType.FIELD)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface OutVertex {
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `@InVertex`
|
||||
|
||||
On an `@EdgeType` class: marks the field holding the in-vertex (target) of the edge.
|
||||
The field type must be a `@VertexType` class.
|
||||
Omitting `@InVertex` entirely = edge-only inclusion; the target vertex is not loaded.
|
||||
|
||||
```java
|
||||
@Target(ElementType.FIELD)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface InVertex {
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `@Alias`
|
||||
|
||||
On a `@SubgraphType` field: specifies the Gremlin `as()` alias that this field is bound
|
||||
to. Defaults to the field name when omitted.
|
||||
|
||||
```java
|
||||
@Target(ElementType.FIELD)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface Alias {
|
||||
String value();
|
||||
}
|
||||
```
|
||||
|
||||
**Example:**
|
||||
|
||||
```java
|
||||
@Alias("dept")
|
||||
Department department; // binds to .as("dept") in the Gremlin query
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Query Annotations
|
||||
|
||||
---
|
||||
|
||||
### `@Query`
|
||||
|
||||
Declares a Gremlin traversal. Used on `@ClothoRepository` interface methods (primary use)
|
||||
or on `@VertexType` classes as named queries (secondary use).
|
||||
|
||||
```java
|
||||
@Target({ElementType.METHOD, ElementType.TYPE})
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
@Repeatable(Queries.class) // allows multiple @Query on a class (different names)
|
||||
public @interface Query {
|
||||
String value() default ""; // Gremlin string (for method use)
|
||||
String name() default ""; // Named query identifier (for class-level use)
|
||||
String gremlin() default ""; // Gremlin string (for class-level use; alias for clarity)
|
||||
boolean mapResult() default true; // false = return raw Gremlin result
|
||||
}
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
```java
|
||||
// On a repository method
|
||||
@Query("g.V().hasLabel('Employee').has('dept',:dept)")
|
||||
List<Employee> findByDepartment(@Param("dept") String dept);
|
||||
|
||||
// Raw result — no Clotho mapping
|
||||
@Query(value = "g.V().hasLabel('Employee').count()", mapResult = false)
|
||||
long countAll();
|
||||
|
||||
// Named query on a class
|
||||
@VertexType("Order")
|
||||
@Query(name = "openForCustomer",
|
||||
gremlin = "g.V().has('Customer','id',:custId).out('PLACED').has('status','OPEN')")
|
||||
public class Order extends ClothoVertex { ... }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `@Param`
|
||||
|
||||
Binds a method parameter to a named placeholder in a `@Query` Gremlin string.
|
||||
|
||||
```java
|
||||
@Target(ElementType.PARAMETER)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface Param {
|
||||
String value(); // placeholder name (without the colon)
|
||||
}
|
||||
```
|
||||
|
||||
**Example:**
|
||||
|
||||
```java
|
||||
@Query("g.V().has('Employee','dept',:dept).has('level',:level)")
|
||||
List<Employee> findByDeptAndLevel(
|
||||
@Param("dept") String department,
|
||||
@Param("level") int level);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Spring Annotation
|
||||
|
||||
---
|
||||
|
||||
### `@ClothoRepository`
|
||||
|
||||
Marks an interface as a Clotho query interface. The `clotho-spring-boot-starter` scans for
|
||||
these interfaces and registers a dynamic proxy as a Spring bean.
|
||||
|
||||
```java
|
||||
@Target(ElementType.TYPE)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface ClothoRepository {
|
||||
}
|
||||
```
|
||||
|
||||
**Example:**
|
||||
|
||||
```java
|
||||
@ClothoRepository
|
||||
public interface OrderQueries {
|
||||
@Query("g.V().has('Order','status','OPEN')")
|
||||
List<Order> findOpenOrders();
|
||||
}
|
||||
```
|
||||
|
||||
Inject via Spring as you would any repository:
|
||||
```java
|
||||
@Autowired OrderQueries orderQueries;
|
||||
```
|
||||
@@ -0,0 +1,248 @@
|
||||
# Architecture
|
||||
|
||||
## Module Overview
|
||||
|
||||
```
|
||||
clotho-core
|
||||
Zero Spring dependency.
|
||||
All mapping, session, registry, and query logic.
|
||||
|
||||
clotho-spring-boot-starter
|
||||
Spring Boot 3.x autoconfiguration.
|
||||
Thin layer: creates beans, bridges @Transactional, scans @ClothoRepository.
|
||||
Depends on clotho-core.
|
||||
|
||||
clotho-dev-app
|
||||
Minimal Spring Boot application.
|
||||
Connected to a live ArcadeDB instance.
|
||||
Used throughout development for real-DB testing.
|
||||
Not a production artifact; not published.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## clotho-core Component Map
|
||||
|
||||
```
|
||||
ClothoSessionFactory (entry point)
|
||||
│ Holds: DriverRemoteConnection, TypeRegistry, global config
|
||||
│
|
||||
├── TypeRegistry
|
||||
│ Built once at startup from classpath scan.
|
||||
│ Maps: ArcadeDB label → Class<? extends ClothoEntity>
|
||||
│ Knows: Java + ArcadeDB inheritance hierarchy, additionalParents
|
||||
│
|
||||
└── ClothoSession (unit of work, one per transaction/request)
|
||||
│ Holds: identity map (ARID → ClothoEntity instance)
|
||||
│
|
||||
├── load(Class<T>, ARID) → T
|
||||
│ └── SubgraphLoader
|
||||
│ Uses: TypeRegistry, ObjectMapper
|
||||
│ Executes Gremlin traversal for root vertex + @Include boundary
|
||||
│ Cycle detection via visited-ARID set
|
||||
│
|
||||
├── save(entity)
|
||||
│ └── SubgraphPersistor
|
||||
│ Upserts root vertex/edge + all @Include elements recursively
|
||||
│ Uses ArcadeDB @version for optimistic locking
|
||||
│ @SubgraphType: iterates all ClothoEntity fields, saves each
|
||||
│
|
||||
├── delete(entity)
|
||||
│ Removes root vertex/edge from graph
|
||||
│ Does NOT cascade deletion to @Include elements
|
||||
│
|
||||
└── query(Class<T>, queryName, params) → List<T>
|
||||
└── QueryExecutor
|
||||
Resolves named @Query, binds params, executes, maps results
|
||||
Also drives @ClothoRepository proxy methods
|
||||
|
||||
ObjectMapper (used by SubgraphLoader and QueryExecutor)
|
||||
Gremlin Vertex/Edge → ClothoEntity subclass
|
||||
Always uses most-specific registered class (TypeRegistry lookup by label)
|
||||
Sets @Property fields, @OutVertex/@InVertex fields on edges
|
||||
|
||||
SubgraphTypeAssembler (used by QueryExecutor for @SubgraphType returns)
|
||||
Maps Gremlin select() result map → @SubgraphType fields
|
||||
Binding: field name or @Alias → select key
|
||||
Each bound value is mapped via ObjectMapper
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Flow: Loading a Composite Object
|
||||
|
||||
```
|
||||
Developer: session.load(Order.class, arid)
|
||||
│
|
||||
▼
|
||||
SubgraphLoader
|
||||
1. g.V(arid.asString()) → TinkerPop Vertex (Order)
|
||||
2. ObjectMapper.map(vertex) → Order instance (most-specific class)
|
||||
3. Register in identity map
|
||||
4. For each @Include field on Order:
|
||||
@Include @Via("HAS_LINE") List<OrderLine> lines
|
||||
┌──────────────────────────────────────────┐
|
||||
│ g.V(arid).out("HAS_LINE") │
|
||||
│ → [TinkerPop Vertex, Vertex, ...] │
|
||||
│ for each: ObjectMapper.map(v) │
|
||||
│ → OrderLine (or subtype by label) │
|
||||
│ recurse: load OrderLine @Include fields│
|
||||
└──────────────────────────────────────────┘
|
||||
5. Assemble Order.lines = [OrderLine, ...]
|
||||
6. Return fully assembled Order
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Flow: Saving a Composite Object
|
||||
|
||||
```
|
||||
Developer: session.save(order)
|
||||
│
|
||||
▼
|
||||
SubgraphPersistor
|
||||
1. Upsert root Order vertex
|
||||
if order.getId() == null → create vertex with label "Order"
|
||||
else → update vertex, check @version (optimistic lock)
|
||||
2. For each @Include field on Order:
|
||||
Field type is @VertexType (e.g., List<OrderLine>):
|
||||
for each element → recursively save (SubgraphPersistor.save(orderLine))
|
||||
ensure edge "HAS_LINE" exists from Order to OrderLine
|
||||
Field type is @EdgeType (e.g., List<WorksAt>):
|
||||
save edge properties; ensure @OutVertex and @InVertex are already persisted
|
||||
3. Identity map deduplication: elements already saved in this call are skipped
|
||||
4. Removed elements: NOT deleted automatically
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Flow: `@Query` on a `@ClothoRepository`
|
||||
|
||||
```
|
||||
Developer: employeeQueries.findByDepartment("Engineering")
|
||||
│
|
||||
▼
|
||||
ClothoRepository proxy (generated by QueryExecutor at startup)
|
||||
1. Read @Query gremlin string from method annotation
|
||||
2. Bind @Param values: replace :dept with "Engineering"
|
||||
3. Execute: g.V().hasLabel('Employee').has('dept','Engineering')
|
||||
4. For each result vertex:
|
||||
ObjectMapper.map(vertex) → most-specific Employee subclass
|
||||
5. Return List<Employee>
|
||||
```
|
||||
|
||||
For `@SubgraphType` return:
|
||||
```
|
||||
3. Execute query with select() → List of Maps
|
||||
4. For each Map:
|
||||
SubgraphTypeAssembler.assemble(EmployeeProfile.class, map)
|
||||
→ bind map keys to fields by name / @Alias
|
||||
→ ObjectMapper.map() each value
|
||||
5. Return List<EmployeeProfile>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Session Identity Map
|
||||
|
||||
The identity map is the session's in-memory cache of loaded vertices and edges.
|
||||
|
||||
- Key: `ARID`
|
||||
- Value: `ClothoEntity` instance
|
||||
|
||||
Rules:
|
||||
- First load of an ARID → fetch from DB, map to Java, store in map, return
|
||||
- Subsequent load of same ARID → return existing instance (no DB call)
|
||||
- `save()` does NOT clear the identity map; the instance is mutated in place
|
||||
- `close()` clears the map and releases the Gremlin connection
|
||||
|
||||
The map operates at the individual vertex/edge level. Multiple composite objects (e.g., an
|
||||
`Order` and an `EmployeeProfile`) may both hold references to the same `Address` instance
|
||||
if their traversals reached the same ARID.
|
||||
|
||||
---
|
||||
|
||||
## TypeRegistry Startup Validation
|
||||
|
||||
At `ClothoSessionFactory.build()` time, the TypeRegistry validates:
|
||||
|
||||
- Every `@VertexType` class extends `ClothoVertex`
|
||||
- Every `@EdgeType` class extends `ClothoEdge`
|
||||
- No two classes claim the same label
|
||||
- `additionalParents` labels are resolvable to registered classes
|
||||
- `parentLabel` values are resolvable to registered classes
|
||||
- Every `@Include` field is paired with `@Via`
|
||||
- `@OutVertex` / `@InVertex` field types are `@VertexType` classes
|
||||
|
||||
Startup failure with a descriptive message is strongly preferred over silent misconfiguration
|
||||
that produces confusing runtime errors.
|
||||
|
||||
---
|
||||
|
||||
## Package Structure
|
||||
|
||||
```
|
||||
com.binarygolem.clotho
|
||||
.model
|
||||
ClothoEntity
|
||||
ClothoVertex
|
||||
ClothoEdge
|
||||
ARID
|
||||
UnknownTypeBehavior
|
||||
|
||||
.annotation
|
||||
VertexType
|
||||
EdgeType
|
||||
SubgraphType
|
||||
RID
|
||||
Property
|
||||
Include
|
||||
Via
|
||||
Direction
|
||||
OutVertex
|
||||
InVertex
|
||||
Alias
|
||||
Query
|
||||
Queries (container for @Repeatable @Query)
|
||||
Param
|
||||
ClothoRepository
|
||||
|
||||
.session
|
||||
ClothoSession
|
||||
ClothoSessionFactory
|
||||
ClothoSessionFactoryBuilder
|
||||
|
||||
.registry
|
||||
TypeRegistry
|
||||
TypeRegistryBuilder
|
||||
TypeDescriptor (holds metadata for one registered type)
|
||||
|
||||
.mapping
|
||||
ObjectMapper
|
||||
SubgraphLoader
|
||||
SubgraphPersistor
|
||||
SubgraphTypeAssembler
|
||||
|
||||
.query
|
||||
QueryExecutor
|
||||
QueryDescriptor (holds parsed @Query metadata for one method)
|
||||
ParameterBinder
|
||||
|
||||
.exception
|
||||
ClothoException
|
||||
UnknownTypeException
|
||||
OptimisticLockException
|
||||
ClothoConfigurationException
|
||||
|
||||
// clotho-spring-boot-starter
|
||||
com.binarygolem.clotho.spring
|
||||
.config
|
||||
ClothoAutoConfiguration
|
||||
ClothoProperties
|
||||
.tx
|
||||
ClothoTransactionManager
|
||||
ClothoTransactionObject
|
||||
.repository
|
||||
ClothoRepositoryScanner
|
||||
ClothoRepositoryProxyFactory
|
||||
```
|
||||
@@ -0,0 +1,686 @@
|
||||
# Getting Started with Clotho
|
||||
|
||||
Clotho is a Java OGM (Object-Graph Mapper) for ArcadeDB built on Apache TinkerPop/Gremlin.
|
||||
A "Clotho object" is not a single vertex — it is a **subgraph**: a root vertex plus a declared
|
||||
set of edges and adjacent vertices that are loaded atomically in a single Gremlin traversal.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Requirement | Version |
|
||||
|---|---|
|
||||
| Java | 21 |
|
||||
| Maven | 3.9+ |
|
||||
| ArcadeDB | any recent release |
|
||||
| Spring Boot | 3.x (optional — Clotho also works standalone) |
|
||||
|
||||
Clotho is **schema-first**: it maps to a schema you have already created in ArcadeDB.
|
||||
It does not generate DDL.
|
||||
|
||||
---
|
||||
|
||||
## 1. Maven dependency
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>com.binarygolem.clotho</groupId>
|
||||
<artifactId>clotho-spring-boot-starter</artifactId>
|
||||
<version>0.1.0-SNAPSHOT</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
Use `clotho-core` instead if you are not using Spring Boot.
|
||||
|
||||
---
|
||||
|
||||
## 2. ArcadeDB schema
|
||||
|
||||
Create the required types in ArcadeDB before starting your application.
|
||||
Use the ArcadeDB console, HTTP API, or any migration tool:
|
||||
|
||||
```sql
|
||||
-- Vertices
|
||||
CREATE VERTEX TYPE Person;
|
||||
CREATE PROPERTY Person.name STRING;
|
||||
CREATE PROPERTY Person.email STRING;
|
||||
CREATE PROPERTY Person.age INTEGER;
|
||||
|
||||
CREATE VERTEX TYPE Company;
|
||||
CREATE PROPERTY Company.name STRING;
|
||||
CREATE PROPERTY Company.industry STRING;
|
||||
|
||||
-- Edge
|
||||
CREATE EDGE TYPE WORKS_AT;
|
||||
CREATE PROPERTY WORKS_AT.role STRING;
|
||||
CREATE PROPERTY WORKS_AT.startYear INTEGER;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Spring Boot configuration
|
||||
|
||||
```properties
|
||||
# application.properties
|
||||
|
||||
clotho.gremlin.url=ws://localhost:8182/gremlin
|
||||
clotho.gremlin.username=root
|
||||
clotho.gremlin.password=playwithdata
|
||||
clotho.gremlin.traversal-source=g
|
||||
|
||||
# Packages to scan for @VertexType, @EdgeType, @ClothoRepository
|
||||
clotho.packages=com.example.myapp
|
||||
|
||||
# Whether unknown graph labels cause an exception (STRICT) or map to a generic type (IGNORE_AND_MAP_TO_GENERIC)
|
||||
clotho.unknown-type-behavior=STRICT
|
||||
|
||||
# Default traversal direction for @Include fields that have no @Direction annotation
|
||||
clotho.default-direction=OUT
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Define entity classes
|
||||
|
||||
### Vertex type
|
||||
|
||||
```java
|
||||
@VertexType("Person")
|
||||
@Getter
|
||||
public class Person extends ClothoVertex {
|
||||
|
||||
@Property("name")
|
||||
private @Nullable String name;
|
||||
|
||||
@Property("email")
|
||||
private @Nullable String email;
|
||||
|
||||
@Property("age")
|
||||
private @Nullable Integer age;
|
||||
|
||||
// Eagerly loaded when Person is fetched — single Gremlin project() query
|
||||
@Include
|
||||
@Via("WORKS_AT")
|
||||
private @Nullable List<WorksAt> jobs;
|
||||
|
||||
// Manual setters call notifyFieldChanged() so Clotho tracks which fields changed.
|
||||
// Do NOT use Lombok @Setter on @Property, @Include, @OutVertex, @InVertex, or @Version fields.
|
||||
|
||||
public void setName(@Nullable String name) {
|
||||
this.name = name;
|
||||
notifyFieldChanged("name");
|
||||
}
|
||||
|
||||
public void setEmail(@Nullable String email) {
|
||||
this.email = email;
|
||||
notifyFieldChanged("email");
|
||||
}
|
||||
|
||||
public void setAge(@Nullable Integer age) {
|
||||
this.age = age;
|
||||
notifyFieldChanged("age");
|
||||
}
|
||||
|
||||
public void setJobs(@Nullable List<WorksAt> jobs) {
|
||||
this.jobs = jobs;
|
||||
notifyFieldChanged("jobs");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Edge type
|
||||
|
||||
```java
|
||||
@EdgeType("WORKS_AT")
|
||||
@Getter
|
||||
public class WorksAt extends ClothoEdge {
|
||||
|
||||
@Property("role")
|
||||
private @Nullable String role;
|
||||
|
||||
@Property("startYear")
|
||||
private @Nullable Integer startYear;
|
||||
|
||||
@OutVertex
|
||||
private @Nullable Person person; // populated when edge is loaded via @Include
|
||||
|
||||
@InVertex
|
||||
private @Nullable Company company; // populated when edge is loaded via @Include
|
||||
|
||||
public void setRole(@Nullable String role) {
|
||||
this.role = role;
|
||||
notifyFieldChanged("role");
|
||||
}
|
||||
|
||||
public void setStartYear(@Nullable Integer startYear) {
|
||||
this.startYear = startYear;
|
||||
notifyFieldChanged("startYear");
|
||||
}
|
||||
|
||||
public void setCompany(@Nullable Company company) {
|
||||
this.company = company;
|
||||
notifyFieldChanged("company");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Using the session
|
||||
|
||||
`ClothoSession` is the primary unit of work. Open one per logical operation, then close it.
|
||||
Sessions are **not thread-safe** — use one per thread or virtual thread.
|
||||
|
||||
```java
|
||||
@Service
|
||||
@RequiredArgsConstructor
|
||||
public class PersonService {
|
||||
|
||||
private final ClothoSessionFactory sessionFactory;
|
||||
|
||||
/** Create a person with an employment edge. */
|
||||
public void createPersonWithJob(String name, String role, String companyName) {
|
||||
try (ClothoSession session = sessionFactory.openSession()) {
|
||||
|
||||
Company company = new Company();
|
||||
company.setName(companyName);
|
||||
company.setIndustry("Technology");
|
||||
|
||||
WorksAt job = new WorksAt();
|
||||
job.setRole(role);
|
||||
job.setStartYear(2024);
|
||||
job.setCompany(company); // @InVertex — resolved during edge creation
|
||||
|
||||
Person person = new Person();
|
||||
person.setName(name);
|
||||
person.setJobs(List.of(job));
|
||||
|
||||
session.save(person);
|
||||
// cascade: person → job → company (all created in order)
|
||||
|
||||
System.out.println("Created: " + person.getId());
|
||||
}
|
||||
}
|
||||
|
||||
/** Load a person — jobs are populated atomically with the vertex. */
|
||||
public Person findById(ARID id) {
|
||||
try (ClothoSession session = sessionFactory.openSession()) {
|
||||
return session.load(Person.class, id);
|
||||
// person.getJobs() is already populated — no extra round-trip
|
||||
}
|
||||
}
|
||||
|
||||
/** Update — only the fields you changed are written. */
|
||||
public void promoteEmployee(ARID personId, String newRole) {
|
||||
try (ClothoSession session = sessionFactory.openSession()) {
|
||||
Person person = session.load(Person.class, personId);
|
||||
|
||||
if (person.getJobs() != null && !person.getJobs().isEmpty()) {
|
||||
person.getJobs().get(0).setRole(newRole);
|
||||
session.save(person);
|
||||
// only role is written; no other properties touched
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/** Auto-save — dirty MANAGED entities are saved when the session closes. */
|
||||
public void updateEmailAutoSave(ARID personId, String newEmail) {
|
||||
try (ClothoSession session = sessionFactory.openSession()) {
|
||||
Person person = session.load(Person.class, personId);
|
||||
person.setEmail(newEmail);
|
||||
// no explicit save() — session.close() persists dirty entities
|
||||
}
|
||||
}
|
||||
|
||||
/** Delete a person — ArcadeDB also removes all incident edges. */
|
||||
public void deletePerson(ARID id) {
|
||||
try (ClothoSession session = sessionFactory.openSession()) {
|
||||
Person person = session.load(Person.class, id);
|
||||
session.delete(person);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Session lifecycle
|
||||
|
||||
### What a session is
|
||||
|
||||
A `ClothoSession` is a unit of work. It wraps a graph connection, keeps an **identity map**
|
||||
(same ARID → same Java instance within a session), tracks dirty fields, and auto-saves
|
||||
managed entities when it closes. Sessions are **not thread-safe** — never share one across
|
||||
threads.
|
||||
|
||||
### Short-lived sessions (recommended default)
|
||||
|
||||
Open a session with try-with-resources. The session closes — and auto-saves any dirty
|
||||
entities — at the end of the block:
|
||||
|
||||
```java
|
||||
try (ClothoSession session = sessionFactory.openSession()) {
|
||||
Person alice = session.load(Person.class, id);
|
||||
alice.setEmail("new@example.com");
|
||||
} // auto-saves alice here
|
||||
```
|
||||
|
||||
This is the right pattern for web request handlers, background jobs, and any operation
|
||||
with a clear start and end.
|
||||
|
||||
### Long-lived sessions
|
||||
|
||||
For a simple single-threaded process (a CLI tool, a startup task, a scheduled job that
|
||||
runs on one thread), you can keep one session open for as long as you need:
|
||||
|
||||
```java
|
||||
ClothoSession session = sessionFactory.openSession();
|
||||
|
||||
// ... do many things ...
|
||||
|
||||
session.close(); // or call in a shutdown hook
|
||||
```
|
||||
|
||||
The trade-off is that the **identity map grows indefinitely** — every entity loaded stays
|
||||
in memory until the session closes. For long-running processes that load many entities,
|
||||
call `session.clearCache()` periodically to release them without closing the session:
|
||||
|
||||
```java
|
||||
// After a large batch operation — drop all cached instances from memory.
|
||||
// The next load() for any of those IDs will re-fetch from the graph.
|
||||
session.clearCache();
|
||||
```
|
||||
|
||||
`clearCache()` does NOT flush dirty fields first. Call `session.save(entity)` explicitly
|
||||
for anything you want to keep before clearing.
|
||||
|
||||
### Do you ever need more than one session?
|
||||
|
||||
**Multiple threads: yes, one per thread.**
|
||||
Sessions bind to the current thread via a `ThreadLocal`. Start a new session on each
|
||||
thread (or virtual thread) and close it when the thread's work is done.
|
||||
|
||||
```java
|
||||
// With virtual threads (Java 21+):
|
||||
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
|
||||
executor.submit(() -> {
|
||||
try (ClothoSession session = sessionFactory.openSession()) {
|
||||
// ... work on this virtual thread ...
|
||||
}
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
**Multiple isolated operations on the same thread: open them sequentially.**
|
||||
Each `openSession()` call replaces the previous thread-local binding, so open only one
|
||||
session at a time on any given thread. Close the first before opening the second:
|
||||
|
||||
```java
|
||||
// First operation
|
||||
try (ClothoSession s1 = sessionFactory.openSession()) {
|
||||
session.load(Person.class, id);
|
||||
}
|
||||
// Second operation — clean identity map, independent unit of work
|
||||
try (ClothoSession s2 = sessionFactory.openSession()) {
|
||||
session.load(Person.class, id); // fresh load, not the cached s1 instance
|
||||
}
|
||||
```
|
||||
|
||||
**Spring Boot — session-per-request:**
|
||||
The `clotho-spring-boot-starter` provides a `ClothoSessionFactory` bean. Wire it into
|
||||
your `@Service` classes and open a session per method (as shown in section 5), or use a
|
||||
request-scoped session bean if you want one session for the lifetime of an HTTP request:
|
||||
|
||||
```java
|
||||
@Bean
|
||||
@RequestScope
|
||||
public ClothoSession requestSession(ClothoSessionFactory factory) {
|
||||
return factory.openSession();
|
||||
}
|
||||
```
|
||||
|
||||
Declare the bean as `@RequestScope` and Spring will open it on the first injection and
|
||||
call `close()` (triggering auto-save) at the end of the request.
|
||||
|
||||
### Transactional sessions
|
||||
|
||||
By default, each Gremlin traversal is auto-committed immediately by ArcadeDB. If a
|
||||
multi-step save fails midway, the graph is left in a partial state. Use a **transactional
|
||||
session** to wrap all operations in a single atomic transaction:
|
||||
|
||||
```java
|
||||
try (ClothoSession session = sessionFactory.openTransactionalSession()) {
|
||||
session.save(alice);
|
||||
session.save(acme);
|
||||
} // ← tx.commit() fires here; any exception triggers tx.rollback()
|
||||
```
|
||||
|
||||
With the Spring Boot starter you can use `@Transactional` instead of managing the
|
||||
session manually. `ClothoTransactionManager` is registered automatically:
|
||||
|
||||
```java
|
||||
@Service
|
||||
@RequiredArgsConstructor
|
||||
public class PersonService {
|
||||
|
||||
private final ClothoSessionFactory sessionFactory;
|
||||
|
||||
@Transactional
|
||||
public void promote(ARID personId) {
|
||||
try (ClothoSession session = sessionFactory.openSession()) { // borrows tx session
|
||||
Person p = session.load(Person.class, personId);
|
||||
p.setRole("SENIOR");
|
||||
} // session close is a no-op; Spring tx manager commits on method return
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Inside a `@Transactional` method, `openSession()` detects the existing transaction and
|
||||
borrows its session rather than opening a new one. The transaction is committed (or rolled
|
||||
back) when the outermost `@Transactional` boundary exits.
|
||||
|
||||
See [docs/TRANSACTIONS.md](TRANSACTIONS.md) for a complete guide including nested
|
||||
transactions, multi-manager setups, and the interaction with `@Version` optimistic locking.
|
||||
|
||||
### Summary
|
||||
|
||||
| Scenario | Pattern |
|
||||
|---|---|
|
||||
| Web request / discrete operation | `try (ClothoSession s = factory.openSession())` |
|
||||
| Atomic multi-step write | `try (ClothoSession s = factory.openTransactionalSession())` |
|
||||
| Spring `@Transactional` | Annotate service method; use `openSession()` inside |
|
||||
| Single-threaded background process | Open once; call `clearCache()` after big batches |
|
||||
| Multi-threaded / virtual threads | One session per thread, opened and closed on that thread |
|
||||
| Spring HTTP request scope | `@Bean @RequestScope ClothoSession` |
|
||||
|
||||
---
|
||||
|
||||
## 7. Repository pattern
|
||||
|
||||
Define a repository by extending `ClothoRepository<T>` and annotating with `@ClothoRepository`.
|
||||
The Spring Boot starter registers it as a bean automatically.
|
||||
|
||||
```java
|
||||
@ClothoRepository
|
||||
public class PersonRepository extends ClothoRepository<Person> {
|
||||
|
||||
public PersonRepository(ClothoSessionFactory factory) {
|
||||
super(factory);
|
||||
}
|
||||
|
||||
// Built-in: findAll(), findById(), count(), save(), delete(), findWithPagination()
|
||||
|
||||
public List<Person> findByName(String name) {
|
||||
return execute(g().V().has("Person", "name", name));
|
||||
}
|
||||
|
||||
public List<Person> findByAgeGreaterThan(int minAge) {
|
||||
return execute(allEntities(), t -> t.has("age", P.gt(minAge)));
|
||||
}
|
||||
|
||||
public List<Person> findEmployed() {
|
||||
// people who have at least one outgoing WORKS_AT edge
|
||||
return execute(allEntities(), t -> t.where(__.outE("WORKS_AT")));
|
||||
}
|
||||
|
||||
public long countByIndustry(String industry) {
|
||||
// raw result — no Clotho mapping
|
||||
return this.<Long>executeRaw(
|
||||
g().V().has("Company", "industry", industry).count()
|
||||
).get(0);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Inject the repository in your service:
|
||||
|
||||
```java
|
||||
@Service
|
||||
@RequiredArgsConstructor
|
||||
public class PersonService {
|
||||
|
||||
private final PersonRepository personRepository;
|
||||
|
||||
public List<Person> listSeniorEngineers() {
|
||||
return personRepository.findByAgeGreaterThan(35);
|
||||
}
|
||||
|
||||
public List<Person> listAll() {
|
||||
return personRepository.findAll(); // inherited
|
||||
}
|
||||
|
||||
public List<Person> listPage(long page, long pageSize) {
|
||||
return personRepository.findWithPagination(page * pageSize, pageSize); // inherited
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Ad-hoc traversals from a loaded entity
|
||||
|
||||
Repository methods can traverse any edge in the graph — there is no requirement that the
|
||||
edge be declared as `@Include` on the entity class. Start from the loaded entity's ID and
|
||||
write a Gremlin traversal as usual.
|
||||
|
||||
**Example: find co-workers** — people who share a company via `WORKS_AT`, but where
|
||||
`WORKS_AT` is not declared as `@Include` on `Person`:
|
||||
|
||||
```java
|
||||
@ClothoRepository
|
||||
public class PersonRepository extends ClothoRepository<Person> {
|
||||
|
||||
// ...
|
||||
|
||||
public List<Person> findCoworkers(Person person) {
|
||||
return execute(
|
||||
g().V(person.getId().asString()).as("self")
|
||||
.out("WORKS_AT") // Person → Company
|
||||
.in("WORKS_AT") // Company → all Persons at that company
|
||||
.where(P.neq("self")) // exclude the starting person
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Call it with any already-loaded `Person`:
|
||||
|
||||
```java
|
||||
try (ClothoSession session = sessionFactory.openSession()) {
|
||||
Person alice = session.load(Person.class, aliceId);
|
||||
List<Person> coworkers = personRepository.findCoworkers(alice);
|
||||
// returned Person objects have their @Include fields populated (jobs, etc.)
|
||||
}
|
||||
```
|
||||
|
||||
**Key point:** `execute()` maps every resulting vertex to its most-specific registered
|
||||
Clotho type and calls `populateAll()` on the result list, so the returned objects are fully
|
||||
hydrated (all eager `@Include` fields present) — regardless of how the traversal was built.
|
||||
The object boundary and the query traversal are completely independent concerns.
|
||||
|
||||
### Tracked results — execute with a session
|
||||
|
||||
By default, `execute()` returns **detached** entities: they are not registered in any
|
||||
session and mutations are silently ignored. Pass a `ClothoSession` to get back **MANAGED**
|
||||
entities instead — dirty-field tracking fires, and the session auto-saves any changes when
|
||||
it closes:
|
||||
|
||||
```java
|
||||
public List<Person> findCoworkers(Person person, ClothoSession session) {
|
||||
return execute(session,
|
||||
g().V(person.getId().asString()).as("self")
|
||||
.out("WORKS_AT").in("WORKS_AT")
|
||||
.where(P.neq("self"))
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
try (ClothoSession session = sessionFactory.openSession()) {
|
||||
Person alice = session.load(Person.class, aliceId);
|
||||
List<Person> coworkers = personRepository.findCoworkers(alice, session);
|
||||
|
||||
// Mutations are tracked — no explicit save() needed
|
||||
coworkers.get(0).setEmail("new@example.com");
|
||||
} // ← session.close() auto-saves the dirty co-worker
|
||||
```
|
||||
|
||||
`session.register(vertex)` is the underlying mechanism — it recursively marks the vertex
|
||||
and all entities reachable through its `@Include` boundary as MANAGED and adds them to the
|
||||
session's identity map. You can call it directly if you need finer control.
|
||||
|
||||
For raw scalar results (counts, aggregates), use `executeRaw()`:
|
||||
|
||||
```java
|
||||
public long countCoworkers(Person person) {
|
||||
return this.<Long>executeRaw(
|
||||
g().V(person.getId().asString())
|
||||
.out("WORKS_AT").in("WORKS_AT")
|
||||
.where(P.neq("self"))
|
||||
.count()
|
||||
).get(0);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Object boundary with @Include
|
||||
|
||||
`@Include @Via("EDGE_LABEL")` declares that a field is part of this object's boundary.
|
||||
All `@Include` fields on a vertex are loaded in a single atomic `project()` traversal —
|
||||
no N+1 queries, no risk of seeing inconsistent state between fields.
|
||||
|
||||
```java
|
||||
@VertexType("Department")
|
||||
@Getter
|
||||
public class Department extends ClothoVertex {
|
||||
|
||||
@Property("name") private @Nullable String name;
|
||||
|
||||
// EAGER (default): loaded with the vertex, always present
|
||||
@Include
|
||||
@Via("HAS_MANAGER")
|
||||
private @Nullable Person manager;
|
||||
|
||||
// LAZY: skipped on initial load; call session.loadField() when needed
|
||||
@Include(fetchType = FetchType.LAZY)
|
||||
@Via("HAS_MEMBER")
|
||||
private @Nullable List<Person> members;
|
||||
}
|
||||
```
|
||||
|
||||
Load a lazy field on demand:
|
||||
|
||||
```java
|
||||
try (ClothoSession session = sessionFactory.openSession()) {
|
||||
Department dept = session.load(Department.class, deptId);
|
||||
// dept.getMembers() is null here — field was declared LAZY
|
||||
|
||||
session.loadField(dept, "members");
|
||||
// dept.getMembers() is now populated
|
||||
log.info("Members: {}", dept.getMembers().size());
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Optimistic locking with @Version
|
||||
|
||||
ArcadeDB maintains a `@version` counter on every record that increments on each write.
|
||||
Clotho reads it on load and includes it in update traversals, so concurrent writes are detected.
|
||||
|
||||
```java
|
||||
@VertexType("Order")
|
||||
@Getter
|
||||
public class Order extends ClothoVertex {
|
||||
|
||||
@Property("status") private @Nullable String status;
|
||||
|
||||
@Version // maps to ArcadeDB's built-in @version property
|
||||
private @Nullable Long version;
|
||||
|
||||
public void setStatus(@Nullable String status) {
|
||||
this.status = status;
|
||||
notifyFieldChanged("status");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If two sessions load the same Order and both try to save a change, the second save throws
|
||||
`OptimisticLockException`:
|
||||
|
||||
```java
|
||||
try (ClothoSession session = sessionFactory.openSession()) {
|
||||
Order order = session.load(Order.class, orderId);
|
||||
order.setStatus("SHIPPED");
|
||||
session.save(order);
|
||||
} catch (OptimisticLockException e) {
|
||||
log.warn("Concurrent update detected for {} at version {}",
|
||||
e.getId(), e.getExpectedVersion());
|
||||
// retry or report conflict
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Subgraph queries
|
||||
|
||||
Use `executeSubgraph()` when a traversal returns multiple entity types in a single result row.
|
||||
|
||||
```java
|
||||
@SubgraphType
|
||||
public class EmployeeProfile {
|
||||
Person person; // field name matches .as("person") in the Gremlin query
|
||||
@Alias("employer")
|
||||
Company company; // @Alias maps the field to a different Gremlin alias
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
@ClothoRepository
|
||||
public class EmployeeRepo extends ClothoRepository<Person> {
|
||||
|
||||
public EmployeeRepo(ClothoSessionFactory factory) { super(factory); }
|
||||
|
||||
public List<EmployeeProfile> findProfiles() {
|
||||
return executeSubgraph(EmployeeProfile.class,
|
||||
g().V().hasLabel("Person").as("person")
|
||||
.out("WORKS_AT").in("WORKS_AT").as("company") // traverse to Company
|
||||
.select("person", "company"));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. Type inheritance
|
||||
|
||||
Define a class hierarchy in Java and tell Clotho which ArcadeDB parent types to wire:
|
||||
|
||||
```java
|
||||
@VertexType(value = "Employee", additionalParents = {"Person"})
|
||||
public class Employee extends Person {
|
||||
@Property("employeeNumber") private @Nullable String employeeNumber;
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
When Clotho loads a vertex labeled `Employee`, it maps it to `Employee.class`.
|
||||
When it loads a vertex labeled `Person` (no `Employee` subtype), it maps it to `Person.class`.
|
||||
This "most specific type wins" rule is enforced by the `TypeRegistry`.
|
||||
|
||||
---
|
||||
|
||||
## Reference docs
|
||||
|
||||
| Document | Contents |
|
||||
|---|---|
|
||||
| `docs/TYPE_SYSTEM.md` | Entity hierarchy, inheritance, label resolution |
|
||||
| `docs/OBJECT_BOUNDARY.md` | `@Include`/`@Via`, multi-hop, edge-only inclusion, cycle detection |
|
||||
| `docs/ANNOTATIONS.md` | Complete annotation reference |
|
||||
| `docs/QUERY_MODEL.md` | Repository pattern, `executeSubgraph`, result mapping |
|
||||
| `docs/SPRING_INTEGRATION.md` | Autoconfigure, properties reference |
|
||||
| `docs/ARCHITECTURE.md` | Module breakdown, session lifecycle, data flow |
|
||||
|
||||
The `clotho-dev-app` module contains a runnable `FeatureDemo` that exercises all the patterns
|
||||
described here against a live ArcadeDB instance.
|
||||
@@ -0,0 +1,165 @@
|
||||
# Object Boundary
|
||||
|
||||
## What Is the Object Boundary?
|
||||
|
||||
Clotho has no lazy loading. When you call `session.load(Employee.class, rid)`, you receive the
|
||||
fully assembled object — root vertex plus everything within its declared boundary — in one
|
||||
operation. Nothing is deferred.
|
||||
|
||||
The **object boundary** is the set of edges and vertices Clotho traverses and assembles when
|
||||
loading a `@VertexType` instance. It is declared entirely in the Java class using `@Include`
|
||||
and `@Via`. Everything outside the boundary is accessed via `@Query` traversals written by
|
||||
the developer.
|
||||
|
||||
---
|
||||
|
||||
## Declaring the Boundary: `@Include` and `@Via`
|
||||
|
||||
```java
|
||||
@VertexType("Order")
|
||||
public class Order extends ClothoVertex {
|
||||
String status;
|
||||
|
||||
@Include @Via("HAS_LINE")
|
||||
List<OrderLine> lines;
|
||||
|
||||
@Include @Via("HAS_BILLING_ADDRESS")
|
||||
Address billingAddress;
|
||||
}
|
||||
```
|
||||
|
||||
- `@Include` marks the field as part of this object's boundary.
|
||||
- `@Via` specifies the ArcadeDB edge label to traverse.
|
||||
- The field type determines what is loaded (see below).
|
||||
|
||||
Both annotations are required together. `@Include` without `@Via` is a compile-time error.
|
||||
|
||||
---
|
||||
|
||||
## What Gets Loaded: Field Type Rules
|
||||
|
||||
### Field type is a `@VertexType` class
|
||||
|
||||
Clotho traverses the edge, loads the target vertex (and its own boundary recursively),
|
||||
and discards the edge itself (edge properties are not available).
|
||||
|
||||
```java
|
||||
@Include @Via("HAS_BILLING_ADDRESS")
|
||||
Address billingAddress; // Address is a @VertexType; edge properties ignored
|
||||
```
|
||||
|
||||
### Field type is an `@EdgeType` class
|
||||
|
||||
Clotho loads the full edge object — edge properties, plus `@OutVertex` and `@InVertex`
|
||||
fields if declared on the edge class.
|
||||
|
||||
```java
|
||||
@Include @Via("HAS_LINE")
|
||||
List<OrderLineEdge> lines; // OrderLineEdge is an @EdgeType; edge props + vertices loaded
|
||||
```
|
||||
|
||||
### Edge-only inclusion (no `@InVertex` on the edge class)
|
||||
|
||||
When the `@EdgeType` class declares no `@InVertex` field, the target vertex is not fetched.
|
||||
Useful when you need the edge's own properties but not the vertex it points to.
|
||||
|
||||
```java
|
||||
@EdgeType("TAGGED_WITH")
|
||||
public class TagEdge extends ClothoEdge {
|
||||
@OutVertex Order order;
|
||||
// No @InVertex — Tag vertex is never loaded
|
||||
String tagValue;
|
||||
int weight;
|
||||
}
|
||||
|
||||
// In Order:
|
||||
@Include @Via("TAGGED_WITH")
|
||||
List<TagEdge> tags; // Only edge properties; Tag vertices stay in the DB
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Edge Direction
|
||||
|
||||
Default direction is `OUT` (follow outgoing edges from the current vertex).
|
||||
Override per field with `@Direction`:
|
||||
|
||||
```java
|
||||
@Include @Via("ASSIGNED_TO") @Direction(Direction.IN)
|
||||
List<Task> assignedTasks; // follow INCOMING ASSIGNED_TO edges to find tasks
|
||||
|
||||
@Include @Via("CONNECTED") @Direction(Direction.BOTH)
|
||||
List<Node> neighbors; // follow edges in both directions
|
||||
```
|
||||
|
||||
The global default can be changed in session factory configuration:
|
||||
```properties
|
||||
clotho.default-direction=OUT
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Multi-Hop Boundaries
|
||||
|
||||
`@Include` is applied recursively. If `OrderLine` itself has `@Include` fields, they are
|
||||
loaded as part of loading `Order`.
|
||||
|
||||
```java
|
||||
@VertexType("Order")
|
||||
public class Order extends ClothoVertex {
|
||||
@Include @Via("HAS_LINE")
|
||||
List<OrderLine> lines; // hop 1
|
||||
}
|
||||
|
||||
@VertexType("OrderLine")
|
||||
public class OrderLine extends ClothoVertex {
|
||||
int quantity;
|
||||
BigDecimal unitPrice;
|
||||
|
||||
@Include @Via("HAS_NOTE")
|
||||
List<Note> notes; // hop 2 — loaded as part of Order
|
||||
}
|
||||
```
|
||||
|
||||
Loading an `Order` traverses: `Order → HAS_LINE → OrderLine → HAS_NOTE → Note`.
|
||||
|
||||
There is no depth limit. The developer is responsible for designing boundaries that do not
|
||||
load unbounded portions of the graph.
|
||||
|
||||
---
|
||||
|
||||
## Cycle Detection
|
||||
|
||||
Clotho tracks visited ARIDs during a boundary load. If a traversal reaches a vertex it has
|
||||
already loaded in the current operation, it uses the existing instance and stops traversing
|
||||
further — it does not loop. The developer still bears responsibility for not creating
|
||||
boundaries that load huge subgraphs.
|
||||
|
||||
---
|
||||
|
||||
## Persistence of Boundary Elements
|
||||
|
||||
When `session.save(order)` is called:
|
||||
|
||||
1. The root `Order` vertex is upserted (created if ARID is null, updated if set).
|
||||
2. Each `@Include` field is recursively persisted in the same way.
|
||||
3. Elements reachable via multiple paths are saved exactly once (identity map deduplication).
|
||||
4. **Removed items are NOT automatically deleted.** If you remove an `OrderLine` from
|
||||
`order.lines`, calling `save()` does not delete the `OrderLine` vertex or its edges.
|
||||
Call `session.delete(orderLine)` explicitly.
|
||||
|
||||
---
|
||||
|
||||
## Design Guidance
|
||||
|
||||
The boundary should reflect **ownership**, not just connectivity. Include elements that:
|
||||
- Are always loaded and managed together with the root
|
||||
- Are not meaningful without the root (e.g., `OrderLine` without `Order`)
|
||||
- Form a bounded transaction unit
|
||||
|
||||
Do NOT include:
|
||||
- Large, unbounded collections (e.g., all products a customer ever bought)
|
||||
- Elements that are independently meaningful and queried on their own
|
||||
- Elements reachable via long traversal chains across the domain
|
||||
|
||||
For everything outside the boundary, write a `@Query` on a `@ClothoRepository` interface.
|
||||
@@ -0,0 +1,194 @@
|
||||
# Query Model
|
||||
|
||||
## Philosophy
|
||||
|
||||
Graph databases excel at complex relationship queries. That complexity belongs in the
|
||||
developer's Gremlin code, not inside the ORM. Clotho's query model is a **bridge**:
|
||||
|
||||
- Developer writes a Gremlin traversal
|
||||
- Clotho executes it and maps the results back to registered Java types
|
||||
- Developer injects the repository interface like any Spring bean
|
||||
|
||||
---
|
||||
|
||||
## `@ClothoRepository` Interfaces
|
||||
|
||||
The primary way to define queries. Clotho generates a dynamic proxy at startup.
|
||||
|
||||
```java
|
||||
@ClothoRepository
|
||||
public interface EmployeeQueries {
|
||||
|
||||
@Query("g.V().hasLabel('Employee').has('dept',:dept)")
|
||||
List<Employee> findByDepartment(@Param("dept") String dept);
|
||||
|
||||
@Query("""
|
||||
g.V().has('Employee','id',:id)
|
||||
.repeat(out('MANAGES')).times(2).emit()
|
||||
.dedup()
|
||||
""")
|
||||
List<Employee> findTwoLevelsOfReports(@Param("id") String managerId);
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
@Autowired EmployeeQueries employeeQueries;
|
||||
|
||||
List<Employee> staff = employeeQueries.findByDepartment("Engineering");
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Parameter Binding
|
||||
|
||||
Use `:paramName` placeholders in the Gremlin string and `@Param("paramName")` on the
|
||||
corresponding method parameter.
|
||||
|
||||
```java
|
||||
@Query("g.V().has('Order','status',:status).has('total',gt(:minTotal))")
|
||||
List<Order> findByStatusAndMinTotal(
|
||||
@Param("status") String status,
|
||||
@Param("minTotal") BigDecimal minTotal);
|
||||
```
|
||||
|
||||
Clotho substitutes parameters before executing the traversal. Parameter types are passed
|
||||
as-is to Gremlin — use Java types that Gremlin/ArcadeDB understands (String, int, long,
|
||||
double, boolean, LocalDate, etc.).
|
||||
|
||||
---
|
||||
|
||||
## Return Type Rules
|
||||
|
||||
The declared return type tells Clotho how to map the traversal result.
|
||||
|
||||
### `@VertexType` or `@EdgeType` class
|
||||
|
||||
Clotho maps each result element to the most specific registered class matching its label.
|
||||
The declared type is the upper bound.
|
||||
|
||||
```java
|
||||
// May return Employee, HourlyEmployee, SalariedEmployee — all ClothoVertex subtypes
|
||||
List<Employee> findAll();
|
||||
|
||||
// Explicitly mixed: any registered @VertexType
|
||||
List<ClothoVertex> findAllVertices();
|
||||
```
|
||||
|
||||
When the return type is a single object (not a `List`), Clotho returns the first result or
|
||||
`null` if none.
|
||||
|
||||
```java
|
||||
@Nullable
|
||||
@Query("g.V().has('Employee','id',:id)")
|
||||
Employee findById(@Param("id") String id);
|
||||
```
|
||||
|
||||
### `@SubgraphType` class
|
||||
|
||||
When the return type is annotated `@SubgraphType`, Clotho expects the traversal to return a
|
||||
`select()` map. It maps each key to the matching field by name (or by `@Alias`).
|
||||
|
||||
```java
|
||||
@Query("""
|
||||
g.V().has('Employee','id',:id).as('employee')
|
||||
.out('MANAGED_BY').as('manager')
|
||||
.out('IN_DEPT').as('dept')
|
||||
.select('employee','manager','dept')
|
||||
""")
|
||||
EmployeeProfile loadProfile(@Param("id") String id);
|
||||
```
|
||||
|
||||
```java
|
||||
@SubgraphType
|
||||
public class EmployeeProfile {
|
||||
Employee employee; // bound to key "employee"
|
||||
Manager manager; // bound to key "manager"
|
||||
@Alias("dept") Department department; // bound to key "dept"
|
||||
}
|
||||
```
|
||||
|
||||
If the traversal returns a list of select maps, declare `List<EmployeeProfile>`.
|
||||
|
||||
### Raw result (no mapping)
|
||||
|
||||
Set `mapResult = false` to receive the Gremlin result directly without Clotho mapping.
|
||||
Return type can be a scalar, `List<Object>`, or any type Gremlin produces.
|
||||
|
||||
```java
|
||||
@Query(value = "g.V().hasLabel('Employee').count()", mapResult = false)
|
||||
long countEmployees();
|
||||
|
||||
@Query(value = "g.V().has('Order','id',:id).values('status')", mapResult = false)
|
||||
String getOrderStatus(@Param("id") String id);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Named Queries on `@VertexType` Classes
|
||||
|
||||
An alternative to repository interfaces for simple per-type queries.
|
||||
Place `@Query` directly on the vertex class with a `name` attribute:
|
||||
|
||||
```java
|
||||
@VertexType("Order")
|
||||
@Query(name = "openForCustomer",
|
||||
gremlin = "g.V().has('Customer','id',:custId).out('PLACED').has('status','OPEN')")
|
||||
public class Order extends ClothoVertex { ... }
|
||||
```
|
||||
|
||||
Invoke via the session:
|
||||
```java
|
||||
List<Order> open = session.query(Order.class, "openForCustomer",
|
||||
Map.of("custId", customerId));
|
||||
```
|
||||
|
||||
**Note on magic strings**: the query name `"openForCustomer"` is a raw string.
|
||||
Prefer defining it as a constant on the class:
|
||||
|
||||
```java
|
||||
@VertexType("Order")
|
||||
@Query(name = Order.QUERY_OPEN_FOR_CUSTOMER, ...)
|
||||
public class Order extends ClothoVertex {
|
||||
public static final String QUERY_OPEN_FOR_CUSTOMER = "openForCustomer";
|
||||
}
|
||||
|
||||
// Call site:
|
||||
session.query(Order.class, Order.QUERY_OPEN_FOR_CUSTOMER, params);
|
||||
```
|
||||
|
||||
Multiple `@Query` annotations on a class are allowed (the annotation is `@Repeatable`).
|
||||
|
||||
---
|
||||
|
||||
## Gremlin Traversal Source
|
||||
|
||||
The `GraphTraversalSource` (`g`) is managed by `ClothoSessionFactory`. It is configured
|
||||
once and shared across sessions. Clotho configures the traversal source to use the remote
|
||||
ArcadeDB connection.
|
||||
|
||||
For advanced cases where a developer needs direct traversal source access:
|
||||
|
||||
```java
|
||||
@Autowired ClothoSessionFactory factory;
|
||||
|
||||
GraphTraversalSource g = factory.traversalSource();
|
||||
// Write raw Gremlin, then map manually:
|
||||
List<ClothoVertex> results = factory.currentSession()
|
||||
.mapVertices(ClothoVertex.class, g.V().has("name", "Alice").out("KNOWS"));
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Mapping Detail: How Clotho Maps a Gremlin Vertex to a Java Object
|
||||
|
||||
1. Read the vertex label from the TinkerPop `Vertex` object
|
||||
2. Look up the label in the `TypeRegistry` → find the most specific registered class
|
||||
3. Construct an instance of that class (via reflection; Lombok builder support planned)
|
||||
4. Set the `ARID` from the vertex ID
|
||||
5. For each `@Property` field on the class: read the property from the vertex, set the field
|
||||
6. For each `@Include` field: recursively execute the boundary traversal (see `OBJECT_BOUNDARY.md`)
|
||||
7. Register the instance in the session identity map keyed by ARID
|
||||
8. Return the assembled instance
|
||||
|
||||
If the same ARID is encountered again during step 6, the identity map returns the already-
|
||||
assembled instance without re-fetching from the DB.
|
||||
@@ -0,0 +1,165 @@
|
||||
# Spring Integration
|
||||
|
||||
## Overview
|
||||
|
||||
The `clotho-spring-boot-starter` module provides:
|
||||
|
||||
- Autoconfiguration of `ClothoSessionFactory` as a singleton Spring bean
|
||||
- Session scoping tied to the Spring `@Transactional` lifecycle
|
||||
- Classpath scanning for `@ClothoRepository` interfaces and automatic proxy bean registration
|
||||
- `application.properties` / `application.yml` configuration support
|
||||
|
||||
The core `clotho-core` module has zero Spring dependency. Everything Spring-specific lives
|
||||
in `clotho-spring-boot-starter`.
|
||||
|
||||
---
|
||||
|
||||
## Adding the Starter
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>com.binarygolem.clotho</groupId>
|
||||
<artifactId>clotho-spring-boot-starter</artifactId>
|
||||
<version>${clotho.version}</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
No additional `@EnableXxx` annotation is required. The autoconfiguration activates
|
||||
automatically when the starter is on the classpath and `clotho.gremlin.url` is configured.
|
||||
|
||||
---
|
||||
|
||||
## `application.properties` Reference
|
||||
|
||||
| Key | Default | Description |
|
||||
|---|---|---|
|
||||
| `clotho.gremlin.url` | (required) | WebSocket URL for ArcadeDB Gremlin endpoint |
|
||||
| `clotho.gremlin.username` | `""` | ArcadeDB username |
|
||||
| `clotho.gremlin.password` | `""` | ArcadeDB password |
|
||||
| `clotho.gremlin.traversal-source` | `g` | Name of the traversal source on the server |
|
||||
| `clotho.default-direction` | `OUT` | Default edge direction for `@Via` fields |
|
||||
| `clotho.unknown-type-behavior` | `STRICT` | `STRICT`, `NEAREST_ANCESTOR`, or `GENERIC` |
|
||||
| `clotho.packages` | (required) | Comma-separated packages to scan for `@VertexType` / `@EdgeType` / `@ClothoRepository` |
|
||||
|
||||
**Example:**
|
||||
```properties
|
||||
clotho.gremlin.url=ws://localhost:8182/gremlin
|
||||
clotho.gremlin.username=root
|
||||
clotho.gremlin.password=playwithdata
|
||||
clotho.gremlin.traversal-source=g
|
||||
clotho.default-direction=OUT
|
||||
clotho.unknown-type-behavior=STRICT
|
||||
clotho.packages=com.example.myapp.domain,com.example.myapp.repository
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Beans Provided by Autoconfiguration
|
||||
|
||||
| Bean | Type | Description |
|
||||
|---|---|---|
|
||||
| `clothoSessionFactory` | `ClothoSessionFactory` | Singleton; holds connection and TypeRegistry |
|
||||
| `clothoTransactionManager` | `PlatformTransactionManager` | Bridges Spring `@Transactional` to Clotho sessions |
|
||||
|
||||
Repository beans (one per `@ClothoRepository` interface found during scan) are also
|
||||
registered automatically.
|
||||
|
||||
---
|
||||
|
||||
## Transaction Integration
|
||||
|
||||
Clotho integrates with Spring's `@Transactional` annotation via a `PlatformTransactionManager`
|
||||
implementation. A `ClothoSession` is opened when a transaction begins and closed (or rolled
|
||||
back) when the transaction ends.
|
||||
|
||||
```java
|
||||
@Service
|
||||
public class OrderService {
|
||||
|
||||
@Autowired ClothoSessionFactory sessionFactory;
|
||||
@Autowired OrderQueries orderQueries;
|
||||
|
||||
@Transactional
|
||||
public void fulfillOrder(ARID orderId) {
|
||||
ClothoSession session = sessionFactory.currentSession();
|
||||
Order order = session.load(Order.class, orderId);
|
||||
|
||||
order.setStatus("FULFILLED");
|
||||
session.save(order);
|
||||
// session.save() is called; commit happens when @Transactional method returns
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Session Scope
|
||||
|
||||
Within a `@Transactional` method, `sessionFactory.currentSession()` always returns the
|
||||
same `ClothoSession`. The identity map is scoped to this session — the same ARID loaded
|
||||
twice returns the same Java instance.
|
||||
|
||||
Outside a transaction, each `sessionFactory.openSession()` call creates a new session.
|
||||
The caller is responsible for closing it:
|
||||
|
||||
```java
|
||||
try (ClothoSession session = sessionFactory.openSession()) {
|
||||
Employee emp = session.load(Employee.class, rid);
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### Transaction Semantics
|
||||
|
||||
**Note**: ArcadeDB's Gremlin Server transaction behavior needs verification. Gremlin
|
||||
typically treats each request as an auto-committed transaction. For multi-step operations
|
||||
(e.g., creating a vertex and then an edge), the behavior depends on the server configuration.
|
||||
This will be refined once verified against the live ArcadeDB instance.
|
||||
|
||||
---
|
||||
|
||||
## `@ClothoRepository` Injection
|
||||
|
||||
```java
|
||||
@ClothoRepository
|
||||
public interface EmployeeQueries {
|
||||
@Query("g.V().hasLabel('Employee').has('dept',:dept)")
|
||||
List<Employee> findByDepartment(@Param("dept") String dept);
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
@Service
|
||||
public class EmployeeService {
|
||||
|
||||
@Autowired EmployeeQueries employeeQueries; // injected by Spring
|
||||
|
||||
public List<Employee> getEngineers() {
|
||||
return employeeQueries.findByDepartment("Engineering");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The proxy generated for `EmployeeQueries` uses the `ClothoSession` from the current
|
||||
transaction context (or opens a new one for the call duration if no transaction is active).
|
||||
|
||||
---
|
||||
|
||||
## Manually Constructing `ClothoSessionFactory` (without Spring)
|
||||
|
||||
```java
|
||||
ClothoSessionFactory factory = ClothoSessionFactory.builder()
|
||||
.url("ws://localhost:8182/gremlin")
|
||||
.credentials("root", "playwithdata")
|
||||
.traversalSource("g")
|
||||
.defaultDirection(Direction.OUT)
|
||||
.unknownTypeBehavior(UnknownTypeBehavior.STRICT)
|
||||
.scanPackages("com.example.domain")
|
||||
.build();
|
||||
|
||||
try (ClothoSession session = factory.openSession()) {
|
||||
Employee emp = session.load(Employee.class, ARID.of("#10:0"));
|
||||
emp.setName("Updated");
|
||||
session.save(emp);
|
||||
}
|
||||
|
||||
factory.close();
|
||||
```
|
||||
@@ -0,0 +1,341 @@
|
||||
# Clotho Transactions
|
||||
|
||||
Clotho provides two levels of transactional control:
|
||||
|
||||
1. **Optimistic locking** via `@Version` — detects concurrent modifications on individual
|
||||
entities at write time. Does not require a database transaction.
|
||||
2. **Transactional sessions** — wraps all reads and writes in a single ArcadeDB transaction,
|
||||
providing atomicity for multi-step operations.
|
||||
|
||||
This document covers transactional sessions.
|
||||
|
||||
---
|
||||
|
||||
## Why transactions?
|
||||
|
||||
Without a transaction:
|
||||
|
||||
- Each Gremlin traversal is auto-committed by ArcadeDB immediately.
|
||||
- A multi-step save that fails midway leaves the graph in a partial state.
|
||||
- Two concurrent sessions can read and overwrite each other's changes without any
|
||||
isolation guarantee.
|
||||
|
||||
With a transactional session, all operations share a single transaction scope. Either
|
||||
everything commits or nothing does.
|
||||
|
||||
---
|
||||
|
||||
## Manual transactional sessions
|
||||
|
||||
```java
|
||||
ClothoSession session = sessionFactory.openTransactionalSession();
|
||||
try {
|
||||
Company acme = new Company();
|
||||
acme.setName("Acme Corp");
|
||||
|
||||
Person alice = new Person();
|
||||
alice.setName("Alice");
|
||||
|
||||
session.save(alice);
|
||||
session.save(acme);
|
||||
session.close(); // auto-save dirty entities + tx.commit()
|
||||
} catch (RuntimeException e) {
|
||||
session.rollback(); // tx.rollback(), cache cleared, session unbound
|
||||
throw e;
|
||||
}
|
||||
```
|
||||
|
||||
Or use try-with-resources (preferred — `close()` commits on success, rolls back on
|
||||
exception):
|
||||
|
||||
```java
|
||||
try (ClothoSession session = sessionFactory.openTransactionalSession()) {
|
||||
session.save(alice);
|
||||
session.save(acme);
|
||||
} // ← tx.commit() fires here; RuntimeException triggers tx.rollback()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Spring `@Transactional`
|
||||
|
||||
When using the Spring Boot starter, `ClothoTransactionManager` is registered automatically
|
||||
(conditional on no other `PlatformTransactionManager` bean being present). This wires
|
||||
Clotho into Spring's standard `@Transactional` machinery.
|
||||
|
||||
### Obtaining the session inside a transactional method
|
||||
|
||||
**Option A — `openSession()` (recommended):** behaves correctly in and out of a transaction.
|
||||
Inside a `@Transactional` method the active session is borrowed (no new session created);
|
||||
outside, a new non-transactional session is opened.
|
||||
|
||||
```java
|
||||
@Service
|
||||
@RequiredArgsConstructor
|
||||
public class PersonService {
|
||||
|
||||
private final ClothoSessionFactory sessionFactory;
|
||||
private final PersonRepository personRepo;
|
||||
|
||||
@Transactional
|
||||
public void promote(ARID personId) {
|
||||
try (ClothoSession session = sessionFactory.openSession()) { // borrows tx session
|
||||
Person p = session.load(Person.class, personId);
|
||||
p.setRole("SENIOR");
|
||||
// auto-saved on session close; tx committed by Spring tx manager
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Option B — `getCurrentSession()`:** throws `ClothoException` if no session is active.
|
||||
Use when you explicitly require a session to already be bound (e.g. in a helper that
|
||||
must only be called from within a `@Transactional` context).
|
||||
|
||||
```java
|
||||
@Transactional
|
||||
public void doWork() {
|
||||
ClothoSession session = sessionFactory.getCurrentSession();
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### Repository queries inside a transaction
|
||||
|
||||
`ClothoRepository.execute(traversal)` (no-session overload) uses the factory's base
|
||||
`GraphTraversalSource` and is **not** part of the transaction. Use the session-aware
|
||||
overload instead:
|
||||
|
||||
```java
|
||||
@Transactional
|
||||
public void updateEngineers() {
|
||||
try (ClothoSession session = sessionFactory.openSession()) {
|
||||
List<Person> engineers = personRepo.execute(session,
|
||||
personRepo.allEntities(), t -> t.has("role", "Engineer"));
|
||||
for (Person p : engineers) {
|
||||
p.setRole("Senior Engineer");
|
||||
// dirty tracking fires; auto-saved on session close
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Nested `@Transactional` methods
|
||||
|
||||
Spring's default propagation is `REQUIRED`: an inner `@Transactional` method joins the
|
||||
outer transaction rather than starting a new one. Clotho honours this via the borrow
|
||||
counter:
|
||||
|
||||
```java
|
||||
@Transactional // outer — opens a transactional session
|
||||
public void outer() {
|
||||
inner(); // inner joins; no new session or commit
|
||||
// commit happens here when outer returns
|
||||
}
|
||||
|
||||
@Transactional // inner — borrows the outer session
|
||||
public void inner() {
|
||||
// ... same transaction
|
||||
}
|
||||
```
|
||||
|
||||
If you need the inner method to run in its own transaction, use
|
||||
`@Transactional(propagation = Propagation.REQUIRES_NEW)`. Clotho does not currently
|
||||
support REQUIRES_NEW natively — the inner `openSession()` will still borrow the outer
|
||||
session. If true nested transaction isolation is required, manage sessions manually with
|
||||
separate `openTransactionalSession()` calls.
|
||||
|
||||
---
|
||||
|
||||
## Apps with another transaction manager (JPA, R2DBC)
|
||||
|
||||
`ClothoTransactionManager` registers with `@ConditionalOnMissingBean(PlatformTransactionManager.class)`.
|
||||
If your application already has a JPA or R2DBC transaction manager, the Clotho bean is
|
||||
skipped.
|
||||
|
||||
To use Clotho transactions alongside another tx manager, declare the bean explicitly
|
||||
and qualify it:
|
||||
|
||||
```java
|
||||
@Bean
|
||||
public ClothoTransactionManager clothoTransactionManager(ClothoSessionFactory factory) {
|
||||
return new ClothoTransactionManager(factory);
|
||||
}
|
||||
```
|
||||
|
||||
Then annotate service methods:
|
||||
|
||||
```java
|
||||
@Transactional("clothoTransactionManager")
|
||||
public void myGraphOperation() { ... }
|
||||
```
|
||||
|
||||
Or declare Clotho's manager as `@Primary` if it is the dominant transaction manager
|
||||
in your application.
|
||||
|
||||
---
|
||||
|
||||
## Relationship between `@Version` and transactions
|
||||
|
||||
`@Version` provides **optimistic** concurrency control — it detects conflicts at write time
|
||||
by checking the entity's application-managed version counter against what is stored in the
|
||||
database. It works independently of the transactional session API.
|
||||
|
||||
Combining both:
|
||||
|
||||
- The batch auto-save at `close()` provides atomic writing of all dirty entities in one
|
||||
Gremlin request (the only atomicity guarantee available over ArcadeDB's Gremlin
|
||||
WebSocket).
|
||||
- `@Version` prevents lost updates when two sessions modify the same entity concurrently,
|
||||
via a two-step check-then-write that fails the entire batch if any version is stale.
|
||||
|
||||
A `@Version` check failure throws `OptimisticLockException` during the pre-flight step.
|
||||
Inside a transactional session, the exception propagates out of `close()`. Since no
|
||||
properties were written during the pre-flight, no rollback is necessary (but `close()`
|
||||
will attempt `g.tx().rollback()` regardless, which is a no-op with ArcadeDB Gremlin).
|
||||
|
||||
---
|
||||
|
||||
## Session auto-close behaviour in transactions
|
||||
|
||||
| Scenario | What happens on `session.close()` |
|
||||
|---|---|
|
||||
| Non-transactional | Auto-saves dirty managed entities; clears cache; unbinds |
|
||||
| Transactional (new) | Auto-saves dirty managed entities; `tx.commit()`; clears cache; unbinds |
|
||||
| Transactional (borrowed) | Decrements borrow count; no-op until count reaches 0 |
|
||||
| Exception during auto-save | `tx.rollback()`; clears cache; unbinds; re-throws |
|
||||
|
||||
Call `session.rollback()` explicitly to abort the transaction at any point without saving.
|
||||
`rollback()` always resets the borrow count to 0 and unbinds immediately.
|
||||
|
||||
---
|
||||
|
||||
## Batch auto-save and the safe session pattern
|
||||
|
||||
When `session.close()` triggers auto-save, Clotho collects every dirty MANAGED entity from
|
||||
the session cache — vertices and edges — and persists them in **a single Gremlin traversal**:
|
||||
|
||||
```
|
||||
inject(0).union(
|
||||
__.V(id1).property("name", "Alice"), // dirty vertex
|
||||
__.V(id2).property("dept", "Eng"), // dirty vertex
|
||||
__.E(eid).property("role", "Senior"), // dirty edge
|
||||
...
|
||||
).iterate()
|
||||
```
|
||||
|
||||
This collapses N round-trips into one, making the auto-save as efficient as possible and
|
||||
treating all updates as a single ArcadeDB request.
|
||||
|
||||
### Recommended session pattern
|
||||
|
||||
Load everything you intend to modify at the start of the session, make your changes, then
|
||||
let `close()` flush them together:
|
||||
|
||||
```java
|
||||
try (ClothoSession session = sessionFactory.openSession()) {
|
||||
Person alice = session.load(Person.class, aliceId); // load upfront
|
||||
Person bob = session.load(Person.class, bobId);
|
||||
Company acme = session.load(Company.class, acmeId);
|
||||
|
||||
// ... fetch any read-only helper data here too ...
|
||||
|
||||
alice.setEmail("alice@new.example.com"); // dirty tracking fires
|
||||
bob.setRole("Senior Engineer");
|
||||
acme.setName("Acme Corp International");
|
||||
}
|
||||
// ↑ single batch traversal flushes all three changes here
|
||||
```
|
||||
|
||||
The more entities you modify before closing, the more work is consolidated into that one
|
||||
round-trip.
|
||||
|
||||
### Atomicity — what "single request" means here
|
||||
|
||||
ArcadeDB auto-commits each incoming Gremlin request as one database operation. Because the
|
||||
auto-save batch is one request, updates to entities that **pass** their checks are committed
|
||||
together. Any interruption (network failure, server error) affects the entire request.
|
||||
|
||||
However, there are two important caveats:
|
||||
|
||||
**Explicit `session.save()` calls mid-session are NOT batched.** Each call to `session.save(entity)`
|
||||
issues an immediate individual traversal. Only the auto-save triggered by `session.close()`
|
||||
uses the batch path.
|
||||
|
||||
**`@Version` conflicts fail the whole batch.** The batch auto-save runs in two Gremlin
|
||||
round-trips:
|
||||
|
||||
1. **Pre-flight** — one request checks that every `@Version`-guarded entity still has its
|
||||
expected version in the database. If any version is stale, `OptimisticLockException` is
|
||||
thrown immediately and no properties are written.
|
||||
2. **Batch update** — one request writes all dirty properties for all entities, plus the
|
||||
incremented version for each `@Version` entity.
|
||||
|
||||
Concretely: if session has dirty entities A (no `@Version`), B (`@Version`, stale), and C
|
||||
(`@Version`, current), the outcome is:
|
||||
- Pre-flight detects B's stale version → `OptimisticLockException` thrown
|
||||
- Neither A, B, nor C has been written yet
|
||||
|
||||
There is a narrow TOCTOU window between the pre-flight and the write (a concurrent session
|
||||
could change B's version in that gap), but within that window only already-confirmed
|
||||
entities would be overwritten.
|
||||
|
||||
### `@Version` — application-managed OCC
|
||||
|
||||
`@Version` does **not** rely on ArcadeDB's internal `@version` property (which is not
|
||||
accessible via the Gremlin WebSocket interface). Instead, Clotho manages the counter as
|
||||
a regular graph property:
|
||||
|
||||
- **On create**: the version property is initialised to `0` in the graph; the in-memory
|
||||
field is set to `0`.
|
||||
- **On load**: the version is read like any other property.
|
||||
- **On update**: the pre-flight filter is `.has(versionProp, currentVersion)`. If matched,
|
||||
the new version `currentVersion + 1` is written atomically in the same traversal step.
|
||||
The in-memory field is updated after a successful write.
|
||||
|
||||
The property name defaults to `"_version"` and can be overridden via `@Version("myProp")`.
|
||||
|
||||
### ArcadeDB Gremlin transaction limitations
|
||||
|
||||
ArcadeDB's Gremlin WebSocket interface returns a transaction-bound `GraphTraversalSource`
|
||||
from `g.tx().begin()`, but subsequent Gremlin bytecode operations on that source fail at
|
||||
runtime. `openTransactionalSession()` therefore uses the base traversal source — the same
|
||||
one used by non-transactional sessions. The practical consequences:
|
||||
|
||||
- Each Gremlin request is auto-committed by ArcadeDB immediately.
|
||||
- `g.tx().commit()` / `g.tx().rollback()` (called by `close()` / `rollback()`) are
|
||||
effective no-ops in this mode.
|
||||
- The **batch auto-save** at `close()` is still a single Gremlin request, so it is
|
||||
atomic at the request level.
|
||||
- The **borrow counter** and **Spring `@Transactional` bridge** (`ClothoTransactionManager`)
|
||||
work correctly and provide the expected API surface.
|
||||
|
||||
True multi-request atomicity requires ArcadeDB's native Java or HTTP API directly.
|
||||
|
||||
### OrientDB Gremlin transaction limitations
|
||||
|
||||
OrientDB with `orient-transactional=false` (required so that `addV` returns real record IDs
|
||||
immediately rather than temporary `#-1:-2` IDs) rejects `g.tx()` calls entirely, throwing
|
||||
`Graph does not support transactions`.
|
||||
|
||||
At startup, `ClothoSessionFactory` probes transaction support by calling `g.tx().rollback()`.
|
||||
If the graph rejects the call with the "does not support transactions" message, all
|
||||
`g.tx().commit()` and `g.tx().rollback()` calls are skipped for every session. The
|
||||
`transactional` flag still drives the batch auto-save path and the borrow/Spring
|
||||
`@Transactional` semantics — only the explicit `g.tx()` calls are suppressed.
|
||||
|
||||
- Each Gremlin request auto-commits individually; the batch auto-save in `close()` provides
|
||||
request-level atomicity (one request = all dirty entity writes).
|
||||
- True multi-request transactions require OrientDB's native Java or binary protocol.
|
||||
|
||||
---
|
||||
|
||||
## Limitations
|
||||
|
||||
- `ClothoRepository.execute(traversal)` without a session is NOT part of the current
|
||||
transaction. Always use `execute(session, traversal)` for transactional repository queries.
|
||||
- `ClothoSession` is NOT thread-safe. One session per thread / virtual thread.
|
||||
- ArcadeDB requires the schema (vertex and edge types) to exist before any write.
|
||||
Clotho does not manage schema creation.
|
||||
@@ -0,0 +1,231 @@
|
||||
# Type System
|
||||
|
||||
## Base Class Hierarchy
|
||||
|
||||
Every type Clotho knows about descends from `ClothoEntity`:
|
||||
|
||||
```
|
||||
ClothoEntity (abstract)
|
||||
├── ClothoVertex (abstract)
|
||||
│ └── Employee, Person, Company, ... (developer-defined @VertexType classes)
|
||||
└── ClothoEdge (abstract)
|
||||
└── WorksAt, PlacedBy, ... (developer-defined @EdgeType classes)
|
||||
|
||||
@SubgraphType classes do NOT extend ClothoEntity — they are plain Java classes
|
||||
that aggregate ClothoVertex / ClothoEdge instances.
|
||||
```
|
||||
|
||||
### ClothoEntity
|
||||
|
||||
Carries the identity and metadata common to all graph elements:
|
||||
|
||||
| Member | Purpose |
|
||||
|---|---|
|
||||
| `ARID getId()` | ArcadeDB record ID; null for unsaved elements |
|
||||
| `String getLabel()` | ArcadeDB type name (e.g. `"Employee"`) |
|
||||
| `Object getProperty(String key)` | Raw property access; bypass typed fields when needed |
|
||||
| `boolean hasLabel(String label)` | Convenience type check |
|
||||
|
||||
### ClothoVertex
|
||||
|
||||
Adds vertex-specific behavior. All `@VertexType` classes must extend this.
|
||||
|
||||
### ClothoEdge
|
||||
|
||||
Adds edge-specific behavior. Carries `outVertexId` and `inVertexId` as `ARID` values.
|
||||
All `@EdgeType` classes must extend this.
|
||||
|
||||
---
|
||||
|
||||
## ARID — ArcadeDB Record ID
|
||||
|
||||
`ARID` is a typed value object wrapping the ArcadeDB record ID string (e.g. `#10:0`).
|
||||
It is deliberately opaque to avoid coupling call sites to ArcadeDB's ID format.
|
||||
|
||||
```java
|
||||
ARID id = ARID.of("#10:0");
|
||||
String raw = id.asString();
|
||||
```
|
||||
|
||||
Using `ARID` rather than `String` everywhere:
|
||||
- Makes it impossible to accidentally pass an arbitrary string as a record ID
|
||||
- Allows the internal representation to evolve (e.g., for future DB portability)
|
||||
- Null `ARID` reliably indicates "not yet persisted"
|
||||
|
||||
---
|
||||
|
||||
## Vertex Types
|
||||
|
||||
```java
|
||||
@VertexType("Employee")
|
||||
public class Employee extends ClothoVertex {
|
||||
@Property("name") String name;
|
||||
@Property("dept") String department;
|
||||
}
|
||||
```
|
||||
|
||||
The `@VertexType` label must match the ArcadeDB vertex type name exactly (case-sensitive).
|
||||
Field names that match the ArcadeDB property name do not need `@Property`; use it when
|
||||
names differ or for explicit documentation.
|
||||
|
||||
---
|
||||
|
||||
## Edge Types
|
||||
|
||||
```java
|
||||
@EdgeType("WORKS_AT")
|
||||
public class WorksAt extends ClothoEdge {
|
||||
public static final String LABEL = "WORKS_AT"; // avoids magic strings at call sites
|
||||
|
||||
@OutVertex Employee employee;
|
||||
@InVertex Company company;
|
||||
|
||||
@Property("startDate") LocalDate startDate;
|
||||
@Property("role") String role;
|
||||
}
|
||||
```
|
||||
|
||||
Declaring `@InVertex` is optional. Omitting it means the edge is loaded for its own
|
||||
properties only — the target vertex is not fetched. See `docs/OBJECT_BOUNDARY.md`.
|
||||
|
||||
---
|
||||
|
||||
## Subgraph Types
|
||||
|
||||
```java
|
||||
@SubgraphType
|
||||
public class EmployeeProfile {
|
||||
Employee employee; // matches Gremlin as("employee")
|
||||
Manager manager; // matches Gremlin as("manager")
|
||||
@Alias("dept")
|
||||
Department department; // @Alias when field name ≠ Gremlin alias
|
||||
List<WorksAt> workHistory;
|
||||
}
|
||||
```
|
||||
|
||||
- Has no `ARID`; does not extend `ClothoEntity`
|
||||
- Assembled by `SubgraphTypeAssembler` from a Gremlin `select()` result
|
||||
- `session.save(profile)` iterates all `ClothoEntity` fields and saves each;
|
||||
the session identity map ensures each element is persisted exactly once
|
||||
- See `docs/QUERY_MODEL.md` for how `@Query` populates subgraph types
|
||||
|
||||
---
|
||||
|
||||
## Inheritance
|
||||
|
||||
### Standard Single-Parent Inheritance
|
||||
|
||||
Mirror the ArcadeDB `EXTENDS` hierarchy in Java:
|
||||
|
||||
```java
|
||||
@VertexType("Person")
|
||||
public abstract class Person extends ClothoVertex {
|
||||
String name;
|
||||
}
|
||||
|
||||
@VertexType("Employee")
|
||||
public class Employee extends Person {
|
||||
String employeeId;
|
||||
}
|
||||
|
||||
@VertexType("HourlyEmployee")
|
||||
public class HourlyEmployee extends Employee {
|
||||
BigDecimal hourlyRate;
|
||||
}
|
||||
```
|
||||
|
||||
Clotho infers: `"HourlyEmployee"` is a subtype of `"Employee"` is a subtype of `"Person"`.
|
||||
|
||||
### Diamond Inheritance
|
||||
|
||||
ArcadeDB supports multi-parent inheritance. Java does not allow extending multiple classes.
|
||||
Declare the second (and further) ArcadeDB parents explicitly:
|
||||
|
||||
```java
|
||||
// ArcadeDB schema: ContractEmployee EXTENDS Employee, Contractor
|
||||
@VertexType(value = "ContractEmployee", additionalParents = {"Contractor"})
|
||||
public class ContractEmployee extends Employee {
|
||||
// Java hierarchy: ContractEmployee IS-A Employee
|
||||
// ArcadeDB hierarchy: ContractEmployee is also subtype of Contractor (via annotation)
|
||||
}
|
||||
```
|
||||
|
||||
Clotho uses `additionalParents` only for type registry resolution — not for Java polymorphism.
|
||||
If you need `ContractEmployee` to be usable as a `Contractor` in Java, use an interface:
|
||||
|
||||
```java
|
||||
public interface ContractorType { /* shared interface */ }
|
||||
|
||||
@VertexType("Contractor")
|
||||
public class Contractor extends ClothoVertex implements ContractorType { ... }
|
||||
|
||||
@VertexType(value = "ContractEmployee", additionalParents = {"Contractor"})
|
||||
public class ContractEmployee extends Employee implements ContractorType { ... }
|
||||
```
|
||||
|
||||
### Divergent Hierarchies
|
||||
|
||||
When the ArcadeDB hierarchy cannot be represented via Java `extends` at all, declare the
|
||||
parent explicitly:
|
||||
|
||||
```java
|
||||
@VertexType(value = "ExternalEmployee", parentLabel = "Employee")
|
||||
public class ExternalEmployee extends ClothoVertex {
|
||||
// Does not extend Employee in Java, but is a subtype in ArcadeDB
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Result Mapping Rule
|
||||
|
||||
**Clotho always instantiates the most specific registered class matching the vertex/edge label.**
|
||||
|
||||
The declared return type is an upper bound — the actual runtime instances are the narrowest
|
||||
match in the TypeRegistry.
|
||||
|
||||
```java
|
||||
// The query may return HourlyEmployee and SalariedEmployee vertices
|
||||
List<Employee> staff = repo.findAllEmployees();
|
||||
// → List contains HourlyEmployee and SalariedEmployee instances
|
||||
// (both assignable to Employee; caller may instanceof-check if needed)
|
||||
|
||||
List<ClothoVertex> anything = repo.findMixed();
|
||||
// → List contains whatever registered types the traversal returned
|
||||
```
|
||||
|
||||
### Unknown Types
|
||||
|
||||
When a vertex/edge label has no registered Java class, behavior depends on the configured
|
||||
`UnknownTypeBehavior`:
|
||||
|
||||
| Mode | Behavior |
|
||||
|---|---|
|
||||
| `STRICT` (default) | Throw `UnknownTypeException` |
|
||||
| `NEAREST_ANCESTOR` | Instantiate closest registered ancestor; subtype-specific fields are null |
|
||||
| `GENERIC` | Wrap in `ClothoVertex`/`ClothoEdge` with raw `getProperty()` access |
|
||||
|
||||
Configure globally:
|
||||
```properties
|
||||
clotho.unknown-type-behavior=STRICT
|
||||
```
|
||||
|
||||
Or per session factory:
|
||||
```java
|
||||
ClothoSessionFactory.builder()
|
||||
.unknownTypeBehavior(UnknownTypeBehavior.NEAREST_ANCESTOR)
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## TypeRegistry
|
||||
|
||||
The `TypeRegistry` is built once at `ClothoSessionFactory` creation time.
|
||||
It scans the declared packages for `@VertexType` and `@EdgeType` classes and builds:
|
||||
|
||||
- `label → Class<? extends ClothoEntity>` direct lookup
|
||||
- Inheritance tree (for `NEAREST_ANCESTOR` resolution and polymorphic query hints)
|
||||
- Validation: duplicate labels, missing `extends ClothoVertex`/`ClothoEdge`, etc.
|
||||
|
||||
Startup failure is preferred over silent misconfiguration at runtime.
|
||||
@@ -0,0 +1,136 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project xmlns="http://maven.apache.org/POM/4.0.0"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
|
||||
http://maven.apache.org/xsd/maven-4.0.0.xsd">
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
||||
<groupId>com.binarygolem.clotho</groupId>
|
||||
<artifactId>clotho-parent</artifactId>
|
||||
<version>0.1.0-SNAPSHOT</version>
|
||||
<packaging>pom</packaging>
|
||||
|
||||
<name>Clotho Parent</name>
|
||||
<description>Graph ORM for ArcadeDB via TinkerPop/Gremlin — parent POM</description>
|
||||
|
||||
<modules>
|
||||
<module>clotho-core</module>
|
||||
<module>clotho-spring-boot-starter</module>
|
||||
<module>clotho-dev-app</module>
|
||||
</modules>
|
||||
|
||||
<properties>
|
||||
<java.version>21</java.version>
|
||||
<maven.compiler.source>21</maven.compiler.source>
|
||||
<maven.compiler.target>21</maven.compiler.target>
|
||||
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
|
||||
|
||||
<spring-boot.version>3.3.4</spring-boot.version>
|
||||
<tinkerpop.version>3.7.2</tinkerpop.version>
|
||||
<lombok.version>1.18.34</lombok.version>
|
||||
<jspecify.version>1.0.0</jspecify.version>
|
||||
<classgraph.version>4.8.174</classgraph.version>
|
||||
|
||||
<maven-compiler-plugin.version>3.13.0</maven-compiler-plugin.version>
|
||||
<maven-surefire-plugin.version>3.3.1</maven-surefire-plugin.version>
|
||||
</properties>
|
||||
|
||||
<dependencyManagement>
|
||||
<dependencies>
|
||||
|
||||
<!-- Spring Boot BOM — provides managed versions for Spring, JUnit 5, etc. -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-dependencies</artifactId>
|
||||
<version>${spring-boot.version}</version>
|
||||
<type>pom</type>
|
||||
<scope>import</scope>
|
||||
</dependency>
|
||||
|
||||
<!-- TinkerPop -->
|
||||
<dependency>
|
||||
<groupId>org.apache.tinkerpop</groupId>
|
||||
<artifactId>gremlin-driver</artifactId>
|
||||
<version>${tinkerpop.version}</version>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>org.apache.tinkerpop</groupId>
|
||||
<artifactId>tinkergraph-gremlin</artifactId>
|
||||
<version>${tinkerpop.version}</version>
|
||||
</dependency>
|
||||
|
||||
<!-- Clotho inter-module -->
|
||||
<dependency>
|
||||
<groupId>com.binarygolem.clotho</groupId>
|
||||
<artifactId>clotho-core</artifactId>
|
||||
<version>${project.version}</version>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>com.binarygolem.clotho</groupId>
|
||||
<artifactId>clotho-spring-boot-starter</artifactId>
|
||||
<version>${project.version}</version>
|
||||
</dependency>
|
||||
|
||||
<!-- Lombok -->
|
||||
<dependency>
|
||||
<groupId>org.projectlombok</groupId>
|
||||
<artifactId>lombok</artifactId>
|
||||
<version>${lombok.version}</version>
|
||||
<scope>provided</scope>
|
||||
</dependency>
|
||||
|
||||
<!-- JSpecify null annotations -->
|
||||
<dependency>
|
||||
<groupId>org.jspecify</groupId>
|
||||
<artifactId>jspecify</artifactId>
|
||||
<version>${jspecify.version}</version>
|
||||
</dependency>
|
||||
|
||||
<!-- ClassGraph — classpath scanning for TypeRegistry -->
|
||||
<dependency>
|
||||
<groupId>io.github.classgraph</groupId>
|
||||
<artifactId>classgraph</artifactId>
|
||||
<version>${classgraph.version}</version>
|
||||
</dependency>
|
||||
|
||||
</dependencies>
|
||||
</dependencyManagement>
|
||||
|
||||
<build>
|
||||
<pluginManagement>
|
||||
<plugins>
|
||||
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-compiler-plugin</artifactId>
|
||||
<version>${maven-compiler-plugin.version}</version>
|
||||
<configuration>
|
||||
<source>${java.version}</source>
|
||||
<target>${java.version}</target>
|
||||
<annotationProcessorPaths>
|
||||
<path>
|
||||
<groupId>org.projectlombok</groupId>
|
||||
<artifactId>lombok</artifactId>
|
||||
<version>${lombok.version}</version>
|
||||
</path>
|
||||
</annotationProcessorPaths>
|
||||
</configuration>
|
||||
</plugin>
|
||||
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-surefire-plugin</artifactId>
|
||||
<version>${maven-surefire-plugin.version}</version>
|
||||
</plugin>
|
||||
|
||||
<plugin>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-maven-plugin</artifactId>
|
||||
<version>${spring-boot.version}</version>
|
||||
</plugin>
|
||||
|
||||
</plugins>
|
||||
</pluginManagement>
|
||||
</build>
|
||||
|
||||
</project>
|
||||
Reference in New Issue
Block a user