001/* 002 * Copyright 2002-2012 the original author or authors. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * https://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package org.springframework.beans.factory.parsing; 018 019import org.springframework.beans.BeanMetadataElement; 020import org.springframework.beans.factory.config.BeanDefinition; 021import org.springframework.beans.factory.config.BeanReference; 022 023/** 024 * Interface that describes the logical view of a set of {@link BeanDefinition BeanDefinitions} 025 * and {@link BeanReference BeanReferences} as presented in some configuration context. 026 * 027 * <p>With the introduction of {@link org.springframework.beans.factory.xml.NamespaceHandler pluggable custom XML tags}, 028 * it is now possible for a single logical configuration entity, in this case an XML tag, to 029 * create multiple {@link BeanDefinition BeanDefinitions} and {@link BeanReference RuntimeBeanReferences} 030 * in order to provide more succinct configuration and greater convenience to end users. As such, it can 031 * no longer be assumed that each configuration entity (e.g. XML tag) maps to one {@link BeanDefinition}. 032 * For tool vendors and other users who wish to present visualization or support for configuring Spring 033 * applications it is important that there is some mechanism in place to tie the {@link BeanDefinition BeanDefinitions} 034 * in the {@link org.springframework.beans.factory.BeanFactory} back to the configuration data in a way 035 * that has concrete meaning to the end user. As such, {@link org.springframework.beans.factory.xml.NamespaceHandler} 036 * implementations are able to publish events in the form of a {@code ComponentDefinition} for each 037 * logical entity being configured. Third parties can then {@link ReaderEventListener subscribe to these events}, 038 * allowing for a user-centric view of the bean metadata. 039 * 040 * <p>Each {@code ComponentDefinition} has a {@link #getSource source object} which is configuration-specific. 041 * In the case of XML-based configuration this is typically the {@link org.w3c.dom.Node} which contains the user 042 * supplied configuration information. In addition to this, each {@link BeanDefinition} enclosed in a 043 * {@code ComponentDefinition} has its own {@link BeanDefinition#getSource() source object} which may point 044 * to a different, more specific, set of configuration data. Beyond this, individual pieces of bean metadata such 045 * as the {@link org.springframework.beans.PropertyValue PropertyValues} may also have a source object giving an 046 * even greater level of detail. Source object extraction is handled through the 047 * {@link SourceExtractor} which can be customized as required. 048 * 049 * <p>Whilst direct access to important {@link BeanReference BeanReferences} is provided through 050 * {@link #getBeanReferences}, tools may wish to inspect all {@link BeanDefinition BeanDefinitions} to gather 051 * the full set of {@link BeanReference BeanReferences}. Implementations are required to provide 052 * all {@link BeanReference BeanReferences} that are required to validate the configuration of the 053 * overall logical entity as well as those required to provide full user visualisation of the configuration. 054 * It is expected that certain {@link BeanReference BeanReferences} will not be important to 055 * validation or to the user view of the configuration and as such these may be omitted. A tool may wish to 056 * display any additional {@link BeanReference BeanReferences} sourced through the supplied 057 * {@link BeanDefinition BeanDefinitions} but this is not considered to be a typical case. 058 * 059 * <p>Tools can determine the important of contained {@link BeanDefinition BeanDefinitions} by checking the 060 * {@link BeanDefinition#getRole role identifier}. The role is essentially a hint to the tool as to how 061 * important the configuration provider believes a {@link BeanDefinition} is to the end user. It is expected 062 * that tools will <strong>not</strong> display all {@link BeanDefinition BeanDefinitions} for a given 063 * {@code ComponentDefinition} choosing instead to filter based on the role. Tools may choose to make 064 * this filtering user configurable. Particular notice should be given to the 065 * {@link BeanDefinition#ROLE_INFRASTRUCTURE INFRASTRUCTURE role identifier}. {@link BeanDefinition BeanDefinitions} 066 * classified with this role are completely unimportant to the end user and are required only for 067 * internal implementation reasons. 068 * 069 * @author Rob Harrop 070 * @author Juergen Hoeller 071 * @since 2.0 072 * @see AbstractComponentDefinition 073 * @see CompositeComponentDefinition 074 * @see BeanComponentDefinition 075 * @see ReaderEventListener#componentRegistered(ComponentDefinition) 076 */ 077public interface ComponentDefinition extends BeanMetadataElement { 078 079 /** 080 * Get the user-visible name of this {@code ComponentDefinition}. 081 * <p>This should link back directly to the corresponding configuration data 082 * for this component in a given context. 083 */ 084 String getName(); 085 086 /** 087 * Return a friendly description of the described component. 088 * <p>Implementations are encouraged to return the same value from 089 * {@code toString()}. 090 */ 091 String getDescription(); 092 093 /** 094 * Return the {@link BeanDefinition BeanDefinitions} that were registered 095 * to form this {@code ComponentDefinition}. 096 * <p>It should be noted that a {@code ComponentDefinition} may well be related with 097 * other {@link BeanDefinition BeanDefinitions} via {@link BeanReference references}, 098 * however these are <strong>not</strong> included as they may be not available immediately. 099 * Important {@link BeanReference BeanReferences} are available from {@link #getBeanReferences()}. 100 * @return the array of BeanDefinitions, or an empty array if none 101 */ 102 BeanDefinition[] getBeanDefinitions(); 103 104 /** 105 * Return the {@link BeanDefinition BeanDefinitions} that represent all relevant 106 * inner beans within this component. 107 * <p>Other inner beans may exist within the associated {@link BeanDefinition BeanDefinitions}, 108 * however these are not considered to be needed for validation or for user visualization. 109 * @return the array of BeanDefinitions, or an empty array if none 110 */ 111 BeanDefinition[] getInnerBeanDefinitions(); 112 113 /** 114 * Return the set of {@link BeanReference BeanReferences} that are considered 115 * to be important to this {@code ComponentDefinition}. 116 * <p>Other {@link BeanReference BeanReferences} may exist within the associated 117 * {@link BeanDefinition BeanDefinitions}, however these are not considered 118 * to be needed for validation or for user visualization. 119 * @return the array of BeanReferences, or an empty array if none 120 */ 121 BeanReference[] getBeanReferences(); 122 123}