Java Doc for Digester.java in  » Library » Apache-commons-digester-1.8-src » org » apache » commons » digester » Java Source Code / Java DocumentationJava Source Code and Java Documentation

A Digester processes an XML input stream by matching a series of element nesting patterns to execute Rules that have been added prior to the start of parsing. This package was inspired by the XmlMapper class that was part of Tomcat 3.0 and 3.1, but is organized somewhat differently.

See the Digester Developer Guide for more information.

IMPLEMENTATION NOTE - A single Digester instance may only be used within the context of a single thread at a time, and a call to parse() must be completed before another can be initiated even from the same thread.

IMPLEMENTATION NOTE - A bug in Xerces 2.0.2 prevents the support of XML schema. You need Xerces 2.1/2.3 and up to make this class working with XML schema

List of InputSource instances created by a createInputSourceFromURL() method call.

Register a new Rule matching the specified pattern.

Clean up allocated resources after parsing is complete.

Provide a hook for lazy configuration of this Digester instance.

Ideally this function would not be needed and code could just use new InputSource(entityURL).

If the digester stack was "primed" by explicitly pushing a root object onto the stack before parsing started, then that root object is returned here.

Alternatively, if a Rule which creates an object (eg ObjectCreateRule) matched the root element of the xml, then the object created will be returned here.

In other cases, the object most recently pushed onto an empty digester stack is returned.

Provides a hook for lazy initialization of this Digester instance.

Gets the top object from the stack with the given name.

Gets the top object from the stack with the given name. This method does not remove the object from the stack.

Note: a stack is considered empty if no objects have been pushed onto it yet.

Return the top object on the parameters stack without removing it.

Return the n'th object down the parameters stack, where 0 is the top element and [getCount()-1] is the bottom element.

Pops (gets and removes) the top object from the stack with the given name.

Note: a stack is considered empty if no objects have been pushed onto it yet.

Pop the top object off of the parameters stack, and return it.

Push a new object onto the top of the parameters stack.

The parameters stack is used to store CallMethodRule parameters.

Register the specified DTD URL for the specified public identifier. This must be called before the first call to parse().

Digester contains an internal EntityResolver implementation.

It is not considered safe for a digester instance to be reused to parse multiple xml documents.

When this object's customContentHandler is non-null, any SAX events received from the parser will simply be passed on to the specified object instead of this object handling them.

It is often desirable to force the input document to be validated against a particular schema regardless of what type the input document declares itself to be.

List of InputSource instances created by a createInputSourceFromURL() method call. These represent open input streams that need to be closed to avoid resource leaks, as well as potentially locked JAR files on Windows.

Note that when attempting to locate a matching method to invoke, the true type of the paramObj is used, so that despite the paramObj being passed in here as type Object, the target method can declare its parameters as being the true type of the object (or some ancestor type, according to the usual type-conversion rules).
Parameters:
  paramIndex - The zero-relative parameter number
Parameters:
  paramObj - Any arbitrary object to be passed to the targetmethod.
See Also:   CallMethodRule
since:
   1.6

Register a new Rule matching the specified pattern. This method sets the Digester property on the rule.

Clean up allocated resources after parsing is complete. The default method closes input streams that have been created by Digester itself. If you override this method in a subclass, be sure to call super.cleanup() to invoke this logic.

Calling this method might allow another document of the same type to be correctly parsed. However this method was not intended for this purpose. In general, a separate Digester object should be created for each document to be parsed.

Provide a hook for lazy configuration of this Digester instance. The default implementation does nothing, but subclasses can override as needed.

Note This method may be called more than once. Once only initialization code should be placed in Digester.initialize or the code should take responsibility by checking and setting the Digester.configured flag.

Ideally this function would not be needed and code could just use new InputSource(entityURL). Unfortunately it appears that when the entityURL points to a file within a jar archive a caching mechanism inside the InputSource implementation causes a file-handle to the jar file to remain open. On Windows systems this then causes the jar archive file to be locked on disk ("in use") which makes it impossible to delete the jar file - and that really stuffs up "undeploy" in webapps in particular.

In JDK1.4 and later, Apache XercesJ is used as the xml parser. The InputSource object provided is converted into an XMLInputSource, and eventually passed to an instance of XMLDocumentScannerImpl to specify the source data to be converted into tokens for the rest of the XMLReader code to handle. XMLDocumentScannerImpl calls fEntityManager.startDocumentEntity(source), where fEntityManager is declared in ancestor class XMLScanner to be an XMLEntityManager. In that class, if the input source stream is null, then:

 URL location = new URL(expandedSystemId);
 URLConnection connect = location.openConnection();
 if (connect instanceof HttpURLConnection) {
 setHttpProperties(connect,xmlInputSource);
 }
 stream = connect.getInputStream();
 

Convenience method that creates an InputSource from the string version of a URL.

• The class loader set by setClassLoader(), if any
• The thread context class loader, if it exists and the useContextClassLoader property is set to true
• The class loader used to load the Digester class itself.

If the digester stack was "primed" by explicitly pushing a root object onto the stack before parsing started, then that root object is returned here.

Alternatively, if a Rule which creates an object (eg ObjectCreateRule) matched the root element of the xml, then the object created will be returned here.

In other cases, the object most recently pushed onto an empty digester stack is returned. This would be a most unusual use of digester, however; one of the previous configurations is much more likely.

Note that when using one of the Digester.parse methods, the return value from the parse method is exactly the same as the return value from this method. However when the Digester is being used as a SAXContentHandler, no such return value is available; in this case, this method allows you to access the root object that has been created after parsing has completed. the root object that has been created after parsingor null if the digester has not parsed any XML yet.

Provides a hook for lazy initialization of this Digester instance. The default implementation does nothing, but subclasses can override as needed. Digester (by default) only calls this method once.

Note This method will be called by Digester.configure only when the Digester.configured flag is false. Subclasses that override configure or who set configured may find that this method may be called more than once.

Is the stack with the given name empty?

Note: a stack is considered empty if no objects have been pushed onto it yet.

Gets the top object from the stack with the given name. This method does not remove the object from the stack.

Note: a stack is considered empty if no objects have been pushed onto it yet.

Gets the top object from the stack with the given name. This method does not remove the object from the stack.

Note: a stack is considered empty if no objects have been pushed onto it yet.

Return the top object on the parameters stack without removing it. If there are no objects on the stack, return null.

The parameters stack is used to store CallMethodRule parameters. See Digester.params .

Return the n'th object down the parameters stack, where 0 is the top element and [getCount()-1] is the bottom element. If the specified index is out of range, return null.

The parameters stack is used to store CallMethodRule parameters. See Digester.params .

Pops (gets and removes) the top object from the stack with the given name.

Note: a stack is considered empty if no objects have been pushed onto it yet.

Pop the top object off of the parameters stack, and return it. If there are no objects on the stack, return null.

The parameters stack is used to store CallMethodRule parameters. See Digester.params .

Push a new object onto the top of the parameters stack.

The parameters stack is used to store CallMethodRule parameters. See Digester.params .

Register the specified DTD URL for the specified public identifier. This must be called before the first call to parse().

Digester contains an internal EntityResolver implementation. This maps PUBLICID's to URLs (from which the resource will be loaded). A common use case for this method is to register local URLs (possibly computed at runtime by a classloader) for DTDs. This allows the performance advantage of using a local version without having to ensure every SYSTEM URI on every processed xml document is local. This implementation provides only basic functionality. If more sophisticated features are required, using Digester.setEntityResolver to set a custom resolver is recommended.

Note: This method will have no effect when a custom EntityResolver has been set. (Setting a custom EntityResolver overrides the internal implementation.)

Convenience method that registers the string version of an entity URL instead of a URL version.

It is not considered safe for a digester instance to be reused to parse multiple xml documents. However if you are determined to do so, then you should call both clear() and resetRoot() before each parse.
since:
   1.7

When this object's customContentHandler is non-null, any SAX events received from the parser will simply be passed on to the specified object instead of this object handling them. This allows Rule classes to take control of the SAX event stream for a while in order to do custom processing. Such a rule should save the old value before setting a new one, and restore the old value in order to resume normal digester processing.

An example of a Rule which needs this feature is NodeCreateRule.

Note that saving the old value is probably not needed as it should always be null; a custom rule that wants to take control could only have been called when there was no custom content handler. But it seems cleaner to properly save/restore the value and maybe some day this will come in useful.

Note also that this is not quite equivalent to

 digester.getXMLReader().setContentHandler(handler)
 

• Some xml parsers don't like having setContentHandler called after parsing has started. The Aelfred parser is one example.
• Directing the events via the Digester object potentially allows us to log information about those SAX events at the digester level.

It is often desirable to force the input document to be validated against a particular schema regardless of what type the input document declares itself to be. This method allows that to be done.

Note, however, that there is no standard API for enabling this feature on the underlying SAX parser; this method therefore only works for those parsers explicitly supported by Digester's ParserFeatureSetterFactory class. If the underlying parser does not support the feature, or is not one of the supported parsers, then an exception will be thrown when getParser is called (explicitly, or implicitly via the parse method).

See also method setSchemaLanguage which allows the type of the schema specified here to be defined. By default, the schema is expected to be a W3C xml schema definition.

IMPORTANT NOTE: This functionality was never very reliable, and has been horribly broken since the 1.6 release of Digester. There are currently no plans to fix it, so you are strongly recommended to avoid using this method. Instead, create an XMLParser instance yourself, configure validation appropriately, and pass it as a parameter to the Digester constructor.
Parameters:
  schemaLocation - a URI to the schema.