### Arranging features in configs

Resolved configuration models are meant to be further processed by provisioning plugins that actually generate the final configuration files. A resolved config is basically is a collection of features and properties. Plugins simply iterate through the features in a resolved config and generate the corresponding configuration fragments.

The order in which features appear in the resolved config may be significant. By default the order of the features in the resolved config reflects the order in which the features where added to the config, i.e. the order in which the features appear in `config` element. Although, in case there dependencies between features, the mechanism will re-order the features according to their dependencies, i.e. if feature *F1* depends on feature *F2*, even if *F1* was added to the config model before *F2*, in the resolved config *F2* will appear before *F1*.

#### Feature branches

In the resolved config features are actually organized into branches. In the simplest case, there is only one branch in the config and all the features of the config appear on that branch.

There are cases though, when a set of features has to be handled in a different way than the rest of the features from the same config. E.g. there could be a few features that form a circular dependency. The mechanism may automatically identify those and notifies the plugins in case they need to handle them in a special way. Other examples of branches will be described below.

#### Batches

Batch is nothing more than a flag in a branch. This flag is meant to indicate to the plugins whether features on the branch should be handled in a batch (i.e. in a transactional way) or not. In other words, if batch is on for a branch it means "transaction required" for this branch. This is useful for cases when features form circular dependencies and handling them one by one may result in referential (or other) integrity constraint violation in the final config generation.

By default, branches are not flagged as batches. This can be configured though with config property *config.branch-is-batch*. E.g.

[source="xml"]
----
    <config model="standalone">
        <props>
            <prop name="config.branch-is-batch" value="true"/>
        </props>
        <!-- the rest is skipped -->
----

This means that in all the *standalone* configs all the branches will be flagged as batches by default.

Batch flag can further be enabled or disabled for a specific branch by using feature spec annotations.

[source="xml"]
----
<feature-spec xmlns="urn:jboss:galleon:feature-spec:1.0" name="core-service.management">
    <annotation name="feature-branch">
        <elem name="id" value="core-service.management"/>
        <elem name="batch" value="true"/>
    </annotation>
        <!-- the rest is skipped -->
----

This flags branch *core-service.management* as batch.

#### Branch per feature spec

In some cases it might be useful to arrange features in the resolved config by their specs. Which means a plugin prefers to handle all the features of *Spec1* first then all the features of *Spec2*, etc. The mechanism can be instructed to that by including property *config.branch-per-spec* in `config` element, e.g.

[source="xml"]
----
    <config model="standalone">
        <props>
            <prop name="config.branch-per-spec" value="true"/>
        </props>
        <!-- the rest is skipped -->
----

NOTE: the resulting branches will be ordered according to feature dependencies. E.g. if features of *Spec1* reference features of *Spec2*, the branch of features *Spec2* will appear in the config before the branch of *Spec1*.

The example above is arranging all the features in the config by specs. In some cases though it would be useful to group only features of specific specs together and leave the rest of the features as they are. This can be configured by adding the following feature spec annotation

[source="xml"]
----
<feature-spec xmlns="urn:jboss:galleon:feature-spec:1.0" name="core-service.management">
    <annotation name="feature-branch">
        <elem name="spec" value="true"/>
    </annotation>
        <!-- the rest is skipped -->
----

#### Isolating circular dependencies

The mechanism may identify circular dependencies between features in a config model and create a separate branch for them. Here is how to enable this
[source="xml"]
----
    <config model="standalone">
        <props>
            <prop name="config.isolate-circular-deps" value="true"/>
        </props>
        <!-- the rest is skipped -->
----

#### Parent-children branch

Often in configs features form parent-children references. It could be useful for plugins to arrange features by parent-children branches. This can be configured per feature spec. E.g.

[source="xml"]
----
<feature-spec xmlns="urn:jboss:galleon:feature-spec:1.0" name="SpecP">
    <annotation name="feature-branch">
        <elem name="parent-children"/>
    </annotation>
    <!-- the rest is skipped -->
----

Which means every feature of spec *SpecP* will start a branch which contain all the features that are children (direct or transitive) of the parent feature *SpecP*.

#### Branches with explicit IDs

When a branch is created, the mechanism assigns an ID to the branch. A user may instruct the mechanism to group features of certain specs on a branch with a given ID. E.g.

[source="xml"]
----
<feature-spec xmlns="urn:jboss:galleon:feature-spec:1.0" name="Spec1">
    <annotation name="feature-branch">
        <elem name="id" value="Branch1"/>
    </annotation>
    <!-- the rest is skipped -->
</feature-spec>

<feature-spec xmlns="urn:jboss:galleon:feature-spec:1.0" name="Spec2">
    <annotation name="feature-branch">
        <elem name="id" value="Branch1"/>
    </annotation>
    <!-- the rest is skipped -->
</feature-spec>
----

In the example above features of *Spec1* and *Spec2* will be collected on the same branch *Branch1*.

#### Merging independent branches

After the config has been resolved it the could be branches have certain common characteristics. E.g. most probably some features in the config will depend other features. Which means that some feature branches will depend on other feature branches. There could be a few branches though that don't depend on other branches (although there could be branches that depend on them). Those independent branches could be merged into one independent branch. If that is useful it can configured by adding the following property to the `config` element

[source="xml"]
----
    <config model="standalone">
        <props>
            <prop name="config.merge-independent-branches" value="true"/>
        </props>
        <!-- the rest is skipped -->
----

#### Merging branches with the same dependencies

While the previous option merges only the independent branches, this one identifies branches with identical dependencies on other branches and merges them into one branch. It can be enabled by adding the following property

[source="xml"]
----
    <config model="standalone">
        <props>
            <prop name="config.config.merge-same-deps-branches" value="true"/>
        </props>
        <!-- the rest is skipped -->
----

