Apache Hop
Download
Development Documentation 2.20.0

User manual

Edit this page

Value Metadata Plugins

A value metadata plugin defines a new data type that flows across pipeline hops in row streams (such as JSON, Avro, UUID, or XML). The plugin defines how values are stored in memory, converted to other data types, compared, formatted, and serialized across network hops.

Implementing a Value Type

Annotate your class with @ValueMetaPlugin and extend ValueMetaBase:

java
import org.apache.hop.core.exception.HopValueException;
import org.apache.hop.core.row.IValueMeta;
import org.apache.hop.core.row.value.ValueMetaBase;
import org.apache.hop.core.row.value.ValueMetaPlugin;
import java.util.UUID;

@ValueMetaPlugin(
    id = "32",                               // Permanent numeric ID constant as a String
    name = "UUID",
    description = "Universally Unique Identifier",
    image = "uuid.svg"
)
public class ValueMetaUuid extends ValueMetaBase implements IValueMeta {

  public static final int TYPE_UUID = 32;

  public ValueMetaUuid() {
    this(null);
  }

  public ValueMetaUuid(String name) {
    super(name, TYPE_UUID);
  }

  @Override
  public int getType() {
    return TYPE_UUID;
  }

  @Override
  public Class<?> getNativeDataTypeClass() {
    return UUID.class;
  }

  @Override
  public String getString(Object object) throws HopValueException {
    if (object == null) return null;
    return object.toString();
  }

  @Override
  public Object convertData(IValueMeta meta2, Object data2) throws HopValueException {
    if (data2 == null) return null;
    if (data2 instanceof UUID) return data2;
    if (data2 instanceof String str) {
      return UUID.fromString(str);
    }
    return super.convertData(meta2, data2);
  }

  @Override
  public Object clone() {
    return new ValueMetaUuid(getName());
  }
}

Key Architectural Rules

  • Permanent Numeric ID: The id string represents a permanent integer constant serialized into .hpl pipeline files.

  • Conversion Coverage: Every value type must provide lossless conversions to String and Binary so transforms that do not explicitly recognize your custom type can still process or store the data.

Concrete Codebase Examples

  • core/src/main/java/org/apache/hop/core/row/value/ValueMetaString.java: Core string value metadata implementation.

  • core/src/main/java/org/apache/hop/core/row/value/ValueMetaJson.java: JSON value metadata. JSON is a core value type, not a plugin under plugins/valuetypes.

See also