ComponentMetadataHandler (Gradle API 2.14)
Date: 2016-06-14

Package: org.gradle.api.artifacts.dsl

## [Java] Interface ComponentMetadataHandler

- Allows the build to provide rules that modify the metadata of depended-on software components.

  Possible uses of component metadata rules are:

  - Setting the status and status scheme of a component, overriding the value specified in the component descriptor.
  - Declaring whether or not a component is 'changing', thus impacting the cache behaviour of the component.

  Example:

       dependencies {
           components {
               // Set the status and status scheme for every component belonging to a module in the group "org.foo"
               all { ComponentMetadataDetails details ->
                   if (details.id.group == "org.foo") {
                       def version = details.id.version
                       // assuming status is last part of version string
                       details.status = version.substring(version.lastIndexOf("-") + 1)
                       details.statusScheme = ["bronze", "silver", "gold", "platinum"]
                   }
               }

               // Treat all components in the module "org.foo:bar" as changing
               withModule("org.foo:bar") { ComponentMetadataDetails details ->
                   details.changing = true
               }
           }
       }

  Since:
    1.8

- - ### Methods Summary

    Methods
    Type | Name and description
    --- | ---
    `ComponentMetadataHandler` | `all(Action<? super ComponentMetadataDetails> rule)` Adds a rule action that may modify the metadata of any resolved software component.
    `ComponentMetadataHandler` | `all(groovy.lang.Closure<?> rule)` Adds a rule closure that may modify the metadata of any resolved software component.
    `ComponentMetadataHandler` | `all(Object ruleSource)` Adds a rule that may modify the metadata of any resolved software component.
    `ComponentMetadataHandler` | `withModule(Object id, Action<? super ComponentMetadataDetails> rule)` Adds a rule that may modify the metadata of any resolved software component belonging to the specified module.
    `ComponentMetadataHandler` | `withModule(Object id, groovy.lang.Closure<?> rule)` Adds a rule that may modify the metadata of any resolved software component belonging to the specified module.
    `ComponentMetadataHandler` | `withModule(Object id, Object ruleSource)` Adds a rule that may modify the metadata of any resolved software component belonging to the specified module.

- - ### Method Detail

    - #### public ComponentMetadataHandler all(Action<? super ComponentMetadataDetails> rule)

      Adds a rule action that may modify the metadata of any resolved software component.

      Parameters:
        `rule` - the rule to be added
      Returns:
        this

    - #### public ComponentMetadataHandler all(groovy.lang.Closure<?> rule)

      Adds a rule closure that may modify the metadata of any resolved software component.

      The supplied rule closure must declare a ComponentMetadataDetails as it's first parameter, allowing the component metadata to be modified.

      In addition, the rule can declare additional (read-only) parameters, which may provide extra details about the component. The order of these additional parameters is not significant.

      The following additional parameter types are supported:

      - IvyModuleDescriptor - additional Ivy-specific metadata. Rules declaring this parameter will only be invoked for components packaged as an Ivy module.
      Parameters:
        `rule` - the rule to be added
      Returns:
        this

    - #### public ComponentMetadataHandler all(Object ruleSource)

      Adds a rule that may modify the metadata of any resolved software component.

      The ruleSource is an Object that has a single rule method annotated with Mutate.

      This rule method:

      - must return void.
      - must have ComponentMetadataDetails as the first parameter.
      - may have an additional parameter of type IvyModuleDescriptor.
      Parameters:
        `ruleSource` - the rule source object to be added
      Returns:
        this

    - #### public ComponentMetadataHandler withModule(Object id, Action<? super ComponentMetadataDetails> rule)

      Adds a rule that may modify the metadata of any resolved software component belonging to the specified module.

      Parameters:
        `id` - the module to apply this rule to in "group:module" format or as a ModuleIdentifier
        `rule` - the rule to be added
      Returns:
        this

    - #### public ComponentMetadataHandler withModule(Object id, groovy.lang.Closure<?> rule)

      Adds a rule that may modify the metadata of any resolved software component belonging to the specified module.

      The rule closure parameter is subject to the same requirements as all(groovy.lang.Closure).

      Parameters:
        `id` - the module to apply this rule to in "group:module" format or as a ModuleIdentifier
        `rule` - the rule to be added
      Returns:
        this

    - #### public ComponentMetadataHandler withModule(Object id, Object ruleSource)

      Adds a rule that may modify the metadata of any resolved software component belonging to the specified module.

      The rule source parameter is subject to the same requirements as all(Object).

      Parameters:
        `id` - the module to apply this rule to in "group:module" format or as a ModuleIdentifier
        `ruleSource` - the rule source object to be added
      Returns:
        this