Package org.backsource.utils.xml

Utils to make it easier and faster to work with XML document, either as files, DOM trees or strings.

See:
Description

Class Summary

Catalog	A simple extension of the Catalog to make it easier to construct instances progranatically.
CatalogEntry	A simple wrapper to make it easier to create CatalogEntry entries programatically.
CatalogEntry.CatalogEntryType
CatalogResolver	A Catalog based resolver which is originally based on org.apache.xml.resolver.tools.CatalogResolver.
DocumentUtil	Util to handle stuff relating to documents and nodes.
ElementUtil	Utility methods to help working with Elements.
Example	Just an example of how to use the xml classes.
Resolver	A Resolver container.
ResolverContext	Resolver context is a flexible static class to allow setting of EntityResolver and URIResolver when using all the static methods in these utility classes.
UtilsConfig	UtilsConfig.java Created: Fri Apr 23 10:05:04 2004
XmlBeanUtil	XPath based property setter util.
XPathUtil	Util to make it easy to get nodes from a document with the help of an XPath expression.

Exception Summary

XmlException

Common exception for all the XML utils.

Package org.backsource.utils.xml Description

Utils to make it easier and faster to work with XML document, either as files, DOM trees or strings.

This package contains a number of utils to make it a little easier to work with XML. It is beased on a number of utility rutines and stuff I have found usefull when programming XML stuff. Remember: for many things when it commes to XML hthere is already a convinient API, from the DOM to JAXP. Often these API:s will do well. I have, however, during a number of occassions felt that a somewhat more simplified API was also good to have. This package contains the basis for such an api. It is mean to be used to fast solve the simple things. If you find that some advanced stuff is missing: well use the ordinary API:s or contribute a solution to timutils.

The basis for the package is that you should be able to quickly get a Document from a stream or a string and quicky get the string version of that XML, be it a full document or a document fragment. Inserting new fragments is allways a pain, so we help with that to. See DocumentUtil

To get and set the content of an Element is allways a pain. One almost allways also have to write special code to get at a required element or an optional element. The ElementUtil provide a number of handy methods to quicky be able to get work with elements. The test in org/backsource/utils/xml/TestElementUtil.java contains a rich number of examples on how to use it.

Here is a teaser on how easy it is to use setElement():

        Element xml = DocumentUtil.getDocumentElement("<my><rep><disap/></rep></my>");
        Element rep = ElementUtil.getUniqueChild(xml,"rep");
        Element elem = DocumentUtil.getDocumentElement("<my-newdisap><hej/><my-newdisap>");
        ElementUtil.setElement(rep, elem);

The new xml will look like this:

<my><rep><my-newdisap><hej/><my-newdisap></rep></my>

One even nicer way to access XML is to use XPath. With XPath you may take a DOM and the point deeply into it ant get the node you want without heavy traversal of the XML. The XPathUtil makes it easy to do this. Say you wanted to get at all MBean:s in a jboss-service file which have an Attribute element of name Port and with 1099 as content you might do it like this:

Node n = XPathUtil.selectNodes(xml,"//mbean/attribute[@name='Port'][text()='1099']");

Taking all this together and adding some extra stuff gives us XmlBeanUtil. This bean ties together the java Bean paradigm with DOM and xpath. With it you can get string values from a dom with xpath, you can set bean attributes from a dom with xpath and bean property specifyers. You can also set values in the dom with xpath, even directly from a bean! Neat, is it not. The test in org/backsource/utils/xml/TestXmlBeanUtil.java contains a wast number of examples. Here is one:

XmlBeanUtil.setXmlProperty(xml,"//mbean/attribute[@name='Port' and text() = '1099']", "1199");

This one example will find al nodes specifyed with the XPath an substitute the value 1099 with 1199 in the live dom tree. Ok, one more. Here we set the strinifyed XML from the sublement into the String attribute of the given bean:

      TestBean b = new TestBean();
       XmlBeanUtil.setBeanProperty(b,"attribute" ,xml,"//mbean/attribute/@name");

How resources are resolved is often a pain when parsing XML or doing transaformations. The JAXP api:s to do it is simple, but to write stable resolvers is not. We therefor have a wrapper above the apache resolver package to make it trully easy to set up and alternative resolver, which uses a Catalog as its base, CatalogResolver.

So to the last point. As said, these utils is for easy tasks. We have one not so easy thing to solve, namley how to configure the parser/transformer when we reallt need to. We can't, with one exception. With the ResolverContext we might set a resolver the parser/transformer should try to use when looking up publid and systemid. The resolver is based on the ideas developed around local classloader and the org.backsource.utils.resource package. To use the resolver you have to have your own resolvers. Create a Resolver, put your resolvers into that and configure the ResolverContext to your need. Here is how it is done to use the ant XMLCatalog resolvers:

  ad = (XMLCatalog)o;
  Resolver r = new Resolver((EntityResolver)ad,(URIResolver)ad);
  ResolverContext.set(r);