Ivy
Date: 2014-12-13

org.apache.ivy

## Class Ivy

- java.lang.Object
- - 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:

  - resolve dependencies
  - retrieve artifacts to a local location
  - deliver and publish modules
  - repository search and listing
  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

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `Ivy.IvyCallback` Callback used to execute a set of Ivy related methods within an `IvyContext`.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.text.SimpleDateFormat` | `DATE_FORMAT` Deprecated. Use the `DateUtil` utility class instead.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Ivy()` The default constructor of Ivy allows to create an instance of Ivy with none of its dependencies (engines, settings, ...) created.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `bind()` This method is used to bind this Ivy instance to required dependencies, i.e. instance of settings, engines, and so on.
    `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(java.io.File ivySource, ResolveOptions options)`
    `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)`
    `RetrieveReport` | `retrieve(ModuleRevisionId mrid, RetrieveOptions 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

          @Deprecated
          public static final java.text.SimpleDateFormat DATE_FORMAT

      Deprecated. Use the `DateUtil` utility class instead.

  - ### 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(java.io.File 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`

    - #### retrieve

          public RetrieveReport retrieve(ModuleRevisionId mrid,
                                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()