KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > springframework > beans > factory > parsing > ComponentDefinition


1 /*
2  * Copyright 2002-2006 the original author or authors.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 package org.springframework.beans.factory.parsing;
18
19 import org.springframework.beans.BeanMetadataElement;
20 import org.springframework.beans.factory.config.BeanDefinition;
21 import org.springframework.beans.factory.config.BeanReference;
22
23 /**
24  * Interface that describes the logical view of a set of {@link BeanDefinition BeanDefinitions}
25  * and {@link BeanReference BeanReferences} as presented in some configuration context.
26  *
27  * <p>With the introduction of {@link org.springframework.beans.factory.xml.NamespaceHandler pluggable custom XML tags},
28  * it is now possible for a single logical configuration entity, in this case an XML tag, to
29  * create multiple {@link BeanDefinition BeanDefinitions} and {@link BeanReference RuntimeBeanReferences}
30  * in order to provide more succinct configuration and greater convenience to end users. As such, it can
31  * no longer be assumed that each configuration entity (e.g. XML tag) maps to one {@link BeanDefinition}.
32  * For tool vendors and other users who wish to present visualization or support for configuring Spring
33  * applications it is important that there is some mechanism in place to tie the {@link BeanDefinition BeanDefinitions}
34  * in the {@link org.springframework.beans.factory.BeanFactory} back to the configuration data in a way
35  * that has concrete meaning to the end user. As such, {@link org.springframework.beans.factory.xml.NamespaceHandler}
36  * implementations are able to publish events in the form of a <code>ComponentDefinition</code> for each
37  * logical entity being configured. Third parties can then {@link org.springframework.beans.factory.parsing.ReaderEventListener subscribe to these events},
38  * allowing for a user-centric view of the bean metadata.
39  *
40  * <p>Each <code>ComponentDefinition</code> has a {@link #getSource source object} which is configuration-specific.
41  * In the case of XML-based configuration this is typically the {@link org.w3c.dom.Node} which contains the user
42  * supplied configuration information. In addition to this, each {@link BeanDefinition} enclosed in a
43  * <code>ComponentDefinition</code> has its own {@link BeanDefinition#getSource() source object} which may point
44  * to a different, more specific, set of configuration data. Beyond this, individual pieces of bean metadata such
45  * as the {@link org.springframework.beans.PropertyValue PropertyValues} may also have a source object giving an
46  * even greater level of detail. Source object extraction is handled through the
47  * {@link org.springframework.beans.factory.parsing.SourceExtractor} which can be customized as required.
48  *
49  * <p>Whilst direct access to important {@link BeanReference BeanReferences} is provided through
50  * {@link #getBeanReferences}, tools may wish to inspect all {@link BeanDefinition BeanDefinitions} to gather
51  * the full set of {@link BeanReference BeanReferences}. Implementations are required to provide
52  * all {@link BeanReference BeanReferences} that are required to validate the configuration of the
53  * overall logical entity as well as those required to provide full user visualisation of the configuration.
54  * It is expected that certain {@link BeanReference BeanReferences} will not be important to
55  * validation or to the user view of the configuration and as such these may be ommitted. A tool may wish to
56  * display any additional {@link BeanReference BeanReferences} sourced through the supplied
57  * {@link BeanDefinition BeanDefinitions} but this is not considered to be a typical case.
58  *
59  * <p>Tools can determine the important of contained {@link BeanDefinition BeanDefinitions} by checking the
60  * {@link BeanDefinition#getRole role identifier}. The role is essentially a hint to the tool as to how
61  * important the configuration provider believes a {@link BeanDefinition} is to the end user. It is expected
62  * that tools will <strong>not</strong> display all {@link BeanDefinition BeanDefinitions} for a given
63  * <code>ComponentDefinition</code> choosing instead to filter based on the role. Tools may choose to make
64  * this filtering user configurable. Particular notice should be given to the
65  * {@link BeanDefinition#ROLE_INFRASTRUCTURE INFRASTRUCTURE role identifier}. {@link BeanDefinition BeanDefinitions}
66  * classified with this role are completely unimportant to the end user and are required only for
67  * internal implementation reasons.
68  *
69  * @author Rob Harrop
70  * @author Juergen Hoeller
71  * @since 2.0
72  * @see AbstractComponentDefinition
73  * @see CompositeComponentDefinition
74  * @see BeanComponentDefinition
75  * @see ReaderEventListener#componentRegistered(ComponentDefinition)
76  */
77 public interface ComponentDefinition extends BeanMetadataElement {
78
79     /**
80      * Get the user-visible name of this <code>ComponentDefinition</code>.
81      * <p>This should link back directly to the corresponding configuration data
82      * for this component in a given context.
83      */
84     String JavaDoc getName();
85
86     /**
87      * Return a friendly description of the described component.
88      * <p>Implementations are encouraged to return the same value from
89      * <code>toString()</code>.
90      */
91     String JavaDoc getDescription();
92
93     /**
94      * Return the {@link BeanDefinition BeanDefinitions} that were registered
95      * to form this <code>ComponentDefinition</code>.
96      * <p>It should be noted that a <code>ComponentDefinition</code> may well be related with
97      * other {@link BeanDefinition BeanDefinitions} via {@link BeanReference references},
98      * however these are <strong>not</strong> included as they may be not available immediately.
99      * 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</code>.
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 }
124
Popular Tags