Free download commons-digester.jar

The order of the rules you return is significant, and should match the order in which rules were initally added. Your policy for rule selection should generally be sensitive to whether Namespace Aware Parsing is taking place. In general, if namespaceAware is true, you should select only rules that:. ExtendedBaseRules , adds some additional expression syntax for pattern matching to the default mechanism, but it also executes more slowly.

See the JavaDocs for more details on the new pattern matching syntax, and suggestions on when this implementation should be used.

To use it, simply do the following as part of your Digester initialization:. RegexRules is an advanced Rules implementation which does not build on the default pattern matching rules. It uses a pluggable RegexMatcher implementation to test if a path matches the pattern for a Rule. All matching rules are returned note that this behaviour differs from longest matching rule of the default pattern matching rules. See the Java Docs for more details. This implementation is unsophisticated and lacks many good features lacking in more power Regex libraries.

There are some good reasons why this approach was adopted. The first is that SimpleRegexMatcher is simple, it is easy to write and runs quickly. The second has to do with the way that RegexRules is intended to be used. There are many good regex libraries available. The pluggable RegexMatcher is a thin bridge designed to adapt other Regex systems.

This allows any Regex library the user desires to be plugged in and used just by creating one class. Digester does not currently ship with bridges to the major regex to allow the dependencies required by Digester to be kept to. WithDefaultsRulesWrapper allows default Rule instances to be added to any existing Rules implementation. These default Rule instances will be returned for any match for which the wrapped implementation does not return any matches. All of the examples above have described a scenario where the rules to be processed are registered with a Digester instance immediately after it is created.

However, this approach makes it difficult to reuse the same set of rules in more than one application environment. Ideally, one could package a set of rules into a single class, which could be easily loaded and registered with a Digester instance in one easy step. In addition, the rule instances registered with a particular RuleSet can optionally be associated with a particular namespace, as described under Namespace Aware Processing. You might use this RuleSet as follow to initialize a Digester instance:.

Digester is based on Rule instances working together to process xml. For anything other than the most trival processing, communication between Rule instances is necessary. Since Rule instances are processed in sequence, this usually means storing an Object somewhere where later instances can retrieve it.

Digester is based on SAX. The most natural data structure to use with SAX based xml processing is the stack. This allows more powerful processes to be specified more simply since the pushing and popping of objects can mimic the nested structure of the xml. Digester uses two basic stacks: one for the main beans and the other for parameters for method calls. These are inadequate for complex processing where many different Rule instances need to communicate through different channels.

In this case, it is recommended that named stacks are used. In addition to the two basic stacks, Digester allows rules to use an unlimited number of other stacks referred to by an identifying string the name. That's where the term named stack comes from. These stacks are accessed through calls to:. Note: all stack names beginning with org. It is also recommended that users choose stack names prefixed by the name of their own domain to avoid conflicts with other Rule implementations.

The system-identifier is an URI from which the resource can be obtained either directly or indirectly. Many valid URIs may identify the same resource. The public-identifier is an additional free identifier which may be used by the parser to locate the resource.

In practice, the weakness with a system-identifier is that most parsers will attempt to interprete this URI as an URL, try to download the resource directly from the URL and stop the parsing if this download fails. URLs may be local or remote but if the URL is chosen to be local, it is likely only to function correctly on a small number of machines which are configured precisely to allow the xml to be parsed. This is usually unsatisfactory and so a universally accessable URL is preferred.

This usually means an internet URL. To recap, in practice the system-identifier will most likely be an internet URL. Unfortunately downloading from an internet URL is not only slow but unreliable since successfully downloading a document from the internet relies on the client being connect to the internet and the server being able to satisfy the request.

The public-identifier is a freely defined name but in practice it is strongly recommended that a unique, readable and open format is used for reasons that should become clear later. This public identifier is often used to provide a unique and location independent key which can be used to subsistute local resources for remote ones hint: this is why ;.

By using the second PUBLIC form combined with some form of local catalog which matches public-identifiers to local resources and where the public-identifier is a unique name and the system-identifier is an internet URL, the practical disadvantages of specifying just a system-identifier can be avoided.

Those external entities which have been store locally on the machine parsing the document can be identified and used. Only when no local copy exists is it necessary to download the document from the internet URL. This naming scheme is recommended when using Digester. SAX factors out the resolution of external entities into an EntityResolver. Digester supports the use of custom EntityResolver but ships with a simple internal implementation. This implementation allows local URLs to be easily associated with public-identifiers.

Note: This is a simple but useful implementation. Greater sophistication requires a custom EntityResolver. Digestion throws two kinds of Exception :. The first is rarely thrown and indicates the kind of fundemental IO exception that developers know all about.

So, to diagnose the cause a certain familiarity with the way that SAX error handling works is very useful. This is a short, potted guide to SAX error handling strategies.

It's not intended as a proper guide to error handling in SAX. This is a subclass of SAXException and contains a bit of extra information about what exactly when wrong - and more importantly, where it went wrong.

If you catch an exception of this sort, you can be sure that the problem is with the XML and not Digester or your rules. It is usually a good idea to catch this exception and log the extra information to help with diagnosing the reason for the failure. General SAXException instances may wrap a causal exception. When exceptions are throw by Digester each of these will be wrapped into a SAXException and rethrown. So, catch these and examine the wrapped exception to diagnose what went wrong.

Three extension packages are included within the Digester distribution. These provide extra functionality extending the core Digester concepts. Detailed descriptions are contained within their own package documentation.

There is an issue when invoking public methods contained in a default access superclass. Reflection locates these methods fine and correctly assigns them as public. However, an IllegalAccessException is thrown if the method is invoked. MethodUtils contains a workaround for this situation. It will attempt to call setAccessible on this method. If this call succeeds, then the method can be invoked as normal.

This call will only succeed when the application has sufficient security privilages. If this call fails then a warning will be logged and the method may fail.

Digester uses MethodUtils and so there may be an issue accessing methods of this kind from a high security environment. If you think that you might be experiencing this problem, please ask on the mailing list. Last Published: 19 September Version: 2. ApacheCon Apache Commons. External Dependencies The Digester component Version 2.

Compatible implementations are included in JDKs 1. Introduction In many application environments that deal with XML-formatted data, it is useful to be able to process an XML document in an "event driven" manner, where particular Java objects are created or methods of existing objects are invoked when particular patterns of nested XML elements have been recognized.

In order to use a Digester, the following basic steps are required: Create a new instance of the org. Digester class. Previously created Digester instances may be safely reused, as long as you have completed any previously requested parse, and you do not try to utilize a particular Digester instance from more than one thread at a time.

Set any desired configuration properties that will customize the operation of the Digester when you next initiate a parse operation. Optionally, push any desired initial object s onto the Digester's object stack. Register all of the element matching patterns for which you wish to have processing rules fired when this pattern is recognized in an input document. You may register as many rules as you like for any particular pattern. If there is more than one rule for a given pattern, the rules will be executed in the order that they were listed.

Call the digester. See the Digester. Note that you will need to be prepared to catch any IOException or SAXException that is thrown by the parser, or any runtime expression that is thrown by one of the processing rules. Set any desired configuration properties on that parser object. Create an instance of org. Register patterns and rules with the digester instance.

Call parser. Configuration Properties A org. Property Description classLoader You can optionally specify the class loader that will be used to load classes when required by the ObjectCreateRule and FactoryCreateRule rules. If not specified, application classes will be loaded from the thread's context class loader if the useContextClassLoader property is set to true or the same class loader that was used to load the Digester class itself.

By default, any parsing errors that are encountered are logged, but Digester will continue processing as well. Among other things, this setting affects how elements are matched to processing rules. See Namespace Aware Parsing for more information.

This setting is only effective if the parsing is already configured to be namespace aware. By default, Digester includes a Rules implementation that behaves as described in this document. See Pluggable Rules Processing for more information. By default, classes will be loaded from the class loader that loaded this Digester class. NOTE - This property is ignored if you set a value for the classLoader property; that class loader will be used unconditionally.

The default value of false requests a parse that only detects "well formed" XML documents, rather than "valid" ones. The Object Stack One very common use of org. The usual stack-related operations are made available, including the following: clear - Clear the current contents of the object stack. Several potential issues with this design pattern are addressed by other features of the Digester functionality: How do I relate the objects being created to each other?

This rule makes it easy to establish parent-child relationships between these objects. One-to-one and one-to-many relationships are both easy to construct.

How do I retain a reference to the first object that was created? As you review the description of what the "object create" processing rule does, it would appear that the first object you create i. However, Digester will maintain a reference to the very first object ever pushed onto the object stack, and will return it to you as the return value from the parse call.

Alternatively, you can push a reference to some application object onto the stack before calling parse , and arrange that a parent-child relationship be created by appropriate processing rules between this manually pushed object and the ones that are dynamically created. In this way, the pushed object will retain a reference to the dynamically created objects and therefore all of their children , and will be returned to you after the parse finishes as well.

Element Matching Patterns A primary feature of the org. Processing Rules The previous section documented how you identify when you wish to have certain actions take place. Each Rule implements one or more of the following event methods that are called at well-defined times when the matching patterns corresponding to this rule trigger it: begin - Called when the beginning of the matched XML element is encountered. A data structure containing all of the attributes corresponding to this element are passed as well.

Any leading or trailing whitespace will have been removed as part of the parsing process. If nested XML elements that matched other processing rules was included in the body of this element, the appropriate processing rules for the matched rules will have already been completed before this method is called. These classes include the following: ObjectCreateRule - When the begin method is called, this rule instantiates a new instance of a specified Java class, and pushes it on the stack.

The class name to be used is defaulted according to a parameter passed to this rule's constructor, but can optionally be overridden by a classname passed via the specified attribute to the XML element being processed. When the end method is called, the top object on the stack presumably, the one we added in the begin method will be popped, and any reference to it within the Digester will be discarded. FactoryCreateRule - A variation of ObjectCreateRule that is useful when the Java class with which you wish to create an object instance does not have a no-arguments constructor, or where you wish to perform other setup processing before the object is handed over to the Digester.

SetPropertiesRule - When the begin method is called, the digester uses the standard Java Reflection API to identify any JavaBeans property setter methods on the object at the top of the digester's stack who have property names that match the attributes specified on this XML element, and then call them individually, passing the corresponding attribute values. These natural mappings can be overridden. This allows for example a class attribute to be mapped correctly.

It is recommended that this feature should not be overused - in most cases, it's better to use the standard BeanInfo mechanism. A very common idiom is to define an object create rule, followed by a set properties rule, with the same element matching pattern.

This causes the creation of a new Java object, followed by "configuration" of that object's properties based on the attributes of the same XML element that created this object. SetPropertyRule - When the begin method is called, the digester calls a specified property setter where the property itself is named by an attribute with a specified value where the value is named by another attribute , on the object at the top of the digester's stack.

This is useful when your XML file conforms to a particular DTD, and you wish to configure a particular property that does not have a corresponding attribute in the DTD. SetNextRule - When the end method is called, the digester analyzes the next-to-top element on the stack, looking for a property setter method for a specified property.

It then calls this method, passing the object at the top of the stack as an argument. This rule is commonly used to establish one-to-many relationships between the two objects, with the method name commonly being something like "addChild". BeanPropertySetterRule org. CallMethodRule org. CallParamRule org. Digester org. ExtendedBaseRules org.

FactoryCreateRule org. NodeCreateRule org. ObjectCreateRule org. ObjectCreationFactory org. ObjectParamRule org. ParserFeatureSetterFactory org. PathCallParamRule org. RegexMatcher org. RegexRules org. Rule Show all. Rule org. RuleSet org. RuleSetBase org. Rules org. RulesBase org. SetNestedPropertiesRule org. SetNextRule org. SetPropertiesRule org. SetPropertyRule org. SetRootRule org. SetTopRule org. SimpleRegexMatcher org. Substitutor org. WithDefaultsRulesWrapper org. GenericParser org.

XercesParser org. Declaration org. InitializableRule org. LogUtils org. PluginAssertionFailure org. PluginConfigurationException org.