KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > springframework > beans > factory > xml > NamespaceHandler


1 /*
2  * Copyright 2002-2007 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.xml;
18
19 import org.w3c.dom.Element JavaDoc;
20 import org.w3c.dom.Node JavaDoc;
21
22 import org.springframework.beans.factory.config.BeanDefinition;
23 import org.springframework.beans.factory.config.BeanDefinitionHolder;
24
25 /**
26  * Base interface used by the {@link DefaultBeanDefinitionDocumentReader} for
27  * handling custom namespaces in a Spring XML configuration file.
28  *
29  * <p>Implementations are expected to return implementations of the
30  * {@link BeanDefinitionParser} interface for custom top-level tags and
31  * implementations of the {@link BeanDefinitionDecorator} interface for
32  * custom nested tags.
33  *
34  * <p>The parser will call {@link #parse} when it encounters a custom tag
35  * directly under the <code>&lt;beans&gt;</code> tags and {@link #decorate} when
36  * it encounters a custom tag directly under a <code>&lt;bean&gt;</code> tag.
37  *
38  * <p>Developers writing their own custom element extensions typically will
39  * not implement this interface drectly, but rather make use of the provided
40  * {@link NamespaceHandlerSupport} class.
41  *
42  * @author Rob Harrop
43  * @author Erik Wiersma
44  * @since 2.0
45  * @see DefaultBeanDefinitionDocumentReader
46  * @see NamespaceHandlerResolver
47  */
48 public interface NamespaceHandler {
49
50     /**
51      * Invoked by the {@link DefaultBeanDefinitionDocumentReader} after
52      * construction but before any custom elements are parsed.
53      * @see NamespaceHandlerSupport#registerBeanDefinitionParser(String, BeanDefinitionParser)
54      */
55     void init();
56
57     /**
58      * Parse the specified {@link Element} and register any resulting
59      * {@link BeanDefinition BeanDefinitions} with the
60      * {@link org.springframework.beans.factory.support.BeanDefinitionRegistry}
61      * that is embedded in the supplied {@link ParserContext}.
62      * <p>Implementations should return the primary <code>BeanDefinition</code>
63      * that results from the parse phase if they wish to be used nested
64      * inside (for example) a <code>&lt;property&gt;</code> tag.
65      * <p>Implementations may return <code>null</code> if they will
66      * <strong>not</strong> be used in a nested scenario.
67      * @param element the element that is to be parsed into one or more <code>BeanDefinitions</code>
68      * @param parserContext the object encapsulating the current state of the parsing process
69      * @return the primary <code>BeanDefinition</code> (can be <code>null</code> as explained above)
70      */
71     BeanDefinition parse(Element JavaDoc element, ParserContext parserContext);
72
73     /**
74      * Parse the specified {@link Node} and decorate the supplied
75      * {@link BeanDefinitionHolder}, returning the decorated definition.
76      * <p>The {@link Node} may be either an {@link org.w3c.dom.Attr} or an
77      * {@link Element}, depending on whether a custom attribute or element
78      * is being parsed.
79      * <p>Implementations may choose to return a completely new definition,
80      * which will replace the original definition in the resulting
81      * {@link org.springframework.beans.factory.BeanFactory}.
82      * <p>The supplied {@link ParserContext} can be used to register any
83      * additional beans needed to support the main definition.
84      * @param source the source element or attribute that is to be parsed
85      * @param definition the current bean definition
86      * @param parserContext the object encapsulating the current state of the parsing process
87      * @return the decorated definition (to be registered in the BeanFactory)
88      */
89     BeanDefinitionHolder decorate(Node JavaDoc source, BeanDefinitionHolder definition, ParserContext parserContext);
90
91 }
92
Popular Tags