Shrinkwrap Resolvers

Introduction to ShrinkWrap Resolvers

ShrinkWrap Resolvers is a Java API designed to simplify the process of obtaining artifacts from a repository system. It simplifies the retrieval of third-party libraries and dependent modules, allowing developers to easily incorporate them into their projects.

The project primarily focuses on supporting Maven-based repository structures, enabling developers to specify coordinates that uniquely identify an artifact in the repository. It also provides basic support for Gradle-based projects.

Requirements

Build:

JDK: Version 8 or newer.
Maven: Version 3.6.3 or newer.

Use:

JDK: Version 8 or newer.
Maven: Version 3.3.9 or newer.
Gradle: Version 3 or newer.

Maven 4 Notes:

You must create or add the following to your ~/.m2/maven-user.properties in order to run tests properly, and enable running tests from within your project's submodules: maven.consumer.pom.flatten=true or add -Dmaven.consumer.pom.flatten=true to your Maven verify command line.

Adding ShrinkWrap Resolvers to Your Project

To include ShrinkWrap Resolvers in your project, you can add a dependency on the shrinkwrap-resolver-depchain module in your Maven pom.xml:

<dependencies>
    <dependency>
      <groupId>org.jboss.shrinkwrap.resolver</groupId>
      <artifactId>shrinkwrap-resolver-depchain</artifactId>
      <version>${version.shrinkwrap.resolvers}</version>
      <scope>test</scope>
      <type>pom</type>
    </dependency>
</dependencies>

If you are using Arquillian BOM prior to version 1.1.0.Final, ensure that you import ShrinkWrap Resolvers BOM preceding Arquillian BOM to get version 2.0.x.

Resolving Dependencies

To initiate the resolution of dependencies, utilize the org.jboss.shrinkwrap.resolver.api.maven.Maven class. Below are typical scenarios for its usage.

Resolution of Artifacts by Maven Coordinates

Maven coordinates follow groupId:artifactId:[packagingType:[classifier]]:version format. You can use these coordinates to resolve a file, where G is the group ID, A is the artifact ID, P is the packaging type, C is the classifier, and V is the version.

Resolve a file using Maven coordinates with transitive dependencies:

File[] files = Maven.resolver().resolve("G:A:V").withTransitivity().asFile();

Resolve a single file without transitive dependencies:

File file = Maven.resolver().resolve("G:A:V").withoutTransitivity().asSingleFile();

Resolve multiple artifacts:

File[] files = Maven.resolver().resolve("G1:A1:V1", "G2:A2:V2").withTransitivity().asFile();

Specifying Packaging and Classifier

File file = Maven.resolver().resolve("G:A:war:V").withTransitivity().asFile();
File fileWithClassifier = Maven.resolver().resolve("G:A:test-jar:tests:V").withTransitivity().asFile();

Returning Resolved Artifacts

ShrinkWrap Resolvers provides various options to retrieve resolved artifacts. You can obtain them as files, streams, URLs, or specific archive types like JavaArchive, WebArchive, or EnterpriseArchive. For example:

// Get the resolved artifact as a URL
URL[] urls = Maven.resolver().resolve("G:A:V").withTransitivity().as(URL.class);
// Get the resolved artifact as a JAR
JavaArchive[] jars = Maven.resolver().resolve("G:A:V").withTransitivity().as(JavaArchive.class);
// Get the resolved artifact as a WAR
WebArchive war = Maven.resolver().resolve("G:A:war:V").withTransitivity().asSingle(WebArchive.class);

Working with Artifact Metadata

MavenResolvedArtifact artifact = Maven.resolver().resolve("G:A:war:V").withoutTransitivity()
  .asSingle(MavenResolvedArtifact.class);
MavenCoordinate coordinates = artifact.getCoordinate();
MavenArtifactInfo[] dependencies = artifact.getDependencies();
String version = artifact.getResolvedVersion();
ScopeType scope = artifact.getScope();
// You can still retrieve resolved artifact from MavenResolvedArtifact
File file = artifact.asFile();

Working with artifact coordinates

MavenCoordinate[] coordinates = Maven.resolver().resolve("G:A:V")
   .withTransitivity().as(MavenCoordinate.class);

Resolution of artifacts as collection

List<File> files = Maven.resolver().resolve("G:A:V")
    .withTransitivity().asList(File.class);

Exclude specific dependencies while resolving an artifact

File file = Maven.resolver().addDependencies(
    MavenDependencies.createDependency("G:A:V", ScopeType.COMPILE, false,
      MavenDependencies.createExclusion("G:B"))).resolve().withTransitivity().asFile();

Control Resolution Results with Strategy

File file = Maven.resolver().resolve("G:A:V").using(new RejectDependenciesStrategy(false, "G:B")).asFile();

ShrinkWrap Resolver Strategies

In ShrinkWrap Resolver, strategies allow you to modify the dependency graph and change the default behavior for resolving transitive dependencies.

By default, Maven and ShrinkWrap Resolver do not resolve dependencies in provided and test scope, and skip optional dependencies.

Available Strategies:

AcceptAllStrategy (same as TransitiveStrategy): Accepts all dependencies of artifacts.
AcceptScopesStrategy: Accepts only dependencies with defined scope types.
CombinedStrategy: Combines multiple strategies with a logical AND operation.
NonTransitiveStrategy: Rejects all transitive dependencies; only directly specified dependencies are accepted.
RejectDependenciesStrategy: Rejects dependencies defined by G:A. By default, it is transitive, meaning all dependencies originating at G:A are removed. To change this behavior to reject defined dependencies but keep their descendants, use RejectDependenciesStrategy(false, "G:A").
TransitiveStrategy (same as AcceptAllStrategy): Accepts all dependencies of artifacts.

Control Sources of Resolution

ShrinkWrap Resolvers allows you to specify artifact resolution sources. By default, it uses the classpath (Maven Reactor) and Maven Central repository.

// Disable classpath resolution
Maven.configureResolver().withClassPathResolution(false).resolve("G:A:V").withTransitivity().asFile();
// Disable using Maven Central repository
Maven.configureResolver().withMavenCentralRepo(false).resolve("G:A:V").withTransitivity().asFile();
// Enable offline mode to use only local cache, avoiding remote repositories
Maven.configureResolver().workOffline().resolve("G:A:V").withTransitivity().asFile();
// Ignore the origin of artifacts present in the local repository
Maven.configureResolver().useLegacyLocalRepo(true).resolve("G:A:V").withTransitivity().asFile();

Specify settings.xml

Maven.configureResolver().fromFile("/path/to/settings.xml")
  .resolve("G:A:V").withTransitivity().asFile();

Maven.configureResolver().fromClassloaderResource("path/to/settings.xml")
  .resolve("G:A:V").withTransitivity().asFile();

<sub>Warning: ShrinkWrap Resolvers doesn't consume settings.xml specified on the command line or in the IDE. It reads settings.xml files at standard locations: ~/.m2/settings.xml and $M2_HOME/conf/settings.xml, unless overridden in the API or via System property.</sub>

Define Maven repositories manually

Maven.configureResolver().withRemoteRepo("my-repository-id", "url://to/my/repository", "layout")
  .resolve("G:A:V").withTransitivity().asFile();

Maven.configureResolver().withRemoteRepo(MavenRemoteRepositories.createRemoteRepository("my-repository-id", "url://to/my/repository", "layout"))
  .resolve("G:A:V").withTransitivity().asFile();

<sub>Note: If a repository with the same ID is configured in either settings.xml or pom.xml, it will be ignored.</sub>

Resolution of Artifacts from POM Files

In Maven projects, dependencies are specified in the pom.xml file. ShrinkWrap Resolvers follow the DRY principle by loading this metadata automatically. It creates an effective POM model using your pom.xml, parent hierarchy, and Super POM, allowing you to resolve artifacts with the included metadata from local, classpath, and remote repositories.

Load dependencies from the POM:

Maven.resolver().loadPomFromFile("/path/to/pom.xml").resolve("G:A").withTransitivity().asFile();

Load dependencies with non-JAR packaging or classifier:

Maven.resolver().loadPomFromClassLoaderResource("/path/to/pom.xml").resolve("G:A:P:?").withTransitivity().asFile();

Import and resolve dependencies based on specific scopes:

Maven.resolver().loadPomFromFile("/path/to/pom.xml").importDependencies(ScopeType.TEST, ScopeType.PROVIDED).resolve().withTransitivity().asFile();
Maven.resolver().loadPomFromFile("/path/to/pom.xml").importRuntimeDependencies().resolve().withTransitivity().asFile();

Activate profiles:

By default, ShrinkWrap Resolvers activates profiles based on property value, file presence, active by default profiles, operating system and JDK.

Maven.resolver().loadPomFromFile("/path/to/pom.xml", "activate-profile-1", "!disable-profile-2").importRuntimeAndTestDependencies().resolve().withTransitivity().asFile();

Version Range Resolution

The ShrinkWrap Resolver API allows for resolution of available versions info from a requested range. The Maven documentation specifies the version range syntax.

final MavenVersionRangeResult versionRangeResult = Maven.resolver().resolveVersionRange("G:A:[1.0.0]");

System properties

ShrinkWrap Resolvers allows you to override any programmatic configuration via System properties.

org.apache.maven.user-settings: Path to user settings.xml file, which takes priority in merging over global settings if both are provided.
org.apache.maven.global-settings: Path to global settings.xml fil

Resolver

Install / Use

README