Clun/pcu groups

[clun]

PCU Groups Support Implementation

Overview

This PR introduces comprehensive support for PCU (Processing Capacity Units) Groups in the Astra DB Java SDK. PCU Groups allow users to manage compute resources for databases across cloud providers and regions, providing fine-grained control over database provisioning and capacity management.

Key Features

1. PCU Groups Management API

Added complete PCU Groups operations in AstraDBAdmin:

List PCU Groups

// List all PCU groups in the organization
List<PCUGroupDefinition> allGroups = astraDBAdmin.listPCUGroups();

// List PCU groups filtered by cloud provider and region
List<PCUGroupDefinition> awsGroups = astraDBAdmin.listPCUGroups(CloudProviderType.AWS, "us-east-1");

Check PCU Group Existence

// Check if a PCU group exists globally
boolean exists = astraDBAdmin.PCUGroupExists(pcuGroupId);

// Check if a PCU group exists in a specific cloud/region
boolean existsInRegion = astraDBAdmin.PCUGroupExists(
    pcuGroupId, 
    CloudProviderType.AWS, 
    "us-east-1"
);

2. Database Creation with PCU Groups

Enhanced database creation to support PCU group assignment:

DatabaseDefinition definition = DatabaseDefinition.builder()
    .name("my-database")
    .cloudProvider(CloudProviderType.AWS)
    .region("us-east-1")
    .pcuGroupId(pcuGroupId)  // Assign to specific PCU group
    .build();

DatabaseAdmin dbAdmin = astraDBAdmin.createDatabase("my-database", definition, options);

3. Automatic PCU Group Validation

When creating a database with a PCU group, the SDK automatically validates:

1. Global Existence: Verifies the PCU group exists in the organization
2. Regional Availability: Confirms the PCU group is available in the specified cloud provider and region
3. Graceful Error Handling: If PCU group listing fails, validation is skipped with a warning (non-blocking)

Validation Logic:

• Calls the PCU Groups API only once for efficiency
• Filters results in-memory to check regional availability
• Throws descriptive exceptions if validation fails:
  • "Pcu group {id} does not exist" - Group not found globally
  • "Pcu group {id} is not in expected cloud/region: {cloud}/{region}" - Group not in target region

4. DevOps API Integration

Added comprehensive PCU Groups client in astra-sdk-devops:

PCUGroupsOpsClient

• findAll() - List all PCU groups
• create(request) - Create new PCU group
• pcuGroup(id) - Get specific PCU group client

PCUGroupOpsClient

• find() - Get PCU group details
• update(request) - Update PCU group
• delete() - Delete PCU group
• datacenterAssociations() - Manage datacenter associations

Domain Models

• PCUGroup - Complete PCU group representation
• PCUType - PCU type configuration
• PCUGroupCreationRequest - Request for creating PCU groups
• PCUGroupUpdateRequest - Request for updating PCU groups
• PCUGroupDatacenterAssociation - Datacenter association details
• Enums: PCUInstanceType, PCUProvisionType, PCUGroupStatusType, PCUCapacityWorkloadType

5. Database Creation Request Enhancement

Updated DatabaseCreationRequest to support PCU groups:

DatabaseCreationRequest request = DatabaseCreationRequest.builder()
    .name("my-database")
    .cloudProvider(CloudProviderType.AWS)
    .cloudRegion("us-east-1")
    .keyspace("my_keyspace")
    .pcuGroupId(pcuGroupId)  // NEW: Assign to PCU group
    .withVector()
    .build();

---

API Changes

New Methods in AstraDBAdmin

Method	Description
listPCUGroups()	List all PCU groups
listPCUGroups(CloudProviderType, String)	List PCU groups by cloud/region
PCUGroupExists(UUID)	Check if PCU group exists
PCUGroupExists(UUID, CloudProviderType, String)	Check if PCU group exists in cloud/region

Enhanced Methods

Method	Enhancement
createDatabase(String, DatabaseDefinition, CreateDatabaseOptions)	Now supports PCU group assignment and validation

New Options

Class	Field	Description
DatabaseDefinition	pcuGroupId	UUID of PCU group to assign
CreateDatabaseOptions	waitForDb	Wait for database to become active