Package com.kamikazejam.kamicommon.yaml.source

Interface ConfigSource

All Known Implementing Classes:
FileConfigSource, StringConfigSource
public interface ConfigSource
Represents a source of configuration data that can provide an InputStream for reading
and may optionally support writing/persistence.

Typical implementations:
- File-backed source (writable)
- Provider/remote/in-memory source (read-only)

Contract notes:
- Each call to openStream() should return a fresh stream positioned at the start.
- If isWritable() is false, write(byte[], Charset) must throw UnsupportedOperationException.
- ensureExistsIfWritable() should create any required backing structures for writable sources.
- asFileIfPresent() returns a File only for file-backed sources; otherwise null.

  • Method Summary

    Modifier and Type
    Method
    Description
    default @Nullable File
    asFileIfPresent()
    Returns the underlying File if this source is file-backed; otherwise null.
    Useful for compatibility with APIs that require a File.
    default boolean
    ensureExistsIfWritable()
    Ensures the writable source has any required backing structures (e.g., parent directories/files).
    No-op for read-only sources.
    @Nullable String
    getResourceStreamPath()
    Returns the path to a resource stream for default configuration data, if available.
    This is typically used to load default settings bundled with the application/plugin.

    If no resource stream is associated, may return null.
    @NotNull String
    id()
    A human-readable identifier for this source (e.g., absolute file path, URL, logical name).
    Uniqueness is not required and the value is intended primarily for logging/debugging.
    default boolean
    isWritable()
    Indicates whether this source supports persisting data via write(...).
    @NotNull Optional<InputStream>
    openStream()
    Opens a fresh InputStream for the current contents of this source.
    The caller is responsible for closing the returned stream.
    default boolean
    write(byte[] data, @NotNull Charset charset)
    Writes serialized data to this source using the provided charset.
    Implementations should overwrite the existing contents atomically when possible.

    For read-only sources, this method must throw UnsupportedOperationException.

  • Method Details

    • id

      @NotNull @NotNull String id()
      A human-readable identifier for this source (e.g., absolute file path, URL, logical name).
      Uniqueness is not required and the value is intended primarily for logging/debugging.
      Returns:
      identifier string for this source (not necessarily unique)

    • openStream

      @NotNull @NotNull Optional<InputStream> openStream() throws IOException
      Opens a fresh InputStream for the current contents of this source.
      The caller is responsible for closing the returned stream.
      Returns:
      an Optional containing a new InputStream if content is available; empty if absent
      Throws:
      IOException - if the stream cannot be opened due to I/O errors

    • isWritable

      default boolean isWritable()
      Indicates whether this source supports persisting data via write(...).
      Returns:
      true if writable; false if read-only

    • ensureExistsIfWritable

      default boolean ensureExistsIfWritable() throws IOException
      Ensures the writable source has any required backing structures (e.g., parent directories/files).
      No-op for read-only sources.
      Returns:
      true if the source exists or was created successfully; false otherwise
      Throws:
      IOException - if creation fails due to I/O errors

    • write

      default boolean write(byte[] data, @NotNull @NotNull Charset charset) throws IOException
      Writes serialized data to this source using the provided charset.
      Implementations should overwrite the existing contents atomically when possible.

      For read-only sources, this method must throw UnsupportedOperationException.
      Parameters:
      data - bytes to persist
      charset - character set used to interpret textual data (if relevant)
      Returns:
      true if the data was persisted successfully; false otherwise
      Throws:
      IOException - if an I/O error occurs while writing
      UnsupportedOperationException - if the source is not writable

    • asFileIfPresent

      @Nullable default @Nullable File asFileIfPresent()
      Returns the underlying File if this source is file-backed; otherwise null.
      Useful for compatibility with APIs that require a File.
      Returns:
      File when applicable; null for non-file-backed sources

    • getResourceStreamPath

      @Nullable @Nullable String getResourceStreamPath()
      Returns the path to a resource stream for default configuration data, if available.
      This is typically used to load default settings bundled with the application/plugin.

      If no resource stream is associated, may return null.