File	Date	Author	Commit
src	2008-05-20	genman	[ae3f19] Add JDk 1.5 generic types and @Override annotat...
.classpath	2008-05-20	genman	[ae3f19] Add JDk 1.5 generic types and @Override annotat...
.cvsignore	2002-07-15	genman	[137c1f] Fixed retry bug, added unit-tests
.project	2008-05-20	genman	[ae3f19] Add JDk 1.5 generic types and @Override annotat...
HEADER.txt	2002-08-01	genman	[d2e60c] Fixed javadoc to be more consistant
LICENCE.txt	2002-06-04	genman	[1c7fe3] This commit was generated by cvs2svn to compens...
README.txt	2002-08-01	genman	[d2e60c] Fixed javadoc to be more consistant
TODO.txt	2002-10-31	genman	[a4f8e6] updated TODO
pom.xml	2007-09-08	genman	[81eb3a] Initial restructure into separate Maven packages

Read Me

	      E-XML Library:  For XML, XML-RPC, HTTP, and related.
			 Copyright (C) 2002  Elias Ross

genman@maison-otaku.net
http://maison-otaku.net/~genman


				  WHAT IS IT?

This library is a collection of tools for parsing XML.  For better or worse,
DOM and SAX are fairly heavy-weight and cumbersome parsing tools, which have
lead others to create libraries such as JDOM and KXML (Enhydra).  For most
of you, the Xerces library will be just fine, and I suggest you stick with
that if performance is not a big problem.


			       PARSE PERFORMANCE

XML parsing is pretty damn inefficient, at least when you're parsing
hundreds of XML messages a second.  Take a look at XMLSParser.  It
is a XML pull-parser (look that up on Google) which makes it very
cheap in terms of object creation overhead.

Most of the pull-parsers don't support String pools or allow for
re-using existing objects.  Most small-footprint parsers have lousy
performance, often much worse than Xerces SAX and DOM.

If you test this library's performance against Xerces DOM, it's comparable 
(perhaps a little faster) for reading a whole document.

For the ultimate in parse speed, use XmlSParser.


				 STREAMING XML

Another problem is handling streaming protocol data, which can't be
gracefully done with SAX, and cannot be done with any DOM parsers.
An XML pull-parser makes it fairly simple to write efficient protocol
handling routines.  However, the XML pull-parsers I've seen are fairly
cumbersome as well, maybe because they were designed for low-memory
devices.

The XmlParser class lets you parse streaming data in a straight-forward
manner.  XmlSParser is a little more complicated to use, and does not
support DTD validation.


				    XML-RPC

I include an XML-RPC implementation which streams XML data over HTTP.
It doesn't do any fancy object marshalling or demarshalling, but you can
follow my example package and implement your own streaming conversion routines.


			  RELATED TOOLS AND LIBRARIES

The java.net.URLConnection library is not very good at sending streaming data,
so I had to write my own HTTP library.  It's not exactly user-friendly, but it
is better than any other library I've seen so far.  You will have to write
your own "smart" HttpClient if you want to do more than what I wrote there.


			   EXAMPLES AND DOCUMENTATION

First, create the Java-Docs.  Take a look at the "src-test" directory, which
demonstrates every method in the library.  Since this is open-source, you
of course have access to the source code.  Please send me e-mail if you
have a suggestion.

I will eventually add in example programs later.