doc/tutorial/multiple.html - ant-ivy - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
 <!--
    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.
 -->
 <html>
 <head>
 	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
 	<script type="text/javascript">var xookiConfig = {level: 1};</script>
 	<script type="text/javascript" src="../xooki/xooki.js"></script>
 </head>
 <body>
 	<textarea id="xooki-source">
 This tutorial is an example of how modules can be retrieved by multiple resolvers. Using multiple resolvers can be useful in many contexts. For example:
 <ul>
 <li>separating integration builds from releases</li>
 <li>using a public repository for third party modules and a private one for internal modules</li>
 <li>use a repository for storing modules which are not accurate in an unmanaged public repository</li>
 <li>use a local repository to expose builds made on one developer's station</li>
 </ul>

 In Ivy, the use of multiple resolvers is supported by a compound resolver called the chain resolver.

 In our example, we will simply show you how to use two resolvers, one on a local repository and one using the maven2 repository.

 <h1>project description</h1>
 <h2>the project: chained-resolvers</h2>
 The project is very simple and contains only one simple class: example.Hello.

 It depends on two libraries: Apache's commons-lang and a custom library named test (sources are included in test-1.0jar file). The test library is used by the project to uppercase a string, and commons-lang is used to capitalize the same string.

 Here is the content of the project:
 <ul>
   <li>build.xml: the ant build file for the project</li>
   <li>ivy.xml: the Ivy project file</li>
   <li>src\example\Hello.java: the only class of the project</li>
 </ul>
 Let's have a look at the <b>ivy.xml</b> file:
 <code>
 <ivy-module version="1.0">
     <info organisation="org.apache" module="chained-resolvers"/>
     <dependencies>
         <dependency org="commons-lang" name="commons-lang" rev="2.0"/>
         <dependency name="test" rev="1.0"/>
     </dependencies>
 </ivy-module>
 </code>
 As we'd expect, the ivy file declares this module to be dependent on the two libraries it uses: 'commons-lang' and 'test'. Note that we didn't specify the org for the dependency 'test'. When we exclude org, Ivy assumes it is in the same org as the declaring module. (i.e. 'org.apache').

 <h2>the <b>ivy settings</b></h2>
 The settings are defined in the ivysettings.xml file located in the settings directory of the project. Below are its contents, followed by an explanation of what it's doing.

 <code>
 <ivysettings>
   <settings defaultResolver="chain-example"/>
   <resolvers>
     <chain name="chain-example">
       <filesystem name="libraries">
         <artifact pattern="${ivy.settings.dir}/repository/[artifact]-[revision].[ext]" />
       </filesystem>
       <ibiblio name="ibiblio" m2compatible="true" />
     </chain>
   </resolvers>
 </ivysettings>
 </code>
 <h2>the <b>settings</b> tag</h2>
 This tag initializes Ivy with some parameters. Here only one parameter is set, the name of the resolver to use by default.

 <h2>the <b>resolvers</b> tag</h2>
 The resolvers section defines the list of resolvers that Ivy will use to locate artifacts. In our example, we have only one resolver named "chain-example", which is unique in that it defines a list (hence a chain) of resolvers.
 The resolvers in this chain are:
 <ul>
   <li>libraries : It is a filesystem resolver, so looks at a directory structure to retrieve the artifacts. This one is configured to look in the <tt>repository</tt> sub directory of the directory that contains the <tt>ivysettings.xml</tt> file.</li>
   <li>ibiblio : It looks in the ibiblio maven repository to retrieve the artifacts.</li>
 </ul>

 That's it, we have just configured a chain of resolvers!

 <h1>walkthrough</h1>
 <div class="step">
 <h2>step 1: preparation</h2>
 Open a DOS or shell window, and go to the "chained-resolvers" directory.
 </div>
 <div class="step">
 <h2>step 2: clean directory tree</h2>
 On the prompt type: ant<br>
 This will clean up the entire project directory tree and Ivy cache. You can do this each time you want to clean up this example.

 <div class="tip">
 In almost all examples, we provide a clean target as default target. Since most examples use the same Ivy cache, you will clean the whole Ivy cache each time you call this target.

 Cleaning the Ivy cache is something you can do without fear (except performance): it's only a cache, so everything can be (and should be) obtained again from repositories. This may sound strange to those coming from maven 2 land. But remember that in Ivy, the cache is not a local repository and the two are completely isolated.
 </div>
 </div>
 <div class="step">
 <h2>step 3: run the project</h2>
 Go to <tt>chained-resolvers</tt> project directory. And simply run <tt>ant</tt>.

 <div class="shell"><pre>
 [<tutorial/log/chained-resolvers.txt>]
 </pre></div></div>

 We can see in the log of the resolve task, that the two dependencies have been retrieved (2 artifacts) and copied to the Ivy cache directory (2 downloaded).

 Also notice that the 'run' Ant target succeeded in using both commons-lang.jar coming from the ibiblio repository and test.jar coming from the local repository.

 <h1>Going further</h1>
 This very simple example helps us see how to set up two resolvers in a chain. The [[resolver/chain chain resolver's reference documentation]] is available for those who would like to know all the features offered by this resolver.

 Below are a few more interesting things worth knowing about chain resolvers. After reading them, go ahead and try tweaking this example using your new wealth of knowledge!
 <ul>
 <li>a chain is not limited to two nested resolvers, you can use as many as you want</li>
 <li>by setting <tt>returnFirst="true"</tt>, you can have a chain which stops as soon as it has found a result for a given module</li>
 <li>by setting <tt>dual="true"</tt>, the full chain will be used both for module descriptors and artifacts, while setting <tt>dual="false"</tt>, the resolver in the chain which found the module descriptor (if any) is also used for artifacts</li>
 </ul>

 	</textarea>
 <script type="text/javascript">xooki.postProcess();</script>
 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
	<!--
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->
	<html>
	<head>
	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
	<script type="text/javascript">var xookiConfig = {level: 1};</script>
	<script type="text/javascript" src="../xooki/xooki.js"></script>
	</head>
	<body>
	<textarea id="xooki-source">
	This tutorial is an example of how modules can be retrieved by multiple resolvers. Using multiple resolvers can be useful in many contexts. For example:
	<ul>
	<li>separating integration builds from releases</li>
	<li>using a public repository for third party modules and a private one for internal modules</li>
	<li>use a repository for storing modules which are not accurate in an unmanaged public repository</li>
	<li>use a local repository to expose builds made on one developer's station</li>
	</ul>

	In Ivy, the use of multiple resolvers is supported by a compound resolver called the chain resolver.

	In our example, we will simply show you how to use two resolvers, one on a local repository and one using the maven2 repository.

	<h1>project description</h1>
	<h2>the project: chained-resolvers</h2>
	The project is very simple and contains only one simple class: example.Hello.

	It depends on two libraries: Apache's commons-lang and a custom library named test (sources are included in test-1.0jar file). The test library is used by the project to uppercase a string, and commons-lang is used to capitalize the same string.

	Here is the content of the project:
	<ul>
	<li>build.xml: the ant build file for the project</li>
	<li>ivy.xml: the Ivy project file</li>
	<li>src\example\Hello.java: the only class of the project</li>
	</ul>
	Let's have a look at the <b>ivy.xml</b> file:
	<code>
	<ivy-module version="1.0">
	<info organisation="org.apache" module="chained-resolvers"/>
	<dependencies>
	<dependency org="commons-lang" name="commons-lang" rev="2.0"/>
	<dependency name="test" rev="1.0"/>
	</dependencies>
	</ivy-module>
	</code>
	As we'd expect, the ivy file declares this module to be dependent on the two libraries it uses: 'commons-lang' and 'test'. Note that we didn't specify the org for the dependency 'test'. When we exclude org, Ivy assumes it is in the same org as the declaring module. (i.e. 'org.apache').

	<h2>the <b>ivy settings</b></h2>
	The settings are defined in the ivysettings.xml file located in the settings directory of the project. Below are its contents, followed by an explanation of what it's doing.

	<code>
	<ivysettings>
	<settings defaultResolver="chain-example"/>
	<resolvers>
	<chain name="chain-example">
	<filesystem name="libraries">
	<artifact pattern="${ivy.settings.dir}/repository/[artifact]-[revision].[ext]" />
	</filesystem>
	<ibiblio name="ibiblio" m2compatible="true" />
	</chain>
	</resolvers>
	</ivysettings>
	</code>
	<h2>the <b>settings</b> tag</h2>
	This tag initializes Ivy with some parameters. Here only one parameter is set, the name of the resolver to use by default.

	<h2>the <b>resolvers</b> tag</h2>
	The resolvers section defines the list of resolvers that Ivy will use to locate artifacts. In our example, we have only one resolver named "chain-example", which is unique in that it defines a list (hence a chain) of resolvers.
	The resolvers in this chain are:
	<ul>
	<li>libraries : It is a filesystem resolver, so looks at a directory structure to retrieve the artifacts. This one is configured to look in the <tt>repository</tt> sub directory of the directory that contains the <tt>ivysettings.xml</tt> file.</li>
	<li>ibiblio : It looks in the ibiblio maven repository to retrieve the artifacts.</li>
	</ul>

	That's it, we have just configured a chain of resolvers!

	<h1>walkthrough</h1>
	<div class="step">
	<h2>step 1: preparation</h2>
	Open a DOS or shell window, and go to the "chained-resolvers" directory.
	</div>
	<div class="step">
	<h2>step 2: clean directory tree</h2>
	On the prompt type: ant<br>
	This will clean up the entire project directory tree and Ivy cache. You can do this each time you want to clean up this example.

	<div class="tip">
	In almost all examples, we provide a clean target as default target. Since most examples use the same Ivy cache, you will clean the whole Ivy cache each time you call this target.

	Cleaning the Ivy cache is something you can do without fear (except performance): it's only a cache, so everything can be (and should be) obtained again from repositories. This may sound strange to those coming from maven 2 land. But remember that in Ivy, the cache is not a local repository and the two are completely isolated.
	</div>
	</div>
	<div class="step">
	<h2>step 3: run the project</h2>
	Go to <tt>chained-resolvers</tt> project directory. And simply run <tt>ant</tt>.

	<div class="shell"><pre>
	[<tutorial/log/chained-resolvers.txt>]
	</pre></div></div>

	We can see in the log of the resolve task, that the two dependencies have been retrieved (2 artifacts) and copied to the Ivy cache directory (2 downloaded).

	Also notice that the 'run' Ant target succeeded in using both commons-lang.jar coming from the ibiblio repository and test.jar coming from the local repository.

	<h1>Going further</h1>
	This very simple example helps us see how to set up two resolvers in a chain. The [[resolver/chain chain resolver's reference documentation]] is available for those who would like to know all the features offered by this resolver.

	Below are a few more interesting things worth knowing about chain resolvers. After reading them, go ahead and try tweaking this example using your new wealth of knowledge!
	<ul>
	<li>a chain is not limited to two nested resolvers, you can use as many as you want</li>
	<li>by setting <tt>returnFirst="true"</tt>, you can have a chain which stops as soon as it has found a result for a given module</li>
	<li>by setting <tt>dual="true"</tt>, the full chain will be used both for module descriptors and artifacts, while setting <tt>dual="false"</tt>, the resolver in the chain which found the module descriptor (if any) is also used for artifacts</li>
	</ul>

	</textarea>
	<script type="text/javascript">xooki.postProcess();</script>
	</body>
	</html>