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.Node;
020
021import org.springframework.beans.factory.config.BeanDefinitionHolder;
022
023/**
024 * Interface used by the {@link DefaultBeanDefinitionDocumentReader}
025 * to handle custom, nested (directly under a {@code <bean>}) tags.
026 *
027 * <p>Decoration may also occur based on custom attributes applied to the
028 * {@code <bean>} tag. Implementations are free to turn the metadata in the
029 * custom tag into as many
030 * {@link org.springframework.beans.factory.config.BeanDefinition BeanDefinitions} as
031 * required and to transform the
032 * {@link org.springframework.beans.factory.config.BeanDefinition} of the enclosing
033 * {@code <bean>} tag, potentially even returning a completely different
034 * {@link org.springframework.beans.factory.config.BeanDefinition} to replace the
035 * original.
036 *
037 * <p>{@link BeanDefinitionDecorator BeanDefinitionDecorators} should be aware that
038 * they may be part of a chain. In particular, a {@link BeanDefinitionDecorator} should
039 * be aware that a previous {@link BeanDefinitionDecorator} may have replaced the
040 * original {@link org.springframework.beans.factory.config.BeanDefinition} with a
041 * {@link org.springframework.aop.framework.ProxyFactoryBean} definition allowing for
042 * custom {@link org.aopalliance.intercept.MethodInterceptor interceptors} to be added.
043 *
044 * <p>{@link BeanDefinitionDecorator BeanDefinitionDecorators} that wish to add an
045 * interceptor to the enclosing bean should extend
046 * {@link org.springframework.aop.config.AbstractInterceptorDrivenBeanDefinitionDecorator}
047 * which handles the chaining ensuring that only one proxy is created and that it
048 * contains all interceptors from the chain.
049 *
050 * <p>The parser locates a {@link BeanDefinitionDecorator} from the
051 * {@link NamespaceHandler} for the namespace in which the custom tag resides.
052 *
053 * @author Rob Harrop
054 * @since 2.0
055 * @see NamespaceHandler
056 * @see BeanDefinitionParser
057 */
058public interface BeanDefinitionDecorator {
059
060        /**
061         * Parse the specified {@link Node} (either an element or an attribute) and decorate
062         * the supplied {@link org.springframework.beans.factory.config.BeanDefinition},
063         * returning the decorated definition.
064         * <p>Implementations may choose to return a completely new definition, which will
065         * replace the original definition in the resulting
066         * {@link org.springframework.beans.factory.BeanFactory}.
067         * <p>The supplied {@link ParserContext} can be used to register any additional
068         * beans needed to support the main definition.
069         */
070        BeanDefinitionHolder decorate(Node node, BeanDefinitionHolder definition, ParserContext parserContext);
071
072}