Principle:Datahub project Datahub Client Resource Cleanup

Property	Value
Principle Name	Client_Resource_Cleanup
Workflow	Java_SDK_V2_Entity_Management
Scope	Deterministic resource cleanup
Implementation	Implementation:Datahub_project_Datahub_DataHubClientV2_Close
Repository	https://github.com/datahub-project/datahub
Last Updated	2026-02-09 17:00 GMT

Overview

Description

Client Resource Cleanup is the principle of deterministic cleanup of client resources after metadata operations are complete. The DataHub Java SDK V2 client (DataHubClientV2) manages underlying HTTP connections, thread pools, and async client resources through a RestEmitter. These resources must be explicitly released when the client is no longer needed to prevent resource leaks, connection pool exhaustion, and thread leaks in long-running applications.

The SDK implements the AutoCloseable interface, enabling the use of Java's try-with-resources pattern for guaranteed cleanup, even in the presence of exceptions. This ensures that all HTTP connections are properly shut down and all thread pools are terminated when the client goes out of scope.

Usage

Resource cleanup is relevant in all applications that create a DataHubClientV2 instance. Key scenarios include:

• Short-lived scripts that create a client, perform operations, and exit -- cleanup prevents resource leaks during JVM shutdown
• Long-running services that create clients on demand -- cleanup prevents accumulated resource leaks
• Batch processing jobs that create a client per batch -- cleanup ensures each batch starts clean
• Integration tests that create and destroy clients per test case -- cleanup prevents test interference

Theoretical Basis

Resource Management Pattern

The Resource Management pattern (also known as Resource Acquisition Is Initialization, or RAII in C++) ensures that resources are properly released when they are no longer needed. In Java, this pattern is formalized through the AutoCloseable interface and the try-with-resources statement (introduced in Java 7).

The pattern addresses a fundamental tension in client library design:

1. Performance: Creating HTTP connections and thread pools is expensive, so they should be reused across operations
2. Safety: Shared resources must be deterministically cleaned up to prevent leaks

By implementing AutoCloseable, the client delegates cleanup responsibility to the Java language runtime when used with try-with-resources, while still allowing manual cleanup via explicit close() calls.

Underlying Resources

The DataHubClientV2 manages a chain of resources that require cleanup:

Resource	Managed By	Cleanup Action
HTTP async client	RestEmitter	Shuts down async HTTP client and connection pool
Thread pools	RestEmitter	Terminates worker threads for async I/O
Connection pool	RestEmitter	Closes all pooled HTTP connections
Server config cache	DataHubClientV2	Garbage collected (no explicit cleanup needed)

Try-With-Resources Guarantee

The try-with-resources statement provides the strongest guarantee for resource cleanup in Java:

1. The close() method is called automatically when the try block exits, whether normally or via exception
2. If both the try block and close() throw exceptions, the close() exception is suppressed (attached to the primary exception)
3. Multiple AutoCloseable resources in the same try statement are closed in reverse order of declaration

This guarantee is stronger than relying on finalizers (finalize()) or shutdown hooks, which are not guaranteed to run promptly or at all.

Thread Safety Considerations

The DataHubClientV2 is thread-safe and designed to be shared across threads. The close() method should only be called when no other threads are using the client. In practice, this means:

• Single-threaded applications: Close the client when all operations are complete
• Multi-threaded applications: Use a shared client instance and close it during application shutdown
• Concurrent operations: Ensure all pending upsert/get futures have completed before closing

Related Pages

• Implementation:Datahub_project_Datahub_DataHubClientV2_Close
• Principle:Datahub_project_Datahub_V2_Client_Setup -- Client creation that establishes resources requiring cleanup
• Principle:Datahub_project_Datahub_Entity_Upsert -- Operations that use client resources
• Principle:Datahub_project_Datahub_Entity_Retrieval -- Operations that use client resources