How To Use caGrid Libraries in Your Application


	Contents Overview Ivy Introduction Depending on caGrid Using Ivy A Simple Example Project that Needs caGrid Integrating Ivy into the Project Using Ivy to Extract Libraries from a Local caGrid Installation Using Ivy to Download Libraries from the Remote caGrid Repository Looking at Ivy reports as a guide to manually copying libraries from a local caGrid installation Ivy Summary

Overview

caGrid is released as a source distribution and as a graphical installer. You are strongly encouraged to still use a caGrid release. When developing applications that use caGrid libraries, however, it can be difficult to know which caGrid libraries (or external libraries caGrid needs) you need for your aims. As of caGrid 1.2, this information is formally managed and documented using the popular dependency management framework call Ivy. Ivy is a sub-project of Ant, and provides a number of custom Ant tasks focused solely on creating an enterprise dependency manager. caGrid transparently makes use of Ivy for its build process to manage its internal and external dependencies. Those who do not want to use Ivy are unaffected by this fact, but for those who do, it provides great advantages in determining exactly which libraries are needed for which tasks.

Ivy Introduction

The Ivy Documentation itself is quite good, and those new to Ivy are encouraged to review it. However, the main idea is that dependencies are described by each project in an Ivy file. An Ant-based build process (such as caGrid's process) is developed to use Ivy, and configures Ivy's settings, which control things like how Ivy should find dependencies. Then when a given project is built by the Ant build process, first its dependencies are resolved and retrieved from a repository into the project (such as into its lib directory). The project can then be built as it normally would, and optionally could publish itself to such a repository. A graphical representation of this process is shown below.

The use of Ivy does not necessarily need to affect the project's normal build process. In fact, only the main caGrid build process uses Ivy, and each caGrid project build process is completely independent of Ivy.

Depending on caGrid Using Ivy

There are several options for leveraging the power of Ivy when developing a project that depends on caGrid. This includes different ways of integrating Ivy directly into the project's build framework, just using Ivy to initially copy what you need or looking at the detailed reports Ivy generates and copying libraries "the old fashioned way". In the following sections, some of these options are discussed in the framework of a running example. NOTE: this article assumes that you have the libraries from a Globus installation on your classpath. These are not modeled in the Ivy dependencies, though this may change in the future.

A Simple Example Project that Needs caGrid

For the purposes of demonstrating Ivy, a sample project that uses the Discovery APIs of caGrid is explained below. The full source code for the example can be downloaded here or can be checked out from the Demos module of caGrid's source control system.

The sample project contains a single source file, contained in the src folder, and its Ant build process (defined in build.xml) expects to find the libraries it needs in the lib directory and the lib directory of the Globus installation; it expects the GLOBUS_LOCATION environment variable to be set. The build process compiles into the build directory and contains a target to run the main method of the source code (which makes various discovery queries). Thus far, this is a fairly typical project and makes no reference to Ivy or a caGrid installation.

The build process for this project:

        <project name="ivyexamples-discovery" default="run">

	<property name="lib.dir" value="lib" />
	<property name="build.dir" value="build" />
	<property name="src.dir" value="src" />

	<property environment="env" />
	<property name="globus.dir" value="${env.GLOBUS_LOCATION}" />
	<fail unless="env.GLOBUS_LOCATION" message="You must set the environment variable GLOBUS_LOCATION to the directory in which you have Globus installed." />


	<path id="lib.path.id">
		<fileset dir="${lib.dir}">
			<include name="*.jar" />
		</fileset>
		<fileset dir="${globus.dir}/lib">
			<include name="*.jar" />
			<exclude name="caGrid-*.jar" />
		</fileset>
	</path>
	<path id="run.path.id">
		<path refid="lib.path.id" />
		<path location="${build.dir}" />
		<path location="${globus.dir}" />
	</path>

	<target name="run" depends="clean" description="--> compile and run the project">
		<mkdir dir="${build.dir}" />
		<javac srcdir="${src.dir}" destdir="${build.dir}" classpathref="lib.path.id" />
		<java classpathref="run.path.id" classname="org.cagrid.ivyexamples.discovery.DiscoveryExamples" />
	</target>

	<target name="clean" description="--> cleans the project">
		<delete dir="${build.dir}" failonerror="false" />
	</target>
</project>

If you run this project as is, it will attempt to compile the project and generate a number of compiler errors. If you were to place all of the caGrid dependencies needed to compile this project's source code, it would run correctly.

Integrating Ivy into the Project

As mentioned above, there are numerous ways Ivy can be used to solve problems of dependency on caGrid. If you want to use Ivy directly in the project, you need to describe to Ivy what your dependencies are. The approach taken in this example is to isolate the Ivy-related portions of the build (such as retrieving dependencies), from the "standard" build targets and build process. In this way, you will actually create additional Ant build files that import your standard build, and add the Ivy support. You will use these additional targets when you need to leverage Ivy but can use the standard build file for the normal compile and run process. The advantage to this approach is that you can exclude the Ivy-related files if you were to create a distribution of the project that has all the jars it needs in its lib directory. However, if you wanted to integrate Ivy into your build process, that is also an option.

The first step to integrating Ivy into the project is to define the project in terms of what it is, how it may be depended on, and what dependencies it has. This is done by creating an Ivy file (ivy.xml)for the project. It indicates that version 1.4 of the discovery module of caGrid is needed. For more information about Ivy files, see the Ivy documentation. Additionally, the caGrid release itself contains hundreds of Ivy files that can be used as examples. You can also look at these online in the caGrid remote Ivy repository.

The Ivy file used for this project is shown below:

    <ivy-module version="2.0">
    <info organisation="org.cagrid.ivyexamples" module="discovery"/>
    <dependencies>
        <dependency org="caGrid" name="discovery" rev="1.4"/>
    </dependencies>
</ivy-module>

Now that you have defined the project and its needs in a way Ivy understands, you must inform Ivy of what you want it to do. In the Ivy Introduce section you saw that Ivy retrieves project dependencies from a repository. You have to tell Ivy what repository it should use to locate the caGrid dependencies the project needs. The sample project actually demonstrates two different ways to do this.

Using Ivy to Extract Libraries from a Local caGrid Installation

In the first example, you will configure Ivy to copy caGrid dependencies from a local build of the caGrid source distribution. Refer to this installation's location with the environment variable CAGRID_LOCATION. You can integrate Ivy by creating another Ant build file, which extends the project's regular build process. In this second build file, create the ivy-resolve target, which will instruct Ivy to copy the dependencies you need into your lib directory. Next, define the supporting targets of ivy-clean that will remove these copied dependencies and ivy-report, which informs Ivy to create a report of what it has completed. Create an all target, which calls all three of these targets, and set is as the default for the project.

The build file is shown here:

        <project name="ivyexamples-discovery-local-ivy" default="all" xmlns:ivy="antlib:org.apache.ivy.ant">

	<import file="build.xml" />

	<property name="caGrid.dir" value="${env.CAGRID_LOCATION}" />
	<fail unless="env.CAGRID_LOCATION" message="You must set the environment variable CAGRID_LOCATION to the directory in which you have caGrid installed (the caGrid directory)." />

	<taskdef resource="org/apache/ivy/ant/antlib.xml" uri="antlib:org.apache.ivy.ant">
		<classpath>
			<fileset dir="${lib.dir}" includes="ivy-*.jar" />
		</classpath>
	</taskdef>

	<property name="repository.dir" location="${caGrid.dir}/repository" />
	<property name="integration.repository.dir" location="${caGrid.dir}/integration-repository" />
	<ivy:settings id="ivy.instance" file="${caGrid.dir}/antfiles/ivy/ivysettings.xml" override="true" />

	<target name="ivy-resolve" description="--> retreive dependencies with ivy">
		<ivy:retrieve type="jar" />
	</target>

	<target name="ivy-report" depends="ivy-resolve" description="--> generates a report of dependencies">
		<ivy:report todir="${build.dir}" />
	</target>

	<target name="ivy-clean" description="--> cleans all the libraries which were retrieved for the project">
		<delete includeemptydirs="true" failonerror="false">
			<fileset dir="${lib.dir}">
				<include name="**/*" />
				<exclude name="ivy*.jar" />
			</fileset>
		</delete>
		<ivy:cleancache />
	</target>

	<target name="all" depends="ivy-clean,ivy-resolve,ivy-report"/>
</project>

Now you must define the new Ant tasks Ivy provides with an Ant taskdef and a namespace (ivy). This process is explained in the Ivy Ant documentation. Next, configure Ivy with the ivy:settings task. The use of this task is defined in the relevant section of the Ivy documentation, but of notice is that you are just pointing to the settings file which caGrid uses in its build process. This settings file requires two variables to be set using simple Ant properties. The first is the repository.dir property, which is where the external libraries caGrid needs are stored, and the second is the integration.repository.dir which is where caGrid projects publish themselves when built so other caGrid projects can depend on them.

Once Ivy is configured, you need to call ivy:retrieve to get the necessary jars. It is worth noting that you are taking advantage of some of the default settings of Ivy, but these can always be overridden. For example, Ivy by default, will copy jars into the lib directory, but that can be changed.

To actually run this process and copy the dependencies you need into your lib directory, type:ant -f local-ivy-build.xml.

Below is an example output:

[oster@gcity ~...ivyexamples/discovery]$ ant -f local-ivy-build.xml
Buildfile: local-ivy-build.xml
[ivy:settings] :: Ivy 2.0.0-beta2 - 20080225093827 :: http://ant.apache.org/ivy/ ::
[ivy:settings] :: loading settings :: file = D:\projects\caBIG\ReleaseWork\caGrid-1.4\caGrid-1.4-rc6\caGrid\antfiles\ivy\ivysettings.xml

ivy-clean:

ivy-resolve:
[ivy:retrieve] :: resolving dependencies :: org.cagrid.ivyexamples#discovery;working@gcity
[ivy:retrieve]  confs: [default
[ivy:retrieve]  found caGrid#discovery;1.4 in caGrid-local-fs-fs
[ivy:retrieve]  found caGrid#core;1.4 in caGrid-local-fs-fs
[ivy:retrieve]  found castor#castor;0.9.9 in caGrid-fs-fs
[ivy:retrieve]  found jdom#jdom;1.0 in caGrid-fs-fs
[ivy:retrieve]  found caGrid#metadatautils;1.4 in caGrid-local-fs-fs
[ivy:retrieve]  found caGrid#metadata;1.4 in caGrid-local-fs-fs
[ivy:retrieve]  found jasciidammit#jasciidammit;1.1 in caGrid-fs-fs
[ivy:retrieve]  found clarkware#jdepend;2.7 in caGrid-fs-fs
[ivy:retrieve] :: resolution report :: resolve 474ms :: artifacts dl 35ms
        ---------------------------------------------------------------------
        |                  |            modules            ||   artifacts   |
        |       conf       | number| search|dwnlded|evicted|| number|dwnlded|
        ---------------------------------------------------------------------
        |      default     |   8   |   8   |   0   |   0   ||   17  |   0   |
        ---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: org.cagrid.ivyexamples#discovery
[ivy:retrieve]  confs: [default]
[ivy:retrieve]  12 artifacts copied (2777kB/240ms)

ivy-report:
[ivy:report] Processing d:\projects\caBIG\cagrid-1-0\Demos\ivyexamples\discovery\.cache\org.cagrid.ivyexamples-discovery-default.xml to D:\projects\caBIG\cagrid-1-0\Demos\ivyexamples\discovery\build\org.cagrid.ivyexamples-discovery-default.html
[ivy:report] Processing d:\projects\caBIG\cagrid-1-0\Demos\ivyexamples\discovery\.cache\org.cagrid.ivyexamples-discovery-default.xml to D:\projects\caBIG\cagrid-1-0\Demos\ivyexamples\discovery\build\org.cagrid.ivyexamples-discovery-default.graphml

all:

BUILD SUCCESSFUL
Total time: 2 seconds

NOTE: Ivy reported that it copied 12 artifacts into the project. You can view the report in your build directory.

You can now run the regular build by typing:

ant

You should see output similar to this:

Buildfile: build.xml

clean:
   [delete] Deleting directory D:\projects\caBIG\cagrid-1-0\Demos\ivyexamples\discovery\build

run:
    [mkdir] Created dir: D:\projects\caBIG\cagrid-1-0\Demos\ivyexamples\discovery\build
    [javac] Compiling 1 source file to D:\projects\caBIG\cagrid-1-0\Demos\ivyexamples\discovery\build
     [java] ==================================================
     [java] Querying by All Services
     [java] ==================================================
     [java] 	0)  Address: https://140.254.80.54:6443/wsrf/services/cagrid/Dorian
     [java] 	1)  Address: https://cagrid-cccwfu.medctr.ad.wfubmc.edu:8443/wsrf/services/cagrid/Caaers
     [java] 	2)  Address: http://165.112.132.173:18080/wsrf/services/cagrid/CaArraySvc
     [java] 	3)  Address: http://165.112.132.241:18080/wsrf/services/cagrid/CaArraySvc
     [java] 	4)  Address: http://128.252.227.214:18080/wsrf/services/cagrid/CaArraySvc
     [java] 	5)  Address: https://192.168.200.198:8443/wsrf/services/cagrid/CoffeeMaker
     [java] 	6)  Address: http://cagrid-service.nci.nih.gov:8080/wsrf/services/cagrid/EVSGridService
     [java] 	7)  Address: https://10.144.36.26:8443/wsrf/services/cagrid/Dorian
     [java] 	8)  Address: http://140.254.80.50:50101/wsrf/services/cagrid/GridImageResultService
     [java] 	9)  Address: https://cagrid-dorian.nci.nih.gov:8443/wsrf/services/cagrid/Dorian
     [java] 	10)  Address: https://localhost:443/wsrf/services/cagrid/QueryService
     [java] 	11)  Address: https://cagrid-workflow.nci.nih.gov:8443/wsrf/services/cagrid/WorkflowFactoryService
     [java] 	12)  Address: https://10.120.79.112:8443/wsrf/services/cagrid/Dorian
     [java] 	13)  Address: https://localhost:443/wsrf/services/cagrid/CaTIES
     [java] 	14)  Address: http://140.254.80.50:50100/wsrf/services/cagrid/OrderQueueService
     [java] 	15)  Address: https://137.187.66.137:58091/wsrf/services/cagrid/CaTissueCore
     [java] 	16)  Address: https://cagrid-workflow.nci.nih.gov:8443/wsrf/services/cagrid/FederatedQueryProcessor
     [java] 	17)  Address: https://cagrid-gts-slave.nci.nih.gov:8443/wsrf/services/cagrid/GTS
     [java] 	18)  Address: https://cagrid-cccwfu.medctr.ad.wfubmc.edu:8443/wsrf/services/cagrid/GTS
     [java] 	19)  Address: http://127.0.0.1:18080/wsrf/services/cagrid/CaArraySvc
     [java] 	20)  Address: http://137.187.66.137:18080/wsrf/services/cagrid/CaArraySvc
     [java] 	21)  Address: https://192.168.200.198:8443/wsrf/services/cagrid/RegistrationConsuserService
     [java] 	22)  Address: https://localhost:8443/wsrf/services/cagrid/CaGridTutorialService
     [java] 	23)  Address: https://cagrid-gts-master.nci.nih.gov:8443/wsrf/services/cagrid/GTS
     [java] 	24)  Address: http://141.161.25.20:8080/wsrf/services/cagrid/GridPIR
     [java] 	25)  Address: https://10.10.10.2:8443/wsrf/services/cagrid/Caaers
     [java] 	26)  Address: https://10.0.2.13:8443/wsrf/services/cagrid/Dorian
     [java] 	27)  Address: http://cacti-g5-12.wustl.edu:8080/wsrf-canano/services/cagrid/CaNanoLabSvc
     [java] 	28)  Address: https://127.0.1.1:8443/wsrf/services/cagrid/HelloWorld
     [java] 	29)  Address: http://137.187.182.58:18080/wsrf/services/cagrid/CaArraySvc
     [java] 	30)  Address: https://caaers.mayo.edu:8443/wsrf/services/cagrid/CaaersDataService
     [java] 	31)  Address: http://cagrid-service.nci.nih.gov:8080/wsrf/services/cagrid/GlobalModelExchange
     [java] 	32)  Address: http://cpas.nci.nih.gov:8080/wsrf/services/cagrid/CpasSvc
     [java] 	33)  Address: http://137.187.66.137:44210/wsrf/services/cagrid/Ctods
     [java] 	34)  Address: https://192.168.88.79:38443/wsrf/services/cagrid/GTS
     [java] 	35)  Address: https://137.187.182.60:47210/wsrf/services/cagrid/CaTissueCore
     [java] 	36)  Address: http://sonicserver-dev.northwestern.edu:9000/wsrf/services/cagrid/HelloWorld
     [java] 	37)  Address: http://140.254.80.50:50101/wsrf/services/cagrid/ImageDataService
     [java] 	38)  Address: http://128.252.178.222:8080/wsrf/services/cagrid/GeneConnect
     [java] 	39)  Address: http://cananolab.nci.nih.gov:80/wsrf-canano/services/cagrid/CaNanoLabSvc
     [java] 	40)  Address: http://cananogrid.bme.gatech.edu:8088/wsrf-canano/services/cagrid/CaNanoLabSvc
     [java] 	41)  Address: http://127.0.0.1:8080/inp2/services/cagrid/InPxService
     [java] 	42)  Address: http://140.254.80.50:50100/wsrf/services/cagrid/DICOMDataService
     [java] 	43)  Address: http://140.254.80.50:50101/wsrf/services/cagrid/DICOMDataService
     [java] 	44)  Address: http://137.187.182.173:8080/wsrf/services/cagrid/NCIAQueryService
     [java] 	45)  Address: https://cagrid-dorian-qa.nci.nih.gov:8443/wsrf/services/cagrid/Dorian
     [java] 	46)  Address: https://152.11.189.189:8443/wsrf/services/cagrid/Caaers
     [java] 	47)  Address: http://cabio-gridservice.nci.nih.gov:80/wsrf-cabio/services/cagrid/CaBIOSvc
     [java] 	48)  Address: https://cagrid-auth.nci.nih.gov:8443/wsrf/services/cagrid/AuthenticationService
     [java] 	49)  Address: https://192.168.88.79:8443/psc-wsrf/services/cagrid/AdverseEventConsumer
     [java] 	50)  Address: http://cananolab.abcc.ncifcrf.gov:8080/wsrf-canano/services/cagrid/CaNanoLabSvc
     [java] 	51)  Address: https://localhost:443/wsrf-security/services/cagrid/Dorian
     [java] 	52)  Address: https://157.229.220.121:8443/wsrf/services/cagrid/Dorian
     [java] 	53)  Address: https://tropixdev04.mayo.edu:8443/wsrf/services/cagrid/AuthenticationService
     [java] 	54)  Address: http://137.187.182.60:42210/wsrf/services/cagrid/CAGWAS
     [java] 	55)  Address: https://localhost:443/wsrf-security/services/cagrid/AuthenticationService
     [java] 	56)  Address: https://10.20.2.95:8443/wsrf/services/cagrid/Caaers
     [java] 	57)  Address: https://137.187.182.58:58091/wsrf/services/cagrid/CaTissueCore
     [java] 	58)  Address: http://cgwb.nci.nih.gov:80/wsrf/services/cagrid/CGWBDataService
     [java] 	59)  Address: https://128.101.190.104:8443/wsrf/services/cagrid/Sequest
     [java] 	60)  Address: https://cagrid-gridgrouper.nci.nih.gov:8443/wsrf/services/cagrid/GridGrouper
     [java] 	61)  Address: http://140.254.80.50:50010/wsrf/services/cagrid/PathologyDataService
     [java] 	62)  Address: http://cagrid.jax.org:18080/wsrf/services/cagrid/CaArraySvc
     [java] 	63)  Address: http://caintegrator-stage.nci.nih.gov:8080/wsrf/services/cagrid/CgomCgems
     [java] 	64)  Address: http://array.nci.nih.gov:80/wsrf/services/cagrid/CaArraySvc
     [java] 	65)  Address: http://140.254.80.84:8080/wsrf/services/cagrid/TMADataService
     [java] 	66)  Address: http://cagrid-service.nci.nih.gov:8080/wsrf/services/cagrid/CaDSRService
     [java] 	67)  Address: https://dorian.training.cagrid.org:6443/wsrf/services/cagrid/Dorian
     [java] 	68)  Address: https://157.229.221.119:8443/wsrf/services/cagrid/Dorian
     [java] 	69)  Address: https://cagrid-cccwfu.medctr.ad.wfubmc.edu:8443/wsrf/services/cagrid/HelloWorld
     [java] 	70)  Address: https://147.140.9.23:8443/wsrf/services/cagrid/Dorian
     [java] 	71)  Address: https://dorian.bmi.ohio-state.edu:9443/wsrf/services/cagrid/Dorian
     [java] 	72)  Address: https://tropixdev01.mayo.edu:8443/wsrf/services/cagrid/LexBIGCaGridServices
     [java] --------------------------------------------------


     [java] ==================================================
     [java] Querying by Search String [Scott]
     [java] ==================================================
     [java] 	0)  Address: https://cagrid-workflow.nci.nih.gov:8443/wsrf/services/cagrid/FederatedQueryProcessor
     [java] 	1)  Address: http://cagrid-service.nci.nih.gov:8080/wsrf/services/cagrid/CaDSRService
     [java] --------------------------------------------------


     [java] ==================================================
     [java] Querying by Research Center Name [OSU]
     [java] ==================================================
     [java] no results.
     [java] --------------------------------------------------


     [java] ==================================================
     [java] Querying by POC [gov.nih.nci.cagrid.metadata.common.PointOfContact@94f965d]
     [java] ==================================================
     [java] 	0)  Address: https://cagrid-workflow.nci.nih.gov:8443/wsrf/services/cagrid/FederatedQueryProcessor
     [java] 	1)  Address: http://cagrid-service.nci.nih.gov:8080/wsrf/services/cagrid/CaDSRService
     [java] --------------------------------------------------


     [java] ==================================================
     [java] Querying by Service name [CaDSRService]
     [java] ==================================================
     [java] 	0)  Address: http://cagrid-service.nci.nih.gov:8080/wsrf/services/cagrid/CaDSRService
     [java] --------------------------------------------------


     [java] ==================================================
     [java] Querying by Operation name [findAllProjects]
     [java] ==================================================
     [java] 	0)  Address: http://cagrid-service.nci.nih.gov:8080/wsrf/services/cagrid/CaDSRService
     [java] --------------------------------------------------


     [java] ==================================================
     [java] Querying by Operation input [gov.nih.nci.cagrid.metadata.common.UMLClass@50c8e2fa]
     [java] ==================================================
     [java] 	0)  Address: http://cagrid-service.nci.nih.gov:8080/wsrf/services/cagrid/CaDSRService
     [java] --------------------------------------------------


     [java] ==================================================
     [java] Querying by Operation output [gov.nih.nci.cagrid.metadata.common.UMLClass@50c8e2fa]
     [java] ==================================================
     [java] 	0)  Address: http://cagrid-service.nci.nih.gov:8080/wsrf/services/cagrid/CaDSRService
     [java] --------------------------------------------------


     [java] ==================================================
     [java] Querying by Operation class [gov.nih.nci.cagrid.metadata.common.UMLClass@50c8e2fa]
     [java] ==================================================
     [java] 	0)  Address: http://cagrid-service.nci.nih.gov:8080/wsrf/services/cagrid/CaDSRService
     [java] --------------------------------------------------



BUILD SUCCESSFUL
Total time: 19 seconds

Using Ivy to Download Libraries from the Remote caGrid Repository

In the second example, you will configure Ivy to copy caGrid dependencies from a remote Ivy repository accessible over the Internet. You will no longer require a local caGrid installation or environment variable as was necessary for the previous example. Create another Ant build file, which extends the project's regular build process, to integrate Ivy. You will create an alternative (remote-ivy-build.xml) to the local-ivy-build.xml used in the previous example. You will, however, use all the same Ant targets names and processes. The only difference in the local and remote examples is the way in which you tell Ivy about the settings it should use. Whereas in the last example you pointed to settings in the caGrid release, in this example you will point to settings provided by the remote repository itself; all you need to know is the URL of these settings.

The build file is shown here:

        <project name="ivyexamples-discovery-remote-ivy" default="all" xmlns:ivy="antlib:org.apache.ivy.ant">

	<import file="build.xml" />

	<taskdef resource="org/apache/ivy/ant/antlib.xml" uri="antlib:org.apache.ivy.ant">
		<classpath>
			<fileset dir="${lib.dir}" includes="ivy-*.jar" />
		</classpath>
	</taskdef>

	<property name="ivy.settings.url" value="http://software.cagrid.org/repository-1.4/ivysettings.xml" />
	<ivy:settings id="ivy.instance" url="${ivy.settings.url}" override="true" />

	<target name="ivy-resolve" description="--> retreive dependencies with ivy">
		<ivy:retrieve type="jar" />
	</target>

	<target name="ivy-report" depends="ivy-resolve" description="--> generates a report of dependencies">
		<ivy:report todir="${build.dir}" />
	</target>

	<target name="ivy-clean" description="--> cleans all the libraries which were retrieved for the project">
		<delete includeemptydirs="true" failonerror="false">
			<fileset dir="${lib.dir}">
				<include name="**/*" />
				<exclude name="ivy*.jar" />
			</fileset>
		</delete>
		<ivy:cleancache />
	</target>

	<target name="all" depends="ivy-clean,ivy-resolve,ivy-report" />
</project>

To actually run this process and copy the dependencies you need into your lib directory, you just need to type:

 ant -f remote-ivy-build.xml

An example output of this can be see below:

Buildfile: remote-ivy-build.xml
[ivy:settings] :: Ivy 2.0.0-beta2 - 20080225093827 :: http://ant.apache.org/ivy/ ::
[ivy:settings] :: loading settings :: url = http://software.cagrid.org/repository-1.4/ivysettings.xml

ivy-resolve:
[ivy:retrieve] :: resolving dependencies :: org.cagrid.ivyexamples#discovery;working@gcity
[ivy:retrieve]  confs: [default]
[ivy:retrieve]  found caGrid#discovery;1.4 in remote-caGrid-ivy-resolver
[ivy:retrieve]  found caGrid#core;1.4 in remote-caGrid-ivy-resolver
[ivy:retrieve]  found castor#castor;0.9.9 in remote-caGrid-ivy-resolver
[ivy:retrieve]  found jdom#jdom;1.0 in remote-caGrid-ivy-resolver
[ivy:retrieve]  found caGrid#metadatautils;1.4 in remote-caGrid-ivy-resolver
[ivy:retrieve]  found caGrid#metadata;1.4 in remote-caGrid-ivy-resolver
[ivy:retrieve]  found jasciidammit#jasciidammit;1.1 in remote-caGrid-ivy-resolver
[ivy:retrieve]  found clarkware#jdepend;2.7 in remote-caGrid-ivy-resolver
[ivy:retrieve] :: resolution report :: resolve 375ms :: artifacts dl 23ms
        ---------------------------------------------------------------------
        |                  |            modules            ||   artifacts   |
        |       conf       | number| search|dwnlded|evicted|| number|dwnlded|
        ---------------------------------------------------------------------
        |      default     |   8   |   0   |   0   |   0   ||   17  |   0   |
        ---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: org.cagrid.ivyexamples#discovery
[ivy:retrieve]  confs: [default]
[ivy:retrieve]  0 artifacts copied, 12 already retrieved (0kB/12ms)

BUILD SUCCESSFUL
Total time: 1 second

NOTE: this time it was significantly faster and it didn't need to retrieve anything new. You can experiment with this by removing a few of the jars from the lib directory and doing another ivy-resolve; it will only download what it needs.

You can now run the main build file just as before, and you should see the same results.

Looking at Ivy reports as a guide to manually copying libraries from a local caGrid installation

The preceding two examples demonstrated how Ivy could be used programmatically in the build process to copy dependencies into a project. If for some reason you do not have the ability to integrate with Ivy in this way, you can use the output of the Ivy-generated reports (as shown in the preceding examples), to look at any given project's dependencies, and manually copy the dependencies you need. It is recommended you allow Ivy to do this for, even if you don't do it as part of your build process.

Shown below is a portion of the report generated by running the ivy-report target of the ivy builds files:

You can see in the Dependencies Overview section, a tree-like representation of the transitive dependencies are shown. In the example, the project only depends on caGrid Discovery, which in turn depends on the metadatautils, metadata, and core caGrid projects. These projects in turn have dependencies which are also retrieved. This information informs which libraries are needed for use of any caGrid project and why they are needed. The full report contains the specific details of each module's artifacts. Ivy reports for every caGrid project can be found in each project's ext directory.

Ivy Summary

This section has shown a variety of ways in which the power of an Ivy-enabled caGrid build can be leveraged. However, it has only scratched the surface of what Ivy can do, and those who find utility in the mechanisms described here are encouraged to look further into Ivy. If you are doing extensive development work that depends on caGrid, it is very convenient to stay integrated with both released versions of caGrid, as well as supporting nightly or continuous integration versions. Switching between the two can be as simple as pointing to a different Ivy settings file. It also ensures the project will be more "future proof" in that when new caGrid releases are made available, you can automatically update the projects to leverage them.

Knowledgebase