ResolveEngine
Date: 2014-12-13

org.apache.ivy.core.resolve

## Class ResolveEngine

- java.lang.Object
- - org.apache.ivy.core.resolve.ResolveEngine

-     public class ResolveEngine
      extends java.lang.Object

  The resolve engine which is the core of the dependency resolution mechanism used in Ivy. It features several resolve methods, some very simple, like `resolve(File)` and `resolve(URL)` which allow to simply resolve dependencies of a single module descriptor, or more complete one, like the `resolve(ModuleDescriptor, ResolveOptions)` which allows to provide options to the resolution engine.
  See Also:
    `ResolveOptions`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ResolveEngine(ResolveEngineSettings settings, EventManager eventManager, SortEngine sortEngine)` Constructs a ResolveEngine.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ArtifactDownloadReport` | `download(Artifact artifact, DownloadOptions options)` Download an artifact to the cache.
    `ArtifactDownloadReport` | `download(ArtifactOrigin origin, DownloadOptions options)` Materialize an artifact already located.
    `void` | `downloadArtifacts(ResolveReport report, Filter artifactFilter, DownloadOptions options)`
    `ResolvedModuleRevision` | `findModule(ModuleRevisionId id, ResolveOptions options)`
    `IvyNode[]` | `getDependencies(ModuleDescriptor md, ResolveOptions options, ResolveReport report)` Resolve the dependencies of a module without downloading corresponding artifacts.
    `IvyNode[]` | `getDependencies(java.net.URL ivySource, ResolveOptions options)` Resolve the dependencies of a module without downloading corresponding artifacts.
    `DependencyResolver` | `getDictatorResolver()` Returns the currently configured dictator resolver, which when non null is used in place of any specified resolver in the `IvySettings`
    `EventManager` | `getEventManager()`
    `ResolveEngineSettings` | `getSettings()`
    `SortEngine` | `getSortEngine()`
    `ArtifactOrigin` | `locate(Artifact artifact)` Locates an artifact in dependency resolvers, and return its location if it can be located and actually exists, or an unknown `ArtifactOrigin` in other cases.
    `DependencyDescriptor` | `mediate(DependencyDescriptor dd, ResolveOptions options)` Mediates the given dependency descriptor according to given options.
    `void` | `outputReport(ResolveReport report, ResolutionCacheManager cacheMgr, ResolveOptions options)`
    `ResolveReport` | `resolve(java.io.File ivySource)`
    `ResolveReport` | `resolve(ModuleDescriptor md, ResolveOptions options)` Resolve dependencies of a module described by a module descriptor.
    `ResolveReport` | `resolve(ModuleRevisionId mrid, ResolveOptions options, boolean changing)` Resolves the module identified by the given mrid with its dependencies if transitive is set to true.
    `ResolveReport` | `resolve(java.net.URL ivySource)`
    `ResolveReport` | `resolve(java.net.URL ivySource, ResolveOptions options)` Resolve dependencies of a module described by an ivy file.
    `void` | `setDictatorResolver(DependencyResolver dictatorResolver)` Sets a dictator resolver, which is used in place of regular dependency resolver for subsequent dependency resolution by this engine.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### ResolveEngine

          public ResolveEngine(ResolveEngineSettings settings,
                       EventManager eventManager,
                       SortEngine sortEngine)

      Constructs a ResolveEngine.
      Parameters:
        `settings` - the settings to use to configure the engine. Must not be null.
        `eventManager` - the event manager to use to send events about the resolution process. Must not be null.
        `sortEngine` - the sort engine to use to sort modules before producing the dependency resolution report. Must not be null.

  - ### Method Detail

    - #### getDictatorResolver

          public DependencyResolver getDictatorResolver()

      Returns the currently configured dictator resolver, which when non null is used in place of any specified resolver in the `IvySettings`
      Returns:
        the currently configured dictator resolver, may be null.

    - #### setDictatorResolver

          public void setDictatorResolver(DependencyResolver dictatorResolver)

      Sets a dictator resolver, which is used in place of regular dependency resolver for subsequent dependency resolution by this engine.
      Parameters:
        `dictatorResolver` - the dictator resolver to use in this engine, null if regular settings should used

    - #### 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

      Resolves the module identified by the given mrid with its dependencies if transitive is set to true.
      Throws:
        `java.text.ParseException`
        `java.io.IOException`

    - #### resolve

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

      Resolve dependencies of a module described by an ivy file.
      Throws:
        `java.text.ParseException`
        `java.io.IOException`

    - #### resolve

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

      Resolve dependencies of a module described by a module descriptor.
      Throws:
        `java.text.ParseException`
        `java.io.IOException`

    - #### outputReport

          public void outputReport(ResolveReport report,
                          ResolutionCacheManager cacheMgr,
                          ResolveOptions options)
                            throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### downloadArtifacts

          public void downloadArtifacts(ResolveReport report,
                               Filter artifactFilter,
                               DownloadOptions options)

    - #### download

          public ArtifactDownloadReport download(Artifact artifact,
                                        DownloadOptions options)

      Download an artifact to the cache. Not used internally, useful especially for IDE plugins needing to download artifact one by one (for source or javadoc artifact, for instance).

      Downloaded artifact file can be accessed using `ArtifactDownloadReport.getLocalFile()`.

      It is possible to track the progression of the download using classical ivy progress monitoring feature (see addTransferListener).

      Parameters:
        `artifact` - the artifact to download
      Returns:
        a report concerning the download
      See Also:
        `download(ArtifactOrigin, DownloadOptions)`

    - #### locate

          public ArtifactOrigin locate(Artifact artifact)

      Locates an artifact in dependency resolvers, and return its location if it can be located and actually exists, or an unknown `ArtifactOrigin` in other cases.
      Parameters:
        `artifact` - the artifact to locate.
      Returns:
        the artifact location, should be tested with `ArtifactOrigin.isUnknown(ArtifactOrigin)` to check if the artifact has actually been located.

    - #### download

          public ArtifactDownloadReport download(ArtifactOrigin origin,
                                        DownloadOptions options)

      Materialize an artifact already located.

      Not used internally, useful especially for IDE plugins needing to download artifact one by one (for source or javadoc artifact, for instance).

      Materialized artifact file can be accessed using `ArtifactDownloadReport.getLocalFile()`.

      It is possible to track the progression of the download using classical ivy progress monitoring feature (see addTransferListener).

      Parameters:
        `origin` - the artifact origin to materialize
      Returns:
        a report concerning the download
      See Also:
        `download(Artifact, DownloadOptions)`, `locate(Artifact)`

    - #### getDependencies

          public IvyNode[] getDependencies(java.net.URL ivySource,
                                  ResolveOptions options)
                                    throws java.text.ParseException,
                                           java.io.IOException

      Resolve the dependencies of a module without downloading corresponding artifacts. The module to resolve is given by its ivy file URL. This method requires appropriate configuration of the ivy instance, especially resolvers.
      Parameters:
        `ivySource` - url of the ivy file to use for dependency resolving
        `confs` - an array of configuration names to resolve - must not be null nor empty
        `getCache` - the cache to use - default cache is used if null
        `date` - the date to which resolution must be done - may be null
      Returns:
        an array of the resolved dependencies
      Throws:
        `java.text.ParseException` - if a parsing problem occurred in the ivy file
        `java.io.IOException` - if an IO problem was raised during ivy file parsing

    - #### getDependencies

          public IvyNode[] getDependencies(ModuleDescriptor md,
                                  ResolveOptions options,
                                  ResolveReport report)

      Resolve the dependencies of a module without downloading corresponding artifacts. The module to resolve is given by its module descriptor. This method requires appropriate configuration of the ivy instance, especially resolvers.

      The `IvyNode`s are ordered from the most dependent to the less dependent, so that an IvyNode is always found in the list after all IvyNode depending directly on it.

      Parameters:
        `md` - the descriptor of the module for which we want to get dependencies - must not be null
        `options` - the resolve options to use to resolve the dependencies
        `report` - a resolve report to fill during resolution - may be null
      Returns:
        an array of the resolved Dependencies

    - #### findModule

          public ResolvedModuleRevision findModule(ModuleRevisionId id,
                                          ResolveOptions options)

    - #### mediate

          public DependencyDescriptor mediate(DependencyDescriptor dd,
                                     ResolveOptions options)

      Mediates the given dependency descriptor according to given options.

      The mediated dependency descriptor must return the actually requested module revision id when the method `DependencyDescriptor.getDependencyRevisionId()` is called.

      Parameters:
        `dd` - the dependency descriptor for which the requested module revision id should be returned
        `options` - the resolve options to use
      Returns:
        the mediated `DependencyDescriptor`.

    - #### getEventManager

          public EventManager getEventManager()

    - #### getSettings

          public ResolveEngineSettings getSettings()

    - #### getSortEngine

          public SortEngine getSortEngine()