Implementation:Apache Paimon Factory

Knowledge Sources	Apache_Paimon
Domains	Plugin System, Service Discovery
Last Updated	2026-02-08 00:00 GMT

Overview

Factory is the base interface for all plugin factories in Apache Paimon that create object instances from key-value configuration pairs.

Description

The Factory interface establishes the foundation for Paimon's extensible plugin system. It uses Java's Service Provider Interface (SPI) mechanism to discover and load implementations at runtime, allowing for a flexible, modular architecture where different components can be plugged in without modifying core code.

Each factory implementation is uniquely identified by a combination of its interface type and a string identifier returned by the `identifier()` method. This two-level identification allows multiple factories of the same type to coexist, such as different catalog implementations (filesystem, hive, jdbc) or different file format handlers.

The convention for identifiers is to use lowercase single words (like "kafka" or "hive"). For version-specific implementations, a hyphen followed by the version number should be appended (like "elasticsearch-7"). This naming convention ensures consistency across the ecosystem and makes configuration intuitive for users.

Factories are discovered via Java SPI by placing implementation classes in META-INF/services files within JAR files, enabling dynamic loading of plugins without compile-time dependencies.

Usage

Implement this interface when creating a new pluggable component type in Paimon, such as a catalog provider, file format handler, or connector. The factory pattern allows users to specify which implementation to use through configuration, and Paimon will automatically discover and instantiate the appropriate factory at runtime.

Code Reference

Source Location

• Repository: Apache_Paimon
• File: paimon-api/src/main/java/org/apache/paimon/factories/Factory.java

Signature

public interface Factory {
    /**
     * Returns a unique identifier among same factory interfaces.
     *
     * For consistency, an identifier should be declared as one lower case word (e.g. kafka).
     * If multiple factories exist for different versions, a version should be appended using "-"
     * (e.g. elasticsearch-7).
     */
    String identifier();
}

Import

import org.apache.paimon.factories.Factory;

I/O Contract

Inputs

Name	Type	Required	Description
N/A	N/A	N/A	No inputs; this is a marker interface with one method

Outputs

Name	Type	Description
identifier	String	Unique identifier for this factory implementation

Usage Examples

// Implementing a custom catalog factory
public class MyCatalogFactory implements CatalogFactory, Factory {
    @Override
    public String identifier() {
        return "mycatalog";
    }

    @Override
    public Catalog createCatalog(Context context) {
        Options options = Options.fromMap(context.getOptions());
        return new MyCatalog(options);
    }
}

// Implementing a versioned factory
public class ElasticsearchSinkFactory implements SinkFactory, Factory {
    @Override
    public String identifier() {
        return "elasticsearch-7";
    }

    @Override
    public Sink createSink(Context context) {
        return new ElasticsearchSink(context.getOptions());
    }
}

// Registering factory via SPI
// Create file: META-INF/services/org.apache.paimon.factories.Factory
// Contents:
// com.example.MyCatalogFactory
// com.example.ElasticsearchSinkFactory

// Using factory through configuration
Map<String, String> options = new HashMap<>();
options.put("type", "mycatalog");
options.put("warehouse", "/path/to/warehouse");

// Factory will be discovered and used automatically
CatalogFactory factory = FactoryUtil.discoverFactory(
    Thread.currentThread().getContextClassLoader(),
    CatalogFactory.class,
    "mycatalog"
);
Catalog catalog = factory.createCatalog(context);

// Multiple implementations example
public class HiveCatalogFactory implements CatalogFactory, Factory {
    @Override
    public String identifier() {
        return "hive";
    }
}

public class JdbcCatalogFactory implements CatalogFactory, Factory {
    @Override
    public String identifier() {
        return "jdbc";
    }
}

Related Pages

• Principle:Apache_Paimon_Catalog_Object_Model