Apache Sling Context-Aware Configuration - Default Implementation
By default the 'default implementation' us used by the Context-Aware Configuration concerning lookup and persistence of configuration data, resource and property inheritance and context path detection. Using the SPI it is possible to overlay, extend or replace this functionality.
This page documents the details of the default implementation.
By default all configuration data is stored in
/conf. Fallback paths are
The paths are configurable in the service configuration.
The content resource hierarchy is defined by setting
sling:configRef properties. Each resource that has a
sling:configRef property set defines the root resource of a context, the whole subtree is the context. Within the subtree further nested contexts can be defined.
This illustration shows an example for configuration resource lookup:
If you get the context-aware configuration via the API for any resource below
/content/tenant1/region1/site1 it is looked up in this path in this order:
/conf/brand1/tenant1/region1/site1- because referenced by
/conf/brand1/tenant1/region1- because referenced by
/conf/brand1/tenant1- because referenced by
/conf/brand1- because it is a parent of by
/conf/global- because it is configured as fallback path
/apps/conf- because it is configured as fallback path
/libs/conf- because it is configured as fallback path
So the basic rules are:
- Go up in the content resource tree until a resource with
sling:configRefis found. This is the 'inner-most' context. Check if a configuration resource exists at the path the property points to.
- Check for parent resources of the references configuration resource (below
- Go further up in the content resource tree for parent contexts, and check their configuration resources as well (they may reference completely different location below
- Check the fallback paths
Example for the resource structure for a configuration resource at
/conf /mysite /sling:configs /x.y.z.MyConfig @prop1 = 'value1' @prop2 = 123 @prop3= true
sling:configsis the bucket named which is used by the ConfigurationResolver by default for context-aware configurations. May be another name if you use the ConfigurationResourceResolver directly.
x.y.z.MyConfigis the configuration name, in this case derived from an annotation class. May be any other custom name as well.
prop1..3are example for configuration properties
- It is possible to use deeper hierarchies below
- Nested configurations are supported as well. This can be mapped to annotation classes referencing other annotation classes.
We distinguish between:
- Singleton resources: Configuration resources looked up by the
- Collection resources: Configuration resources lists looked up by the
For singleton resources, there is not resource inheritance. The first resource that is found in the configuration resource resolving lookup order is returned.
For collection resources there is no resource inheritance enabled by default. The children of the first resource that is found in the configuration resource resolving lookup order are returned.
By defining a property
sling:configCollectionInherit on the configuration resource, the children of the next resource that is found in the configuration resource resolving lookup order are combined with the children of the current configuration resource, returned a merged list. If both configuration resources contain child resources with the same name, duplicates are eliminated and only the children of the first resource are included.
By setting the property
sling:configCollectionInherit on multiple configuration resources that are part of the lookup order it is possible to form deeper inheritance chains following the same rules.
Example for resource inheritance:
The result of this example is: C, A, B. It would by just C if the
sling:configCollectionInherit is not set.
By default, no property inheritance takes place. That means only the properties that are stored in the configuration resource are mapped to the annotation class or returned as value map, regardless whether singleton or collection resources are returned, or if resource collection inheritance is enabled or not.
By defining a property
sling:configPropertyInherit on the configuration resource, property merging is enabled between the current configuration resource and the next resource with the same name (singleton or resource collection item) in the configuration resource lookup order. That means that all properties that are not defined on the current configuration resource are inherited from the next resources and a merged value map is used for the configuration mapping.
By setting the property
sling:configPropertyInherit on multiple configuration resources that are part of the lookup order it is possible to form deeper inheritance chains following the same rules.