FactoryCreateRule


1   /* $Id: FactoryCreateRule.java 467222 2006-10-24 03:17:11Z markt $
2    *
3    * Licensed to the Apache Software Foundation (ASF) under one or more
4    * contributor license agreements.  See the NOTICE file distributed with
5    * this work for additional information regarding copyright ownership.
6    * The ASF licenses this file to You under the Apache License, Version 2.0
7    * (the "License"); you may not use this file except in compliance with
8    * the License.  You may obtain a copy of the License at
9    * 
10   *      http://www.apache.org/licenses/LICENSE-2.0
11   * 
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */ 
18  
19  
20  package org.apache.tomcat.util.digester;
21  
22  import org.xml.sax.Attributes  ;
23  
24  
25  /**
26   * <p>Rule implementation that uses an {@link ObjectCreationFactory} to create
27   * a new object which it pushes onto the object stack.  When the element is
28   * complete, the object will be popped.</p>
29   *
30   * <p>This rule is intended in situations where the element's attributes are
31   * needed before the object can be created.  A common senario is for the
32   * ObjectCreationFactory implementation to use the attributes  as parameters
33   * in a call to either a factory method or to a non-empty constructor.
34   */
35  
36  public class FactoryCreateRule extends Rule {
37  
38      // ----------------------------------------------------------- Fields
39      
40      /** Should exceptions thrown by the factory be ignored? */
41      private boolean ignoreCreateExceptions;
42      /** Stock to manage */
43      private ArrayStack exceptionIgnoredStack;
44  
45      // ----------------------------------------------------------- Constructors
46  
47  
48      /**
49       * Construct a factory create rule that will use the specified
50       * class name to create an {@link ObjectCreationFactory} which will
51       * then be used to create an object and push it on the stack.
52       *
53       * @param digester The associated Digester
54       * @param className Java class name of the object creation factory class
55       *
56       * @deprecated The digester instance is now set in the {@link Digester#addRule} method. 
57       * Use {@link #FactoryCreateRule(String className)} instead.
58       */
59      public FactoryCreateRule(Digester digester, String   className) {
60  
61          this(className);
62  
63      }
64  
65  
66      /**
67       * Construct a factory create rule that will use the specified
68       * class to create an {@link ObjectCreationFactory} which will
69       * then be used to create an object and push it on the stack.
70       *
71       * @param digester The associated Digester
72       * @param clazz Java class name of the object creation factory class
73       *
74       * @deprecated The digester instance is now set in the {@link Digester#addRule} method. 
75       * Use {@link #FactoryCreateRule(Class clazz)} instead.
76       */
77      public FactoryCreateRule(Digester digester, Class   clazz) {
78  
79          this(clazz);
80  
81      }
82  
83  
84      /**
85       * Construct a factory create rule that will use the specified
86       * class name (possibly overridden by the specified attribute if present)
87       * to create an {@link ObjectCreationFactory}, which will then be used
88       * to instantiate an object instance and push it onto the stack.
89       *
90       * @param digester The associated Digester
91       * @param className Default Java class name of the factory class
92       * @param attributeName Attribute name which, if present, contains an
93       *  override of the class name of the object creation factory to create.
94       *
95       * @deprecated The digester instance is now set in the {@link Digester#addRule} method. 
96       * Use {@link #FactoryCreateRule(String className, String attributeName)} instead.
97       */
98      public FactoryCreateRule(Digester digester,
99                               String   className, String   attributeName) {
100 
101         this(className, attributeName);
102 
103     }
104 
105 
106     /**
107      * Construct a factory create rule that will use the specified
108      * class (possibly overridden by the specified attribute if present)
109      * to create an {@link ObjectCreationFactory}, which will then be used
110      * to instantiate an object instance and push it onto the stack.
111      *
112      * @param digester The associated Digester
113      * @param clazz Default Java class name of the factory class
114      * @param attributeName Attribute name which, if present, contains an
115      *  override of the class name of the object creation factory to create.
116      *
117      * @deprecated The digester instance is now set in the {@link Digester#addRule} method. 
118      * Use {@link #FactoryCreateRule(Class clazz, String attributeName)} instead.
119      */
120     public FactoryCreateRule(Digester digester,
121                              Class   clazz, String   attributeName) {
122 
123         this(clazz, attributeName);
124 
125     }
126 
127 
128     /**
129      * Construct a factory create rule using the given, already instantiated,
130      * {@link ObjectCreationFactory}.
131      *
132      * @param digester The associated Digester
133      * @param creationFactory called on to create the object.
134      *
135      * @deprecated The digester instance is now set in the {@link Digester#addRule} method. 
136      * Use {@link #FactoryCreateRule(ObjectCreationFactory creationFactory)} instead.
137      */
138     public FactoryCreateRule(Digester digester,
139                              ObjectCreationFactory creationFactory) {
140 
141         this(creationFactory);
142 
143     }    
144 
145     /**
146      * <p>Construct a factory create rule that will use the specified
147      * class name to create an {@link ObjectCreationFactory} which will
148      * then be used to create an object and push it on the stack.</p>
149      *
150      * <p>Exceptions thrown during the object creation process will be propagated.</p>
151      *
152      * @param className Java class name of the object creation factory class
153      */
154     public FactoryCreateRule(String   className) {
155 
156         this(className, false);
157 
158     }
159 
160 
161     /**
162      * <p>Construct a factory create rule that will use the specified
163      * class to create an {@link ObjectCreationFactory} which will
164      * then be used to create an object and push it on the stack.</p>
165      *
166      * <p>Exceptions thrown during the object creation process will be propagated.</p>
167      *
168      * @param clazz Java class name of the object creation factory class
169      */
170     public FactoryCreateRule(Class   clazz) {
171 
172         this(clazz, false);
173 
174     }
175 
176 
177     /**
178      * <p>Construct a factory create rule that will use the specified
179      * class name (possibly overridden by the specified attribute if present)
180      * to create an {@link ObjectCreationFactory}, which will then be used
181      * to instantiate an object instance and push it onto the stack.</p>
182      *
183      * <p>Exceptions thrown during the object creation process will be propagated.</p>
184      *
185      * @param className Default Java class name of the factory class
186      * @param attributeName Attribute name which, if present, contains an
187      *  override of the class name of the object creation factory to create.
188      */
189     public FactoryCreateRule(String   className, String   attributeName) {
190 
191         this(className, attributeName, false);
192 
193     }
194 
195 
196     /**
197      * <p>Construct a factory create rule that will use the specified
198      * class (possibly overridden by the specified attribute if present)
199      * to create an {@link ObjectCreationFactory}, which will then be used
200      * to instantiate an object instance and push it onto the stack.</p>
201      *
202      * <p>Exceptions thrown during the object creation process will be propagated.</p>
203      *
204      * @param clazz Default Java class name of the factory class
205      * @param attributeName Attribute name which, if present, contains an
206      *  override of the class name of the object creation factory to create.
207      */
208     public FactoryCreateRule(Class   clazz, String   attributeName) {
209 
210         this(clazz, attributeName, false);
211 
212     }
213 
214 
215     /**
216      * <p>Construct a factory create rule using the given, already instantiated,
217      * {@link ObjectCreationFactory}.</p>
218      *
219      * <p>Exceptions thrown during the object creation process will be propagated.</p>
220      *
221      * @param creationFactory called on to create the object.
222      */
223     public FactoryCreateRule(ObjectCreationFactory creationFactory) {
224 
225         this(creationFactory, false);
226 
227     }
228     
229     /**
230      * Construct a factory create rule that will use the specified
231      * class name to create an {@link ObjectCreationFactory} which will
232      * then be used to create an object and push it on the stack.
233      *
234      * @param className Java class name of the object creation factory class
235      * @param ignoreCreateExceptions if true, exceptions thrown by the object
236      *  creation factory
237      * will be ignored.
238      */
239     public FactoryCreateRule(String   className, boolean ignoreCreateExceptions) {
240 
241         this(className, null, ignoreCreateExceptions);
242 
243     }
244 
245 
246     /**
247      * Construct a factory create rule that will use the specified
248      * class to create an {@link ObjectCreationFactory} which will
249      * then be used to create an object and push it on the stack.
250      *
251      * @param clazz Java class name of the object creation factory class
252      * @param ignoreCreateExceptions if true, exceptions thrown by the
253      *  object creation factory
254      * will be ignored.
255      */
256     public FactoryCreateRule(Class   clazz, boolean ignoreCreateExceptions) {
257 
258         this(clazz, null, ignoreCreateExceptions);
259 
260     }
261 
262 
263     /**
264      * Construct a factory create rule that will use the specified
265      * class name (possibly overridden by the specified attribute if present)
266      * to create an {@link ObjectCreationFactory}, which will then be used
267      * to instantiate an object instance and push it onto the stack.
268      *
269      * @param className Default Java class name of the factory class
270      * @param attributeName Attribute name which, if present, contains an
271      *  override of the class name of the object creation factory to create.
272      * @param ignoreCreateExceptions if true, exceptions thrown by the object
273      *  creation factory will be ignored.
274      */
275     public FactoryCreateRule(
276                                 String   className, 
277                                 String   attributeName,
278                                 boolean ignoreCreateExceptions) {
279 
280         this.className = className;
281         this.attributeName = attributeName;
282         this.ignoreCreateExceptions = ignoreCreateExceptions;
283 
284     }
285 
286 
287     /**
288      * Construct a factory create rule that will use the specified
289      * class (possibly overridden by the specified attribute if present)
290      * to create an {@link ObjectCreationFactory}, which will then be used
291      * to instantiate an object instance and push it onto the stack.
292      *
293      * @param clazz Default Java class name of the factory class
294      * @param attributeName Attribute name which, if present, contains an
295      *  override of the class name of the object creation factory to create.
296      * @param ignoreCreateExceptions if true, exceptions thrown by the object
297      *  creation factory will be ignored.
298      */
299     public FactoryCreateRule(
300                                 Class   clazz, 
301                                 String   attributeName,
302                                 boolean ignoreCreateExceptions) {
303 
304         this(clazz.getName(), attributeName, ignoreCreateExceptions);
305 
306     }
307 
308 
309     /**
310      * Construct a factory create rule using the given, already instantiated,
311      * {@link ObjectCreationFactory}.
312      *
313      * @param creationFactory called on to create the object.
314      * @param ignoreCreateExceptions if true, exceptions thrown by the object
315      *  creation factory will be ignored.
316      */
317     public FactoryCreateRule(
318                             ObjectCreationFactory creationFactory, 
319                             boolean ignoreCreateExceptions) {
320 
321         this.creationFactory = creationFactory;
322         this.ignoreCreateExceptions = ignoreCreateExceptions;
323     }
324 
325     // ----------------------------------------------------- Instance Variables
326 
327 
328     /**
329      * The attribute containing an override class name if it is present.
330      */
331     protected String   attributeName = null;
332 
333 
334     /**
335      * The Java class name of the ObjectCreationFactory to be created.
336      * This class must have a no-arguments constructor.
337      */
338     protected String   className = null;
339 
340 
341     /**
342      * The object creation factory we will use to instantiate objects
343      * as required based on the attributes specified in the matched XML
344      * element.
345      */
346     protected ObjectCreationFactory creationFactory = null;
347 
348 
349     // --------------------------------------------------------- Public Methods
350 
351 
352     /**
353      * Process the beginning of this element.
354      *
355      * @param attributes The attribute list of this element
356      */
357     public void begin(String   namespace, String   name, Attributes   attributes) throws Exception   {
358         
359         if (ignoreCreateExceptions) {
360         
361             if (exceptionIgnoredStack == null) {
362                 exceptionIgnoredStack = new ArrayStack();
363             }
364             
365             try {
366                 Object   instance = getFactory(attributes).createObject(attributes);
367                 
368                 if (digester.log.isDebugEnabled()) {
369                     digester.log.debug("[FactoryCreateRule]{" + digester.match +
370                             "} New " + instance.getClass().getName());
371                 }
372                 digester.push(instance);
373                 exceptionIgnoredStack.push(Boolean.FALSE);
374                 
375             } catch (Exception   e) {
376                 // log message and error
377                 if (digester.log.isInfoEnabled()) {
378                     digester.log.info("[FactoryCreateRule] Create exception ignored: " +
379                         ((e.getMessage() == null) ? e.getClass().getName() : e.getMessage()));
380                     if (digester.log.isDebugEnabled()) {
381                         digester.log.debug("[FactoryCreateRule] Ignored exception:", e);
382                     }
383                 }
384                 exceptionIgnoredStack.push(Boolean.TRUE);
385             }
386             
387         } else {
388             Object   instance = getFactory(attributes).createObject(attributes);
389             
390             if (digester.log.isDebugEnabled()) {
391                 digester.log.debug("[FactoryCreateRule]{" + digester.match +
392                         "} New " + instance.getClass().getName());
393             }
394             digester.push(instance);
395         }
396     }
397 
398 
399     /**
400      * Process the end of this element.
401      */
402     public void end(String   namespace, String   name) throws Exception   {
403         
404         // check if object was created 
405         // this only happens if an exception was thrown and we're ignoring them
406         if (    
407                 ignoreCreateExceptions &&
408                 exceptionIgnoredStack != null &&
409                 !(exceptionIgnoredStack.empty())) {
410                 
411             if (((Boolean  ) exceptionIgnoredStack.pop()).booleanValue()) {
412                 // creation exception was ignored
413                 // nothing was put onto the stack
414                 if (digester.log.isTraceEnabled()) {
415                     digester.log.trace("[FactoryCreateRule] No creation so no push so no pop");
416                 }
417                 return;
418             }
419         } 
420 
421         Object   top = digester.pop();
422         if (digester.log.isDebugEnabled()) {
423             digester.log.debug("[FactoryCreateRule]{" + digester.match +
424                     "} Pop " + top.getClass().getName());
425         }
426 
427     }
428 
429 
430     /**
431      * Clean up after parsing is complete.
432      */
433     public void finish() throws Exception   {
434 
435         if (attributeName != null) {
436             creationFactory = null;
437         }
438 
439     }
440 
441 
442     /**
443      * Render a printable version of this Rule.
444      */
445     public String   toString() {
446 
447         StringBuffer   sb = new StringBuffer  ("FactoryCreateRule[");
448         sb.append("className=");
449         sb.append(className);
450         sb.append(", attributeName=");
451         sb.append(attributeName);
452         if (creationFactory != null) {
453             sb.append(", creationFactory=");
454             sb.append(creationFactory);
455         }
456         sb.append("]");
457         return (sb.toString());
458 
459     }
460 
461 
462     // ------------------------------------------------------ Protected Methods
463 
464 
465     /**
466      * Return an instance of our associated object creation factory,
467      * creating one if necessary.
468      *
469      * @param attributes Attributes passed to our factory creation element
470      *
471      * @exception Exception if any error occurs
472      */
473     protected ObjectCreationFactory getFactory(Attributes   attributes)
474             throws Exception   {
475 
476         if (creationFactory == null) {
477             String   realClassName = className;
478             if (attributeName != null) {
479                 String   value = attributes.getValue(attributeName);
480                 if (value != null) {
481                     realClassName = value;
482                 }
483             }
484             if (digester.log.isDebugEnabled()) {
485                 digester.log.debug("[FactoryCreateRule]{" + digester.match +
486                         "} New factory " + realClassName);
487             }
488             Class   clazz = digester.getClassLoader().loadClass(realClassName);
489             creationFactory = (ObjectCreationFactory)
490                     clazz.newInstance();
491             creationFactory.setDigester(digester);
492         }
493         return (creationFactory);
494 
495     }    
496 }
497
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags