Package dev.turboism.sdk.config

Interface PluginConfigRegistry

public interface PluginConfigRegistry
Plugin-scoped access to legacy string settings and Preview typed configuration.

Obtain this service from PluginContext.config(); do not construct paths beneath turboism.home. The runtime confines data to the plugin configuration scope, validates schemas, runs declared migrations, and schedules persistence. Typed methods can be absent in compatibility contexts and then throw UnsupportedOperationException.

  • Method Details

    • readScope

      Registration readScope(String relativePath)
      Declares a legacy string-read scope.
      Parameters:
      relativePath - plugin-relative configuration path
      Returns:
      reversible scope registration; close it when the declaration is no longer needed

    • writeScope

      Registration writeScope(String relativePath)
      Declares a legacy string-write scope.
      Parameters:
      relativePath - plugin-relative configuration path
      Returns:
      reversible scope registration; close it when the declaration is no longer needed

    • readString

      Optional<String> readString(String relativePath, String key)
      Reads a legacy string value from a declared read scope.
      Parameters:
      relativePath - plugin-relative configuration path
      key - logical string key
      Returns:
      stored value, or empty when absent or inaccessible according to the legacy contract

    • writeString

      void writeString(String relativePath, String key, String value) throws PluginConfigException
      Writes a legacy string value to a declared write scope.
      Parameters:
      relativePath - plugin-relative configuration path
      key - logical string key
      value - value to persist
      Throws:
      PluginConfigException - if the legacy write cannot complete

    • registerSchema

      default CompletionStage<Void> registerSchema(ConfigSchema schema, List<ConfigMigration> migrations)
      Validates and asynchronously registers a typed schema and its migration route.

      Schema defects throw ConfigSchemaValidationException synchronously. Operational denial, unavailability, or publication failure completes the returned stage exceptionally with ConfigRegistrationException.

      Parameters:
      schema - non-null plugin-owned schema
      migrations - non-null migration declarations leading to schema.version()
      Returns:
      completion stage for accepted registration
      Throws:
      ConfigSchemaValidationException - if the schema or migration graph is invalid
      UnsupportedOperationException - if typed configuration is not available in this context

    • read

      default <T> CompletionStage<ConfigReadResult<T>> read(ConfigKey<T> key)
      Asynchronously reads a registered typed key.

      The result always includes an effective default when storage, migration, permissions, or runtime availability prevent a stored read; inspect source and error before treating it as persisted state.

      Type Parameters:
      T - key value type
      Parameters:
      key - non-null key from an accepted schema
      Returns:
      completion stage with the effective value and provenance
      Throws:
      UnsupportedOperationException - if typed configuration is not available in this context

    • write

      default <T> CompletionStage<ConfigWriteResult> write(ConfigKey<T> key, T value, long expectedRevision)
      Asynchronously writes a registered typed key using optimistic revision control.

      Pass the revision observed from ConfigValue.revision(). The returned result distinguishes invalid values, conflicts, permission denial, persistence failure, and runtime unavailability without exposing backing paths.

      Type Parameters:
      T - key value type
      Parameters:
      key - non-null key from an accepted schema
      value - candidate value accepted by the key's codec
      expectedRevision - non-negative revision observed by the caller
      Returns:
      completion stage with write success or typed failure
      Throws:
      IllegalArgumentException - if expectedRevision is negative
      UnsupportedOperationException - if typed configuration is not available in this context