This guide is for plugin authors and business module integrators. It answers three practical questions:

1. What fe-extension-spi is responsible for.
2. When to use SPI only, and when to combine SPI with Loader.
3. How to implement a plugin package that Doris FE can discover and execute.

fe-extension-spi provides contracts only. It does not provide runtime loading.

Core contracts in this module:

1. Plugin: plugin instance lifecycle.
2. PluginFactory: plugin factory contract.
3. PluginContext: runtime configuration carrier.
4. PluginException: common runtime exception type.

Capabilities intentionally excluded from this module:

1. Directory scanning.
2. Jar discovery and resolution.
3. Classloader creation and close.
4. Load failure aggregation and staging.
5. Loaded plugin runtime registry.

Those runtime capabilities belong to fe-extension-loader.

Use fe-extension-spi directly if:

1. Your module already has a custom loading pipeline.
2. Your module already has a classloader framework.
3. You only need compile-time contracts for plugin implementers.

Use SPI + Loader if:

1. You want directory-driven loading by pluginRoots.
2. You want unified child-first classloading behavior.
3. You want standardized load failure stages (scan, resolve, discover, etc.).
4. You want to reduce duplicated loading code in each business module.

Responsibilities:

1. initialize(context): initialize plugin instance.
2. close(): release plugin resources.

Recommendations:

1. Keep initialize minimal and deterministic.
2. Make close idempotent.
3. Do not open external connections in static initializers.

Responsibilities:

1. name(): return stable logical plugin name.
2. create(): create a plugin instance.
3. create(context): optional context-aware create path (defaults to create()).

Recommendations:

1. Keep name() stable across environments.
2. Keep create() lightweight and side-effect-free.
3. Let business modules decide instance caching policy.

Responsibilities:

1. Carry runtime config (Map<String, String>).
2. Provide input for plugin initialization.

Recommendations:

1. Use stable key prefixes (for example: ldap.*, auth.*).
2. Validate required keys and apply defaults in plugin code.

Responsibilities:

1. Represent common plugin runtime failures.

Recommendations:

1. Include useful context in message: plugin name, stage, and key config item.
2. Keep original cause to preserve root-cause traceability.

public final class DemoPlugin implements Plugin {
    @Override
    public void initialize(PluginContext context) {
        // init
    }

    @Override
    public void close() {
        // cleanup
    }
}

public final class DemoPluginFactory implements PluginFactory {
    @Override
    public String name() {
        return "demo";
    }

    @Override
    public Plugin create() {
        return new DemoPlugin();
    }
}

File path:

META-INF/services/org.apache.doris.extension.spi.PluginFactory

File content:

com.example.demo.DemoPluginFactory

Your plugin jar should include:

1. Factory implementation class.
2. Plugin implementation class.
3. META-INF/services/... service declaration file.

1. name() must not be empty and should be globally distinguishable.
2. Fail fast during invalid initialization to avoid partial state.
3. Release thread pools and connection pools in close().
4. Avoid global mutable state inside plugin logic.

Check in this order:

1. Is META-INF/services/... file present?
2. Is provider class name fully qualified and correctly spelled?
3. Is the factory class included in final jar?

Check in this order:

1. Does factory create() depend on uninitialized resources?
2. Are required PluginContext entries missing?
3. Are plugin dependency jars complete?

Check in this order:

1. Does close() actually release pools and handles?
2. Is business code holding strong references to old plugin instances?
3. In external loading mode, is classloader close strategy applied?

Recommended composition:

1. Define plugin contracts in fe-extension-spi.
2. Perform directory-driven loading in fe-extension-loader.
3. Do factory registration, instance caching, and routing in business modules.

Detailed Loader integration guide:

../fe-extension-loader/README.md

1. Chinese developer guide: README_CN.md
2. Loader module runtime guide: ../fe-extension-loader/README.md
3. Unified runtime design (CN): ../fe-authentication/EXTENSION_LOADER_UNIFIED_DESIGN_CN.md