Package: groovy.grape.ivy

## [Groovy] Class GrapeIvy

- groovy.grape.ivy.GrapeIvy

- All Implemented Interfaces and Traits:
    GrapeEngine

      @AutoFinal
      @CompileStatic
      class GrapeIvy
      extends Object
      implements GrapeEngine

  Implementation supporting `@Grape` and `@Grab` annotations based on Ivy.

- - ### Properties Summary

    Properties
    Type | Name and description
    --- | ---
    `Set<String>` | `downloadedArtifacts` Artifact files downloaded during the last resolution.
    `boolean` | `enableGrapes` Enables or disables grape resolution.
    `Set<IvyGrabRecord>` | `grabRecordsForCurrDependencies` Stores the IvyGrabRecord(s) for all dependencies in each grab() call.
    `Ivy` | `ivyInstance` Active Ivy instance used for dependency resolution.
    `Map<ClassLoader, Set<IvyGrabRecord>>` | `loadedDeps` Dependencies loaded into each class loader.
    `Set<String>` | `resolvedDependencies` Module revisions resolved during the last resolution.
    `IvySettings` | `settings` Ivy settings backing this engine.

  - ### Constructor Summary

    Constructors
    Constructor and description
    `GrapeIvy()` Creates an Ivy-backed grape engine.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `void` | `addResolver(Map<String, Object> args)` Adds a resolver to the front of the Ivy resolver chain.
    `` | `ClassLoader` | `chooseClassLoader(Map args)` Chooses the target class loader for a grab operation.
    `` | `IvyGrabRecord` | `createGrabRecord(Map dep)` Converts dependency coordinates into an Ivy grab record.
    `` | `Map<String, Map<String, List<String>>>` | `enumerateGrapes()` Enumerates cached grapes by group, module, and version.
    `` | `ResolveReport` | `getDependencies(Map args, IvyGrabRecord[] grabRecords)` Resolves the supplied grab records with Ivy.
    `` | `File` | `getGrapeCacheDir()` Returns the cache directory used for downloaded artifacts.
    `` | `File` | `getGrapeDir()` Returns the root directory used by grape.
    `` | `File` | `getGroovyRoot()` Returns the configured Groovy home directory for grape state.
    `` | `File` | `getLocalGrapeConfig()` Returns the local Ivy grape configuration file.
    `` | `Object` | `grab(String endorsedModule)` Grabs the endorsed module for the current Groovy version.
    `` | `Object` | `grab(Map args)` Grabs a dependency described by a single argument map.
    `` | `Object` | `grab(Map args, Map[] dependencies)` Grabs one or more dependencies and adds them to the target class loader.
    `` | `Map[]` | `listDependencies(ClassLoader classLoader)` Lists dependencies already loaded into the supplied class loader.
    `` | `IvyListener` | `makeIvyListener(Closure c)` Creates an Ivy listener from a progress closure.
    `` | `URI[]` | `resolve(Map args, Map[] dependencies)` Resolves dependencies using the implicit target class loader.
    `` | `URI[]` | `resolve(Map args, List depsInfo, Map[] dependencies)` Resolves dependencies and optionally collects dependency metadata.
    `` | `URI[]` | `resolve(ClassLoader loader, Map args, Map[] dependencies)` Resolves dependencies for an explicit class loader.
    `` | `URI[]` | `resolve(ClassLoader loader, Map args, List depsInfo, Map[] dependencies)` Resolves dependencies for an explicit class loader and optional metadata sink.
    `` | `URL` | `resolveGrapeConfigUrl()` Resolves the active Grape Ivy config URL.
    `` | `void` | `setLoggingLevel(int level)` Sets the Ivy logging verbosity.
    `` | `void` | `uninstallArtifact(String group, String module, String rev)` Removes a cached artifact version from the grape cache.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Property Detail

    - #### Set<String> downloadedArtifacts

      Artifact files downloaded during the last resolution.

    - #### boolean enableGrapes

      Enables or disables grape resolution.

    - #### final Set<IvyGrabRecord> grabRecordsForCurrDependencies

      Stores the IvyGrabRecord(s) for all dependencies in each grab() call.

    - #### Ivy ivyInstance

      Active Ivy instance used for dependency resolution.

    - #### final Map<ClassLoader, Set<IvyGrabRecord>> loadedDeps

      Dependencies loaded into each class loader.

    - #### Set<String> resolvedDependencies

      Module revisions resolved during the last resolution.

    - #### IvySettings settings

      Ivy settings backing this engine.

  - ### Constructor Detail

    - #### GrapeIvy()

      Creates an Ivy-backed grape engine.

  - ### Method Detail

    - #### @Override
      void addResolver(@NamedParams(value=[@NamedParam(value="name", type=String, required=true), @NamedParam(value="root", type=String, required=true), @NamedParam(value="m2Compatible", type=Boolean, required=false)])
      Map<String, Object> args)

      Adds a resolver to the front of the Ivy resolver chain.

      Parameters:
        `args` - the resolver configuration

    - #### ClassLoader chooseClassLoader(Map args)

      Chooses the target class loader for a grab operation.

      Parameters:
        `args` - grab arguments
      Returns:
        the chosen class loader

    - #### IvyGrabRecord createGrabRecord(Map dep)

      Converts dependency coordinates into an Ivy grab record.

      Parameters:
        `dep` - the dependency map
      Returns:
        the corresponding grab record

    - #### @Override
      Map<String, Map<String, List<String>>> enumerateGrapes()

      Enumerates cached grapes by group, module, and version.

      Returns:
        the cached grape coordinates

    - #### ResolveReport getDependencies(Map args, IvyGrabRecord[] grabRecords)

      Resolves the supplied grab records with Ivy.

      Parameters:
        `args` - the resolution arguments
        `grabRecords` - the dependencies to resolve
      Returns:
        the Ivy resolve report

    - #### File getGrapeCacheDir()

      Returns the cache directory used for downloaded artifacts.

      Returns:
        the grape cache directory

    - #### File getGrapeDir()

      Returns the root directory used by grape.

      Returns:
        the grape root directory

    - #### File getGroovyRoot()

      Returns the configured Groovy home directory for grape state.

      Returns:
        the Groovy home directory

    - #### File getLocalGrapeConfig()

      Returns the local Ivy grape configuration file.

      Retained for backwards compatibility — only honors filesystem-path forms of `-Dgrape.config`. The runtime now resolves the active config through resolveGrapeConfigUrl, which additionally accepts the `relaxed`, `default`, and `classpath:<resource>` shorthand forms.

      Returns:
        the grape configuration file (may not exist on disk)

    - #### @Override
      Object grab(String endorsedModule)

      Grabs the endorsed module for the current Groovy version.

      Parameters:
        `endorsedModule` - the endorsed module name

    - #### @Override
      Object grab(Map args)

      Grabs a dependency described by a single argument map.

      Parameters:
        `args` - the grab arguments
      Returns:
        the grab result or exception when suppressed

    - #### @Override
      Object grab(Map args, Map[] dependencies)

      Grabs one or more dependencies and adds them to the target class loader.

      Parameters:
        `args` - the shared grab arguments
        `dependencies` - the dependency descriptors
      Returns:
        `null` on success or the suppressed exception

    - #### @Override
      Map[] listDependencies(ClassLoader classLoader)

      Lists dependencies already loaded into the supplied class loader.

      Parameters:
        `classLoader` - the class loader to inspect
      Returns:
        the loaded dependency descriptors

    - #### IvyListener makeIvyListener(Closure c)

      Creates an Ivy listener from a progress closure.

      Parameters:
        `c` - the progress callback
      Returns:
        the corresponding Ivy listener

    - #### @Override
      URI[] resolve(Map args, Map[] dependencies)

      Resolves dependencies using the implicit target class loader.

      Parameters:
        `args` - the resolution arguments
        `dependencies` - the dependencies to resolve
      Returns:
        the resolved artifact URIs

    - #### @Override
      URI[] resolve(Map args, List depsInfo, Map[] dependencies)

      Resolves dependencies and optionally collects dependency metadata.

      Parameters:
        `args` - the resolution arguments
        `depsInfo` - the optional dependency metadata sink
        `dependencies` - the dependencies to resolve
      Returns:
        the resolved artifact URIs

    - #### URI[] resolve(ClassLoader loader, Map args, Map[] dependencies)

      Resolves dependencies for an explicit class loader.

      Parameters:
        `loader` - the target class loader
        `args` - the resolution arguments
        `dependencies` - the dependencies to resolve
      Returns:
        the resolved artifact URIs

    - #### URI[] resolve(ClassLoader loader, Map args, List depsInfo, Map[] dependencies)

      Resolves dependencies for an explicit class loader and optional metadata sink.

      Parameters:
        `loader` - the target class loader
        `args` - the resolution arguments
        `depsInfo` - the optional dependency metadata sink
        `dependencies` - the dependencies to resolve
      Returns:
        the resolved artifact URIs

    - #### URL resolveGrapeConfigUrl()

      Resolves the active Grape Ivy config URL.

      Precedence:

      1. `-Dgrape.config=<value>` — see resolveExplicitConfig. If the value is set but cannot be resolved, a `WARNING` is logged and the method returns null so the caller falls back to `defaultGrapeConfig.xml`. (This matches the existing semantics where a missing sys-prop file bypasses `~/.groovy/grapeConfig.xml`.)
      2. `~/.groovy/grapeConfig.xml` (or the configured grape dir).
      3. `null` — caller is expected to fall back to `defaultGrapeConfig.xml`.
      Returns:
        the resolved config URL, or null if no override was selected

    - #### @Override
      void setLoggingLevel(int level)

      Sets the Ivy logging verbosity.

      Parameters:
        `level` - the grape logging level

    - #### void uninstallArtifact(String group, String module, String rev)

      Removes a cached artifact version from the grape cache.

      Parameters:
        `group` - the artifact group
        `module` - the artifact module
        `rev` - the artifact revision