Dual Resolver
This tutorial presents the use of the DualResolver, a feature introduced in the version 0.6 of Ivy.
Dual Resolver is used when ivy files can be found in a repository while artifacts are in another. It is especially useful to use full power of ivy (including transitive dependencies) with the ibiblio repository for artifacts. The problem with the maven ibiblio repository is that it does not contain ivy files. Since transitive dependencies are based upon ivy files, using the ibiblio resolver does not permit to use transitive dependencies.
The solution to this problem is to store your own repository only for ivy files, and use ibiblio for artifacts. That's what is done in this tutorial.
project description
Let's have a look at the src/example/dual directory in your ivy distribution.
It contains a build file and 3 directories:
- config: contains the ivy configuration file
- repository: a sample repository of ivy files
- project: the project making use of ivy with dual resolver
the dual project
The project is very simple and contains only one test class : example.Hello
It depends on two libraries: apache commons-lang and apache commons-httpclient.
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
Take a look at it's ivy.xml file:
<ivy-module version="1.0">
<info organisation="jayasoft" module="hello-ivy" />
<dependencies>
<dependency org="apache" name="commons-httpclient" rev="2.0.2" />
<dependency org="apache" name="commons-lang" rev="2.0" />
</dependencies>
</ivy-module>As you can see, nothing special here... Indeed, it's the philosophy of ivy to keep ivy files independent of the way dependencies are retrieved.
the ivy configuration
The ivy configuration is made in the config directory it contains only one file: ivyconf.xml.
Let's analyse it.
<ivyconf>
<conf defaultResolver="dual-example" />
<resolvers>
<dual name="dual-example">
<filesystem name="ivys">
<ivy pattern="${ivy.conf.dir}/../repository/[module]-ivy-[revision].xml" />
</filesystem>
<ibiblio name="ibiblio" />
</dual>
</resolvers>
</ivyconf>Here we configure one resolver, the default one, which is a dual resolver. This dual resolver has two sub resolvers : the first is what is called the "ivy" resolver of the dual resolver, and the second one is what is called the "artifact" resolver. It is important that the dual resolver exactly has two sub resolvers in this given order.
The ivy resolver, here a filesystem one, is used only to find ivy files. The configuration given in this resolver
says that all ivy files are in the same directory, named like that: [module]-ivy-[revision].xml. If we check the repository directory, we can confirm that it contains a file named commons-httpclient-ivy-2.0.2.xml. It fulfills the given pattern and will thus be find by this resolver.
The artifact resolver is simply an ibiblio one, and will thus try to find required artifacts in the maven ibiblio repository.
walkthrough
step 1 : preparation
Open a DOS or shell window, and go to the "dual" directory.
step 2 : clean up
On the prompt type : ant
This will clean up the entire project directory tree (compiled classes and retrieved libs) and ivy cache.
You can do it each time you want to clean up this example.
step 3 : run the project
Goto project directory. And simply run ant.
I:\dual\project>ant Buildfile: build.xml configure: :: Ivy 1.0-rc3 - 20050421161206 :: http://ivy.jayasoft.org/ :: resolve: :: resolving dependencies :: jayasoft/hello-ivy-working@xmen confs: [default] downloading http://www.ibiblio.org/maven/commons-lang/jars/commons-lang-2.0.jar(2.0) ... ..... ......... .......... ........... . (165kB) [SUCCESSFUL ] apache/commons-lang-2.0/commons-lang.jar[jar] (8032ms) downloading http://www.ibiblio.org/maven/commons-httpclient/jars/commons-httpclient-2.0.2.jar(2.0.2) ... ........... ...... .... .......... ............ ........ (220kB) [SUCCESSFUL ] apache/commons-httpclient-2.0.2/commons-httpclient.jar[jar] (10031ms) downloading http://www.ibiblio.org/maven/commons-logging/jars/commons-logging-1.0.4.jar(1.0.4) ... ......... (37kB) [SUCCESSFUL ] apache/commons-logging-1.0.4/commons-logging.jar[jar] (1469ms) :: resolution report :: --------------------------------------------------------------------- | | modules || artifacts | | conf | number| search|dwnlded|evicted|| number|dwnlded| --------------------------------------------------------------------- | default | 3 | 3 | 1 | 0 || 3 | 3 | --------------------------------------------------------------------- :: retrieving :: jayasoft/hello-ivy confs: [default] 3 artifacts copied, 0 already retrieved run: [mkdir] Created dir: I:\dual\project\build [javac] Compiling 1 source file to I:\dual\project\build [java] standard message : hello ivy ! [java] capitalized by org.apache.commons.lang.WordUtils : Hello Ivy ! [java] head status code with httpclient: 200 [java] now check if httpclient dependency on commons-logging has been realized [java] found logging class in classpath: interface org.apache.commons.logging.Log BUILD SUCCESSFUL Total time: 24 seconds
As you can see, ivy not only downloaded commons-lang and commons-httpclient, but also commons-logging. Indeed, commons-logging is a dependency of httpclient, as we can see in the httpclient ivy file found in the repository directory:
<ivy-module version="1.0">
<info organisation="apache" module="commons-httpclient" revision="2.0.2" status="release" publication="20041010174300" />
<dependencies>
<dependency name="commons-logging" rev="1.0.4" conf="default" />
</dependencies>
</ivy-module>
So everything worked well, ivy file has been found in the repository directory and artifacts have been downloaded from ibiblio. You now just have to write ivy files for the module you often use, and they will be much easier to use... And imagine a world in which each module delivers also an ivy file. Since it is independent of the way to retrieve dependencies, it would made all dependencies handling much easier, wouldn't it ?