Implementation:Datahub project Datahub RequiresMutable

Knowledge Sources	Datahub_project_Datahub
Domains	Java_SDK, Metadata_Emission, Entity_Mutability
Last Updated	2026-02-10 00:00 GMT

Overview

A runtime Java annotation that marks entity methods requiring a mutable entity, serving as both documentation and a contract enforced through automated bytecode inspection tests.

Description

The @RequiresMutable annotation is applied to methods on DataHub V2 SDK entity classes that perform mutations (e.g., setDescription, addCustomProperty). It has two purposes:

1. Documentation: Makes it immediately clear in the source code that the annotated method requires the entity to be in a mutable state (i.e., obtained via Entity.mutable() rather than being a read-only entity fetched from the server).
2. Test enforcement: Automated tests verify via bytecode inspection that all annotated methods properly call validation methods like checkNotReadOnly(String).

The annotation supports two attributes:

• operation -- An optional custom description for error messages. If empty, the operation name is auto-derived from the method name (e.g., setDescription becomes "set description").
• checks -- An array of Check enum values specifying which validations are required. Defaults to {Check.NOT_READ_ONLY}.

The inner Check enum currently defines one value:

• NOT_READ_ONLY -- Validates that the entity is not read-only. Read-only entities throw ReadOnlyEntityException if mutated without first calling mutable().

The enum is designed for future extension with additional check types (e.g., NOT_DIRTY, IN_TRANSACTION, HAS_PERMISSION).

Usage

Apply this annotation to any entity method that modifies state. The annotated method must manually call the appropriate check method (e.g., checkNotReadOnly("operation")) as the annotation itself does not perform runtime interception.

Code Reference

Source Location

metadata-integration/java/datahub-client/src/main/java/datahub/client/v2/annotations/RequiresMutable.java

Signature

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface RequiresMutable {
    String operation() default "";
    Check[] checks() default {Check.NOT_READ_ONLY};

    enum Check {
        NOT_READ_ONLY
    }
}

Import

import datahub.client.v2.annotations.RequiresMutable;
import datahub.client.v2.annotations.RequiresMutable.Check;

I/O Contract

Inputs

Attribute	Type	Default	Description
operation	String	"" (auto-derived)	Custom operation description for error messages
checks	Check[]	{Check.NOT_READ_ONLY}	Validation checks to enforce

Outputs

This is an annotation; it does not produce direct output. It is retained at runtime (RUNTIME retention) for reflective access by both test infrastructure (bytecode inspection) and potentially future AOP-based validation.

Usage Examples

// Basic usage - operation auto-derived as "set description"
@RequiresMutable
public Chart setDescription(@Nonnull String description) {
    checkNotReadOnly("set description");
    // ... mutation logic ...
    return this;
}

// Custom operation name
@RequiresMutable(operation = "add custom property")
public Chart addCustomProperty(@Nonnull String key, @Nonnull String value) {
    checkNotReadOnly("add custom property");
    // ... mutation logic ...
    return this;
}

// Future: Multiple validation checks
@RequiresMutable(checks = {Check.NOT_READ_ONLY})
public Chart strictMethod() {
    checkNotReadOnly("strict method");
    return this;
}

Related Pages

• Datahub_project_Datahub_DataHubClientConfigV2 -- V2 client configuration that works with mutable entities
• Datahub_project_Datahub_RestEmitterEmitMode -- Controls how mutations are persisted