Interface that describes the logical view of a set of BeanDefinitions and BeanReferences as presented in some configuration context.

With the introduction of pluggable custom XML tags, it is now possible for a single logical configuration entity, in this case an XML tag, to create multiple BeanDefinitions and RuntimeBeanReferences in order to provide more succinct configuration and greater convenience to end users. As such, it can no longer be assumed that each configuration entity (e.g. XML tag) maps to one BeanDefinition. For tool vendors and other users who wish to present visualization or support for configuring Spring applications it is important that there is some mechanism in place to tie the BeanDefinitions in the org.springframework.beans.factory.BeanFactory back to the configuration data in a way that has concrete meaning to the end user. As such, org.springframework.beans.factory.xml.NamespaceHandler implementations are able to publish events in the form of a ComponentDefinition for each logical entity being configured. Third parties can then subscribe to these events, allowing for a user-centric view of the bean metadata.

Each ComponentDefinition has a source object which is configuration-specific. In the case of XML-based configuration this is typically the org.w3c.dom.Node which contains the user supplied configuration information. In addition to this, each BeanDefinition enclosed in a ComponentDefinition has its own source object which may point to a different, more specific, set of configuration data. Beyond this, individual pieces of bean metadata such as the PropertyValues may also have a source object giving an even greater level of detail. Source object extraction is handled through the SourceExtractor which can be customized as required.

Whilst direct access to important BeanReferences is provided through getBeanReferences, tools may wish to inspect all BeanDefinitions to gather the full set of BeanReferences. Implementations are required to provide all BeanReferences that are required to validate the configuration of the overall logical entity as well as those required to provide full user visualization of the configuration. It is expected that certain BeanReferences will not be important to validation or to the user view of the configuration and as such these may be omitted. A tool may wish to display any additional BeanReferences sourced through the supplied BeanDefinitions but this is not considered to be a typical case.

Tools can determine the importance of contained BeanDefinitions by checking the role identifier. The role is essentially a hint to the tool as to how important the configuration provider believes a BeanDefinition is to the end user. It is expected that tools will not display all BeanDefinitions for a given ComponentDefinition choosing instead to filter based on the role. Tools may choose to make this filtering user configurable. Particular notice should be given to the INFRASTRUCTURE role identifier. BeanDefinitions classified with this role are completely unimportant to the end user and are required only for internal implementation reasons.