X-Git-Url: http://wamblee.org/gitweb/?a=blobdiff_plain;f=support%2Fgeneral%2Fsrc%2Fmain%2Fjava%2Forg%2Fwamblee%2Fxml%2Fpackage-info.java;h=561d6419ee732b58c20ec51805219b1aae2809c0;hb=a2970417bfbaffb8bb1ee13bd6f88ef0dd9b93a0;hp=9ec0a53967260971b450d9b6eb911ca593a4440c;hpb=b9aa4073768e6f2aff963b44cfce59017ec91e29;p=utils

diff --git a/support/general/src/main/java/org/wamblee/xml/package-info.java b/support/general/src/main/java/org/wamblee/xml/package-info.java
index 9ec0a539..561d6419 100644
--- a/support/general/src/main/java/org/wamblee/xml/package-info.java
+++ b/support/general/src/main/java/org/wamblee/xml/package-info.java
@@ -12,8 +12,69 @@
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
- */ 
+ */
 /**
- * Utilities for XML processing.
+ * <p>
+ * Utilities for XML processing. The aim of this package is to simplify the 
+ * common tasks of parsing, validating, and transforming XML files and to 
+ * provide support for XPath. The utlities simply use the standard Java SE APIs
+ * but are much easier to use. For cases where more advanced functionality is required,
+ * the classes provide access to the underlying Java SE types. The implementation is 
+ * based on DOM level 3 parsing.  
+ * </p>
+ * 
+ * <p>
+ * Classes {@link org.wamblee.xml.XMLDocument}, {@link org.wamblee.xml.XMLSchema}, and 
+ * {@link org.wamblee.xml.XSLTransformation} provide parsing, validation, and transformation
+ * of XML files. The {@link org.wamblee.xml.XMLDocument} class provides various static 
+ * methods as entry point for this functionality, simplifying the code a lot when 
+ * static imports are used. The API design uses a fluent interfaces style. For instance, 
+ * to parse, validate, and transform an XML file, one can write:
+ * </p>
+ * <pre>
+ * import static org.wamblee.xml.XMLDocument;
+ * ...
+ * XMLDocument doc = xmldocument(new File("x.xml").toURI()).validate(new File("x.xsd").toURI()).transform(new File("x.xsl").toURI());
+ * </pre>
+ * 
+ * <p>
+ * In addition, a URI resolver {@link org.wamblee.xml.ClasspathUriResolver} is provided to allow resolution of 
+ * documents on the classpath. 
+ * </p>
+ * 
+ * <p>
+ * For XPath the following classes are provided: 
+ * </p>
+ * <ul>
+ *   <li> {@link org.wamblee.xml.SimpleNamespaceContext}: An generic implementation of {@link javax.xml.namespace.NamespaceContext}.
+ *   </li>
+ *   <li> {@link org.wamblee.xml.XPathContext}: A factory of <code>XPathExpression</code> objects based on a given namespace
+ *     context. 
+ *   </li>
+ *   <li> {@link org.wamblee.xml.XPathExpression}: The interface for working with XPath. 
+ *   </li>
+ * </ul>
+ * 
+ * <p>
+ * For instance to apply an XPath expression to an XML document: 
+ * </p>
+ * <pre>
+ *      NamespaceContext context = new XPathContext(new SimpleNamespaceContext()
+ *            .addPrefix("n", "http://example.com/1")
+ *            .addPrefix("m", "http://example.com/2"));
+ *      XMLDocument doc = new XMLDocument(new File("xpathexample.xml").toURI());
+ *      String value = context.createExpression("/n:root/m:x").stringEval(doc);
+ * </pre>
+ * <p>
+ * Or, using static imports: 
+ * </p>
+ *  <pre>
+ *      NamespaceContext context = xpathcontext(namespaces()
+ *            .addPrefix("n", "http://example.com/1")
+ *            .addPrefix("m", "http://example.com/2"));
+ *      XMLDocument doc = xmldocument(new File("xpathexample.xml").toURI());
+ *      String value = context.createExpression("/n:root/m:x").stringEval(doc);
+ * </pre>
  */
 package org.wamblee.xml;
+