KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > tomcat > util > digester > 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 JavaDoc;
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 JavaDoc 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 JavaDoc 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 JavaDoc className, String JavaDoc 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 JavaDoc clazz, String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc className, String JavaDoc 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 JavaDoc clazz, String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc className,
277                                 String JavaDoc 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 JavaDoc clazz,
301                                 String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc namespace, String JavaDoc name, Attributes JavaDoc attributes) throws Exception JavaDoc {
358         
359         if (ignoreCreateExceptions) {
360         
361             if (exceptionIgnoredStack == null) {
362                 exceptionIgnoredStack = new ArrayStack();
363             }
364             
365             try {
366                 Object JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc namespace, String JavaDoc name) throws Exception JavaDoc {
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 JavaDoc) 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 JavaDoc 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 JavaDoc {
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 JavaDoc toString() {
446
447         StringBuffer JavaDoc sb = new StringBuffer JavaDoc("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 JavaDoc attributes)
474             throws Exception JavaDoc {
475
476         if (creationFactory == null) {
477             String JavaDoc realClassName = className;
478             if (attributeName != null) {
479                 String JavaDoc 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 JavaDoc clazz = digester.getClassLoader().loadClass(realClassName);
489             creationFactory = (ObjectCreationFactory)
490                     clazz.newInstance();
491             creationFactory.setDigester(digester);
492         }
493         return (creationFactory);
494
495     }
496 }
497
Popular Tags