Project dependencies
This example is an illustration of dependency between two project.
The dependant project declares that it uses the standalone one. We will illustrate two things :
- public libraries declared by standalone project will automatically be recovered by the dependant project
- the dependant project will retrieve the "latest" version of the standalone project
the projects used
the project : standalone
The standalone project is very simple. It depends on the apache library commons-lang and contains only one class: standalone.Main which provides two services:
- return the version of the project
- capitalize a string using org.apache.commons.lang.WordUtils.capitalizeFully
Here is the content of the project:
- build.xml : the ant build file for the project
- ivy.xml : the ivy project file
- src\standalone\Main.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="standalone" />
<dependencies>
<dependency org="apache" name="commons-lang" rev="2.0" />
</dependencies>
</ivy-module>The ivy dependency file declares only one dependency on apache commons-lang library which by default is a public dependency (see ivy file definition).
the project : depending
The project depending is very simple too. It declares only one dependency on the latest version of the standalone project and it contains only one class depending.Main which make 2 things:
- getting the version of the standalone project throw a call to standalone.Main.getVersion()
- transform a string throw a call to standalone.Main.capitalizeWords(str)
Take a look at it's ivy.xml file:
<ivy-module version="1.0">
<info organisation="jayasoft" module="depending" />
<dependencies>
<dependency name="standalone" rev="latest.integration" />
</dependencies>
</ivy-module>the ivy configuration
The ivy configuration is made in the config directory wich contains 2 files :
- ivyconf.properties : a property file
- ivyconf.xml : the file containing the ivy configuration
Let's analyse the ivyconf.xml file.
<ivyconf>
<properties file="${ivy.conf.dir}/ivyconf.properties" />
<conf defaultCache="${ivy.conf.dir}/ivy-cache" defaultResolver="libraries" />
<resolvers>
<filesystem name="projects">
<artifact pattern="${repository.dir}/[artifact]-[revision].[ext]" />
<ivy pattern="${repository.dir}/[module]-[revision].xml" />
</filesystem>
<ivyrep name="libraries" />
</resolvers>
<modules>
<module organisation="jayasoft" name=".*" resolver="projects" />
</modules>
</ivyconf>The file contains four main tags : properties, conf, resolvers and modules.
the properties tag
This tag only load some properties for the ivy process in the same manner as ant will do it.
the conf tag
This tag is in charge to initialize some parameters for ivy process. The directory that ivy will use to cache (to store) artifacts found will be in a sub directory called ivy-cache of the directory containing the ivyconf.xml file itself.
The second parameter, tells ivy to use a resolver called "libraries" as its default resolver. As a recall, a resolver is in charge to resolve an artifact from some information like : the organisation that provides the artifact, the name of the library and the version of the library. More information can be found in the configuration documentation.
the resolvers tag
This tag defines the resolvers to use. Here we have two resolvers defined: "projects" and "libraries".
The filesystem resolver called "projects" is able to resolve the internal dependencies wanted.
The ivyrep resolver called "libraries" is able to find dependencies on ivyrep.
the modules tag
The modules tag allows to configure which resolver should be use for which module. Here the configuration only tells to use the "projects" resolver for all modules having for organisation "jayasoft" and any module name (.* regexp matches any module name).
For other modules (i.e. all modules not from jayasoft), since there is no special configuration, the default resolver will be used: "libraries".
walkthrough
step 1 : preparation
Open a DOS or shell window, and go to the "dependance" directory.
step 2 : clean directory tree
On the prompt type : ant
This will clean up the entire project directory tree. You can do it each time you want to clean up this example.
step 3 : publication of standalone project
Goto standalone directory and publish the project
I:\standalone>ant publish Buildfile: build.xml configure: :: Ivy 1.0-rc3 - 20050421161206 :: http://ivy.jayasoft.org/ :: resolve: :: resolving dependencies :: jayasoft/standalone-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] (6672ms) :: resolution report :: --------------------------------------------------------------------- | | modules || artifacts | | conf | number| search|dwnlded|evicted|| number|dwnlded| --------------------------------------------------------------------- | default | 1 | 1 | 0 | 0 || 1 | 1 | --------------------------------------------------------------------- :: retrieving :: jayasoft/standalone confs: [default] 1 artifacts copied, 0 already retrieved compile: [mkdir] Created dir: I:\standalone\build\classes [javac] Compiling 1 source file to I:\standalone\build\classes jar: [propertyfile] Creating new property file: I:\standalone\build\classes\version.properties [jar] Building jar: I:\standalone\build\standalone.jar publish: :: delivering :: jayasoft/standalone-working@xmen :: 1 :: release :: Wed Apr 27 08:41:47 CEST 2005 delivering ivy file to I:\standalone/build/ivy.xml :: publishing :: jayasoft/standalone-working@xmen published standalone to I:\config\repository\standalone-1.jar published ivy to I:\config\repository\standalone-1.xml [echo] project standalone released with version 1 BUILD SUCCESSFUL Total time: 10 seconds
What we see here:
- the project depends on 1 library (1 artifact)
- the library was not in the ivy cahe and so was downloaded (1 downloaded)
- the project has been released under version number 1
To give more details on the publish, as you can see the call to the publish task has resulted in two main things:
- the delivery of a resolved ivy file to build/ivy.xml. This has been done because by default the publish task not only publishes artifacts but also ivy file. So it has looked to the path where the ivy file to publish should be, using the artifactspattern: ${build.dir}/[artifact].[ext].
For an ivy file, this resolves to build/ivy.xml. Because this file does not exist, it automatically make a call to the deliver task which delivers a resolved ivy file to this destination.
- the publication of artifact standalone and resolved ivy file to the repository. Both are mere copy of files found in the current project, more precisely in the build dir. This is because the artifactspattern has been set to ${build.dir}/[artifact].[ext], so standalone artifact is found in build/standalone.jar and ivy file in build/ivy.xml. And because we have asked the publish task to publish them using the "projects" resolver, these files are copied to repository\standalone-1.jar and to repository\standalone-1.xml, respecting the artifact and ivy patterns of our configuration (see above).
step 4 : running the depending project
Goto to directory depending and run ant
I:\depending>ant Buildfile: build.xml clean: configure: :: Ivy 1.0-rc3 - 20050421161206 :: http://ivy.jayasoft.org/ :: resolve: :: resolving dependencies :: jayasoft/depending-working@xmen confs: [default] [1] jayasoft/standalone downloading file:/I:/config/repository/standalone-1.jar(1) ... . (1kB) [SUCCESSFUL ] jayasoft/standalone-1/standalone.jar[jar] (15ms) :: resolution report :: --------------------------------------------------------------------- | | modules || artifacts | | conf | number| search|dwnlded|evicted|| number|dwnlded| --------------------------------------------------------------------- | default | 2 | 2 | 2 | 0 || 2 | 1 | --------------------------------------------------------------------- :: retrieving :: jayasoft/depending confs: [default] 2 artifacts copied, 0 already retrieved compile: [mkdir] Created dir: I:\depending\build\classes [javac] Compiling 1 source file to I:\depending\build\classes run: [java] you are using version 1 of class standalone.Main [java] standard message : i am depending.Main and standalone.Main will do the job for me [java] [standalone.Main] capitalizing string "i am depending.Main and standalone.Main will do the job for me" using org.apache.commons.lang.WordUtils [java] capitalized message : I Am Depending.main And Standalone.main Will Do The Job For Me BUILD SUCCESSFUL Total time: 3 seconds
What we see here :
- the project depends on 2 libraries (2 artifacts)
- one of the libraries was in the cache because there was only 1 download (1 downloaded)
- ivy retreived the version 1 of the project standalone. The call to standalone.Main.getVersion() has returned 1. If you look in the depending/lib directory, you should see standalone-1.jar which is the artifact version 1 of the project standalone
- the call to standalone.Main.capitalizeWords(str) succeed, what significate that the required library were in the classpath. If you look at the lib directory, you will see that the library commons-lang-2.0.jar was retreived. This library was declared to be used by the project "standalone", so ivy get it too for the dependant project.
step 5 : new version of standalone project
Like we did before in step 3, publish again the standalone project. This will result as a new version of the project.
I:\standalone>ant publish Buildfile: build.xml configure: :: Ivy 1.0-rc3 - 20050421161206 :: http://ivy.jayasoft.org/ :: resolve: :: resolving dependencies :: jayasoft/standalone-working@xmen confs: [default] :: resolution report :: --------------------------------------------------------------------- | | modules || artifacts | | conf | number| search|dwnlded|evicted|| number|dwnlded| --------------------------------------------------------------------- | default | 1 | 0 | 0 | 0 || 1 | 0 | --------------------------------------------------------------------- :: retrieving :: jayasoft/standalone confs: [default] 0 artifacts copied, 1 already retrieved compile: jar: [propertyfile] Updating property file: I:\standalone\build\classes\version.properties [jar] Building jar: I:\standalone\build\standalone.jar publish: [delete] Deleting: I:\standalone\build\ivy.xml :: delivering :: jayasoft/standalone-working@xmen :: 2 :: release :: Wed Apr 27 09:17:13 CEST 2005 delivering ivy file to I:\standalone/build/ivy.xml :: publishing :: jayasoft/standalone-working@xmen published standalone to I:\config\repository\standalone-2.jar published ivy to I:\config\repository\standalone-2.xml [echo] project standalone released with version 2 BUILD SUCCESSFUL Total time: 2 seconds
Now if you look in your repository folder, you must find 2 version published of the standalone project.
Let's look at it:
I:\dependence\standalone>dir ..\config\repository /w
Le volume dans le lecteur I s'appelle DATA
Le numéro de série du volume est 30E5-91BA
Répertoire de I:\dependence\config\repository
[.] [..] standalone-1.jar standalone-1.xml standalone-2.jar standalone-2.xml
4 fichier(s) 3 936 octets
2 Rép(s) 9 874 350 080 octets libres
I:\dependence\standalone>Ok now our repository contains two versions of the project standalone, other projects can refer to both versions.
step 6 : depending got the new version
What do we expect about running again the depending project? Two major things are expected:
- retrieve the version 2 as the latest.integration version of the standalone project
- running the test must display version 2 of standalone project
Let's go!!!
I:\depending>ant Buildfile: build.xml clean: [delete] Deleting 3 files from I:\depending [delete] Deleted 4 directories from I:\depending configure: :: Ivy 1.0-rc3 - 20050421161206 :: http://ivy.jayasoft.org/ :: resolve: :: resolving dependencies :: jayasoft/depending-working@xmen confs: [default] [2] jayasoft/standalone downloading file:/I:/config/repository/standalone-2.jar(2) ... . (1kB) [SUCCESSFUL ] jayasoft/standalone-2/standalone.jar[jar] (0ms) :: resolution report :: --------------------------------------------------------------------- | | modules || artifacts | | conf | number| search|dwnlded|evicted|| number|dwnlded| --------------------------------------------------------------------- | default | 2 | 2 | 2 | 0 || 2 | 1 | --------------------------------------------------------------------- :: retrieving :: jayasoft/depending confs: [default] 2 artifacts copied, 0 already retrieved compile: [mkdir] Created dir: I:\depending\build\classes [javac] Compiling 1 source file to I:\depending\build\classes run: [java] you are using version 2 of class standalone.Main [java] standard message : i am depending.Main and standalone.Main will do the job for me [java] [standalone.Main] capitalizing string "i am depending.Main and standalone.Main will do the job for me" using org.apache.commons.lang.WordUtils [java] capitalized message : I Am Depending.main And Standalone.main Will Do The Job For Me BUILD SUCCESSFUL Total time: 3 seconds
Ok we have the result expected as the run target shows that we are using the version 2 of the main class of standalone project. If we take a look at the resolve target results, we can see that one artifact has been downloaded to the ivy cache. In fact this file is the version 2 of the standalone project that was taken from the repository, you can now retrieve it in the ivy-cache directory.