01: /*
02: * Copyright 2002-2007 the original author or authors.
03: *
04: * Licensed under the Apache License, Version 2.0 (the "License");
05: * you may not use this file except in compliance with the License.
06: * You may obtain a copy of the License at
07: *
08: * http://www.apache.org/licenses/LICENSE-2.0
09: *
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;
20: import org.w3c.dom.Node;
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}
27: * for 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><beans></code> tags and {@link #decorate} when
36: * it encounters a custom tag directly under a <code><bean></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><property></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 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: * or simply the original bean definition if no decoration is required.
89: * A <code>null</code> value is strictly speaking invalid, but will be leniently
90: * treated like the case where the original bean definition gets returned.
91: */
92: BeanDefinitionHolder decorate(Node source,
93: BeanDefinitionHolder definition, ParserContext parserContext);
94:
95: }
|