Package org.apache.maven.api.services

Interface Source

All Known Subinterfaces:
ModelSource
@Experimental public interface Source
Provides access to the contents of a source independently of the backing store (e.g. file system, database, memory).

This is mainly used to parse files into objects such as Maven projects, models, settings, or toolchains. The source implementation handles all the details of accessing the underlying content while providing a uniform API to consumers.

Sources can represent:

  • Local filesystem files
  • In-memory content
  • Database entries
  • Network resources
Since:
4.0.0
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    getLocation()
    Returns a human-readable description of where this source came from, used primarily for error messages and debugging.
    Path
    getPath()
    Provides access to the file backing this source, if available.
    InputStream
    openStream()
    Creates a new input stream to read the source contents.
    Source
    resolve(String relative)
    Resolves a new source relative to this one.

  • Method Details

    • getPath

      @Nullable Path getPath()
      Provides access to the file backing this source, if available. Not all sources are backed by files - for example, in-memory sources or database-backed sources will return null.
      Returns:
      the underlying Path if this source is file-backed, or null if this source has no associated file

    • openStream

      @Nonnull InputStream openStream() throws IOException
      Creates a new input stream to read the source contents. Each call creates a fresh stream starting from the beginning. The caller is responsible for closing the returned stream.
      Returns:
      a new input stream positioned at the start of the content
      Throws:
      IOException - if the stream cannot be created or opened

    • getLocation

      @Nonnull String getLocation()
      Returns a human-readable description of where this source came from, used primarily for error messages and debugging.

      Examples of locations:

      • Absolute file path: /path/to/pom.xml
      • Relative file path: ../parent/pom.xml
      • URL: https://repo.maven.org/.../pom.xml
      • Description: <memory> or <database>
      Returns:
      a non-null string describing the source location

    • resolve

      @Nullable Source resolve(@Nonnull String relative)
      Resolves a new source relative to this one.

      The resolution strategy depends on the source type:

      • File sources resolve against their parent directory
      • URL sources resolve against their base URL
      • Other sources may not support resolution and return null

      The implementation must handle:

      • Both forward and back slashes as path separators
      • Parent directory references (..)
      • Both file and directory targets
      Parameters:
      relative - path to resolve relative to this source
      Returns:
      the resolved source, or null if resolution not possible
      Throws:
      NullPointerException - if relative is null