The branch-merge overlay provides a mechanism to split access to an inner nested space into a number of branches. Requests on each branch can then be passed through their own sequence of overlays before each branch is merged and passed into the space. This overlay is very useful for selectively applying overlayed functionality such as sessions to part of an application space.
Branch-merge is a overlay mapped into the standard module syntax with a <branch-merge> tag. Being a transparent overlay branch-merge exposes all resources from the nested space.
It is important that all overlays used are transparent otherwise the expected available elements may not be found.
The one or more overlays form, in the most general case, a tree of overlays where the root is the nested space. Requests will be injected into the tree at locations specified by the branch definitions. Once on the tree a request will percolate through the tree towards the root passing through each overlay in turn until it is requested in the nested space.
Overlay definitions are like the overlay definitions within a standard modules space tag but include two additional attributes, "name" and "next". Name defines a unique name for the overlay that is used by the branches and overlays to cross link. Next defines the next overlay that the request should flow to after it has been through this overlay. A blank string indicates it should flow into the nested space.
Each branch must be named and point into the tree of overlays. It defines a set of target elements which will be handled by the branch. The target attribute defines a comma separated list of element ids from the nested space to be handled by this branch. If a branch is defined with targets as an empty string then all unhandled elements will be handled by this branch.
If not all elements in the nested space are explicitly handled then they will by default pass through without additional handling to the nested space unless a default branch has been specified. A default branch is specified with an empty targets attribute.
In the example shown the configuration for branch-merge is a literal within the standard module. It can however be provided by a service referenced by an identifier and resolvable within the nested space. In this case the configuration may change dynamically if needed.