View Javadoc

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