v2: Design value objects — Tenant, Database, CollectionConfiguration, DistanceFunction

[oss-amikos]

Context

The Go client uses first-class value objects for Tenant, Database, and configuration. PR #80 used raw strings for tenant/database, which leads to parameter-swapping bugs and poor discoverability.

Requirements

Tenant and Database

Immutable value objects, not raw strings:

public final class Tenant {
    private final String name;

    public static Tenant of(String name) { ... }
    public static Tenant defaultTenant() { return of("default_tenant"); }

    public String getName() { ... }
    // equals, hashCode, toString
}

public final class Database {
    private final String name;

    public static Database of(String name) { ... }
    public static Database defaultDatabase() { return of("default_database"); }

    public String getName() { ... }
    // equals, hashCode, toString
}

DistanceFunction

Enum for HNSW distance metrics:

public enum DistanceFunction {
    COSINE("cosine"),
    L2("l2"),
    IP("ip");

    private final String value;
    // getValue(), fromString()
}

CollectionConfiguration

Immutable configuration with builder:

public final class CollectionConfiguration {
    // HNSW parameters
    private final DistanceFunction space;
    private final Integer hnswM;
    private final Integer hnswConstructionEf;
    private final Integer hnswSearchEf;
    private final Integer hnswBatchSize;
    private final Integer hnswSyncThreshold;

    public static Builder builder() { ... }
    // getters, no setters
}

CreateCollectionOptions / ListCollectionsOptions

public final class CreateCollectionOptions {
    private final Map<String, Object> metadata;
    private final CollectionConfiguration configuration;

    public static Builder builder() { ... }
    // For convenience:
    public static CreateCollectionOptions withMetadata(Map<String, Object> metadata) { ... }
}

public final class ListCollectionsOptions {
    private final Integer limit;
    private final Integer offset;

    public static ListCollectionsOptions of(int limit, int offset) { ... }
}

Design Principles

• All value objects are immutable and final
• Static factory methods (of(), defaultTenant()) over constructors
• equals, hashCode, toString on all value objects
• Null-safe — use @Nullable annotations where optional

Acceptance Criteria

• Tenant value object with of() and defaultTenant()
• Database value object with of() and defaultDatabase()
• DistanceFunction enum
• CollectionConfiguration with builder
• CreateCollectionOptions with builder
• ListCollectionsOptions
• All are immutable, with equals/hashCode/toString

Depends On

• v2: Define core interfaces — Client and Collection #81 (core interfaces — these objects are used in the interface signatures)

[oss-amikos]

Implemented in PR #95 (v2 API skeleton)