FileDocCategorySizeDatePackage
FactoryCreateRule.javaAPI DocApache Tomcat 6.0.1418083Fri Jul 20 04:20:34 BST 2007org.apache.tomcat.util.digester

FactoryCreateRule

public class FactoryCreateRule extends Rule

Rule implementation that uses an {@link ObjectCreationFactory} to create a new object which it pushes onto the object stack. When the element is complete, the object will be popped.

This rule is intended in situations where the element's attributes are needed before the object can be created. A common senario is for the ObjectCreationFactory implementation to use the attributes as parameters in a call to either a factory method or to a non-empty constructor.

Fields Summary
private boolean
ignoreCreateExceptions
Should exceptions thrown by the factory be ignored?
private ArrayStack
exceptionIgnoredStack
Stock to manage
protected String
attributeName
The attribute containing an override class name if it is present.
protected String
className
The Java class name of the ObjectCreationFactory to be created. This class must have a no-arguments constructor.
protected ObjectCreationFactory
creationFactory
The object creation factory we will use to instantiate objects as required based on the attributes specified in the matched XML element.
Constructors Summary
public FactoryCreateRule(Digester digester, String className)
Construct a factory create rule that will use the specified class name to create an {@link ObjectCreationFactory} which will then be used to create an object and push it on the stack.

param
digester The associated Digester
param
className Java class name of the object creation factory class
deprecated
The digester instance is now set in the {@link Digester#addRule} method. Use {@link #FactoryCreateRule(String className)} instead.


        this(className);
public FactoryCreateRule(ObjectCreationFactory creationFactory)

Construct a factory create rule using the given, already instantiated, {@link ObjectCreationFactory}.

Exceptions thrown during the object creation process will be propagated.

param
creationFactory called on to create the object.


        this(creationFactory, false);
public FactoryCreateRule(String className, boolean ignoreCreateExceptions)
Construct a factory create rule that will use the specified class name to create an {@link ObjectCreationFactory} which will then be used to create an object and push it on the stack.

param
className Java class name of the object creation factory class
param
ignoreCreateExceptions if true, exceptions thrown by the object creation factory will be ignored.


        this(className, null, ignoreCreateExceptions);
public FactoryCreateRule(Class clazz, boolean ignoreCreateExceptions)
Construct a factory create rule that will use the specified class to create an {@link ObjectCreationFactory} which will then be used to create an object and push it on the stack.

param
clazz Java class name of the object creation factory class
param
ignoreCreateExceptions if true, exceptions thrown by the object creation factory will be ignored.


        this(clazz, null, ignoreCreateExceptions);
public FactoryCreateRule(String className, String attributeName, boolean ignoreCreateExceptions)
Construct a factory create rule that will use the specified class name (possibly overridden by the specified attribute if present) to create an {@link ObjectCreationFactory}, which will then be used to instantiate an object instance and push it onto the stack.

param
className Default Java class name of the factory class
param
attributeName Attribute name which, if present, contains an override of the class name of the object creation factory to create.
param
ignoreCreateExceptions if true, exceptions thrown by the object creation factory will be ignored.


        this.className = className;
        this.attributeName = attributeName;
        this.ignoreCreateExceptions = ignoreCreateExceptions;
public FactoryCreateRule(Class clazz, String attributeName, boolean ignoreCreateExceptions)
Construct a factory create rule that will use the specified class (possibly overridden by the specified attribute if present) to create an {@link ObjectCreationFactory}, which will then be used to instantiate an object instance and push it onto the stack.

param
clazz Default Java class name of the factory class
param
attributeName Attribute name which, if present, contains an override of the class name of the object creation factory to create.
param
ignoreCreateExceptions if true, exceptions thrown by the object creation factory will be ignored.


        this(clazz.getName(), attributeName, ignoreCreateExceptions);
public FactoryCreateRule(ObjectCreationFactory creationFactory, boolean ignoreCreateExceptions)
Construct a factory create rule using the given, already instantiated, {@link ObjectCreationFactory}.

param
creationFactory called on to create the object.
param
ignoreCreateExceptions if true, exceptions thrown by the object creation factory will be ignored.


        this.creationFactory = creationFactory;
        this.ignoreCreateExceptions = ignoreCreateExceptions;
public FactoryCreateRule(Digester digester, Class clazz)
Construct a factory create rule that will use the specified class to create an {@link ObjectCreationFactory} which will then be used to create an object and push it on the stack.

param
digester The associated Digester
param
clazz Java class name of the object creation factory class
deprecated
The digester instance is now set in the {@link Digester#addRule} method. Use {@link #FactoryCreateRule(Class clazz)} instead.


        this(clazz);
public FactoryCreateRule(Digester digester, String className, String attributeName)
Construct a factory create rule that will use the specified class name (possibly overridden by the specified attribute if present) to create an {@link ObjectCreationFactory}, which will then be used to instantiate an object instance and push it onto the stack.

param
digester The associated Digester
param
className Default Java class name of the factory class
param
attributeName Attribute name which, if present, contains an override of the class name of the object creation factory to create.
deprecated
The digester instance is now set in the {@link Digester#addRule} method. Use {@link #FactoryCreateRule(String className, String attributeName)} instead.


        this(className, attributeName);
public FactoryCreateRule(Digester digester, Class clazz, String attributeName)
Construct a factory create rule that will use the specified class (possibly overridden by the specified attribute if present) to create an {@link ObjectCreationFactory}, which will then be used to instantiate an object instance and push it onto the stack.

param
digester The associated Digester
param
clazz Default Java class name of the factory class
param
attributeName Attribute name which, if present, contains an override of the class name of the object creation factory to create.
deprecated
The digester instance is now set in the {@link Digester#addRule} method. Use {@link #FactoryCreateRule(Class clazz, String attributeName)} instead.


        this(clazz, attributeName);
public FactoryCreateRule(Digester digester, ObjectCreationFactory creationFactory)
Construct a factory create rule using the given, already instantiated, {@link ObjectCreationFactory}.

param
digester The associated Digester
param
creationFactory called on to create the object.
deprecated
The digester instance is now set in the {@link Digester#addRule} method. Use {@link #FactoryCreateRule(ObjectCreationFactory creationFactory)} instead.


        this(creationFactory);
public FactoryCreateRule(String className)

Construct a factory create rule that will use the specified class name to create an {@link ObjectCreationFactory} which will then be used to create an object and push it on the stack.

Exceptions thrown during the object creation process will be propagated.

param
className Java class name of the object creation factory class


        this(className, false);
public FactoryCreateRule(Class clazz)

Construct a factory create rule that will use the specified class to create an {@link ObjectCreationFactory} which will then be used to create an object and push it on the stack.

Exceptions thrown during the object creation process will be propagated.

param
clazz Java class name of the object creation factory class


        this(clazz, false);
public FactoryCreateRule(String className, String attributeName)

Construct a factory create rule that will use the specified class name (possibly overridden by the specified attribute if present) to create an {@link ObjectCreationFactory}, which will then be used to instantiate an object instance and push it onto the stack.

Exceptions thrown during the object creation process will be propagated.

param
className Default Java class name of the factory class
param
attributeName Attribute name which, if present, contains an override of the class name of the object creation factory to create.


        this(className, attributeName, false);
public FactoryCreateRule(Class clazz, String attributeName)

Construct a factory create rule that will use the specified class (possibly overridden by the specified attribute if present) to create an {@link ObjectCreationFactory}, which will then be used to instantiate an object instance and push it onto the stack.

Exceptions thrown during the object creation process will be propagated.

param
clazz Default Java class name of the factory class
param
attributeName Attribute name which, if present, contains an override of the class name of the object creation factory to create.


        this(clazz, attributeName, false);
Methods Summary
public voidbegin(java.lang.String namespace, java.lang.String name, org.xml.sax.Attributes attributes)
Process the beginning of this element.

param
attributes The attribute list of this element



    // --------------------------------------------------------- Public Methods


                       
              
        
        if (ignoreCreateExceptions) {
        
            if (exceptionIgnoredStack == null) {
                exceptionIgnoredStack = new ArrayStack();
            }
            
            try {
                Object instance = getFactory(attributes).createObject(attributes);
                
                if (digester.log.isDebugEnabled()) {
                    digester.log.debug("[FactoryCreateRule]{" + digester.match +
                            "} New " + instance.getClass().getName());
                }
                digester.push(instance);
                exceptionIgnoredStack.push(Boolean.FALSE);
                
            } catch (Exception e) {
                // log message and error
                if (digester.log.isInfoEnabled()) {
                    digester.log.info("[FactoryCreateRule] Create exception ignored: " +
                        ((e.getMessage() == null) ? e.getClass().getName() : e.getMessage()));
                    if (digester.log.isDebugEnabled()) {
                        digester.log.debug("[FactoryCreateRule] Ignored exception:", e);
                    }
                }
                exceptionIgnoredStack.push(Boolean.TRUE);
            }
            
        } else {
            Object instance = getFactory(attributes).createObject(attributes);
            
            if (digester.log.isDebugEnabled()) {
                digester.log.debug("[FactoryCreateRule]{" + digester.match +
                        "} New " + instance.getClass().getName());
            }
            digester.push(instance);
        }
public voidend(java.lang.String namespace, java.lang.String name)
Process the end of this element.

        
        // check if object was created 
        // this only happens if an exception was thrown and we're ignoring them
        if (	
                ignoreCreateExceptions &&
                exceptionIgnoredStack != null &&
                !(exceptionIgnoredStack.empty())) {
                
            if (((Boolean) exceptionIgnoredStack.pop()).booleanValue()) {
                // creation exception was ignored
                // nothing was put onto the stack
                if (digester.log.isTraceEnabled()) {
                    digester.log.trace("[FactoryCreateRule] No creation so no push so no pop");
                }
                return;
            }
        } 

        Object top = digester.pop();
        if (digester.log.isDebugEnabled()) {
            digester.log.debug("[FactoryCreateRule]{" + digester.match +
                    "} Pop " + top.getClass().getName());
        }
public voidfinish()
Clean up after parsing is complete.


        if (attributeName != null) {
            creationFactory = null;
        }
protected ObjectCreationFactorygetFactory(org.xml.sax.Attributes attributes)
Return an instance of our associated object creation factory, creating one if necessary.

param
attributes Attributes passed to our factory creation element
exception
Exception if any error occurs


        if (creationFactory == null) {
            String realClassName = className;
            if (attributeName != null) {
                String value = attributes.getValue(attributeName);
                if (value != null) {
                    realClassName = value;
                }
            }
            if (digester.log.isDebugEnabled()) {
                digester.log.debug("[FactoryCreateRule]{" + digester.match +
                        "} New factory " + realClassName);
            }
            Class clazz = digester.getClassLoader().loadClass(realClassName);
            creationFactory = (ObjectCreationFactory)
                    clazz.newInstance();
            creationFactory.setDigester(digester);
        }
        return (creationFactory);
public java.lang.StringtoString()
Render a printable version of this Rule.


        StringBuffer sb = new StringBuffer("FactoryCreateRule[");
        sb.append("className=");
        sb.append(className);
        sb.append(", attributeName=");
        sb.append(attributeName);
        if (creationFactory != null) {
            sb.append(", creationFactory=");
            sb.append(creationFactory);
        }
        sb.append("]");
        return (sb.toString());