SAX Quickstart中文翻译

快速入门

这个文档为打算使用SAX2在他们的应用中的Java编程人员提供一个快速入门的教程。

 

环境要求

 SAX是一个被许多不同的XML解析器执行的通用接口（和类似XML解析器的组件） ，就像是JDBC是一个被不同的关系数据库所执行的通用接口（和类似的关系型数据库的组件） 。如果您想使用SAX，您需要以下所有条件：

• Java1.1或更高版本
• 一个兼容SAX2的XML解析器安装在您的Java类路径。 （如果你需要这样一个解析器，请参阅网页左边的链接。 ）
• The SAX2 distribution installed on your Java classpath. (This probably came with your parser.)
  将SAX2配置在您的Java类路径。 （它可能带着您的解析器。 ）

多数Java / XML工具包括SAX2并且解析器会用到它。大多数Web应用程序服务器使用它的核心XML支持。尤其是，环境与JAXP 1.1支持包括SAX2 。

解析文件

首先建立一个继承DefaultHandler的类:

import org.xml.sax.helpers.DefaultHandler;





public class MySAXApp extends DefaultHandler


{





    public MySAXApp ()


    {


	super();


    }





}

由于这是一个Java应用程序，所以我们要利用XMLReaderFactory的createXMLReader方法建立一个动态的main方法去动态的选择SAX驱动。注意，这里的"throws Exception"wimp-out;在实际的应用中将需要真正的错误处理：

    public static void main (String args[])


	throws Exception


    {


	XMLReader xr = XMLReaderFactory.createXMLReader();


    }

 如果您的Java环境默认没有安排compiled-in（或者使用META-INF/services/org.xl.sax.driver系统资源），你有可能需要用一个完整的SAX驱动类名来设置org.xml.sax.driver Java系统参数，例如

java -Dorg.xml.sax.driver=com.example.xml.SAXDriver MySAXApp sample.xml

 一些目前应用比较广泛的SAX2驱动列在"links"页，驱动类名你可以使用的包括：

 

Class Name Notes

gnu.xml.aelfred2.SAXDriver	Lightweight non-validating parser; Free Software
gnu.xml.aelfred2.XmlReader	Optionally validates; Free Software
oracle.xml.parser.v2.SAXParser	Optionally validates; proprietary
org.apache.crimson.parser.XMLReaderImpl	Optionally validates; used in JDK 1.4; Open Source
org.apache.xerces.parsers.SAXParser	Optionally validates; Open Source

或者，如果你不介意耦合耦合你的应用程序到一个特定的SAX驱动，你可以直接用他的结构。我们假设你的XML解析器的SAX驱动名字为com.example.xml.SAXDriver,但它并不真的存在。你必须知道解析器真正驱动的名字，就像这样.

    public static void main (String args[])


	throws Exception


    {


	XMLReader xr = new com.example.xml.SAXDriver();


    }

 我们可以用这个对象去解析XML文档，但首先，我们不得不去注册一个解析器的事件处理程序，它会用XMLReader接口的setContentHandler和setErrorHandler方法接收事件处理程序返回的信息报告。在现实世界里的应用程序，处理器通常被作为一个独立的对象，但是对于这个简单的演示，我们已经绑定处理器和顶级类绑定到了一期，所以我们仅仅需要一个实例类和登记使用的XML。

    public static void main (String args[])


	throws Exception


    {


	XMLReader xr = XMLReaderFactory.createXMLReader();


	MySAXApp handler = new MySAXApp();


	xr.setContentHandler(handler);


	xr.setErrorHandler(handler);


    }

 这个代码建立了一个MySAXApp的实例去接收XML解析事件,并且注册它用XML （他们是其他办法，并且他们很少使用）。现在，让我们假设所有的命令行参数是文件的名字，并且我们将试图用XMLReader接口的parse方法一个一个的解析他们。

    public static void main (String args[])


	throws Exception


    {


	XMLReader xr = XMLReaderFactory.createXMLReader();


	MySAXApp handler = new MySAXApp();


	xr.setContentHandler(handler);


	xr.setErrorHandler(handler);





				// Parse each file provided on the


				// command line.


	for (int i = 0; i < args.length; i++) {


	    FileReader r = new FileReader(args[i]);


	    xr.parse(new InputSource(r));


	}


    }

 注意，每个reader必须在一个InputSource对象中被解析。这就是一个完整的演示类（到目前位置）：

import java.io.FileReader;





import org.xml.sax.XMLReader;


import org.xml.sax.InputSource;


import org.xml.sax.helpers.XMLReaderFactory;


import org.xml.sax.helpers.DefaultHandler;








public class MySAXApp extends DefaultHandler


{





    public static void main (String args[])


	throws Exception


    {


	XMLReader xr = XMLReaderFactory.createXMLReader();


	MySAXApp handler = new MySAXApp();


	xr.setContentHandler(handler);


	xr.setErrorHandler(handler);





				// Parse each file provided on the


				// command line.


	for (int i = 0; i < args.length; i++) {


	    FileReader r = new FileReader(args[i]);


	    xr.parse(new InputSource(r));


	}


    }








    public MySAXApp ()


    {


	super();


    }


}

 你可以编译这段代码并运行它（确定你特定的SAX驱动已经设置在你的org.xml.sax.driver属性），但是没有什么会发生除了文档包含难看的XML，因为你还没有设置你的应用程序去处理SAX事件。

 

 

Handling events

Things get interesting when you start implementing methods to respond to XML parsing events (remember that we registered our class to receive XML parsing events in the previous section). The most important events are the start and end of the document, the start and end of elements, and character data.

To find out about the start and end of the document, the client application implements the startDocument and endDocument methods:

    public void startDocument ()


    {


	System.out.println("Start document");


    }





    public void endDocument ()


    {


	System.out.println("End document");


    }

The start/endDocument event handlers take no arguments. When the SAX driver finds the beginning of the document, it will invoke the startDocument method once; when it finds the end, it will invoke the endDocument method once (even if there have been errors).

These examples simply print a message to standard output, but your application can contain any arbitrary code in these handlers: most commonly, the code will build some kind of an in-memory tree, produce output, populate a database, or extract information from the XML stream.

The SAX driver will signal the start and end of elements in much the same way, except that it will also pass some parameters to the startElement and endElement methods:

    public void startElement (String uri, String name,


			      String qName, Attributes atts)


    {


	if ("".equals (uri))


	    System.out.println("Start element: " + qName);


	else


	    System.out.println("Start element: {" + uri + "}" + name);


    }





    public void endElement (String uri, String name, String qName)


    {


	if ("".equals (uri))


	    System.out.println("End element: " + qName);


	else


	    System.out.println("End element:   {" + uri + "}" + name);


    }

These methods print a message every time an element starts or ends, with any Namespace URI in braces before the element's local name. The qName contains the raw XML 1.0 name, which you must use for all elements that don't have a namespace URI. In this quick introduction, we won't look at how attributes are accessed; you can access them by name, or by iterating through them much as if they were a vector.

Finally, SAX2 reports regular character data through the characters method; the following implementation will print all character data to the screen; it is a little longer because it pretty-prints the output by escaping special characters:

    public void characters (char ch[], int start, int length)


    {


	System.out.print("Characters:    \"");


	for (int i = start; i < start + length; i++) {


	    switch (ch[i]) {


	    case '\\':


		System.out.print("\\\\");


		break;


	    case '"':


		System.out.print("\\\"");


		break;


	    case '\n':


		System.out.print("\\n");


		break;


	    case '\r':


		System.out.print("\\r");


		break;


	    case '\t':


		System.out.print("\\t");


		break;


	    default:


		System.out.print(ch[i]);


		break;


	    }


	}


	System.out.print("\"\n");


    }

Note that a SAX driver is free to chunk the character data any way it wants, so you cannot count on all of the character data content of an element arriving in a single characters event.

<!-- end of "Handling events" -->

Sample SAX2 application

Here is the complete sample application (again, in a serious app the event handlers would probably be implemented in a separate class):

import java.io.FileReader;





import org.xml.sax.XMLReader;


import org.xml.sax.Attributes;


import org.xml.sax.InputSource;


import org.xml.sax.helpers.XMLReaderFactory;


import org.xml.sax.helpers.DefaultHandler;








public class MySAXApp extends DefaultHandler


{





    public static void main (String args[])


	throws Exception


    {


	XMLReader xr = XMLReaderFactory.createXMLReader();


	MySAXApp handler = new MySAXApp();


	xr.setContentHandler(handler);


	xr.setErrorHandler(handler);





				// Parse each file provided on the


				// command line.


	for (int i = 0; i < args.length; i++) {


	    FileReader r = new FileReader(args[i]);


	    xr.parse(new InputSource(r));


	}


    }








    public MySAXApp ()


    {


	super();


    }








    ////////////////////////////////////////////////////////////////////


    // Event handlers.


    ////////////////////////////////////////////////////////////////////








    public void startDocument ()


    {


	System.out.println("Start document");


    }








    public void endDocument ()


    {


	System.out.println("End document");


    }








    public void startElement (String uri, String name,


			      String qName, Attributes atts)


    {


	if ("".equals (uri))


	    System.out.println("Start element: " + qName);


	else


	    System.out.println("Start element: {" + uri + "}" + name);


    }








    public void endElement (String uri, String name, String qName)


    {


	if ("".equals (uri))


	    System.out.println("End element: " + qName);


	else


	    System.out.println("End element:   {" + uri + "}" + name);


    }








    public void characters (char ch[], int start, int length)


    {


	System.out.print("Characters:    \"");


	for (int i = start; i < start + length; i++) {


	    switch (ch[i]) {


	    case '\\':


		System.out.print("\\\\");


		break;


	    case '"':


		System.out.print("\\\"");


		break;


	    case '\n':


		System.out.print("\\n");


		break;


	    case '\r':


		System.out.print("\\r");


		break;


	    case '\t':


		System.out.print("\\t");


		break;


	    default:


		System.out.print(ch[i]);


		break;


	    }


	}


	System.out.print("\"\n");


    }





}

<!-- end of "Sample SAX2 application" -->

Sample Output

Consider the following XML document:

<?xml version="1.0"?>





<poem xmlns="http://www.megginson.com/ns/exp/poetry">


<title>Roses are Red</title>


<l>Roses are red,</l>


<l>Violets are blue;</l>


<l>Sugar is sweet,</l>


<l>And I love you.</l>


</poem>

If this document is named roses.xml and there is a SAX2 driver on your classpath named com.example.xml.SAXDriver (this driver does not actually exist), you can invoke the sample application like this:

java -Dorg.xml.sax.driver=com.example.xml.SAXDriver MySAXApp roses.xml

When you run this, you'll get output something like this:

Start document


Start element: {http://www.megginson.com/ns/exp/poetry}poem


Characters:    "\n"


Start element: {http://www.megginson.com/ns/exp/poetry}title


Characters:    "Roses are Red"


End element:   {http://www.megginson.com/ns/exp/poetry}title


Characters:    "\n"


Start element: {http://www.megginson.com/ns/exp/poetry}l


Characters:    "Roses are red,"


End element:   {http://www.megginson.com/ns/exp/poetry}l


Characters:    "\n"


Start element: {http://www.megginson.com/ns/exp/poetry}l


Characters:    "Violets are blue;"


End element:   {http://www.megginson.com/ns/exp/poetry}l


Characters:    "\n"


Start element: {http://www.megginson.com/ns/exp/poetry}l


Characters:    "Sugar is sweet,"


End element:   {http://www.megginson.com/ns/exp/poetry}l


Characters:    "\n"


Start element: {http://www.megginson.com/ns/exp/poetry}l


Characters:    "And I love you."


End element:   {http://www.megginson.com/ns/exp/poetry}l


Characters:    "\n"


End element:   {http://www.megginson.com/ns/exp/poetry}poem


End document

Note that even this short document generates (at least) 25 events: one for the start and end of each of the six elements used (or, if you prefer, one for each start tag and one for each end tag), one of each of the eleven chunks of character data (including whitespace between elements), one for the start of the document, and one for the end.

If the input document did not include the xmlns="http://www.megginson.com/ns/exp/poetry" attribute to declare that all the elements are in that namespace, the output would instead be like:

Start document


Start element: poem


Characters:    "\n"


Start element: title


Characters:    "Roses are Red"


End element:   title


Characters:    "\n"


Start element: l


Characters:    "Roses are red,"


End element:   l


Characters:    "\n"


Start element: l


Characters:    "Violets are blue;"


End element:   l


Characters:    "\n"


Start element: l


Characters:    "Sugar is sweet,"


End element:   l


Characters:    "\n"


Start element: l


Characters:    "And I love you."


End element:   l


Characters:    "\n"


End element:   poem


End document

You will most likely work with both types of documents: ones using XML namespaces, and ones not using them. You may also work with documents that have some elements (and attributes) with namespaces, and some without. Make sure that your code actually tests for namespace URIs, rather than assuming they are always present (or always missing).