Class PluginCreateRule

  • All Implemented Interfaces:
    InitializableRule

    public class PluginCreateRule
    extends Rule
    implements InitializableRule
    Allows the original rules for parsing the configuration file to define points at which plugins are allowed, by configuring a PluginCreateRule with the appropriate pattern.
    Since:
    1.6
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private java.lang.Class<?> baseClass
      A base class that any plugin must derive from.
      private Declaration defaultPlugin
      Info about optional default plugin to be used if no plugin-id is specified in the input data.
      private PluginConfigurationException initException
      Currently, none of the Rules methods allow exceptions to be thrown.
      private java.lang.String pattern
      In order to invoke the addRules method on the plugin class correctly, we need to know the pattern which this rule is matched by.
      private java.lang.String pluginClassAttr  
      private java.lang.String pluginClassAttrNs  
      private java.lang.String pluginIdAttr  
      private java.lang.String pluginIdAttrNs  
    • Constructor Summary

      Constructors 
      Constructor Description
      PluginCreateRule​(java.lang.Class<?> baseClass)
      Create a plugin rule where the user must specify a plugin-class or plugin-id.
      PluginCreateRule​(java.lang.Class<?> baseClass, java.lang.Class<?> dfltPluginClass)
      Create a plugin rule where the user may specify a plugin.
      PluginCreateRule​(java.lang.Class<?> baseClass, java.lang.Class<?> dfltPluginClass, RuleLoader dfltPluginRuleLoader)
      Create a plugin rule where the user may specify a plugin.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void begin​(java.lang.String namespace, java.lang.String name, org.xml.sax.Attributes attributes)
      Invoked when the Digester matches this rule against an xml element.
      void body​(java.lang.String namespace, java.lang.String name, java.lang.String text)
      This method is called when the body of a matching XML element is encountered.
      void end​(java.lang.String namespace, java.lang.String name)
      This method is called when the end of a matching XML element is encountered.
      void fireBeginMethods​(java.util.List<Rule> rules, java.lang.String namespace, java.lang.String name, org.xml.sax.Attributes list)
      Duplicate the processing that the Digester does when firing the begin methods of rules.
      private void fireBodyMethods​(java.util.List<Rule> rules, java.lang.String namespaceURI, java.lang.String name, java.lang.String text)
      Duplicate the processing that the Digester does when firing the Rule.body(String, String, String) methods of rules.
      void fireEndMethods​(java.util.List<Rule> rules, java.lang.String namespaceURI, java.lang.String name)
      Duplicate the processing that the Digester does when firing the end methods of rules.
      java.lang.String getPattern()
      Return the pattern that this Rule is associated with.
      void postRegisterInit​(java.lang.String matchPattern)
      Called after this Rule object has been added to the list of all Rules.
      void setPluginClassAttribute​(java.lang.String namespaceUri, java.lang.String attrName)
      Sets the xml attribute which the input xml uses to indicate to a PluginCreateRule which class should be instantiated.
      void setPluginIdAttribute​(java.lang.String namespaceUri, java.lang.String attrName)
      Sets the xml attribute which the input xml uses to indicate to a PluginCreateRule which plugin declaration is being referenced.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • pluginClassAttrNs

        private java.lang.String pluginClassAttrNs
      • pluginClassAttr

        private java.lang.String pluginClassAttr
      • pluginIdAttrNs

        private java.lang.String pluginIdAttrNs
      • pluginIdAttr

        private java.lang.String pluginIdAttr
      • pattern

        private java.lang.String pattern
        In order to invoke the addRules method on the plugin class correctly, we need to know the pattern which this rule is matched by.
      • baseClass

        private java.lang.Class<?> baseClass
        A base class that any plugin must derive from.
      • defaultPlugin

        private Declaration defaultPlugin
        Info about optional default plugin to be used if no plugin-id is specified in the input data. This can simplify the syntax where one particular plugin is usually used.
      • initException

        private PluginConfigurationException initException
        Currently, none of the Rules methods allow exceptions to be thrown. Therefore if this class cannot initialise itself properly, it cannot cause the digester to stop. Instead, we cache the exception and throw it the first time the begin() method is called.
    • Constructor Detail

      • PluginCreateRule

        public PluginCreateRule​(java.lang.Class<?> baseClass)
        Create a plugin rule where the user must specify a plugin-class or plugin-id.
        Parameters:
        baseClass - is the class which any specified plugin must be descended from.
      • PluginCreateRule

        public PluginCreateRule​(java.lang.Class<?> baseClass,
                                java.lang.Class<?> dfltPluginClass)
        Create a plugin rule where the user may specify a plugin. If the user doesn't specify a plugin, then the default class specified in this constructor is used.
        Parameters:
        baseClass - is the class which any specified plugin must be descended from.
        dfltPluginClass - is the class which will be used if the user doesn't specify any plugin-class or plugin-id. This class will have custom rules installed for it just like a declared plugin.
      • PluginCreateRule

        public PluginCreateRule​(java.lang.Class<?> baseClass,
                                java.lang.Class<?> dfltPluginClass,
                                RuleLoader dfltPluginRuleLoader)
        Create a plugin rule where the user may specify a plugin. If the user doesn't specify a plugin, then the default class specified in this constructor is used.
        Parameters:
        baseClass - is the class which any specified plugin must be descended from.
        dfltPluginClass - is the class which will be used if the user doesn't specify any plugin-class or plugin-id. This class will have custom rules installed for it just like a declared plugin.
        dfltPluginRuleLoader - is a RuleLoader instance which knows how to load the custom rules associated with this default plugin.
    • Method Detail

      • setPluginClassAttribute

        public void setPluginClassAttribute​(java.lang.String namespaceUri,
                                            java.lang.String attrName)
        Sets the xml attribute which the input xml uses to indicate to a PluginCreateRule which class should be instantiated.

        See PluginRules.setPluginClassAttribute(java.lang.String, java.lang.String) for more info.

        Parameters:
        namespaceUri - is the namespace uri that the specified attribute is in. If the attribute is in no namespace, then this should be null. Note that if a namespace is used, the attrName value should not contain any kind of namespace-prefix. Note also that if you are using a non-namespace-aware parser, this parameter must be null.
        attrName - is the attribute whose value contains the name of the class to be instantiated.
      • setPluginIdAttribute

        public void setPluginIdAttribute​(java.lang.String namespaceUri,
                                         java.lang.String attrName)
        Sets the xml attribute which the input xml uses to indicate to a PluginCreateRule which plugin declaration is being referenced.

        See PluginRules.setPluginIdAttribute(java.lang.String, java.lang.String) for more info.

        Parameters:
        namespaceUri - is the namespace uri that the specified attribute is in. If the attribute is in no namespace, then this should be null. Note that if a namespace is used, the attrName value should not contain any kind of namespace-prefix. Note also that if you are using a non-namespace-aware parser, this parameter must be null.
        attrName - is the attribute whose value contains the id of the plugin declaration to be used when instantiating an object.
      • postRegisterInit

        public void postRegisterInit​(java.lang.String matchPattern)
        Called after this Rule object has been added to the list of all Rules. Note that if a single InitializableRule instance is associated with more than one pattern, then this method will be called more than once.
        Specified by:
        postRegisterInit in interface InitializableRule
        Parameters:
        matchPattern - is the digester match pattern that will trigger this rule.
      • begin

        public void begin​(java.lang.String namespace,
                          java.lang.String name,
                          org.xml.sax.Attributes attributes)
                   throws java.lang.Exception
        Invoked when the Digester matches this rule against an xml element.

        A new instance of the target class is created, and pushed onto the stack. A new "private" PluginRules object is then created and set as the digester's default Rules object. Any custom rules associated with the plugin class are then loaded into that new Rules object. Finally, any custom rules that are associated with the current pattern (such as SetPropertiesRules) have their begin methods executed.

        Overrides:
        begin in class Rule
        Parameters:
        namespace - the namespace URI of the matching element, or an empty string if the parser is not namespace aware or the element has no namespace
        name - the local name if the parser is namespace aware, or just the element name otherwise
        attributes - The attribute list of this element
        Throws:
        java.lang.Exception - if any error occurs
      • body

        public void body​(java.lang.String namespace,
                         java.lang.String name,
                         java.lang.String text)
                  throws java.lang.Exception
        This method is called when the body of a matching XML element is encountered. If the element has no body, this method is called with an empty string as the body text.
        Overrides:
        body in class Rule
        Parameters:
        namespace - the namespace URI of the matching element, or an empty string if the parser is not namespace aware or the element has no namespace
        name - the local name if the parser is namespace aware, or just the element name otherwise
        text - The text of the body of this element
        Throws:
        java.lang.Exception - if any error occurs
      • end

        public void end​(java.lang.String namespace,
                        java.lang.String name)
                 throws java.lang.Exception
        This method is called when the end of a matching XML element is encountered.
        Overrides:
        end in class Rule
        Parameters:
        namespace - the namespace URI of the matching element, or an empty string if the parser is not namespace aware or the element has no namespace
        name - the local name if the parser is namespace aware, or just the element name otherwise
        Throws:
        java.lang.Exception - if any error occurs
      • getPattern

        public java.lang.String getPattern()
        Return the pattern that this Rule is associated with.

        In general, Rule instances can be associated with multiple patterns. A PluginCreateRule, however, will only function correctly when associated with a single pattern. It is possible to fix this, but I can't be bothered just now because this feature is unlikely to be used.

        Returns:
        The pattern value
      • fireBeginMethods

        public void fireBeginMethods​(java.util.List<Rule> rules,
                                     java.lang.String namespace,
                                     java.lang.String name,
                                     org.xml.sax.Attributes list)
                              throws java.lang.Exception
        Duplicate the processing that the Digester does when firing the begin methods of rules. It would be really nice if the Digester class provided a way for this functionality to just be invoked directly.
        Parameters:
        rules - The rules which Rule.begin(String, String, Attributes) method has to be fired
        namespace - the namespace URI of the matching element, or an empty string if the parser is not namespace aware or the element has no namespace
        name - the local name if the parser is namespace aware, or just the element name otherwise
        list - The attribute list of this element
        Throws:
        java.lang.Exception - if any error occurs
      • fireBodyMethods

        private void fireBodyMethods​(java.util.List<Rule> rules,
                                     java.lang.String namespaceURI,
                                     java.lang.String name,
                                     java.lang.String text)
                              throws java.lang.Exception
        Duplicate the processing that the Digester does when firing the Rule.body(String, String, String) methods of rules. It would be really nice if the Digester class provided a way for this functionality to just be invoked directly.
        Parameters:
        rules - The rules which Rule.body(String, String, String) method has to be fired
        namespace - the namespace URI of the matching element, or an empty string if the parser is not namespace aware or the element has no namespace
        name - the local name if the parser is namespace aware, or just the element name otherwise
        text - The text of the body of this element
        Throws:
        java.lang.Exception - if any error occurs
      • fireEndMethods

        public void fireEndMethods​(java.util.List<Rule> rules,
                                   java.lang.String namespaceURI,
                                   java.lang.String name)
                            throws java.lang.Exception
        Duplicate the processing that the Digester does when firing the end methods of rules. It would be really nice if the Digester class provided a way for this functionality to just be invoked directly.
        Parameters:
        rules - The rules which Rule.end(String, String) method has to be fired
        namespaceURI - the namespace URI of the matching element, or an empty string if the parser is not namespace aware or the element has no namespace
        name - the local name if the parser is namespace aware, or just the element name otherwise
        Throws:
        java.lang.Exception - if any error occurs