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.xml; 018 019import org.w3c.dom.Element; 020import org.w3c.dom.Node; 021 022import org.springframework.beans.factory.config.BeanDefinition; 023import org.springframework.beans.factory.config.BeanDefinitionHolder; 024 025/** 026 * Base interface used by the {@link DefaultBeanDefinitionDocumentReader} 027 * for handling custom namespaces in a Spring XML configuration file. 028 * 029 * <p>Implementations are expected to return implementations of the 030 * {@link BeanDefinitionParser} interface for custom top-level tags and 031 * implementations of the {@link BeanDefinitionDecorator} interface for 032 * custom nested tags. 033 * 034 * <p>The parser will call {@link #parse} when it encounters a custom tag 035 * directly under the {@code <beans>} tags and {@link #decorate} when 036 * it encounters a custom tag directly under a {@code <bean>} tag. 037 * 038 * <p>Developers writing their own custom element extensions typically will 039 * not implement this interface directly, but rather make use of the provided 040 * {@link NamespaceHandlerSupport} class. 041 * 042 * @author Rob Harrop 043 * @author Erik Wiersma 044 * @since 2.0 045 * @see DefaultBeanDefinitionDocumentReader 046 * @see NamespaceHandlerResolver 047 */ 048public interface NamespaceHandler { 049 050 /** 051 * Invoked by the {@link DefaultBeanDefinitionDocumentReader} after 052 * construction but before any custom elements are parsed. 053 * @see NamespaceHandlerSupport#registerBeanDefinitionParser(String, BeanDefinitionParser) 054 */ 055 void init(); 056 057 /** 058 * Parse the specified {@link Element} and register any resulting 059 * {@link BeanDefinition BeanDefinitions} with the 060 * {@link org.springframework.beans.factory.support.BeanDefinitionRegistry} 061 * that is embedded in the supplied {@link ParserContext}. 062 * <p>Implementations should return the primary {@code BeanDefinition} 063 * that results from the parse phase if they wish to be used nested 064 * inside (for example) a {@code <property>} tag. 065 * <p>Implementations may return {@code null} if they will 066 * <strong>not</strong> be used in a nested scenario. 067 * @param element the element that is to be parsed into one or more {@code BeanDefinitions} 068 * @param parserContext the object encapsulating the current state of the parsing process 069 * @return the primary {@code BeanDefinition} (can be {@code null} as explained above) 070 */ 071 BeanDefinition parse(Element element, ParserContext parserContext); 072 073 /** 074 * Parse the specified {@link Node} and decorate the supplied 075 * {@link BeanDefinitionHolder}, returning the decorated definition. 076 * <p>The {@link Node} may be either an {@link org.w3c.dom.Attr} or an 077 * {@link Element}, depending on whether a custom attribute or element 078 * is being parsed. 079 * <p>Implementations may choose to return a completely new definition, 080 * which will replace the original definition in the resulting 081 * {@link org.springframework.beans.factory.BeanFactory}. 082 * <p>The supplied {@link ParserContext} can be used to register any 083 * additional beans needed to support the main definition. 084 * @param source the source element or attribute that is to be parsed 085 * @param definition the current bean definition 086 * @param parserContext the object encapsulating the current state of the parsing process 087 * @return the decorated definition (to be registered in the BeanFactory), 088 * or simply the original bean definition if no decoration is required. 089 * A {@code null} value is strictly speaking invalid, but will be leniently 090 * treated like the case where the original bean definition gets returned. 091 */ 092 BeanDefinitionHolder decorate(Node source, BeanDefinitionHolder definition, ParserContext parserContext); 093 094}