CVS Update: xmlpull-api-v1/doc
Aleksander Andrzej Slominski <[email protected]> Tue, 25 Feb 2003 23:50:23 -0500 (EST)
| Newsgroups | gmane.text.xml.xmlpull.devel |
|---|---|
| Message-ID | <[email protected]> |
aslom 03/02/25 23:50:23
Modified: doc quick_intro.html
Added: doc quick_write.html
Log:
added guide on to use XmlSerializer
Revision Changes Path
1.8 +25 -22 xmlpull-api-v1/doc/quick_intro.html
Index: quick_intro.html
===================================================================
RCS file: /l/extreme/cvspub/xmlpull-api-v1/doc/quick_intro.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -b -t -w -r1.7 -r1.8
--- quick_intro.html 29 Apr 2002 17:42:20 -0000 1.7
+++ quick_intro.html 26 Feb 2003 04:50:23 -0000 1.8
@@ -1,69 +1,72 @@
<HTML>
<HEAD>
-<TITLE>Quick Introduction to XMLPULL V1 API
+<TITLE>Quick Introduction to XmlPull v1 API
</TITLE>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Author" content="Aleksander Slominski">
</HEAD>
<BODY BGCOLOR="white">
-<H1>Quick Introduction to XMLPULL V1 API</H2><P>
+<H1>Quick Introduction to XmlPull v1 API</H2><P>
-<p>XMLPULL V1 API is simple to use XML pull parsing API that was designed for
+<p>XmlPull v1 API is a simple to use XML pull parsing API that was designed for
simplicity and very good performance both in constrained environment such as
defined by J2ME and on server side when used in J2EE application servers. XML
-pull parsing allow incremental (sometimes called streaming) parsing of XML where
+pull parsing allows incremental (sometimes called streaming) parsing of XML where
application is in control - the parsing can be interrupted at any given moment
and resumed when application is ready to consume more input.<p>This document
will show step by step how to create a simple application that is using
-XMLPULL API. For more comprehensive introduction to XMLPULL V1 API and XML pull
+XmlPull API to parse XML. If you need to write XML output check a companion
+document <a href="quick_write.html">Quick Introduction to writing XML with
+XmlSerializer</a>. For more comprehensive introduction to XmlPull v1 API and XML pull
parsing in general read JavaWorld.com article "<a href="http://www.javaworld.com/javaworld/jw-04-2002/jw-0426-xmljava3.html">XML
documents on the run, Part 3</a>" by <a href="http://www.sosnoski.com/">Dennis
M. Sosnoski</a>.<H2>Main features of API</H2>
-<P>Java version of XMLPULL V1 API provides:<ul>
+<P>Java version of XmlPull v1 API provides:<ul>
<li><b>simple interface</b> - parser consists of one interface, one exception
and one factory to create parser<li><b>implementation independent</b> - factory
-class is modeled after JAXP and allows easily to switch to different XMLPULL V1
+class is modeled after JAXP and allows easily to switch to different XmlPull V1
API implementation without even modifying source code<li><b>ease of use</b> -
there is only one key method <b><i>next()</i></b> that is used to retrieve next
-event and there are only five events:
+event and there are <b>only five events</b>:
<dl>
-<dt><b>START DOCUMENT</b> <dd>document start - parser has not yet read any input
-<dt><b>START_TAG</b> <dd> parser is on start tag
-<dt><b>TEXT</b> <dd> parser is on element content
-<dt><b>END_TAG</b> <dd> parser is on end tag
-<dt><b>END_DOCUMENT</b> <dd> document finished and no more parsing is allowed
+<dt><b> START DOCUMENT</b> <dd>document start - parser has not yet read any input
+<dt><b> START_TAG</b> <dd> parser is on start tag
+<dt><b> TEXT</b> <dd> parser is on element content
+<dt><b> END_TAG</b> <dd> parser is on end tag
+<dt><b> END_DOCUMENT</b> <dd> document finished and no more parsing is allowed
</dl>
<li><b>versatility</b> - it is generic interface for XML parser and allows for
multiple implementations and extensibility through features and properties
<li><b>performance</b> - the interface is designed to allow implementing very fast XML parsers
<li><b>minimal requirements</b> - designed to be compatible with J2ME (Java 2 Micro Edition)
-to work and on small devices and to allow create XMLPULL compliant parsers of very small
+to work and on small devices and to allow create XmlPull compliant parsers of very small
memory footprint.
</ul>
-<H2>Requirements</H2>
+<H2><a name="reqs"></a>Requirements</H2>
-<p>XMLPULL is API and it requires implementation to run.
+<p>XmlPull is API and it requires implementation to run.
See <a href="http://www.xmlpull.org/impls.shtml">list of implementations</a>
-on XMLPULL website. After downloading one of implementations of XMLPULL API V1 (version 1.0.*)
-add jar file to your CLASSPATH. As XMLPULL uses factory there is no need to
+on XmlPull website. After downloading one of implementations of XmlPull API v1 (version 1.1
+or newer)
+add jar file to your CLASSPATH. As XmlPull uses factory there is no need to
explicitly state what is class with parser implementation: it will be picked up
automatically from implementation jar file.<H2>Code step-by-step</H2>
<p>First we need to create an instance of parser.
To do this three steps are required:<ul>
-<li>get instance of XMLPULL factory
+<li>get instance of XmlPull factory
<li>(optional step) by default factory will produce parsers that are not
namespace aware; to change setNamespaceAware() function must be called
<li>create an instance of the parser
</ul>
-Before doing anything make sure to import XMLPULL V1 API classes:
+Before doing anything make sure to import XmlPull v1 API classes:
<pre>import org.xmlpull.v1.XmlPullParser;
import org.xmlpull.v1.XmlPullParserException;
@@ -86,7 +89,7 @@
and now we can start parsing!
-<p>Typical XMLPULL applicaition will repeatedly call
+<p>Typical XmlPull applicaition will repeatedly call
next() function to retrieve next event, process event
until the even is END_DOCUMENT:
@@ -169,7 +172,7 @@
The finished working sample created that was described is in
-<a href="../src/java/samples/MyXmlPullApp.java">MyXmlPull.java</a> file in
+<a href="../src/java/samples/MyXmlPullApp.java">MyXmlPullApp.java</a> file in
<a href="../src/java/samples/">src/java/samples</a> directory.
<p>For more information please visit <a href="http://www.xmlpull.org/">
1.1 xmlpull-api-v1/doc/quick_write.html
Index: quick_write.html
===================================================================
<HTML>
<HEAD>
<TITLE>Quick Introduction to generting XML with XmlPull v1 API
</TITLE>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Author" content="Aleksander Slominski">
</HEAD>
<BODY BGCOLOR="white">
<H1>Quick Introduction to generating XML with XmlPull v1 API</H2><P>
<p>This document describes how to use XmlSerializer that is part of XmlPull API
to generate/write/serialize XML.
<h2>Main features of API</h2>
<P>XmlSerializer provides:<ul>
<li><b>simple to use</b> API that concentrates on hot generate correct XML
quickly and in straightforward manner<li><b>support for namespaces</b> with automatic prefix declaration to make
it as easy as possible to generate valid XML 1.0 documents with Namespaces
<li><b>control over namespace prefixes</b> even though control over namespace
prefixes is typically not needed
but as prefixes are used in attribute values so it is important to allow
control on how namespace prefixes are assigned if needed<li><b>performance</b>
- the interface is designed to allow implementing <i>very fast</i> XML serializer
<li><b>minimal requirements</b> - designed to be compatible with J2ME (Java 2 Micro Edition)
to work on small devices and to allow creating XmlPull compliant serializer
implementation with very small
memory footprint.
</ul>
<h2>Requirements</h2>
<p>Before running sample code make sure to have parser that implements XmlPull
API 1.1.x (read <a href="quick_intro.html#reqs">relevant part from Quick
Introduction</a>)<h2>Writing XML: in few easy steps</h2>
<p>All XML generating can be done by using XmlSerializer interface.
However before we can start writing we need to obtain instance of class that
implements this interface.
<p>XmlPull API allows multiple implementations to be used.
To achieve this flexibility serializer class is not created directly but by
using configurable factory that is responsible for locating and creating
implementation. In general that involves following steps:
<ul>
<li>get instance of XmlPull factory - you can use system property as argument
to configure factory with list of implementation to try and you can pass
class to use as class loader context (important in servlet and application servers environments)
<li>create an instance of the serializer
</ul>
In your code as the first thing make sure to import XmlPull v1 API classes:
<pre>import org.xmlpull.v1.XmlPullParserException;
import org.xmlpull.v1.XmlPullParserFactory;
import org.xmlpull.v1.XmlSerializer;
</pre>
and the code to create serializer may look like this:
<pre> XmlPullParserFactory factory = XmlPullParserFactory.newInstance(
System.getProperty(XmlPullParserFactory.PROPERTY_NAME), null);
XmlSerializer serializer = factory.newSerializer();
</pre>
Next step is to set serializer output - in this case it is set to write to
standard output but can easily redirected to file or socket:
<pre> serializer.setOutput(new PrintWriter( System.out ));
</pre>
and now we can start using <code>serializer</code> to write XML!
<p>Typical applicaition will write XML declaration and then follow
with writing few element start and end tags and their content.
<p>Output must always have at least one start tag:
<pre> serializer.startTag(NAMESPACE, "poem");
</pre>
then we cna start writing more start tags, text cotnent, and end tags:
<pre> serializer.startTag(NAMESPACE, "title");
serializer.text("Roses are Red");
serializer.endTag(NAMESPACE, "title");
</pre>
where namespace is declared as string constant
<pre>private final static String NAMESPACE = "http://www.megginson.com/ns/exp/poetry";</pre>
<p>it is possible to chain multiple calls:
<pre> serializer.startTag(NAMESPACE, "l")
.text("Roses are red,")
.endTag(NAMESPACE, "l");
</pre>
or put them even in one line:
<pre> serializer.startTag(NAMESPACE, "l").text("Violets are blue;").endTag(NAMESPACE, "l");
</pre>
but what make API really flexible and modular is to define functions that
outputs well defined parts of XML, for example:
<pre> private static void writeLine(XmlSerializer serializer, String line, boolean addNewLine)
throws IOException {
serializer.startTag(NAMESPACE, "l");
serializer.text(line);
serializer.endTag(NAMESPACE, "l");
if(addNewLine) serializer.text("\n");
}
</pre>
and then to write chunkof XML output it is enough to simply call:
<pre> writeLine(serializer, "Sugar is sweet,", addNewLine);
writeLine(serializer, "And I love you.,", addNewLine);
</pre>
<p>Serializer will check that end tag name and namespace is the same as
of matching start tag (very good to validate that XML output is correct)
so to finish writing XML we should close top level start tag:
<pre> serializer.endTag(NAMESPACE, "poem");</pre>
<p>It is important to inform serializer when XML output is finished
so any remianing buffered XML output is send to putput stream and
serializer will not allow any more input to do this call endDocument():
<pre> serializer.endDocument();</pre>
<h3>Controlling namespace prefixes</h3>
There is no need to manually set prefixes as XmlSerializer will automatically
declare prefixes when needed. However sometimes it is necessary to indicate
what prefix should be used:
<pre> serializer.setPrefix("ns", NAMESPACE);</pre>
or what namespace should be bound as default namespace (to special empty string prefix):
<pre> serializer.setPrefix("", NAMESPACE);</pre>
<p>Prefix declaration must be done just before call to start tag and
the prefix declaration scope starts on this star tag and finishes when corresponding
end tag is reached.
<h3>Controlling output formatting</h3>
<p>XmlSerializer allows to create any infoset so it is possible to add manually
new lines or indentation. for exmaple if would like to have new line after every end tag
it is as easy as to call text() with new line:
<pre> if(addNewLine) serializer.text("\n");</pre>
<p>If serializer supports optional formatting properties and features then
they can be used to have output indented automatically.
Read more about them:
<ul>
<li>optional property:
<a href="http://xmlpull.org/v1/doc/properties.html#serializer-indentation">SERIALIZER INDENTATION</a>
<li>optional property:
<a href="http://xmlpull.org/v1/doc/properties.html#serializer-line-separator">SERIALIZER LINE SEPARATOR</a>
<li>optional feature:
<a href="http://xmlpull.org/v1/doc/features.html#serializer-attvalue-use-apostrophe">SERIALIZER ATTVALUE USE APOSTROPHE</a>
</ul>
<p> </p>
</p>
<h2>Sample code</h2>
<p>
The finished working sample created that was described is in
<a href="../src/java/samples/MyXmlWriteApp.java">MyXmlWriteApp.java</a> file in
<a href="../src/java/samples/">src/java/samples</a> directory.
<p>For more information about XmlPull API
please visit
<a href="http://www.xmlpull.org/">http://www.xmlpull.org/</a>.
</p>
<h2>Output from sample application</h2>
<p>When new lines are added manually:
<pre>java MyXmlWriteApp -n
serializer implementation class is class org.kxml2.io.KXmlSerializer
<?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>
</pre>
<p>When using one of optional formatting properties to set indentation:
<pre>java MyXmlWriteApp -i 4
serializer implementation class is class org.xmlpull.mxp1_serializer.MXSerializer
<?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>
</pre>
<hr>
<address><a href="http://www.extreme.indiana.edu/~aslom/">Aleksander Slominski</a><address>
</address>
</BODY>
</HTML>
------------------------ Yahoo! Groups Sponsor ---------------------~-->
Get 128 Bit SSL Encryption!
http://us.click.yahoo.com/FpY02D/vN2EAA/xGHJAA/2U_rlB/TM
---------------------------------------------------------------------~->
To unsubscribe from this group, send an email to:
[email protected]
Your use of Yahoo! Groups is subject to http://docs.yahoo.com/info/terms/