wamblee.org Git - utils/blob - support/general/src/main/java/org/wamblee/xml/package-info.java

   1 /*
   2  * Copyright 2005-2010 the original author or authors.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16 /**
  17  * <p>
  18  * Utilities for XML processing. The aim of this package is to simplify the
  19  * common tasks of parsing, validating, and transforming XML files and to
  20  * provide support for XPath. The utlities simply use the standard Java SE APIs
  21  * but are much easier to use. For cases where more advanced functionality is required,
  22  * the classes provide access to the underlying Java SE types. The implementation is
  23  * based on DOM level 3 parsing.
  24  * </p>
  25  *
  26  * <p>
  27  * Classes {@link org.wamblee.xml.XMLDocument}, {@link org.wamblee.xml.XMLSchema}, and
  28  * {@link org.wamblee.xml.XSLTransformation} provide parsing, validation, and transformation
  29  * of XML files. The {@link org.wamblee.xml.XMLDocument} class provides various static
  30  * methods as entry point for this functionality, simplifying the code a lot when
  31  * static imports are used. The API design uses a fluent interfaces style. For instance,
  32  * to parse, validate, and transform an XML file, one can write:
  33  * </p>
  34  * <pre>
  35  * import static org.wamblee.xml.XMLDocument;
  36  * ...
  37  * XMLDocument doc = xmldocument(new File("x.xml").toURI()).validate(new File("x.xsd").toURI()).transform(new File("x.xsl").toURI());
  38  * </pre>
  39  *
  40  * <p>
  41  * In addition, a URI resolver {@link org.wamblee.xml.ClasspathUriResolver} is provided to allow resolution of
  42  * documents on the classpath.
  43  * </p>
  44  *
  45  * <p>
  46  * For XPath the following classes are provided:
  47  * </p>
  48  * <ul>
  49  *   <li> {@link org.wamblee.xml.SimpleNamespaceContext}: An generic implementation of {@link javax.xml.namespace.NamespaceContext}.
  50  *   </li>
  51  *   <li> {@link org.wamblee.xml.XPathContext}: A factory of <code>XPathExpression</code> objects based on a given namespace
  52  *     context.
  53  *   </li>
  54  *   <li> {@link org.wamblee.xml.XPathExpression}: The interface for working with XPath.
  55  *   </li>
  56  * </ul>
  57  *
  58  * <p>
  59  * For instance to apply an XPath expression to an XML document:
  60  * </p>
  61  * <pre>
  62  *      NamespaceContext context = new XPathContext(new SimpleNamespaceContext()
  63  *            .addPrefix("n", "http://example.com/1")
  64  *            .addPrefix("m", "http://example.com/2"));
  65  *      XMLDocument doc = new XMLDocument(new File("xpathexample.xml").toURI());
  66  *      String value = context.createExpression("/n:root/m:x").stringEval(doc);
  67  * </pre>
  68  * <p>
  69  * Or, using static imports:
  70  * </p>
  71  *  <pre>
  72  *      NamespaceContext context = xpathcontext(namespaces()
  73  *            .addPrefix("n", "http://example.com/1")
  74  *            .addPrefix("m", "http://example.com/2"));
  75  *      XMLDocument doc = xmldocument(new File("xpathexample.xml").toURI());
  76  *      String value = context.createExpression("/n:root/m:x").stringEval(doc);
  77  * </pre>
  78  */
  79 package org.wamblee.xml;
  80