Zero-dependency Java API for coursier

coursier-interface is a zero-dependency Java library, exposing some of the features of the API of coursier. coursier-interface shades coursier, along with all its dependencies, so that it doesn't have any public dependency, and can be safely used along with other Scala or coursier versions.

coursier-interface aims at maintaining backward binary compatibility as much as possible. This means that if you depend on version N of coursier-interface, any version M >= N is safe to use at runtime. Backward binary compatibility has not been broken since the very first release of coursier-interface, 0.0.1 (ignoring version 0.0.11, which exposed some dependencies that should have been shaded).

coursier-interface doesn't support as many features as the API of coursier itself. For now, it has equivalents for:

• coursier.Fetch: coursierapi.Fetch,
• coursier.Versions: coursierapi.Versions.

Note that all parameters of the inputs and results of these coursier APIs don't necessarily have equivalents in coursier-interface yet.

Beware that unlike their coursier counterparts, which are immutable, some coursier-interface classes may rely on mutation.

Missing features are added when they are needed. PRs adding missing features are welcome, as long as backward binary compatibility is not broken. See development for more details about how to proceed.

IMPORTANT: The use-forked-coursier branch contains custom modifications to support URLStreamHandlerFactory via the withCustomHandlerFactory method in the Cache class. This is required for kompile-cli and other projects that need custom URL handling.

To build and publish version 2.1.30-SNAPSHOT with the custom modifications:

# Switch to the custom branch
git checkout use-forked-coursier

# Ensure version.sbt is set correctly
echo 'ThisBuild / version := "2.1.30-SNAPSHOT"' > version.sbt

# Build with Java 21 (Proguard doesn't support Java 24+)
export JAVA_HOME=/path/to/java21
sbt "project interface" +publishLocal

# Publish to Maven repository
scp -P 23 -i ~/.ssh/id_rsa ~/.ivy2/local/io.get-coursier/interface/2.1.30-SNAPSHOT/* \
    [email protected]:/root/maven/io/get-coursier/interface/2.1.30-SNAPSHOT/

• Adds withCustomHandlerFactory(URLStreamHandlerFactory) method to coursierapi.Cache
• Adds getCustomHandlerFactory() accessor
• Updates coursier.internal.api.ApiHelper to handle the custom factory
• Uses coursier 2.1.30 (changed from 2.1.30-test)

The main coursier-interface project doesn't support custom URLStreamHandlerFactory instances. This fork adds that capability for projects that need to customize URL handling (e.g., for custom protocol handlers or JAR URL caching).

This project is built with sbt. If sbt is not installed on your machine, you can easily get a launcher by using sbt-extras. Alternatively, if a recent version of the coursier CLI is installed on your machine, you can either do cs install sbt, or start sbt straightaway from the root of the coursier-interface sources with cs launch sbt.

Most of the public APIs live under interface/src/main/java/coursierapi. New classes can be added there, and new constructors, fields, and methods, can be added to existing classes, as long as this doesn't break backward binary compatibility.

When these public classes need to call methods from coursier itself, they usually do so via coursier.internal.api.ApiHelper. ApiHelper contains:

• methods converting coursier-interface public classes to their equivalent in the coursier API, and
• methods accepting classes of the public API, calling the coursier API itself (to perform some action, like fetching artifacts), and converting their results back to the public API classes.

Overall, the logic in the classes of the public API itself is kept at a minimum: setters / accessors, and calls to coursier.internal.api.ApiHelper.

The coursier project welcomes contributions from anybody wishing to participate. All code or documentation that is provided must be licensed with the same license that coursier is licensed with (Apache 2.0, see LICENSE).

People are expected to follow the Scala Code of Conduct when discussing coursier on GitHub, Gitter channel, or other venues.

Feel free to open an issue if you notice a bug, have an idea for a feature, or have a question about the code. Pull requests are also gladly accepted.