- Documentation (2.0.0)
- Release Notes
- Tutorials
- Reference
- Developer doc
Dual Resolver
In some cases it may happen that your module descriptors (Ivy files, maven pom, ...) are located at one place and module artifacts (jars, ...) at another place.
Dual Resolver is used to address this kind of need, and this tutorial will show how to use it.
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:
- settings: contains the ivy settings 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 simple class: example.HelloIt 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
<ivy-module version="1.0">As you can see, nothing special here... Indeed, it's the philosophy of ivy to keep ivy files independent of the way dependencies are resolved.
<info organisation="org.apache" module="hello-ivy"/>
<dependencies>
<dependency org="commons-httpclient" name="commons-httpclient" rev="2.0.2"/>
<dependency org="commons-lang" name="commons-lang" rev="2.0"/>
</dependencies>
</ivy-module>
the ivy settings
The ivy settings is made in the settings directory; it contains only one file: ivysettings.xml.<ivysettings>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" or "metadata" 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.
<settings defaultResolver="dual-example"/>
<resolvers>
<dual name="dual-example">
<filesystem name="ivys">
<ivy pattern="${ivy.settings.dir}/../repository/[module]-ivy-[revision].xml" />
</filesystem>
<ibiblio name="ibiblio" m2compatible="true" usepoms="false" />
</dual>
</resolvers>
</ivysettings>
The metadata resolver, here a filesystem one, is used only to find module descriptors, in this case Ivy files. The settings 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 found by this resolver.
The artifact resolver is simply an ibiblio one, configured in m2compatible mode to use the maven 2 repository, with usepoms="false" to make sure it won't use maven 2 metadata. Note that this isn't strictly necessary, since the second resolver in a dual resolver (the artifact resolver) is never asked to find module metadata.
walkthrough
step 1 : preparation
Open a DOS or shell window, and go to the "dual" directory.step 2 : clean up
On the prompt type : antThis 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: src\example\dual\project\build.xml resolve: [ivy:retrieve] :: Ivy 2.0.0-beta1-local-20071104204849 - 20071104204849 :: http://ant.apache.org/ivy/ :: [ivy:retrieve] :: loading settings :: file = C:\dev\data\opensource_workspace\ivy\src\example\dual\config\ivysettings.xml [ivy:retrieve] :: resolving dependencies :: [ org.apache | hello-ivy | working@BEN-ScokartG ] [ivy:retrieve] confs: [default] [ivy:retrieve] found [ commons-httpclient | commons-httpclient | 2.0.2 ] in ivys [ivy:retrieve] found [ commons-httpclient | commons-logging | 1.0.4 ] in ibiblio [ivy:retrieve] found [ commons-lang | commons-lang | 2.0 ] in ibiblio [ivy:retrieve] downloading http://www.ibiblio.org/maven/commons-httpclient/jars/commons-httpclient-2.0.2.jar ... [ivy:retrieve] ........................................... [ivy:retrieve] ................................................................................................. [ivy:retrieve] ................ (220kB) [ivy:retrieve] .. (0kB) [ivy:retrieve] [SUCCESSFUL ] [ commons-httpclient | commons-httpclient | 2.0.2 ]/commons-httpclient.jar[jar] (11676ms) [ivy:retrieve] downloading http://www.ibiblio.org/maven/commons-lang/jars/commons-lang-2.0.jar ... [ivy:retrieve] ....................................................................... [ivy:retrieve] .............................................. (165kB) [ivy:retrieve] .. (0kB) [ivy:retrieve] [SUCCESSFUL ] [ commons-lang | commons-lang | 2.0 ]/commons-lang.jar[jar] (7651ms) [ivy:retrieve] downloading http://www.ibiblio.org/maven/commons-logging/jars/commons-logging-1.0.4.jar ... [ivy:retrieve] ........................... (37kB) [ivy:retrieve] .. (0kB) [ivy:retrieve] [SUCCESSFUL ] [ commons-httpclient | commons-logging | 1.0.4 ]/commons-logging.jar[jar] (9724ms) [ivy:retrieve] :: resolution report :: --------------------------------------------------------------------- | | modules || artifacts | | conf | number| search|dwnlded|evicted|| number|dwnlded| --------------------------------------------------------------------- | default | 3 | 3 | 0 | 0 || 3 | 3 | --------------------------------------------------------------------- [ivy:retrieve] :: retrieving :: [ org.apache | hello-ivy ] [ivy:retrieve] confs: [default] [ivy:retrieve] 3 artifacts copied, 0 already retrieved run: [mkdir] Created dir: C:\dev\data\opensource_workspace\ivy\src\example\dual\project\build [javac] Compiling 1 source file to C:\dev\data\opensource_workspace\ivy\src\example\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: 37 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="commons-httpclient"
module="commons-httpclient"
revision="2.0.2"
status="release"
publication="20041010174300"/>
<dependencies>
<dependency org="commons-logging" 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.
This kind of setup can be useful if you don't want to rely on maven 2 repository for metadata, or if you want to take full advantage of Ivy files for some or all modules. Combining chain and dual resolvers can lead to very flexible settings addressing most needs.
For full details about the dual resolver, have a look at the corresponding reference documentation.