From c12ea94eadf5b6a5b3897498b2b43f2dbe611782 Mon Sep 17 00:00:00 2001 From: codistmonk Date: Fri, 2 Jul 2010 22:41:54 +0000 Subject: [PATCH] [Aprog] Updated comments. git-svn-id: https://aprog.svn.sourceforge.net/svnroot/aprog/trunk@80 7cbf5e2b-b55d-4b93-acdd-c0d7b961df51 --- Aprog/src/net/sourceforge/aprog/xml/XMLTools.java | 75 ++++++++++++++++++----- 1 file changed, 58 insertions(+), 17 deletions(-) diff --git a/Aprog/src/net/sourceforge/aprog/xml/XMLTools.java b/Aprog/src/net/sourceforge/aprog/xml/XMLTools.java index 63bc4b5..619ed98 100644 --- a/Aprog/src/net/sourceforge/aprog/xml/XMLTools.java +++ b/Aprog/src/net/sourceforge/aprog/xml/XMLTools.java @@ -234,7 +234,8 @@ public final class XMLTools { transformer.setOutputProperty(OutputKeys.METHOD, "xml"); transformer.setOutputProperty(OutputKeys.INDENT, indent != 0 ? "yes" : "no"); - transformer.setOutputProperty(OutputKeys.OMIT_XML_DECLARATION, node instanceof Document ? "no" : "yes"); + transformer.setOutputProperty(OutputKeys.OMIT_XML_DECLARATION, + node instanceof Document ? "no" : "yes"); transformer.setOutputProperty(OutputKeys.STANDALONE, "yes"); transformer.transform(new DOMSource(node), output); @@ -268,7 +269,7 @@ public final class XMLTools { *
Not null *
New */ - public static final List newList(final NodeList nodeList) { + public static final List toList(final NodeList nodeList) { final List result = new ArrayList(); for (int i = 0; i < nodeList.getLength(); ++i) { @@ -279,12 +280,13 @@ public final class XMLTools { } /** + * Validates the XML input against the specified DTD or schema. * * @param xmlInputStream *
Not null * @param dtdOrSchema *
Not null - * @return + * @return An empty list if validation succeeds *
Not null *
New */ @@ -294,7 +296,8 @@ public final class XMLTools { try { if (schemaLanguage != null) { - final Validator validator = SchemaFactory.newInstance(schemaLanguage).newSchema(dtdOrSchema).newValidator(); + final Validator validator = SchemaFactory.newInstance(schemaLanguage) + .newSchema(dtdOrSchema).newValidator(); validator.validate(new StreamSource(xmlInputStream)); } else { @@ -349,13 +352,16 @@ public final class XMLTools { } /** + * Determines the schema language from the argument's system id. * * @param dtdOrSchema *
Not null * @return {@code null} for a DTD *
Maybe null - *
Range: { {@code null}, {@link XMLConstants#W3C_XML_SCHEMA_NS_URI}, {@link XMLConstants#RELAXNG_NS_URI} } - * @throws IllegalArgumentException If {@code dtdOrSchema}'s system id does not indicate a DTD or a schema (XSD or RNG) + *
Range: { {@code null}, + * {@link XMLConstants#W3C_XML_SCHEMA_NS_URI}, {@link XMLConstants#RELAXNG_NS_URI} } + * @throws IllegalArgumentException If {@code dtdOrSchema}'s system id does not indicate + * a DTD or a schema (XSD or RNG) */ public static final String getSchemaLanguage(final Source dtdOrSchema) { final String dtdOrSchemaId = dtdOrSchema.getSystemId().toLowerCase(); @@ -373,6 +379,7 @@ public final class XMLTools { } /** + * Calls {@link #getNode(java.lang.Object, java.lang.String)}. * * @param context *
Maybe null @@ -387,6 +394,7 @@ public final class XMLTools { } /** + * Calls {@link #getNodes(java.lang.Object, java.lang.String)}. * * @param context *
Maybe null @@ -401,6 +409,8 @@ public final class XMLTools { } /** + * Calls {@link #get(java.lang.Object, java.lang.String, javax.xml.namespace.QName)} + * with {@code returnType == XPathConstants.NODE}. * * @param The expected node type * @param context @@ -417,6 +427,8 @@ public final class XMLTools { } /** + * Calls {@link #get(java.lang.Object, java.lang.String, javax.xml.namespace.QName)} + * with {@code returnType == XPathConstants.NODESET}. * * @param The expected node set type * @param context @@ -433,6 +445,8 @@ public final class XMLTools { } /** + * Calls {@link #get(java.lang.Object, java.lang.String, javax.xml.namespace.QName)} + * with {@code returnType == XPathConstants.BOOLEAN}. * * @param context *
Maybe null @@ -447,6 +461,8 @@ public final class XMLTools { } /** + * Calls {@link #get(java.lang.Object, java.lang.String, javax.xml.namespace.QName)} + * with {@code returnType == XPathConstants.NUMBER}. * * @param context *
Maybe null @@ -461,6 +477,8 @@ public final class XMLTools { } /** + * Calls {@link #get(java.lang.Object, java.lang.String, javax.xml.namespace.QName)} + * with {@code returnType == XPathConstants.STRING}. * * @param context *
Maybe null @@ -475,6 +493,8 @@ public final class XMLTools { } /** + * Evaluates the compiled XPath expression in the specified context + * and returns the result as the specified type. * * @param The expected return type * @param context @@ -505,33 +525,51 @@ public final class XMLTools { } /** + * Evaluates the quasi-XPath expression in the specified context, and returns the corresponding node, + * creating it if necessary. + *
The second argument is called "quasi-XPath" because it allows non-XPath expressions + * like {@code "a/b[]"} which means "add an element b at the end of a". + *
If {@code quasiXPath} is a standard XPath expression and the corresponding node exists, + * then that node is returned. + *
When the node does not exist, + * {@code quasiXPath} is broken down into path elements separated by slashes ("/"). + *
A path element can be created if it is of the form "name[]" or "name[attributes]" where + * "atributes" must be a sequence of "@attribute=value" separated by "and". + *
Example of a valid quasi-XPath expression where each path element can be created if necessary:
    + *
  • {@code "a/b[]/c[@d='e' and @f=42]"} + *
+ *
Example of a valid quasi-XPath expression where + * the path elements cannot be created if they don't exist:
    + *
  • {@code "a[last()]/b[@c<42]/d[position()=33]/e['f'=@g]"} + *
+ * * * @param context *
Not null - * @param xPath + * @param quasiXPath *
Not null * @return *
Maybe null *
Maybe new */ - public static final Node getOrCreateNode(final Node context, final String xPath) { - final String[] xPathElements = xPath.split("/"); + public static final Node getOrCreateNode(final Node context, final String quasiXPath) { + final String[] pathElements = quasiXPath.split("/"); Node result = context; try { - for (int index = 0; index < xPathElements.length && result != null; ++index) { - final String xPathElement = xPathElements[index]; + for (int index = 0; index < pathElements.length && result != null; ++index) { + final String pathElement = pathElements[index]; - if (xPathElement.matches("\\w+\\[\\]")) { - result = addChild(result, xPathElement); + if (pathElement.matches("\\w+\\[\\]")) { + result = addChild(result, pathElement); } else { final Node parent = result; - result = getNode(result, xPathElement); + result = getNode(result, pathElement); if (result == null) { - final Map attributes = getEqualityPredicates(xPathElement); - final Integer nameEnd = xPathElement.indexOf("["); - final String childName = nameEnd < 0 ? xPathElement : xPathElement.substring(0, nameEnd); + final Map attributes = getEqualityPredicates(pathElement); + final Integer nameEnd = pathElement.indexOf("["); + final String childName = nameEnd < 0 ? pathElement : pathElement.substring(0, nameEnd); result = addChild(parent, childName); @@ -549,6 +587,9 @@ public final class XMLTools { } /** + * Creates and adds a new node to {@code parent}. + *
If {@code xPathElement} starts with "@", + * then the new node is an attribute, otherwise it is an element. * * @param parent *
Not null -- 2.11.4.GIT