org.apache.ivy
Class Ivy

java.lang.Object
  extended by org.apache.ivy.Ivy

public class Ivy
extends java.lang.Object

Ivy is a free java based dependency manager.

This class is the main class of Ivy, which acts as a Facade to all services offered by Ivy:

Here is one typical usage:
 Ivy ivy = Ivy.newInstance();
 ivy.configure(new URL("ivysettings.xml"));
 ivy.resolve(new URL("ivy.xml"));
 

Using Ivy engines directly

If the methods offered by the Ivy class are not flexible enough and you want to use Ivy engines directly, you need to call the methods within a single IvyContext associated to the Ivy instance you use.
To do so, it is recommended to use the execute(org.apache.ivy.Ivy.IvyCallback) method like this:

 Ivy ivy = Ivy.newInstance();
 ivy.execute(new IvyCallback() {
     public Object doInIvyContext(Ivy ivy, IvyContext context) {
         // obviously we can use regular Ivy methods in the callback 
         ivy.configure(new URL("ivysettings.xml"));
         // and we can safely use Ivy engines too
         ivy.getResolveEngine().resolve(new URL("ivy.xml"));
         return null;
     }
 });
 


Nested Class Summary
static interface Ivy.IvyCallback
          Callback used to execute a set of Ivy related methods within an IvyContext.
 
Field Summary
static java.text.SimpleDateFormat DATE_FORMAT
           
 
Constructor Summary
Ivy()
          The default constructor of Ivy allows to create an instance of Ivy with none of its dependencies (engines, settings, ...) created.
 
Method Summary
 void bind()
          This method is used to bind this Ivy instance to required dependencies, i.e.
 boolean check(java.net.URL ivyFile, java.lang.String resolvername)
           
 void checkInterrupted()
          Check if the current operation has been interrupted, and if it is the case, throw a runtime exception
 void configure(java.io.File settingsFile)
           
 void configure(java.net.URL settingsURL)
           
 void configureDefault()
           
 void configureDefault14()
          Configures Ivy with 1.4 compatible default settings
 void deliver(ModuleRevisionId mrid, java.lang.String revision, java.lang.String destIvyPattern)
           
 void deliver(ModuleRevisionId mrid, java.lang.String revision, java.lang.String destIvyPattern, DeliverOptions options)
          Example of use: deliver(mrid, "1.5", "target/ivy/ivy-[revision].xml", DeliverOptions.newInstance(settings).setStatus("release").setValidate(false));
 void deliver(java.lang.String revision, java.lang.String destIvyPattern, DeliverOptions options)
           
 java.lang.Object execute(Ivy.IvyCallback callback)
          Executes the given callback in the context of this Ivy instance.
 ResolvedModuleRevision findModule(ModuleRevisionId mrid)
           
 CheckEngine getCheckEngine()
           
 DeliverEngine getDeliverEngine()
           
 EventManager getEventManager()
           
 InstallEngine getInstallEngine()
           
static java.lang.String getIvyDate()
          Returns the date at which this version of Ivy has been built.
static java.lang.String getIvyHomeURL()
          Returns the URL at which Ivy web site can be found.
static java.lang.String getIvyVersion()
          Returns the current version of Ivy, as displayed on the console when Ivy is initialized.
 MessageLoggerEngine getLoggerEngine()
           
 PublishEngine getPublishEngine()
           
 RepositoryManagementEngine getRepositoryEngine()
           
 ResolutionCacheManager getResolutionCacheManager()
           
 ResolveEngine getResolveEngine()
           
 RetrieveEngine getRetrieveEngine()
           
 SearchEngine getSearchEngine()
           
 IvySettings getSettings()
           
 SortEngine getSortEngine()
           
 java.lang.String getVariable(java.lang.String name)
           
static java.lang.String getWorkingRevision()
           
 ResolveReport install(ModuleRevisionId mrid, java.lang.String from, java.lang.String to, InstallOptions options)
           
 void interrupt()
          Interrupts the current running operation, no later than interruptTimeout milliseconds after the call
 void interrupt(java.lang.Thread operatingThread)
          Interrupts the current running operation in the given operating thread, no later than interruptTimeout milliseconds after the call
 boolean isInterrupted()
           
 ModuleEntry[] listModuleEntries(OrganisationEntry org)
           
 ModuleId[] listModules(ModuleId criteria, PatternMatcher matcher)
           
 ModuleRevisionId[] listModules(ModuleRevisionId criteria, PatternMatcher matcher)
           
 java.lang.String[] listModules(java.lang.String org)
           
 OrganisationEntry[] listOrganisationEntries()
           
 java.lang.String[] listOrganisations()
           
 RevisionEntry[] listRevisionEntries(ModuleEntry module)
           
 java.lang.String[] listRevisions(java.lang.String org, java.lang.String module)
           
 java.lang.String[] listTokenValues(java.lang.String token, java.util.Map otherTokenValues)
           
static Ivy newInstance()
           
static Ivy newInstance(IvySettings settings)
           
 void popContext()
          Pops the current Ivy context.
 java.util.Collection publish(ModuleRevisionId mrid, java.util.Collection srcArtifactPattern, java.lang.String resolverName, PublishOptions options)
           
 void pushContext()
          Pushes a new IvyContext bound to this Ivy instance if the current context is not already bound to this Ivy instance.
 ResolveReport resolve(java.io.File ivySource)
           
 ResolveReport resolve(ModuleDescriptor md, ResolveOptions options)
           
 ResolveReport resolve(ModuleRevisionId mrid, ResolveOptions options, boolean changing)
           
 ResolveReport resolve(java.net.URL ivySource)
           
 ResolveReport resolve(java.net.URL ivySource, ResolveOptions options)
           
 int retrieve(ModuleRevisionId mrid, java.lang.String destFilePattern, RetrieveOptions options)
           
 void setCheckEngine(CheckEngine checkEngine)
           
 void setDeliverEngine(DeliverEngine deliverEngine)
           
 void setEventManager(EventManager eventManager)
           
 void setInstallEngine(InstallEngine installEngine)
           
 void setPublishEngine(PublishEngine publishEngine)
           
 void setRepositoryEngine(RepositoryManagementEngine repositoryEngine)
           
 void setResolveEngine(ResolveEngine resolveEngine)
           
 void setRetrieveEngine(RetrieveEngine retrieveEngine)
           
 void setSearchEngine(SearchEngine searchEngine)
           
 void setSettings(IvySettings settings)
           
 void setSortEngine(SortEngine sortEngine)
           
 void setVariable(java.lang.String varName, java.lang.String value)
           
 java.util.List sortModuleDescriptors(java.util.Collection moduleDescriptors, SortOptions options)
          Sorts the given ModuleDescriptors from the less dependent to the more dependent.
 java.util.List sortNodes(java.util.Collection nodes, SortOptions options)
          Sorts the collection of IvyNode from the less dependent to the more dependent
 java.lang.String substitute(java.lang.String str)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DATE_FORMAT

public static final java.text.SimpleDateFormat DATE_FORMAT
Constructor Detail

Ivy

public Ivy()
The default constructor of Ivy allows to create an instance of Ivy with none of its dependencies (engines, settings, ...) created. If you use this constructor, it's your responsibility to set the dependencies of Ivy using the appropriate setters (setResolveEngine, ...). You can also call the bind method to set all the dependencies except those that you have provided using the setters. If you want to get an instance ready to use, prefer the use of Ivy.newInstance().

Method Detail

getIvyVersion

public static java.lang.String getIvyVersion()
Returns the current version of Ivy, as displayed on the console when Ivy is initialized.

Returns:
the current version of Ivy

getIvyDate

public static java.lang.String getIvyDate()
Returns the date at which this version of Ivy has been built.

May be empty if unknown.

Returns:
the date at which this version of Ivy has been built

getIvyHomeURL

public static java.lang.String getIvyHomeURL()
Returns the URL at which Ivy web site can be found.

Returns:
the URL at which Ivy web site can be found

newInstance

public static Ivy newInstance()

newInstance

public static Ivy newInstance(IvySettings settings)

bind

public void bind()
This method is used to bind this Ivy instance to required dependencies, i.e. instance of settings, engines, and so on.

After this call Ivy is still not configured, which means that the settings object is still empty.


execute

public java.lang.Object execute(Ivy.IvyCallback callback)
Executes the given callback in the context of this Ivy instance.

Alternatively you can use the pushContext() and popContext() methods, but this is not recommended:

 Object result = null;
 pushContext();
 try {
     result = callback.doInIvyContext(this, IvyContext.getContext());
 } finally {
     popContext();
 }
 doSomethingWithResult(result);
 

Parameters:
callback -
Returns:

pushContext

public void pushContext()
Pushes a new IvyContext bound to this Ivy instance if the current context is not already bound to this Ivy instance. If the current context is already bound to this Ivy instance, it pushes the current context on the context stack, so that you can (and must) always call popContext() when you're done.

Alternatively, you can use the execute(org.apache.ivy.Ivy.IvyCallback) method which takes care of everything for you.


popContext

public void popContext()
Pops the current Ivy context.

You must call this method once and only once for each call to pushContext(), when you're done with the your Ivy related work.

Alternatively, you can use the execute(org.apache.ivy.Ivy.IvyCallback) method which takes care of everything for you.


configure

public void configure(java.io.File settingsFile)
               throws java.text.ParseException,
                      java.io.IOException
Throws:
java.text.ParseException
java.io.IOException

configure

public void configure(java.net.URL settingsURL)
               throws java.text.ParseException,
                      java.io.IOException
Throws:
java.text.ParseException
java.io.IOException

configureDefault

public void configureDefault()
                      throws java.text.ParseException,
                             java.io.IOException
Throws:
java.text.ParseException
java.io.IOException

configureDefault14

public void configureDefault14()
                        throws java.text.ParseException,
                               java.io.IOException
Configures Ivy with 1.4 compatible default settings

Throws:
java.text.ParseException
java.io.IOException

check

public boolean check(java.net.URL ivyFile,
                     java.lang.String resolvername)

resolve

public ResolveReport resolve(java.io.File ivySource)
                      throws java.text.ParseException,
                             java.io.IOException
Throws:
java.text.ParseException
java.io.IOException

resolve

public ResolveReport resolve(java.net.URL ivySource)
                      throws java.text.ParseException,
                             java.io.IOException
Throws:
java.text.ParseException
java.io.IOException

resolve

public ResolveReport resolve(ModuleRevisionId mrid,
                             ResolveOptions options,
                             boolean changing)
                      throws java.text.ParseException,
                             java.io.IOException
Throws:
java.text.ParseException
java.io.IOException

resolve

public ResolveReport resolve(java.net.URL ivySource,
                             ResolveOptions options)
                      throws java.text.ParseException,
                             java.io.IOException
Throws:
java.text.ParseException
java.io.IOException

resolve

public ResolveReport resolve(ModuleDescriptor md,
                             ResolveOptions options)
                      throws java.text.ParseException,
                             java.io.IOException
Throws:
java.text.ParseException
java.io.IOException

install

public ResolveReport install(ModuleRevisionId mrid,
                             java.lang.String from,
                             java.lang.String to,
                             InstallOptions options)
                      throws java.io.IOException
Throws:
java.io.IOException

retrieve

public int retrieve(ModuleRevisionId mrid,
                    java.lang.String destFilePattern,
                    RetrieveOptions options)
             throws java.io.IOException
Throws:
java.io.IOException

deliver

public void deliver(ModuleRevisionId mrid,
                    java.lang.String revision,
                    java.lang.String destIvyPattern)
             throws java.io.IOException,
                    java.text.ParseException
Throws:
java.io.IOException
java.text.ParseException

deliver

public void deliver(java.lang.String revision,
                    java.lang.String destIvyPattern,
                    DeliverOptions options)
             throws java.io.IOException,
                    java.text.ParseException
Throws:
java.io.IOException
java.text.ParseException

deliver

public void deliver(ModuleRevisionId mrid,
                    java.lang.String revision,
                    java.lang.String destIvyPattern,
                    DeliverOptions options)
             throws java.io.IOException,
                    java.text.ParseException
Example of use: deliver(mrid, "1.5", "target/ivy/ivy-[revision].xml", DeliverOptions.newInstance(settings).setStatus("release").setValidate(false));

Parameters:
mrid -
revision -
destIvyPattern -
options -
Throws:
java.io.IOException
java.text.ParseException

publish

public java.util.Collection publish(ModuleRevisionId mrid,
                                    java.util.Collection srcArtifactPattern,
                                    java.lang.String resolverName,
                                    PublishOptions options)
                             throws java.io.IOException
Throws:
java.io.IOException

sortNodes

public java.util.List sortNodes(java.util.Collection nodes,
                                SortOptions options)
Sorts the collection of IvyNode from the less dependent to the more dependent


sortModuleDescriptors

public java.util.List sortModuleDescriptors(java.util.Collection moduleDescriptors,
                                            SortOptions options)
Sorts the given ModuleDescriptors from the less dependent to the more dependent. This sort ensures that a ModuleDescriptor is always found in the list before all ModuleDescriptors depending directly on it.

Parameters:
moduleDescriptors - a Collection of ModuleDescriptor to sort
options - Options to use to sort the descriptors.
Returns:
a List of sorted ModuleDescriptors
Throws:
CircularDependencyException - if a circular dependency exists and circular dependency strategy decide to throw an exception

findModule

public ResolvedModuleRevision findModule(ModuleRevisionId mrid)

listModuleEntries

public ModuleEntry[] listModuleEntries(OrganisationEntry org)

listModules

public ModuleId[] listModules(ModuleId criteria,
                              PatternMatcher matcher)

listModules

public ModuleRevisionId[] listModules(ModuleRevisionId criteria,
                                      PatternMatcher matcher)

listModules

public java.lang.String[] listModules(java.lang.String org)

listOrganisationEntries

public OrganisationEntry[] listOrganisationEntries()

listOrganisations

public java.lang.String[] listOrganisations()

listRevisionEntries

public RevisionEntry[] listRevisionEntries(ModuleEntry module)

listRevisions

public java.lang.String[] listRevisions(java.lang.String org,
                                        java.lang.String module)

listTokenValues

public java.lang.String[] listTokenValues(java.lang.String token,
                                          java.util.Map otherTokenValues)

interrupt

public void interrupt()
Interrupts the current running operation, no later than interruptTimeout milliseconds after the call


interrupt

public void interrupt(java.lang.Thread operatingThread)
Interrupts the current running operation in the given operating thread, no later than interruptTimeout milliseconds after the call


isInterrupted

public boolean isInterrupted()

checkInterrupted

public void checkInterrupted()
Check if the current operation has been interrupted, and if it is the case, throw a runtime exception


getWorkingRevision

public static java.lang.String getWorkingRevision()

getResolutionCacheManager

public ResolutionCacheManager getResolutionCacheManager()

getVariable

public java.lang.String getVariable(java.lang.String name)

substitute

public java.lang.String substitute(java.lang.String str)

setVariable

public void setVariable(java.lang.String varName,
                        java.lang.String value)

getSettings

public IvySettings getSettings()

getEventManager

public EventManager getEventManager()

getCheckEngine

public CheckEngine getCheckEngine()

setCheckEngine

public void setCheckEngine(CheckEngine checkEngine)

getDeliverEngine

public DeliverEngine getDeliverEngine()

setDeliverEngine

public void setDeliverEngine(DeliverEngine deliverEngine)

getInstallEngine

public InstallEngine getInstallEngine()

setInstallEngine

public void setInstallEngine(InstallEngine installEngine)

getPublishEngine

public PublishEngine getPublishEngine()

setPublishEngine

public void setPublishEngine(PublishEngine publishEngine)

getResolveEngine

public ResolveEngine getResolveEngine()

setResolveEngine

public void setResolveEngine(ResolveEngine resolveEngine)

getRetrieveEngine

public RetrieveEngine getRetrieveEngine()

setRetrieveEngine

public void setRetrieveEngine(RetrieveEngine retrieveEngine)

getSearchEngine

public SearchEngine getSearchEngine()

setSearchEngine

public void setSearchEngine(SearchEngine searchEngine)

getSortEngine

public SortEngine getSortEngine()

setSortEngine

public void setSortEngine(SortEngine sortEngine)

getRepositoryEngine

public RepositoryManagementEngine getRepositoryEngine()

setRepositoryEngine

public void setRepositoryEngine(RepositoryManagementEngine repositoryEngine)

setEventManager

public void setEventManager(EventManager eventManager)

setSettings

public void setSettings(IvySettings settings)

getLoggerEngine

public MessageLoggerEngine getLoggerEngine()