View Javadoc

1   /*
2    * $Id:AbstractMuleBeanDefinitionParser.java 5187 2007-02-16 18:00:42Z rossmason $
3    * --------------------------------------------------------------------------------------
4    * Copyright (c) MuleSoft, Inc.  All rights reserved.  http://www.mulesoft.com
5    *
6    * The software in this package is published under the terms of the CPAL v1.0
7    * license, a copy of which has been included with this distribution in the
8    * LICENSE.txt file.
9    */
10  package org.mule.config.spring.parsers;
11  
12  import org.mule.api.MuleContext;
13  import org.mule.api.component.Component;
14  import org.mule.api.config.MuleProperties;
15  import org.mule.api.lifecycle.Disposable;
16  import org.mule.api.lifecycle.Initialisable;
17  import org.mule.api.routing.OutboundRouter;
18  import org.mule.api.routing.OutboundRouterCollection;
19  import org.mule.api.source.MessageSource;
20  import org.mule.api.transformer.Transformer;
21  import org.mule.config.spring.MuleHierarchicalBeanDefinitionParserDelegate;
22  import org.mule.config.spring.parsers.assembly.BeanAssembler;
23  import org.mule.config.spring.parsers.assembly.BeanAssemblerFactory;
24  import org.mule.config.spring.parsers.assembly.DefaultBeanAssemblerFactory;
25  import org.mule.config.spring.parsers.assembly.configuration.ReusablePropertyConfiguration;
26  import org.mule.config.spring.parsers.assembly.configuration.ValueMap;
27  import org.mule.config.spring.parsers.generic.AutoIdUtils;
28  import org.mule.enricher.MessageEnricher;
29  import org.mule.exception.AbstractExceptionStrategy;
30  import org.mule.util.ClassUtils;
31  import org.mule.util.StringUtils;
32  import org.mule.util.XMLUtils;
33  
34  import java.util.HashSet;
35  import java.util.LinkedList;
36  import java.util.List;
37  import java.util.Map;
38  import java.util.Set;
39  
40  import org.apache.commons.logging.Log;
41  import org.apache.commons.logging.LogFactory;
42  import org.springframework.beans.factory.BeanDefinitionStoreException;
43  import org.springframework.beans.factory.config.BeanDefinition;
44  import org.springframework.beans.factory.support.AbstractBeanDefinition;
45  import org.springframework.beans.factory.support.BeanDefinitionBuilder;
46  import org.springframework.beans.factory.support.BeanDefinitionRegistry;
47  import org.springframework.beans.factory.xml.AbstractBeanDefinitionParser;
48  import org.springframework.beans.factory.xml.ParserContext;
49  import org.w3c.dom.Attr;
50  import org.w3c.dom.Element;
51  import org.w3c.dom.NamedNodeMap;
52  
53  /**
54   * This parser extends the Spring provided {@link AbstractBeanDefinitionParser} to provide additional features for
55   * consistently customising bean representations for Mule bean definition parsers.  Most custom bean definition parsers
56   * in Mule will use this base class. The following enhancements are made -
57   *
58   * <ol>
59   * <li>A property name which ends with the suffix "-ref" is assumed to be a reference to another bean.
60   * Alternatively, a property can be explicitly registered as a bean reference via registerBeanReference()
61   *
62   * <p>For example,
63   * <code> &lt;bpm:connector bpms-ref=&quot;testBpms&quot;/&gt;</code>
64   * will automatically set a property "bpms" on the connector to reference a bean named "testBpms"
65   * </p></li>
66   *
67   * <li>Attribute mappings can be registered to control how an attribute name in Mule Xml maps to the bean name in the
68   * object being created.
69   *
70   * <p>For example -
71   * <code>addAlias("poolExhaustedAction", "poolExhaustedActionString");</code>
72   * Maps the 'poolExhaustedAction' to the 'poolExhaustedActionString' property on the bean being created.
73   * </p></li>
74   *
75   * <li>Value Mappings can be used to map key value pairs from selection lists in the XML schema to property values on the
76   * bean being created. These are a comma-separated list of key=value pairs.
77   *
78   * <p>For example -
79   * <code>addMapping("action", "NONE=0,ALWAYS_BEGIN=1,BEGIN_OR_JOIN=2,JOIN_IF_POSSIBLE=3");</code>
80   * The first argument is the bean name to set, the second argument is the set of possible key=value pairs
81   * </p></li>
82   *
83   * <li>Provides an automatic way of setting the 'init-method' and 'destroy-method' for this object. This will then automatically
84   * wire the bean into the lifecycle of the Application context.</li>
85   *
86   * <li>The 'singleton' property provides a fixed way to make sure the bean is always a singleton or not.</li>
87   *
88   * <li>Collections will be automatically created and extended if the setter matches "property+s".</li>
89   * </ol>
90   *
91   * <p>Note that this class is not multi-thread safe.  The internal state is reset before each "use"
92   * by {@link #preProcess(org.w3c.dom.Element)} which assumes sequential access.</p>
93   *
94   * @see  AbstractBeanDefinitionParser
95   */
96  public abstract class AbstractMuleBeanDefinitionParser extends AbstractBeanDefinitionParser
97      implements MuleDefinitionParser
98  {
99      public static final String ROOT_ELEMENT = "mule";
100     public static final String ATTRIBUTE_ID = "id";
101     public static final String ATTRIBUTE_NAME = "name";
102     public static final String ATTRIBUTE_CLASS = "class";
103     public static final String ATTRIBUTE_REF = "ref";
104     public static final String ATTRIBUTE_REFS = "refs";
105     public static final String ATTRIBUTE_REF_SUFFIX = "-" + ATTRIBUTE_REF;
106     public static final String ATTRIBUTE_REFS_SUFFIX = "-" + ATTRIBUTE_REFS;
107 
108     /**
109      * logger used by this class
110      */
111     protected transient Log logger = LogFactory.getLog(getClass());
112 
113     private BeanAssemblerFactory beanAssemblerFactory = new DefaultBeanAssemblerFactory();
114     protected ReusablePropertyConfiguration beanPropertyConfiguration = new ReusablePropertyConfiguration();
115     private ParserContext parserContext;
116     private BeanDefinitionRegistry registry;
117     private LinkedList<PreProcessor> preProcessors = new LinkedList<PreProcessor>();
118     private List<PostProcessor> postProcessors = new LinkedList<PostProcessor>();
119     private Set<String> beanAttributes = new HashSet<String>();
120     // By default Mule objects are not singletons
121     protected boolean singleton = false;
122 
123     /** Allow the bean class to be set explicitly via the "class" attribute. */
124     private boolean allowClassAttribute = true;
125     private Class<?> classConstraint = null;
126 
127     private String deprecationWarning;
128 
129     public AbstractMuleBeanDefinitionParser()
130     {
131         addIgnored(ATTRIBUTE_ID);
132         addBeanFlag(MuleHierarchicalBeanDefinitionParserDelegate.MULE_FORCE_RECURSE);
133     }
134 
135     public MuleDefinitionParserConfiguration addReference(String propertyName)
136     {
137         beanPropertyConfiguration.addReference(propertyName);
138         return this;
139     }
140 
141     public MuleDefinitionParserConfiguration addMapping(String propertyName, Map mappings)
142     {
143         beanPropertyConfiguration.addMapping(propertyName, mappings);
144         return this;
145     }
146 
147     public MuleDefinitionParserConfiguration addMapping(String propertyName, String mappings)
148     {
149         beanPropertyConfiguration.addMapping(propertyName, mappings);
150         return this;
151     }
152 
153     public MuleDefinitionParserConfiguration addMapping(String propertyName, ValueMap mappings)
154     {
155         beanPropertyConfiguration.addMapping(propertyName, mappings);
156         return this;
157     }
158 
159     /**
160      * @param alias The attribute name
161      * @param propertyName The bean property name
162      * @return This instance, allowing chaining during use, avoiding subclasses
163      */
164     public MuleDefinitionParserConfiguration addAlias(String alias, String propertyName)
165     {
166         beanPropertyConfiguration.addAlias(alias, propertyName);
167         return this;
168     }
169 
170     /**
171      * @param propertyName Property that is a collection
172      * @return This instance, allowing chaining during use, avoiding subclasses
173      */
174     public MuleDefinitionParserConfiguration addCollection(String propertyName)
175     {
176         beanPropertyConfiguration.addCollection(propertyName);
177         return this;
178     }
179 
180     /**
181      * @param propertyName Property that is to be ignored
182      * @return This instance, allowing chaining during use, avoiding subclasses
183      */
184     public MuleDefinitionParserConfiguration addIgnored(String propertyName)
185     {
186         beanPropertyConfiguration.addIgnored(propertyName);
187         return this;
188     }
189 
190     public MuleDefinitionParserConfiguration removeIgnored(String propertyName)
191     {
192         beanPropertyConfiguration.removeIgnored(propertyName);
193         return this;
194     }
195 
196     public MuleDefinitionParserConfiguration setIgnoredDefault(boolean ignoreAll)
197     {
198         beanPropertyConfiguration.setIgnoredDefault(ignoreAll);
199         return this;
200     }
201 
202     protected void processProperty(Attr attribute, BeanAssembler assembler)
203     {
204         assembler.extendBean(attribute);
205     }
206 
207     /**
208      * Hook method that derived classes can implement to inspect/change a
209      * bean definition after parsing is complete.
210      *
211      * @param assembler the parsed (and probably totally defined) bean definition being built
212      * @param element   the XML element that was the source of the bean definition's metadata
213      */
214     protected void postProcess(ParserContext context, BeanAssembler assembler, Element element)
215     {
216         element.setAttribute(ATTRIBUTE_NAME, getBeanName(element));
217         for (String attribute : beanAttributes)
218         {
219             assembler.setBeanFlag(attribute);
220         }
221         for (PostProcessor processor : postProcessors)
222         {
223             processor.postProcess(context, assembler, element);
224         }
225     }
226 
227     /**
228      * Hook method that derived classes can implement to modify internal state before processing.
229      *
230      * Here we make sure that the internal property configuration state is reset to the
231      * initial configuration for each element (it may be modified by the BeanAssembler)
232      * and that other mutable instance variables are cleared.
233      */
234     protected void preProcess(Element element)
235     {
236         parserContext = null;
237         registry = null;
238         beanPropertyConfiguration.reset();
239         for (PreProcessor processor : preProcessors)
240         {
241             processor.preProcess(beanPropertyConfiguration, element);
242         }
243     }
244 
245     /**
246      * Creates a {@link BeanDefinitionBuilder} instance for the {@link #getBeanClass
247      * bean Class} and passes it to the {@link #doParse} strategy method.
248      *
249      * @param element the element that is to be parsed into a single BeanDefinition
250      * @param context the object encapsulating the current state of the parsing
251      *            process
252      * @return the BeanDefinition resulting from the parsing of the supplied
253      *         {@link Element}
254      * @throws IllegalStateException if the bean {@link Class} returned from
255      *             {@link #getBeanClass(org.w3c.dom.Element)} is <code>null</code>
256      * @see #doParse
257      */
258     @Override
259     protected AbstractBeanDefinition parseInternal(Element element, ParserContext context)
260     {
261         preProcess(element);
262         setParserContext(context);
263         setRegistry(context.getRegistry());
264         checkElementNameUnique(element);
265         Class<?> beanClass = getClassInternal(element);
266         BeanDefinitionBuilder builder = createBeanDefinitionBuilder(element, beanClass);
267         builder.getRawBeanDefinition().setSource(context.extractSource(element));
268         builder.setScope(isSingleton() ? BeanDefinition.SCOPE_SINGLETON : BeanDefinition.SCOPE_PROTOTYPE);
269 
270         // Marker for MULE-4813
271         // We don't want lifcycle for the following from spring
272         if (!Component.class.isAssignableFrom(beanClass) && !MessageSource.class.isAssignableFrom(beanClass)
273             && !OutboundRouterCollection.class.isAssignableFrom(beanClass)
274             && !OutboundRouter.class.isAssignableFrom(beanClass)
275             && !AbstractExceptionStrategy.class.isAssignableFrom(beanClass)
276             && !MessageEnricher.class.isAssignableFrom(beanClass)
277             && !Transformer.class.isAssignableFrom(beanClass))
278         {
279             if (Initialisable.class.isAssignableFrom(beanClass))
280             {
281                 builder.setInitMethodName(Initialisable.PHASE_NAME);
282             }
283 
284             if (Disposable.class.isAssignableFrom(beanClass))
285             {
286                 builder.setDestroyMethodName(Disposable.PHASE_NAME);
287             }
288         }
289 
290         if (context.isNested())
291         {
292             // Inner bean definition must receive same singleton status as containing bean.
293             builder.setScope(context.getContainingBeanDefinition().isSingleton()
294                 ? BeanDefinition.SCOPE_SINGLETON : BeanDefinition.SCOPE_PROTOTYPE);
295         }
296 
297         doParse(element, context, builder);
298         return builder.getBeanDefinition();
299     }
300 
301     protected void setRegistry(BeanDefinitionRegistry registry)
302     {
303         this.registry = registry;
304     }
305 
306     protected BeanDefinitionRegistry getRegistry()
307     {
308         if (null == registry)
309         {
310             throw new IllegalStateException("Set the registry from within doParse");
311         }
312         return registry;
313     }
314 
315     protected void checkElementNameUnique(Element element)
316     {
317         if (null != element.getAttributeNode(ATTRIBUTE_NAME))
318         {
319             String name = element.getAttribute(ATTRIBUTE_NAME);
320             if (getRegistry().containsBeanDefinition(name))
321             {
322                 throw new IllegalArgumentException("A service named " + name + " already exists.");
323             }
324         }
325     }
326 
327     protected BeanDefinitionBuilder createBeanDefinitionBuilder(Element element, Class<?> beanClass)
328     {
329         BeanDefinitionBuilder builder = BeanDefinitionBuilder.rootBeanDefinition(beanClass);
330         // If a constructor with a single MuleContext argument is available then use it.
331         if (ClassUtils.getConstructor(beanClass, new Class[]{MuleContext.class}, true) != null)
332         {
333             builder.addConstructorArgReference(MuleProperties.OBJECT_MULE_CONTEXT);
334         }
335         return builder;
336     }
337 
338     protected Class<?> getClassInternal(Element element)
339     {
340         Class<?> beanClass = null;
341         if (isAllowClassAttribute())
342         {
343             beanClass = getBeanClassFromAttribute(element);
344         }
345         if (beanClass == null)
346         {
347             beanClass = getBeanClass(element);
348         }
349         if (null != beanClass && null != classConstraint && !classConstraint.isAssignableFrom(beanClass))
350         {
351             throw new IllegalStateException(beanClass + " not a subclass of " + classConstraint +
352                     " for " + XMLUtils.elementToString(element));
353         }
354         if (null == beanClass)
355         {
356             throw new IllegalStateException("No class for element " + XMLUtils.elementToString(element));
357         }
358         return beanClass;
359     }
360 
361     /**
362      * Determine the bean class corresponding to the supplied {@link Element} based on an
363      * explicit "class" attribute.
364      *
365      * @param element the <code>Element</code> that is being parsed
366      * @return the {@link Class} of the bean that is being defined via parsing the supplied <code>Element</code>
367      *         (must <b>not</b> be <code>null</code>)
368      * @see #parseInternal(org.w3c.dom.Element,ParserContext)
369      */
370     protected Class<?> getBeanClassFromAttribute(Element element)
371     {
372         String att = beanPropertyConfiguration.getAttributeAlias(ATTRIBUTE_CLASS);
373         String className = element.getAttribute(att);
374         Class<?> clazz = null;
375         if (StringUtils.isNotBlank(className))
376         {
377             try
378             {
379                 element.removeAttribute(att);
380                 clazz = ClassUtils.loadClass(className, getClass());
381             }
382             catch (ClassNotFoundException e)
383             {
384                 logger.error("could not load class: " + className, e);
385             }
386         }
387         return clazz;
388     }
389 
390     /**
391      * Determine the bean class corresponding to the supplied {@link Element}.
392      *
393      * @param element the <code>Element</code> that is being parsed
394      * @return the {@link Class} of the bean that is being defined via parsing the supplied <code>Element</code>
395      *         (must <b>not</b> be <code>null</code>)
396      * @see #parseInternal(org.w3c.dom.Element,ParserContext)
397      */
398     protected abstract Class<?> getBeanClass(Element element);
399 
400     /**
401      * Parse the supplied {@link Element} and populate the supplied
402      * {@link BeanDefinitionBuilder} as required.
403      * <p>
404      * The default implementation delegates to the <code>doParse</code> version
405      * without ParserContext argument.
406      *
407      * @param element the XML element being parsed
408      * @param context the object encapsulating the current state of the parsing
409      *            process
410      * @param builder used to define the <code>BeanDefinition</code>
411      */
412     protected void doParse(Element element, ParserContext context, BeanDefinitionBuilder builder)
413     {
414         if (deprecationWarning != null && logger.isWarnEnabled())
415         {
416             logger.warn("Schema warning: Use of element <" + element.getLocalName() + "> is deprecated.  " + deprecationWarning);
417         }
418 
419         BeanAssembler assembler = getBeanAssembler(element, builder);
420         NamedNodeMap attributes = element.getAttributes();
421         for (int x = 0; x < attributes.getLength(); x++)
422         {
423             Attr attribute = (Attr) attributes.item(x);
424             processProperty(attribute, assembler);
425         }
426         postProcess(getParserContext(), assembler, element);
427     }
428 
429     @Override
430     protected String resolveId(Element element, AbstractBeanDefinition definition,
431         ParserContext context) throws BeanDefinitionStoreException
432     {
433         return getBeanName(element);
434     }
435 
436     protected boolean isSingleton()
437     {
438         return singleton;
439     }
440 
441     /**
442      * Restricted use - does not include a target.
443      * If possible, use {@link org.mule.config.spring.parsers.AbstractHierarchicalDefinitionParser#getBeanAssembler(org.w3c.dom.Element, org.springframework.beans.factory.support.BeanDefinitionBuilder)}
444      *
445      * @param bean The bean being constructed
446      * @return An assembler that automates Mule-specific logic for bean construction
447      */
448     protected BeanAssembler getBeanAssembler(Element element, BeanDefinitionBuilder bean)
449     {
450         return getBeanAssemblerFactory().newBeanAssembler(
451                 beanPropertyConfiguration, bean, beanPropertyConfiguration, null);
452     }
453 
454     protected boolean isAllowClassAttribute()
455     {
456         return allowClassAttribute;
457     }
458 
459     protected void setAllowClassAttribute(boolean allowClassAttribute)
460     {
461         this.allowClassAttribute = allowClassAttribute;
462     }
463 
464     protected Class<?> getClassConstraint()
465     {
466         return classConstraint;
467     }
468 
469     protected void setClassConstraint(Class<?> classConstraint)
470     {
471         this.classConstraint = classConstraint;
472     }
473 
474     protected ParserContext getParserContext()
475     {
476         return parserContext;
477     }
478 
479     protected void setParserContext(ParserContext parserContext)
480     {
481         this.parserContext = parserContext;
482     }
483 
484     /**
485      * @param element The element to test
486      * @return true if the element's parent is <mule> or similar
487      */
488     protected boolean isTopLevel(Element element)
489     {
490         return element.getParentNode().getLocalName().equals(ROOT_ELEMENT);
491     }
492 
493     public AbstractBeanDefinition muleParse(Element element, ParserContext context)
494     {
495         return parseInternal(element, context);
496     }
497 
498     public MuleDefinitionParserConfiguration registerPreProcessor(PreProcessor preProcessor)
499     {
500         preProcessors.addFirst(preProcessor);
501         return this;
502     }
503 
504     public MuleDefinitionParserConfiguration registerPostProcessor(PostProcessor postProcessor)
505     {
506         postProcessors.add(postProcessor);
507         return this;
508     }
509 
510     public BeanAssemblerFactory getBeanAssemblerFactory()
511     {
512         return beanAssemblerFactory;
513     }
514 
515     public void setBeanAssemblerFactory(BeanAssemblerFactory beanAssemblerFactory)
516     {
517         this.beanAssemblerFactory = beanAssemblerFactory;
518     }
519 
520     public String getBeanName(Element element)
521     {
522         return AutoIdUtils.getUniqueName(element, "mule-bean");
523     }
524 
525     public MuleDefinitionParserConfiguration addBeanFlag(String flag)
526     {
527         beanAttributes.add(flag);
528         return this;
529     }
530 
531     public void setDeprecationWarning(String deprecationWarning)
532     {
533         this.deprecationWarning = deprecationWarning;
534     }
535 }