Convert-Jpa-To-Spring-Data-Cosmos

# Convert Spring JPA project to Spring Data Cosmos

This generalized guide applies to any JPA to Spring Data Cosmos DB conversion project.

High-level plan

1. Swap build dependencies (remove JPA, add Cosmos + Identity).

2. Add `cosmos` profile and properties.

3. Add Cosmos config with proper Azure identity authentication.

4. Transform entities (ids → `String`, add `@Container` and `@PartitionKey`, remove JPA mappings, adjust relationships).

5. Convert repositories (`JpaRepository` → `CosmosRepository`).

6. **Create service layer** for relationship management and template compatibility.

7. **CRITICAL**: Update ALL test files to work with String IDs and Cosmos repositories.

8. Seed data via `CommandLineRunner`.

9. **CRITICAL**: Test runtime functionality and fix template compatibility issues.

Step-by-step

Step 1 — Build dependencies

- **Maven** (`pom.xml`):

- Remove dependency `spring-boot-starter-data-jpa`

- Remove database-specific dependencies (H2, MySQL, PostgreSQL) unless needed elsewhere

- Add `com.azure:azure-spring-data-cosmos:5.17.0` (or latest compatible version)

- Add `com.azure:azure-identity:1.15.4` (required for DefaultAzureCredential)

- **Gradle**: Apply same dependency changes for Gradle syntax

- Remove testcontainers and JPA-specific test dependencies

Step 2 — Properties and Configuration

- Create `src/main/resources/application-cosmos.properties`:

```properties

azure.cosmos.uri=${COSMOS_URI:https://localhost:8081}

azure.cosmos.database=${COSMOS_DATABASE:petclinic}

azure.cosmos.populate-query-metrics=false

azure.cosmos.enable-multiple-write-locations=false

```

- Update `src/main/resources/application.properties`:

```properties

spring.profiles.active=cosmos

```

Step 3 — Configuration class with Azure Identity

- Create `src/main/java/<rootpkg>/config/CosmosConfiguration.java`:

```java

@Configuration

@EnableCosmosRepositories(basePackages = "<rootpkg>")

public class CosmosConfiguration extends AbstractCosmosConfiguration {

@Value("${azure.cosmos.uri}")

private String uri;

@Value("${azure.cosmos.database}")

private String dbName;

@Bean

public CosmosClientBuilder getCosmosClientBuilder() {

return new CosmosClientBuilder().endpoint(uri).credential(new DefaultAzureCredentialBuilder().build());

}

@Override

protected String getDatabaseName() {

return dbName;

}

@Bean

public CosmosConfig cosmosConfig() {

return CosmosConfig.builder().enableQueryMetrics(false).build();

}

}

```

- **IMPORTANT**: Use `DefaultAzureCredentialBuilder().build()` instead of key-based authentication for production security

Step 4 — Entity transformation

- Target all classes with JPA annotations (`@Entity`, `@MappedSuperclass`, `@Embeddable`)

- **Base entity changes**:

- Change `id` field type from `Integer` to `String`

- Add `@Id` and `@GeneratedValue` annotations

- Add `@PartitionKey` field (typically `String partitionKey`)

- Remove all `jakarta.persistence` imports

- **CRITICAL - Cosmos DB Serialization Requirements**:

- **Remove ALL `@JsonIgnore` annotations** from fields that need to be persisted to Cosmos DB

- **Authentication entities (User, Authority) MUST be fully serializable** - no `@JsonIgnore` on password, authorities, or other persisted fields

- **Use `@JsonProperty` instead of `@JsonIgnore`** when you need to control JSON field names but still persist the data

- **Common authentication serialization errors**: `Cannot pass null or empty values to constructor` usually means `@JsonIgnore` is blocking required field serialization

- **Entity-specific changes**:

- Replace `@Entity` with `@Container(containerName = "<plural-entity-name>")`

- Remove `@Table`, `@Column`, `@JoinColumn`, etc.

- Remove relationship annotations (`@OneToMany`, `@ManyToOne`, `@ManyToMany`)

- For relationships:

- Embed collections for one-to-many (e.g., `List<Pet> pets` in Owner)

- Use referen