resolving javadoc files with Ant and Ivy

Question

I'd like Ivy to fetch both the log4j .jar and JavaDocs. Right now, I am at a dead end. When If I use this in my ivy.xml ...

<dependency org="log4j" name="log4j" rev="1.2.16"/>

... then I just get the .jar file. But when using this ivysettings.xml ...

<?xml version="1.0" encoding="UTF-8"?>
<ivysettings>
    <settings  
            defaultResolver="default"
            defaultConflictManager="all" />
    <resolvers>
        <url name="default" m2compatible="true">
            <artifact pattern="http://repo1.maven.org/maven2/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]"/>
            <artifact pattern="http://repo2.maven.org/maven2/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]"/>
        </url>
    </resolvers>
</ivysettings>

... and this ivy.xml ...

<?xml version="1.0" encoding="UTF-8"?>
<ivy-module version="2.0" 
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:noNamespaceSchemaLocation="http://ant.apache.org/ivy/schemas/ivy.xsd">
    <info organisation="foo" module="bar"/>
    <dependencies>
        <dependency org="log4j" name="log4j" rev="1.2.16">
            <artifact name="log4j" type="jar" ext="jar"/>
            <artifact name="log4j" type="javadoc" ext="jar"/> 
        </dependency>
    </dependencies>
</ivy-module>

... then I get this error message: java.lang.RuntimeException: Multiple artifacts of the module log4j#log4j;1.2.16 are retrieved to the same file! Update the retrieve pattern to fix this error.

What I am missing here? How can I get Ivy to resolve both the JavaDoc and the .jar files?

edit: Thanks for all the fast and detailed responses so far. This is my updated ivy.xml:

<?xml version="1.0" encoding="UTF-8"?>
<ivy-module version="2.0" 
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:noNamespaceSchemaLocation=
                   "http://ant.apache.org/ivy/schemas/ivy.xsd">
    <info organisation="foo" module="bar"/>
    <configurations>
        <conf name="default" visibility="public"/>
        <conf name="compile" visibility="public"/>
        <conf name="master"  visibility="public"/>
        <conf name="javadoc" visibility="public"/>
    </configurations>

    <dependencies>
        <dependency org="log4j"             name="log4j"       rev="1.2.16" conf="default->master,javadoc"/>
        <dependency org="javax.servlet"     name="servlet-api" rev="2.5" />
        <dependency org="com.someother"     name="proprietary-core" rev="1.2.3" force="true"/>
        <dependency org="com.someother"     name="proprietary" rev="1.2.3" force="true"/>
        <dependency org="com.someother"     name="scanner"     rev="1.0"   force="true"/>
    </dependencies>
</ivy-module>

Now I get this error message:

Buildfile: D:\workspace\foobar\build.xml

resolve:
[ivy:retrieve] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] :: loading settings :: file = D:\workspace\foobar\ivysettings.xml
[ivy:retrieve] :: resolving dependencies :: foo#bar;working@myhost
[ivy:retrieve]  confs: [default, compile, master, javadoc]
[ivy:retrieve]  found log4j#log4j;1.2.16 in internal
[ivy:retrieve]  found javax.servlet#servlet-api;2.5 in internal
[ivy:retrieve]  found com.someother#proprietary-core;1.2.3 in internal
[ivy:retrieve]  found com.someother#proprietary;1.2.3 in internal
[ivy:retrieve]  found com.someother#scanner;1.0 in internal
[ivy:retrieve] :: resolution report :: resolve 332ms :: artifacts dl 10ms
    ---------------------------------------------------------------------
    |                  |            modules            ||   artifacts   |
    |       conf       | number| search|dwnlded|evicted|| number|dwnlded|
    ---------------------------------------------------------------------
    |      default     |   5   |   0   |   0   |   0   ||   4   |   0   |
    |      compile     |   4   |   0   |   0   |   0   ||   4   |   0   |
    |      master      |   4   |   0   |   0   |   0   ||   4   |   0   |
    |      javadoc     |   4   |   0   |   0   |   0   ||   4   |   0   |
    ---------------------------------------------------------------------
[ivy:retrieve] 
[ivy:retrieve] :: problems summary ::
[ivy:retrieve] :::: WARNINGS
[ivy:retrieve]      ::::::::::::::::::::::::::::::::::::::::::::::
[ivy:retrieve]      ::          UNRESOLVED DEPENDENCIES         ::
[ivy:retrieve]      ::::::::::::::::::::::::::::::::::::::::::::::
[ivy:retrieve]      :: log4j#log4j;1.2.16: configuration not found in log4j#log4j;1.2.16: 'master'. It was required from foo#bar;working@myhost default
[ivy:retrieve]      ::::::::::::::::::::::::::::::::::::::::::::::
[ivy:retrieve] 
[ivy:retrieve] 
[ivy:retrieve] :: USE VERBOSE OR DEBUG MESSAGE LEVEL FOR MORE DETAILS

There seems to be a problem with the Maven scopes. But what exactly am I missing here?

Answer 1

The problem is the pattern you are using in the ivy retrieve task. It needs to include the optional "classifier" attribute to ensure the file name is unique:

<ivy:retrieve pattern="lib/[conf]/[artifact](-[classifier]).[ext]"/>

Classifier is a Maven thing, is used to identify additional artefacts associated with a Maven module.

Additional observation

No need for complicated ivy settings. Configuration mappings control which artefacts are downloaded from other modules.

Remove the ivysettings.xml file and try the following in your ivy.xml:

<dependency org="log4j" name="log4j" rev="1.2.16" conf="default->master,javadoc"/>

This results in the following files being downloaded:

• log4j-1.2.16.jar
• log4j-1.2.16-javadoc.jar

How does it work?

For Maven modules ivy creates a configuration matching each of the standard Maven scopes:

• master : Main jar only
• compile : main jar, plus jars used for compile (This is also the "default" scope)
• runtime : Main jar, plus jars used for compile, runtime
• test : Main jar, plus jars used for compile, runtime, test

and additionally creates a configuration for each additional artefact (or classifier) published by the module:

• sources
• javadoc

This enables you to mix and match.