# HG changeset patch # User Tim Englich # Date 1274179932 0 # Node ID e7fda0ae8b926d3ccb008bec1983437f4fc3aea6 # Parent d98d3e82118ce445b319e2e6b77973c388f6e842 Add more Javadocs gnv/trunk@1106 c6561f87-3c4e-4783-a992-168aeb5c3f6f diff -r d98d3e82118c -r e7fda0ae8b92 gnv/ChangeLog --- a/gnv/ChangeLog Tue May 18 10:17:51 2010 +0000 +++ b/gnv/ChangeLog Tue May 18 10:52:12 2010 +0000 @@ -1,3 +1,10 @@ +2010-05-18 Tim Englich + + * src/main/java/de/intevation/gnv/util/XSLTransformer.java: + * src/main/java/de/intevation/gnv/util/XMLUtils.java: + * src/main/java/de/intevation/gnv/util/ArtifactNamespaceContext.java: + Added more Javadocs. Did some Codeformatting. + 2010-05-18 Tim Englich * src/main/java/de/intevation/gnv/servlet/GNVActionServlet.java, diff -r d98d3e82118c -r e7fda0ae8b92 gnv/src/main/java/de/intevation/gnv/util/ArtifactNamespaceContext.java --- a/gnv/src/main/java/de/intevation/gnv/util/ArtifactNamespaceContext.java Tue May 18 10:17:51 2010 +0000 +++ b/gnv/src/main/java/de/intevation/gnv/util/ArtifactNamespaceContext.java Tue May 18 10:52:12 2010 +0000 @@ -3,7 +3,6 @@ import java.util.Iterator; import javax.xml.XMLConstants; - import javax.xml.namespace.NamespaceContext; /** @@ -25,9 +24,15 @@ */ public final static String NAMESPACE_PREFIX = "art"; + /** + * The singleton instance of this NamespaceContext + */ public static final ArtifactNamespaceContext INSTANCE = new ArtifactNamespaceContext(); + /** + * Constructor + */ public ArtifactNamespaceContext() { } diff -r d98d3e82118c -r e7fda0ae8b92 gnv/src/main/java/de/intevation/gnv/util/XMLUtils.java --- a/gnv/src/main/java/de/intevation/gnv/util/XMLUtils.java Tue May 18 10:17:51 2010 +0000 +++ b/gnv/src/main/java/de/intevation/gnv/util/XMLUtils.java Tue May 18 10:52:12 2010 +0000 @@ -8,62 +8,99 @@ import javax.xml.namespace.NamespaceContext; import javax.xml.namespace.QName; - import javax.xml.parsers.DocumentBuilder; import javax.xml.parsers.DocumentBuilderFactory; import javax.xml.parsers.ParserConfigurationException; - import javax.xml.transform.Transformer; import javax.xml.transform.TransformerConfigurationException; import javax.xml.transform.TransformerException; import javax.xml.transform.TransformerFactory; import javax.xml.transform.TransformerFactoryConfigurationError; - import javax.xml.transform.dom.DOMSource; - import javax.xml.transform.stream.StreamResult; - import javax.xml.xpath.XPath; import javax.xml.xpath.XPathConstants; import javax.xml.xpath.XPathExpressionException; import javax.xml.xpath.XPathFactory; import org.apache.log4j.Logger; - import org.w3c.dom.Attr; import org.w3c.dom.Document; import org.w3c.dom.Element; import org.w3c.dom.Node; import org.w3c.dom.NodeList; - import org.xml.sax.SAXException; /** - * @author Sascha L. Teichmann + * This class provides many helper-Methods for handling different kinds of + * XML-stuff. + * @author Tim Englich + * @author Sascha L. Teichmann */ public class XMLUtils { + + /** + * the logger, used to log exceptions and additonaly information + */ private static Logger logger = Logger.getLogger(XMLUtils.class); + /** + * Constructor + */ public XMLUtils() { } + /** + * Class which could be used to create XML-Elements + * @author Sascha L. Teichmann + * + */ public static class ElementCreator { + + /** + * The document the elements should be placed in. + */ protected Document document; + + /** + * The namespace that should be used. + */ protected String ns; + + /** + * The prefix of the namespace that should be used. + */ protected String prefix; + /** + * Constructor + * @param document the document the elements should be placed in + * @param ns the namespace that should be used + * @param prefix the prefix of the namespace that should be used + */ public ElementCreator(Document document, String ns, String prefix) { this.document = document; this.ns = ns; this.prefix = prefix; } + /** + * Creates a new element using the given name. + * @param name the name of the new element. + * @return the new element + */ public Element create(String name) { Element element = document.createElementNS(ns, name); element.setPrefix(prefix); return element; } + /** + * Adds a new attribute to the given element. + * @param element the element where the attribute should be placed in. + * @param name the name of the attribute + * @param value the value of the attribute + */ public void addAttr(Element element, String name, String value) { Attr attr = document.createAttributeNS(ns, name); attr.setValue(value); @@ -72,6 +109,10 @@ } } // class ElementCreator + /** + * Creates a new document. + * @return the new document + */ public static Document newDocument() { try { return DocumentBuilderFactory.newInstance().newDocumentBuilder() @@ -82,10 +123,19 @@ return null; } + /** + * Creates a new XPath-expression + * @return the new XPath-expression + */ public static XPath newXPath() { return newXPath(null); } + /** + * Creates a new XPath-expression + * @param namespaceContext the namespacecontext that should be used. + * @return the new XPath-expression + */ public static XPath newXPath(NamespaceContext namespaceContext) { XPathFactory factory = XPathFactory.newInstance(); XPath xpath = factory.newXPath(); @@ -95,66 +145,127 @@ return xpath; } - public static Object xpath(Object root, String query, QName returnTyp) { - return xpath(root, query, returnTyp, null); - } - + /** + * Fetch the value of an element or attribute from the given resource + * using the query. + * @param root the source where the value should be fetch from + * @param query the query that should be used to fetch the value + * @param namespaceContext the namespacecontext that must match to + * fetch the value. + * @return the value + */ public static final String xpathString(Object root, String query, NamespaceContext namespaceContext) { return (String) xpath(root, query, XPathConstants.STRING, namespaceContext); } + /** + * Fetch the object rom the given resource using the query. + * @param root the source where the value should be fetch from + * @param query the query that should be used to fetch the object + * @param returnType the Type that must be used to return the object, + * @param namespaceContext the namespacecontext that must match to + * fetch the object. + * @return the value + */ public static final Object xpath(Object root, String query, QName returnType, NamespaceContext namespaceContext) { if (root == null) { return null; } - try { - XPath xpath = new XMLUtils().newXPath(namespaceContext); + XPath xpath = XMLUtils.newXPath(namespaceContext); if (xpath != null) { return xpath.evaluate(query, root, returnType); } } catch (XPathExpressionException xpee) { logger.error(xpee.getLocalizedMessage(), xpee); } - return null; } + /** + * Fetch the object rom the given resource using the query + * and the default ArtifactNamespaceContext + * @param root the source where the value should be fetch from + * @param query the query that should be used to fetch the object + * @param returnType the Type that must be used to return the object + * @return the value + */ public static Object getXPath(Object root, String query, QName returnType) { return getXPath(root,query,returnType,ArtifactNamespaceContext.INSTANCE); } + /** + * Fetch the object rom the given resource using the query + * and the default ArtifactNamespaceContext + * @param root the source where the value should be fetch from + * @param query the query that should be used to fetch the object + * @param returnType the Type that must be used to return the object. + * @param namespaceContext the namespacecontext that must match to + * fetch the object. + * @return the value + */ public static Object getXPath( Object root, String query, QName returnType, NamespaceContext context ) { return xpath(root, query, returnType, context); } - public static String getStringXPath(String xpath) { - return getStringXPath(xpath, null); - } - + /** + * Fetch a Nodeset value from a XML-Fragment or XML-Document using the + * given query. + * @param root the source where the String should be fetched from + * @param query the query that should be used, + * @return the Nodeset fetched from the source + */ public static NodeList getNodeSetXPath(Object root, String query) { return (NodeList) getXPath(root, query, XPathConstants.NODESET); } + /** + * Fetch a Node from a XML-Fragment or XML-Document using the + * given query. + * @param root the source where the Node should be fetched from + * @param query the query that should be used, + * @return the Node fetched from the source + */ public static Node getNodeXPath(Object root, String query) { return (Node) getXPath(root, query, XPathConstants.NODE); } + /** + * Fetch a String value from a XML-Fragment or XML-Document using the + * given query. + * @param root the source where the String should be fetched from + * @param xpath the query that should be used, + * @return the String fetched from the source + */ public static String getStringXPath(Object root, String xpath) { return getStringXPath(root, xpath, null); } + /** + * Fetch a String value from a XML-Fragment or XML-Document using the + * given query. + * @param root the source where the String should be fetched from + * @param query the query that should be used, + * @param def the default-value that will be returned id no value was found + * @return the String fetched from the source + */ public static String getStringXPath(Object root, String query, String def) { String s = (String) getXPath(root, query, XPathConstants.STRING); return s == null || s.length() == 0 ? def : s; } + /** + * Reads an XML-document from a given InputStream + * @param inputStream the InputStream where the document + * should be read from + * @return the document that could be read. + */ public static Document readDocument(InputStream inputStream) { Document returnValue = null; try { @@ -173,6 +284,11 @@ return returnValue; } + /** + * Writes an single XML-Node to a string + * @param node the XML-Node that should be written + * @return the encoded XML-Node + */ public static String writeNode2String(Node node) { try { DOMSource source = new DOMSource(node); @@ -187,13 +303,25 @@ return null; } + /** + * Reinitialize the doument. + * This is neccessary because the namespace sometimes is invalid + * using a document which was created and used in the same step. + * @param document the document which should be reinitialize + * @return the document + */ public static Document reInitDocument(Document document) { - StringBufferInputStream inputStream = new StringBufferInputStream( writeDocument2String(document)); return readDocument(inputStream); } + /** + * Writes the given Document into a String. + * This is very helpful for debugging. + * @param document the document which should be written to the string. + * @return the encoded xml-document. + */ public static String writeDocument2String(Document document) { try { DOMSource source = new DOMSource(document); @@ -209,8 +337,9 @@ } /** - * @param source - * @return + * Writes a given DOMSource into a String + * @param source the source that should be written to string + * @return the encoded DOMSource * @throws TransformerFactoryConfigurationError * @throws TransformerConfigurationException * @throws TransformerException @@ -228,7 +357,13 @@ return sw.getBuffer().toString(); } - public static boolean toStream(Document document, OutputStream out) { + /** + * Writes a given Document to an OutputStream + * @param document the document that should be written + * @param out the stream where the document should be written to, + * @return true if it was successful, false if not. + */ + public static boolean toStream(Document document, OutputStream out) { try { Transformer transformer = TransformerFactory.newInstance().newTransformer(); @@ -246,7 +381,6 @@ catch (TransformerException te) { logger.error(te.getLocalizedMessage(), te); } - return false; } } diff -r d98d3e82118c -r e7fda0ae8b92 gnv/src/main/java/de/intevation/gnv/util/XSLTransformer.java --- a/gnv/src/main/java/de/intevation/gnv/util/XSLTransformer.java Tue May 18 10:17:51 2010 +0000 +++ b/gnv/src/main/java/de/intevation/gnv/util/XSLTransformer.java Tue May 18 10:52:12 2010 +0000 @@ -3,7 +3,6 @@ import java.io.ByteArrayOutputStream; import java.io.File; import java.io.UnsupportedEncodingException; - import java.util.HashMap; import java.util.Map; @@ -13,14 +12,11 @@ import javax.xml.transform.TransformerException; import javax.xml.transform.TransformerFactory; import javax.xml.transform.TransformerFactoryConfigurationError; - import javax.xml.transform.dom.DOMSource; - import javax.xml.transform.stream.StreamResult; import javax.xml.transform.stream.StreamSource; import org.apache.log4j.Logger; - import org.w3c.dom.Node; /** @@ -30,12 +26,15 @@ * @author Tim Englich */ public class XSLTransformer { + /** * the logger, used to log exceptions and additonaly information */ private static Logger log = Logger.getLogger(XSLTransformer.class); - + /** + * The parameter that is required in the XSL sheet. + */ private Map params; /** @@ -60,7 +59,6 @@ String templateFileName) { String resultValue = null; try { - //XMLUtils xmlUtils = new XMLUtils(); Source templateSource = new StreamSource(new File(templateFileName)); TransformerFactory xformFactory = TransformerFactory.newInstance(); Transformer transformer = xformFactory