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