Multiple Resolvers


This tutorial is an example of how modules can be retrieved by multiple resolvers. Using multiple resolvers can be useful in many contexts. For example:
  • separating integration builds from releases
  • using a public repository for third party modules and a private one for internal modules
  • use a repository for storing modules which are not accurate in an unmanaged public repository
  • use a local repository to expose builds made on one developer's station
In Ivy, the use of multiple resolvers is supported by a compound resolver called the chain resolver.

In our example, we will simply show you how to use two resolvers, one on a local repository and one using the maven2 repository.

project description

the project: chained-resolvers

The project is very simple and contains only one simple class: example.Hello.

It depends on two libraries: Apache's commons-lang and a custom library named test (sources are included in test-1.0jar file). The test library is used by the project to uppercase a string, and commons-lang is used to capitalize the same string.

Here is the content of the project:
  • build.xml: the ant build file for the project
  • ivy.xml: the Ivy project file
  • src\example\Hello.java: the only class of the project
Let's have a look at the ivy.xml file: 
<ivy-module version="1.0">
    <info organisation="org.apache" module="chained-resolvers"/>
    <dependencies>
        <dependency org="commons-lang" name="commons-lang" rev="2.0"/>
        <dependency name="test" rev="1.0"/>
    </dependencies>
</ivy-module>
As we'd expect, the ivy file declares this module to be dependent on the two libraries it uses: 'commons-lang' and 'test'. Note that we didn't specify the org for the dependency 'test'. When we exclude org, Ivy assumes it is in the same org as the declaring module. (i.e. 'org.apache').

the ivy settings

The settings are defined in the ivysettings.xml file located in the settings directory of the project. Below are its contents, followed by an explanation of what it's doing.
<ivysettings>
  <settings defaultResolver="chain-example"/>
  <resolvers>
    <chain name="chain-example">
      <filesystem name="libraries">
        <artifact pattern="${ivy.settings.dir}/repository/[artifact]-[revision].[ext]" />
      </filesystem>
      <ibiblio name="ibiblio" m2compatible="true" />
    </chain>
  </resolvers>
</ivysettings>

the settings tag

This tag initializes Ivy with some parameters. Here only one parameter is set, the name of the resolver to use by default.

the resolvers tag

The resolvers section defines the list of resolvers that Ivy will use to locate artifacts. In our example, we have only one resolver named "chain-example", which is unique in that it defines a list (hence a chain) of resolvers.
The resolvers in this chain are:
  • libraries : It is a filesystem resolver, so looks at a directory structure to retrieve the artifacts. This one is configured to look in the repository sub directory of the directory that contains the ivysettings.xml file.
  • ibiblio : It looks in the ibiblio maven repository to retrieve the artifacts.
That's it, we have just configured a chain of resolvers!

walkthrough

step 1: preparation

Open a DOS or shell window, and go to the "chained-resolvers" directory.

step 2: clean directory tree

On the prompt type: ant
This will clean up the entire project directory tree and Ivy cache. You can do this each time you want to clean up this example.
In almost all examples, we provide a clean target as default target. Since most examples use the same Ivy cache, you will clean the whole Ivy cache each time you call this target.

Cleaning the Ivy cache is something you can do without fear (except performance): it's only a cache, so everything can be (and should be) obtained again from repositories. This may sound strange to those coming from maven 2 land. But remember that in Ivy, the cache is not a local repository and the two are completely isolated.

step 3: run the project

Go to chained-resolvers project directory. And simply run ant.
[ivy@apache:/ivy/chained-resolvers/chainedresolvers-project]$ ant 
Buildfile: /ivy/chained-resolvers/chainedresolvers-project/build.xml

resolve:
[ivy:retrieve] :: Apache Ivy 2.3.0 - 20130110142753 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] :: loading settings :: file = /ivy/chained-resolvers/settings/ivysettings.xml
[ivy:retrieve] :: resolving dependencies :: org.apache#chained-resolvers;working@apache
[ivy:retrieve] 	confs: [default]
[ivy:retrieve] 	found commons-lang#commons-lang;2.0 in ibiblio
[ivy:retrieve] 	found org.apache#test;1.0 in libraries
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-lang/commons-lang/2.0/commons-lang-2.0.jar ...
[ivy:retrieve] ...................... (165kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] 	[SUCCESSFUL ] commons-lang#commons-lang;2.0!commons-lang.jar (484ms)
[ivy:retrieve] downloading /ivy/chained-resolvers/settings/repository/test-1.0.jar ...
[ivy:retrieve] .. (1kB)
[ivy:retrieve] 	[SUCCESSFUL ] org.apache#test;1.0!test.jar (15ms)
[ivy:retrieve] :: resolution report :: resolve 749ms :: artifacts dl 499ms
	---------------------------------------------------------------------
	|                  |            modules            ||   artifacts   |
	|       conf       | number| search|dwnlded|evicted|| number|dwnlded|
	---------------------------------------------------------------------
	|      default     |   2   |   2   |   1   |   0   ||   2   |   2   |
	---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: org.apache#chained-resolvers
[ivy:retrieve] 	confs: [default]
[ivy:retrieve] 	2 artifacts copied, 0 already retrieved (166kB/32ms)

run:
    [mkdir] Created dir: /ivy/chained-resolvers/chainedresolvers-project/build
    [javac] /ivy/chained-resolvers/chainedresolvers-project/build.xml:58: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
    [javac] Compiling 1 source file to /ivy/chained-resolvers/chainedresolvers-project/build
     [java] standard message :example world !
     [java] capitalized by org.apache.commons.lang.WordUtils : Example World !
     [java] upperCased by test.StringUtils : EXAMPLE WORLD !

BUILD SUCCESSFUL
Total time: 3 seconds
We can see in the log of the resolve task, that the two dependencies have been retrieved (2 artifacts) and copied to the Ivy cache directory (2 downloaded).

Also notice that the 'run' Ant target succeeded in using both commons-lang.jar coming from the ibiblio repository and test.jar coming from the local repository.

Going further

This very simple example helps us see how to set up two resolvers in a chain. The chain resolver's reference documentation is available for those who would like to know all the features offered by this resolver.

Below are a few more interesting things worth knowing about chain resolvers. After reading them, go ahead and try tweaking this example using your new wealth of knowledge!
  • a chain is not limited to two nested resolvers, you can use as many as you want
  • by setting returnFirst="true", you can have a chain which stops as soon as it has found a result for a given module
  • by setting dual="true", the full chain will be used both for module descriptors and artifacts, while setting dual="false", the resolver in the chain which found the module descriptor (if any) is also used for artifacts