Package org.gradle.api.artifacts.dsl

# Interface ComponentMetadataHandler

@Incubating public 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

## Method Summary

Modifier and Type
Method
Description
`ComponentMetadataHandler`
`all(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`
`all(Action<? super ComponentMetadataDetails> rule)`
Adds a rule action that may modify the metadata of any resolved software component.
`ComponentMetadataHandler`
`withModule(Object id, 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.
`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.

## Method Details

### all

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

### all

ComponentMetadataHandler all(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

### all

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

### withModule

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

### withModule

ComponentMetadataHandler withModule(Object id, 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

### withModule

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