Package org.apache.sling.feature.builder

# Class BuilderContext

java.lang.Object
org.apache.sling.feature.builder.BuilderContext

public class BuilderContext extends Object
Builder context holds services and configuration used by `FeatureBuilder` and controls how features are assembled and aggregated.

When two features are merged, being it a prototype with the feature using the prototype or two features, there might be a clash with bundles or artifacts. A clash occurs when there is an artifact in the source and the target with different versions. If the version is the same, the source artifact will override the target artifact. However, all other cases need instructions on how to proceed.

An override rule is an artifact id. As the version for the rule, one of `VERSION_OVERRIDE_ALL`, `VERSION_OVERRIDE_LATEST` or `VERSION_OVERRIDE_FIRST` or `VERSION_OVERRIDE_HIGHEST` as well as any version can be specified. If the artifact id should match more than a single artifact `COORDINATE_MATCH_ALL` can be specified as group id, artifact id, type and/or classifier.

A clash might also happen with framework properties or variables. In this case an override must be provided for that variable or framework property as well.

This class is not thread-safe.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final String`
`CONFIG_FAIL_ON_CLASH`
Used to handle configuration merging - fail the merge when there is a clash for a PID - this is the default
`static final String`
`CONFIG_FAIL_ON_PROPERTY_CLASH`
Used to handle configuration merging - fail the merge only when there is a clash on a property level
`static final String`
`CONFIG_MERGE_FIRST`
Used to handle configuration merging - merge the first configuration in, latest props will not override previous values
`static final String`
`CONFIG_MERGE_LATEST`
Used to handle configuration merging - merge the latest configuration in, latest props might override previous values
`static final String`
`CONFIG_USE_FIRST`
Used to handle configuration merging - use the first configuration, don't merge
`static final String`
`CONFIG_USE_LATEST`
Used to handle configuration merging - use the latest configuration, but don't merge
`static final String`
`COORDINATE_MATCH_ALL`
Used in override rule to match all coordinates
`static final String`
`VERSION_OVERRIDE_ALL`
Used in override rule to select all candidates.
`static final String`
`VERSION_OVERRIDE_FIRST`
Used in override rule to select the first candidate applied.
`static final String`
`VERSION_OVERRIDE_HIGHEST`
Used in override rule to select the candidate with the highest version (OSGi version comparison rules).
`static final String`
`VERSION_OVERRIDE_LATEST`
Used in override rule to select the last candidate applied.

## Constructor Summary

Constructors
Constructor
Description
`BuilderContext(FeatureProvider provider)`
Create a new context.

## Method Summary

Modifier and Type
Method
Description
`BuilderContext`
`addArtifactsOverride(ArtifactId override)`
Add an override for artifact clashes.
`BuilderContext`
`addConfigsOverrides(Map<String,String> overrides)`
Add merge policies for configuration clashes.
`BuilderContext`
`addFrameworkPropertiesOverrides(Map<String,String> props)`
Add overrides for the framework properties.
`BuilderContext`
`addMergeExtensions(MergeHandler... extensions)`
Add merge extensions
`BuilderContext`
`addPostProcessExtensions(PostProcessHandler... extensions)`
Add post process extensions
`BuilderContext`
`addVariablesOverrides(Map<String,String> vars)`
Add overrides for the variables.
`BuilderContext`
`setArtifactProvider(ArtifactProvider ap)`
Set the artifact provider.
`BuilderContext`
`setHandlerConfiguration(String name, Map<String,String> cfg)`
Set a handler configuration.

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

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

## Field Details

### VERSION_OVERRIDE_ALL

public static final String VERSION_OVERRIDE_ALL
Used in override rule to select all candidates.

See Also:
  - Constant Field Values

### VERSION_OVERRIDE_HIGHEST

public static final String VERSION_OVERRIDE_HIGHEST
Used in override rule to select the candidate with the highest version (OSGi version comparison rules).

See Also:
  - Constant Field Values

### VERSION_OVERRIDE_LATEST

public static final String VERSION_OVERRIDE_LATEST
Used in override rule to select the last candidate applied.

See Also:
  - Constant Field Values

### VERSION_OVERRIDE_FIRST

public static final String VERSION_OVERRIDE_FIRST
Used in override rule to select the first candidate applied.

Since:
  1.3.0
See Also:
  - Constant Field Values

### COORDINATE_MATCH_ALL

public static final String COORDINATE_MATCH_ALL
Used in override rule to match all coordinates

See Also:
  - Constant Field Values

### CONFIG_FAIL_ON_CLASH

public static final String CONFIG_FAIL_ON_CLASH
Used to handle configuration merging - fail the merge when there is a clash for a PID - this is the default

See Also:
  - Constant Field Values

### CONFIG_FAIL_ON_PROPERTY_CLASH

public static final String CONFIG_FAIL_ON_PROPERTY_CLASH
Used to handle configuration merging - fail the merge only when there is a clash on a property level

See Also:
  - Constant Field Values

### CONFIG_USE_LATEST

public static final String CONFIG_USE_LATEST
Used to handle configuration merging - use the latest configuration, but don't merge

See Also:
  - Constant Field Values

### CONFIG_USE_FIRST

public static final String CONFIG_USE_FIRST
Used to handle configuration merging - use the first configuration, don't merge

See Also:
  - Constant Field Values

### CONFIG_MERGE_LATEST

public static final String CONFIG_MERGE_LATEST
Used to handle configuration merging - merge the latest configuration in, latest props might override previous values

See Also:
  - Constant Field Values

### CONFIG_MERGE_FIRST

public static final String CONFIG_MERGE_FIRST
Used to handle configuration merging - merge the first configuration in, latest props will not override previous values

See Also:
  - Constant Field Values

## Constructor Details

### BuilderContext

public BuilderContext(FeatureProvider provider)
Create a new context. The feature provider is for example used to get a prototype feature.

Parameters:
  `provider` - A provider providing required features for processing
Throws:
  `IllegalArgumentException` - If feature provider is `null`

## Method Details

### setArtifactProvider

public BuilderContext setArtifactProvider(ArtifactProvider ap)
Set the artifact provider. While the artifact provider is not required by the general assembly and merging algorithms, handlers for extensions might need it.

Parameters:
  `ap` - An ArtifactProvider to resolve artifact IDs to URLs
Returns:
  The builder context

### addVariablesOverrides

public BuilderContext addVariablesOverrides(Map<String,String> vars)
Add overrides for the variables. Variables can be overridden if any feature in the aggregation/assembly process contains an overriden variable. If multiple definitions of the same variable are found in the features that are to be aggregated and the values for these variables are different, they must be overridden, otherwise the aggregation will fail.

Parameters:
  `vars` - The overrides keyed by variable name
Returns:
  The builder context

### addFrameworkPropertiesOverrides

public BuilderContext addFrameworkPropertiesOverrides(Map<String,String> props)
Add overrides for the framework properties. Framework properties can be overridden if any feature in the aggregation/assembly process contains an overriden framework property. If multiple definitions of the same framework property are found in the features that are to be aggregated and the values for these properties are different, they must be overridden, otherwise the aggregation will fail.

Parameters:
  `props` - The overrides keyed by framework property name
Returns:
  The builder context

### addArtifactsOverride

public BuilderContext addArtifactsOverride(ArtifactId override)
Add an override for artifact clashes.

Parameters:
  `override` - The override
Returns:
  The builder context

### addConfigsOverrides

public BuilderContext addConfigsOverrides(Map<String,String> overrides)
Add merge policies for configuration clashes.

Parameters:
  `overrides` - The overrides
Returns:
  The builder context

### addMergeExtensions

public BuilderContext addMergeExtensions(MergeHandler... extensions)
Add merge extensions

Parameters:
  `extensions` - A list of merge extensions.
Returns:
  The builder context

### addPostProcessExtensions

public BuilderContext addPostProcessExtensions(PostProcessHandler... extensions)
Add post process extensions

Parameters:
  `extensions` - A list of extensions
Returns:
  The builder context

### setHandlerConfiguration

public BuilderContext setHandlerConfiguration(String name, Map<String,String> cfg)
Set a handler configuration. A configuration can be set for both `MergeHandler`s and `PostProcessHandler`s. The name of a handler is the simple class name of the class implementing the handler. To pass the same configuration to all handlers, use the `CONFIGURATION_ALL_HANDLERS_KEY` name.

Parameters:
  `name` - The name of the handler
  `cfg` - The configuration for the handler
Returns:
  The builder context