NanoXML/Java 2.1 |
|||
Chapter 4. Advanced TopicsThis chapter explains how you can customize the NanoXML parser setup. Unlike NanoXML 1, NanoXML/Java 2 is designed as a framework: it is composed of many different components which you can plug together. It's possible to change the reader, the builder, the validator and even the parser.
4.1. The NanoXML Reader NanoXML/Java comes with one set of components. Except for NanoXML/Lite, every branch offers its own set of components customized for a certain purpose. NanoXML/SAX offers components for using NanoXML as a parser for the SAX framework. The following figure gives a short representation of the major components.
The reader retrieves data from a Java input stream and provides character data to the other components. The parser converts the character data it retrieves from the reader to XML events which it sends to the builder. The validator parses a DTD and validates the XML data. The current validator does only the minimum necessary for a non-validating parser. The entity resolvers converts entity references (&...;) and parameter entity references (%...;) to character data. The resolver uses the reader to access external entities. The builder interpretes XML events coming from the parser and builds a tree of XML elements. The standard builder creates a tree of IXMLElement. You can provide your own builder to create a custom tree or if you are interested in the XML events themselves, e.g. to use XML streaming. 4.1. The NanoXML ReaderThe reader retrieves data from some source and feeds it to the other components. The reader is basically a stack of push-back readers. Every time a new data stream becomes active, the current reader is pushed on a stack. When the current reader has no more data left, the parent reader is popped from the stack. If you want to implement public IDs using e.g. a catalog file similar to SGML, you could implement a reader by overriding the method openStream of StdXMLReader:
public class MyReader In this example, you have to provide a properties object which maps public IDs to system IDs. 4.2. The NanoXML ParserThe parser analyzes the character stream it retrieves from the reader and sends XML events to the builder. It uses a validator to validate the data and an entity resolver to resolve general entities. You rarely need to create a custom parser. If you need to, you have to implement IXMLParser. 4.3. The NanoXML ValidatorThe validator parses the DTD and checks the XML data. NanoXML 2.0 uses a NonValidator implementation that only performs the minimum necessary for a non-validating parser. As a DTD is very vague, you can implement your own validator to perform a more fine-grained check of the XML data. The easiest way to create your own validator is to create a subclass of ValidatorPlugin. The following example shows how to implement a validator. It checks that every attribute named "id" starts with three capital letters.
public class MyValidator To register the validator to a parser, use the following code:
IXMLParser parser ... 4.4. The NanoXML Entity ResolversThe entity resolver converts entity references to XML data. If you want e.g. to retrieve entity values from a database, you have to create your own resolver. Entity resolvers have to implement IXMLEntityResolver. Usually, you only have to make a subclass of XMLEntityResolver and implement the method getEntity or openExternalEntity. Entities can be used in the XML data and in the DTD. As these entities are independent of each other, there are two entity resolvers. 4.4.1. Standard EntitiesThe resolver for standard entities has to be registered to the parser by calling setResolver. The following example registers a resolver that forces the entity "&foo;" to be resolved to "bar":
import net.n3.nanoxml.*; 4.4.2. Parameter EntitiesThe resolver for parameter entities has to be registered to the validator by calling setParameterEntityResolver. The following example show a custom version of the Demo class that registers MyResolver as a parameter entity resolver.
public class Demo 4.5. The NanoXML BuilderThe builder interpretes XML events coming from the parser and builds a tree of Java objects. When the parsing is done, the builder hands over its result to the parser. As explained in chapter 3, the builder can also be used to read XML data while it's being streamed. This feature is useful if you don't want to wait until all the data has been read before processing the information. As an example, we have the following XML structure (document.dtd):
<!ELEMENT Chapter (Paragraph*)> The elements are put in the Java classes Chapter and Paragraph which, for convenience, extend the following base class:
public class DocumentElement This base class simply makes it easy for our builder to set attributes and to add children to an element. The Chapter and Paragraph classes extend this base class to give more practical access to their attributes and children:
public class Chapter The builder creates the data structure based on the XML events it receives from the parser. Because both Chapter and Paragraph extend DocumentElement, the builder is fairly simple.
import net.n3.nanoxml.*; Note that, for simplicity, error and exception handling is not present in this example. The builder holds a stack of the current elements it builds. Character data is read from a reader. The method addPCData reads this data in blocks of 1K. Finally, this application sets up the NanoXML parser and converts an XML document to HTML which it dumps on the standard output:
import java.util.*; If we run the example on the following XML file:
<!DOCTYPE Chapter SYSTEM "document.dtd"> The output will be:
<!DOCTYPE HTML PUBLIC '-//W3C//DTD HTML 4.01//EN' |
|||
|