Skip to main content

Extension guide

Introduction​

Use this guide when the built-in components do not match your environment and you need custom implementations.

Extension model​

The service supports three loading patterns:

  1. Provider SPI (name() + initialize()): loaded by ServiceLoader and selected by config value.
  2. Class-name mapping for strategy handlers and job adapters.
  3. Typed SPI for StatisticsCalculator and MetricsEvaluator.

Extension points and config keys​

AreaInterface / typeConfig keyLoading mode
Recommender statisticsStatisticsProvidergravitino.optimizer.recommender.statisticsProviderProvider SPI by name()
Recommender strategy sourceStrategyProvidergravitino.optimizer.recommender.strategyProviderProvider SPI by name()
Recommender table metadataTableMetadataProvidergravitino.optimizer.recommender.tableMetaProviderProvider SPI by name()
Recommender job submissionJobSubmittergravitino.optimizer.recommender.jobSubmitterProvider SPI by name()
Strategy evaluation logicStrategyHandlergravitino.optimizer.strategyHandler.{strategy_type}.classNameReflection by class name
Job template adaptationGravitinoJobAdaptergravitino.optimizer.jobAdapter.{job_template}.classNameReflection by class name
Update statistics sinkStatisticsUpdatergravitino.optimizer.updater.statisticsUpdaterProvider SPI by name()
Update metrics sinkMetricsUpdatergravitino.optimizer.updater.metricsUpdaterProvider SPI by name()
Monitor metrics sourceMetricsProvidergravitino.optimizer.monitor.metricsProviderProvider SPI by name()
Monitor table-job relationTableJobRelationProvidergravitino.optimizer.monitor.tableJobRelationProviderProvider SPI by name()
Monitor evaluatorMetricsEvaluatorgravitino.optimizer.monitor.metricsEvaluatorTyped SPI (ServiceLoader<MetricsEvaluator>)
Monitor callbacksMonitorCallbackgravitino.optimizer.monitor.callbacksProvider SPI by name() (comma-separated)
CLI calculatorStatisticsCalculatorCLI --calculator-nameTyped SPI (ServiceLoader<StatisticsCalculator>)

Implement a custom provider​

Most extension points use Provider:

MyStatisticsProvider.java
public class MyStatisticsProvider implements StatisticsProvider {
  @Override
  public String name() {
    return "my-statistics-provider";
  }

  @Override
  public void initialize(OptimizerEnv optimizerEnv) {
    // Initialize clients and resources from the configuration file.
  }

  @Override
  public void close() throws Exception {}
}

Requirements:

  • Keep a stable name() value; config resolves by this name (case-insensitive).
  • Provide a public no-arg constructor.
  • Implement initialize(OptimizerEnv) and close() lifecycle correctly.

Register with ServiceLoader​

Provider implementation​

Create the file and add one implementation class name per line.

META-INF/services/org.apache.gravitino.maintenance.optimizer.api.common.Provider
com.example.optimizer.MyStatisticsProvider
com.example.optimizer.MyJobSubmitter

StatisticsCalculator implementation​

Create file:

META-INF/services/org.apache.gravitino.maintenance.optimizer.api.updater.StatisticsCalculator

MetricsEvaluator implementation​

Create file:

META-INF/services/org.apache.gravitino.maintenance.optimizer.api.monitor.MetricsEvaluator

Configure gravitino-optimizer.conf​

gravitino-optimizer.conf
gravitino.optimizer.recommender.statisticsProvider = my-statistics-provider
gravitino.optimizer.recommender.jobSubmitter = my-job-submitter

gravitino.optimizer.strategyHandler.my-strategy.className = com.example.optimizer.MyStrategyHandler
gravitino.optimizer.jobAdapter.my-job-template.className = com.example.optimizer.MyJobAdapter

gravitino.optimizer.monitor.metricsEvaluator = my-metrics-evaluator

Notes:

  • strategyHandler.{strategy_type}.className must match strategy.type in policy content.
  • jobAdapter.{job_template}.className must match the target job template name.
  • jobSubmitterConfig.* entries are passed to job submitters as shared runtime options.

Package and deploy​

  • Build a JAR containing your classes and META-INF/services files.
  • Put the JAR on the runtime classpath, for example ${GRAVITINO_HOME}/optimizer/libs/.
  • Restart the process before testing.

If you also extend Gravitino server job execution, see Automation.

Validation checklist​

  1. --help shows no load-time SPI errors.
  2. Commands using your extension run without No ... found for provider name errors.
  3. Strategy flow can resolve both handler and job adapter mappings.
  4. Dry-run (submit-strategy-jobs --dry-run) prints expected recommendations.
Last updated on