This page provides some examples on how to use Ivy APIs within your applications, to achieve the same functionality that you could have through Ant scripts.

This document does not contain the full set of APIs nor does it have examples for all the features. This is just a start towards making available some documentation for using Ivy APIs. From what i have seen in the mailing lists there isn't a central place where information related to this is available. In fact, i had to browse the Ivy source code and some mails in the user mailing list to find out which APIs to use.

So let's get to the examples now!

Note that at the time of writing this, i had used Ivy version 2.1.0

Getting an Ivy instance

The first step towards using Ivy within your application, is to create an Ivy instance. To create an Ivy instance, you would need to create an instance of Ivy settings first. Here's how you can create the IvySettings instance:

org.apache.ivy.core.settings.IvySettings ivySettings = new IvySettings();
// Now let's set the basedir of the ivy settings to some location
File baseDir = new File("/home/me/ivy");
ivySettings.setBaseDir(baseDir);

Once you have create the Ivy settings, you can now you use it to create an Ivy instance. Here's how it is done:

// create an ivy instance
org.apache.ivy.Ivy ivy = Ivy.newInstance(ivySettings);

With these 2 steps, you have now created an Ivy instance, which will be required to do any operations related to Ivy dependency management.

Configuring the Ivy instance

After creating the Ivy instance, you will have to configure it to use the correct settings file. Here's how it can be done:

// That's where my ivy-settings.xml is located
File ivySettingsXmlFile = new File("/home/me/ivy/conf/ivy-settings.xml");
// configure ivy to use the settings file
ivy.configure(ivySettingsXmlFile);

With these steps, you have now configured an Ivy instance to be usable for dependency management operations.

Resolving dependencies using an Ivy instance

Next, let's see how we can use this Ivy instance to resolve dependencies. In the example here, our dependencies are listed in a file named "ivy.xml" which is located at /home/me/ivy/samples/test/ivy.xml. The contents of ivy.xml are as follows:

<ivy-module version="2.0">
 <info organisation="apache" module="hello-ivy"/>
 <dependencies>
       <dependency org="commons-lang" name="commons-lang" rev="2.0"/>
       <dependency org="commons-cli" name="commons-cli" rev="1.0"/>
 </dependencies>
</ivy-module>

For a detailed explanation of the contents of ivy.xml, please read the Ivy user manual or the tutorials.

Our intention is to feed this dependency file to the ivy instance we created and ask it to resolve the dependencies. Here's how we do this - Comments have been provided inline to explain what we are doing:

// file containing the list of dependencies (ex: ivy.xml)
File dependencyFile = new File("/home/me/ivy/samples/test/ivy.xml");
// resolve the dependencies - Ivy returns a report of the resolution
ResolveReport resolveReport = ivy.resolve(dependencyFile);

// check for errors (if any) during resolve
if (resolveReport.hasError())
{    
      List<String> problems = resolveReport.getAllProblemMessages();
      if (problems != null && !problems.isEmpty())    
      {        
           StringBuffer errorMsgs = new StringBuffer();
          for (String problem : problems)
          {
            errorMsgs.append(problem);
            errorMsgs.append("\n");
          }
            System.err.println("Errors encountered during dependency resolution for package " + pkgCtx + " :");
            System.err.println(errorMsgs);    
        }
}
else
{    System.out.println("Dependencies in file " + dependencyFile + " were successfully resolved");
}

Retrieving the resolved dependencies

Now that the dependencies have been resolved, we can use the ivy instance to retrieve these dependencies

To understand the difference between "resolve" and "retrieve" and other Ivy terminologies, please refer to the Ivy user manual or the tutorials

Comments have been provided inline to explain what's going on

// Now that the dependencies have been resolved, let now retrieve them
// Get the descriptor
org.apache.ivy.core.module.descriptor.ModuleDescriptor md = resolveReport.getModuleDescriptor();
// module revision id of the module whose dependencies were resolved
org.apache.ivy.core.module.id.ModuleRevisionId mRID = md.getModuleRevisionId();

// options that we pass to ivy instance for retrieve the dependencies
org.apache.ivy.core.retrieve.RetrieveOptions retrieveOptions = new RetrieveOptions();

// folder to which we want the dependencies retrieved
File destFolder = new File("/home/me/ivy/samples/test/dependencies");

// the Ivy pattern which will be used for retrieving the dependencies
String pattern = destFolder + "/[organization]/[module]/[type]/[artifact]-[revision].[ext]";
retrieveOptions.setDestIvyPattern(pattern);

// default logging option
retrieveOptions.setLog(LogOptions.LOG_DEFAULT);

// retrieve them!
int packagesRetrieved = ivy.retrieve(mRID, pattern, retrieveOptions);

System.out.println("Retrieved " + packagesRetrieved + " dependencies");

That's it! With these steps you have now successfully resolved and retrieved the dependencies of a module through Ivy APIs.