Package de.aristaflow.adept2.util.xml

Class XMLHelperTools

java.lang.Object
de.aristaflow.adept2.util.xml.XMLHelperTools
public class XMLHelperTools extends Object
Contains important function for both, XML import and export.

  • Field Details

    • DEFAULT_ENCODING

      public static final String DEFAULT_ENCODING
      The encoding that should be used for writing XML files. Some preferable encodings are 'UTF-8', 'UTF-16BE', 'UTF-16LE' or 'ISO-8859-1'.
      Note that Microsoft DBMS do not support UTF-8 but only UTF-16.
      See Also:

    • logger

      protected static final Logger logger
      The logger instance of this class.

  • Constructor Details

    • XMLHelperTools

      public XMLHelperTools()

  • Method Details

    • isValid

      public static boolean isValid(Node node, Schema schema)
      Returns whether the given node is valid against the given Schema.
      Parameters:
      node - The node to be validated.
      schema - The schema to validate the node against.
      Returns:
      Whether the given Node is valid against the given Schema.

    • isStreamValid

      public static boolean isStreamValid(InputStream is, Schema schema)
      Returns whether the given Node is valid against the given Schema.
      Parameters:
      is - The input stream containing the XML data to be validated.
      schema - The schema to validate the node against.
      Returns:
      Whether the given Node is valid against the given Schema.

    • validateAndPrintDoc

      public static void validateAndPrintDoc(Node node, Schema schema) throws XMLFormatException, IOException
      Checks, if a node uses a valid schema. If not the invalid XML will be written to System.out.
      Parameters:
      node - The node, that wants to be checked.
      schema - The Schema, the node has to use, to be valid.
      Throws:
      XMLFormatException - when the validation fails.
      IOException - when conversion to string representation fails.

    • validateDocument

      public static void validateDocument(Node node, Schema schema) throws XMLFormatException
      Checks, if a node uses a valid schema.
      Parameters:
      node - The node, that wants to be checked.
      schema - The Schema, the node has to use, to be valid.
      Throws:
      XMLFormatException - when the validation fails

    • validateStream

      public static void validateStream(InputStream is, Schema schema) throws XMLFormatException
      Checks, if a node uses a valid schema.
      Parameters:
      is - The input stream containing the XML data.
      schema - The Schema, the node has to use, to be valid.
      Throws:
      XMLFormatException - when the validation fails

    • replaceWithXMLEntities

      public static String replaceWithXMLEntities(String string)
      Replaces all occurrences of special characters that may not appear directly in XML (<, >, &, ' and ") with their corresponding XML entities.
      Parameters:
      string - the string to be converted
      Returns:
      the converted string

    • getDocumentFromString

      public static Document getDocumentFromString(String string, Schema schema) throws XMLFormatException, IOException
      Parse a string and converts it to a Document using the DEFAULT_ENCODING.
      Parameters:
      string - The string, that shall be converted.
      schema - The XML Schema to validate the document against or null to omit validation.
      Returns:
      A DOM document for the XML in the given string.
      Throws:
      XMLFormatException - if the document is not well-formed
      IOException - if error occurs while reading from the file

    • getDocumentFromFile

      public static Document getDocumentFromFile(File file, Schema schema, ErrorHandler errorHandler) throws XMLFormatException, FileNotFoundException, IOException
      Read a Document from a stream.
      Parameters:
      file -
      schema - The XML Schema to validate the document against or null to omit validation
      errorHandler - The optional error handler that will be used for the document builder
      Returns:
      A DOM document
      Throws:
      XMLFormatException - if the document is not well-formed or doesn't conform to the given Schema
      FileNotFoundException - if the file does not exist or can't be opened
      IOException - if error occurs while reading from the file

    • getDocumentFromStream

      public static Document getDocumentFromStream(InputStream inputStream) throws XMLFormatException, IOException
      Parse a Stream and converts it to a Document
      Parameters:
      inputStream - The stream that shall be converted
      Returns:
      A DOM document for the given input stream.
      Throws:
      XMLFormatException - if the document is not well-formed
      IOException - if error occurs while reading from the stream

    • getDocumentFromSource

      public static Document getDocumentFromSource(InputSource source) throws XMLFormatException, IOException
      Reads a document from the designated source; namespaces will be used, no validation will take place.
      Parameters:
      source - The source providing the XML.
      Returns:
      A DOM document read from the designated source.
      Throws:
      XMLFormatException - If parsing the XML failed, an XMLFormatException will be thrown.
      IOException - If there are problems reading from the designated source, an IOException will be thrown.

    • getDocumentFromStream

      public static Document getDocumentFromStream(InputStream inputStream, Schema schema, ErrorHandler errorHandler, boolean nsAware) throws XMLFormatException, IOException
      Reads a document from the designated stream. Optionally, the document will be validated against the designated schema and namespaces may be used.
      Parameters:
      inputStream - The input stream providing the XML.
      schema - The XML Schema to validate the document against or null to omit validation.
      nsAware - Whether the input stream should be parsed namespace aware.
      errorHandler - The optional error handler that will be used for the document builder.
      Returns:
      A DOM document read from the designated source.
      Throws:
      XMLFormatException - If parsing or validating the XML failed, an XMLFormatException will be thrown.
      IOException - If there are problems reading from the designated source, an IOException will be thrown.

    • getDocumentFromSource

      public static Document getDocumentFromSource(InputSource source, Schema schema, ErrorHandler errorHandler, boolean nsAware) throws XMLFormatException, IOException
      Reads a document from the designated source. Optionally, the document will be validated against the designated schema and namespaces may be used.
      Parameters:
      source - The source providing the XML.
      schema - The XML Schema to validate the document against or null to omit validation.
      nsAware - Whether the input stream should be parsed namespace aware.
      errorHandler - The optional error handler that will be used for the document builder.
      Returns:
      A DOM document read from the designated source.
      Throws:
      XMLFormatException - If parsing or validating the XML failed, an XMLFormatException will be thrown.
      IOException - If there are problems reading from the designated source, an IOException will be thrown.

    • createDocument

      public static Document createDocument()
      Initialises the document object which will be used for constructing elements.
      Returns:
      The new document

    • getXMLStringForDocument

      public static String getXMLStringForDocument(Node node) throws IOException
      Returns the XML code of a given node as string.
      Parameters:
      node - The node to be transformed
      Returns:
      The XML code of the given node as string.
      Throws:
      IOException - Thrown if an unrecoverable error occurs during the course of the transformation

    • getXMLStringForDocument

      public static String getXMLStringForDocument(Node node, boolean intend) throws IOException
      Returns the XML code of a given node as string.
      Parameters:
      node - The node to be transformed
      intend - Whether to intend child nodes and text content. Use with care! Text content may contain whitespace and linebreaks afterwards!
      Returns:
      The XML code of the given node as string.
      Throws:
      IOException - Thrown if an unrecoverable error occurs during the course of the transformation

    • getXMLStringForInputStream

      @Deprecated(since="15.0.0", forRemoval=true) public static String getXMLStringForInputStream(InputStream is) throws IOException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use StreamTools.readUtf8String(InputStream) instead.
      Returns the XML code of a given input stream as string using the DEFAULT_ENCODING.
      Parameters:
      is - The input stream which should be transformed. This method will close the stream after reading.
      Returns:
      The xml code of the given input stream as string.
      Throws:
      IOException - Thrown if an unrecoverable error occurs during the course of the transformation

    • getInputStreamForDocument

      @Deprecated(since="15.0.0", forRemoval=true) public static AttributedInputStream getInputStreamForDocument(Node node) throws IOException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use getStreamForDocument(Node) instead.
      Returns an input stream containing the XML code of the given node.
      Parameters:
      node - The node to be transformed
      Returns:
      The input stream of the XML code of the node. The caller is responsible for closing.
      Throws:
      IOException - Thrown if an unrecoverable error occurs during the course of the transformation.

    • getInputStreamForDocument

      @Deprecated(since="15.0.0", forRemoval=true) public static AttributedInputStream getInputStreamForDocument(Node node, boolean intend) throws IOException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use getStreamForDocument(Node, boolean) instead.
      Returns an input stream containing the XML code of the given node.
      Parameters:
      node - The node to be transformed
      intend - Whether to intend child nodes and text content. Use with care! Text content may contain whitespace and linebreaks afterwards!
      Returns:
      The input stream of the XML code of the node. The caller is responsible for closing.
      Throws:
      IOException - Thrown if an unrecoverable error occurs during the course of the transformation.

    • getByteArrayForDocument

      public static byte[] getByteArrayForDocument(Node node) throws IOException
      Returns a byte array containing the XML code for the given node.
      Parameters:
      node - The node to be transformed.
      Returns:
      The byte array of the node.
      Throws:
      IOException

    • getByteArrayForDocument

      public static byte[] getByteArrayForDocument(Node node, boolean intend) throws IOException
      Returns a byte array containing the XML code for the given node.
      Parameters:
      node - The node to be transformed.
      intend - Whether to intend child nodes and text content. Use with care! Text content may contain whitespace and linebreaks afterwards!
      Returns:
      The byte array of the node.
      Throws:
      IOException

    • getOutputStreamForDocument

      @Deprecated(since="15.0.0", forRemoval=true) public static ByteArrayOutputStream getOutputStreamForDocument(Node node) throws IOException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use getStreamForDocument(Node) instead.
      Returns an output stream containing the XML code of the given node.
      Parameters:
      node - The node to be transformed.
      Returns:
      The output stream of the XML code of the node. The caller is responsible for closing.
      Throws:
      IOException - Thrown if an unrecoverable error occurs during the course of the transformation.

    • getOutputStreamForDocument

      @Deprecated(since="15.0.0", forRemoval=true) public static ByteArrayOutputStream getOutputStreamForDocument(Node node, boolean intend) throws IOException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use getStreamForDocument(Node, boolean) instead.
      Returns an output stream containing the XML code of the given node.
      Parameters:
      node - The node to be transformed.
      intend - Whether to intend child nodes and text content. Use with care! Text content may contain whitespace and linebreaks afterwards!
      Returns:
      The output stream of the XML code of the node. The caller is responsible for closing.
      Throws:
      IOException - Thrown if an unrecoverable error occurs during the course of the transformation.

    • getOutputStreamForDocument

      @Deprecated(since="15.0.0", forRemoval=true) public static ByteArrayOutputStream getOutputStreamForDocument(Node node, Source xslt) throws IOException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use getStreamForDocument(Node, Source) instead.
      Returns an output stream containing the XML code of the given node.
      Parameters:
      node - The node to be transformed.
      xslt - The XSLT style sheet that should be used for the transformer.
      Returns:
      The output stream of the XML code of the node. The caller is responsible for closing.
      Throws:
      IOException - Thrown if an unrecoverable error occurs during the course of the transformation.

    • getOutputStreamForDocument

      @Deprecated(since="15.0.0", forRemoval=true) public static ByteArrayOutputStream getOutputStreamForDocument(Node node, Source xslt, boolean intend) throws IOException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use getStreamForDocument(Node, Source, boolean) instead.
      Returns an output stream containing the XML code of the given node using the DEFAULT_ENCODING.
      Parameters:
      node - The node to be transformed.
      xslt - The XSLT style sheet that should be used for the transformer.
      intend - Whether to intend child nodes and text content. Use with care! Text content may contain whitespace and linebreaks afterwards!
      Returns:
      The output stream of the XML code of the node. The caller is responsible for closing.
      Throws:
      IOException - Thrown if an unrecoverable error occurs during the course of the transformation.

    • getStreamForDocument

      public static AttributedInputStream getStreamForDocument(Node node) throws IOException
      Gets an input stream containing the XML code of the given node.
      Parameters:
      node - The node to be transformed.
      Returns:
      The output stream of the XML code of the node. The caller is responsible for closing.
      Throws:
      IOException - Thrown if an unrecoverable error occurs during the course of the transformation.

    • getStreamForDocument

      public static AttributedInputStream getStreamForDocument(Node node, boolean intend) throws IOException
      Gets an input stream containing the XML code of the given node.
      Parameters:
      node - The node to be transformed.
      intend - Whether to intend child nodes and text content. Use with care! Text content may contain whitespace and linebreaks afterwards!
      Returns:
      The output stream of the XML code of the node. The caller is responsible for closing.
      Throws:
      IOException - Thrown if an unrecoverable error occurs during the course of the transformation.

    • getStreamForDocument

      public static AttributedInputStream getStreamForDocument(Node node, Source xslt) throws IOException
      Gets an input stream containing the XML code of the given node.
      Parameters:
      node - The node to be transformed.
      xslt - The XSLT style sheet that should be used for the transformer.
      Returns:
      The output stream of the XML code of the node. The caller is responsible for closing.
      Throws:
      IOException - Thrown if an unrecoverable error occurs during the course of the transformation.

    • getStreamForDocument

      public static AttributedInputStream getStreamForDocument(Node node, Source xslt, boolean intend) throws IOException
      Gets an input stream containing the XML code of the given node using the DEFAULT_ENCODING.
      Parameters:
      node - The node to be transformed.
      xslt - The XSLT style sheet that should be used for the transformer.
      intend - Whether to intend child nodes and text content. Use with care! Text content may contain whitespace and linebreaks afterwards!
      Returns:
      The output stream of the XML code of the node. The caller is responsible for closing.
      Throws:
      IOException - Thrown if an unrecoverable error occurs during the course of the transformation.

    • writeDocumentToStream

      public static void writeDocumentToStream(Node node, OutputStream out) throws IOException
      Writes the node to the given output stream.
      Parameters:
      node -
      out -
      Throws:
      IOException

    • writeDocumentToStream

      public static void writeDocumentToStream(Node node, OutputStream out, boolean intend) throws IOException
      Writes the node to the given output stream using the DEFAULT_ENCODING.
      Parameters:
      node -
      out - The stream to which to write the designated node to. Set the encoding appropriately!
      intend - Whether to intend child nodes and text content. Use with care! Text content may contain whitespace and linebreaks afterwards!
      Throws:
      IOException

    • writeDocumentToStream

      public static void writeDocumentToStream(Node node, OutputStream out, boolean intend, String encoding) throws IOException
      Writes the node to the designated output stream with the designated encoding. Please set this encoding in the stream appropriately.
      Parameters:
      node -
      out - The stream to which to write the designated node to. Set the enccoding appropriately!
      intend - Whether to intend child nodes and text content. Use with care! Text content may contain whitespace and linebreaks afterwards!
      encoding - The encoding used for writing the designated node. This has to conform to the encoding of the designated stream and will be set in the XML-header.
      Throws:
      IOException

    • writeDocumentToStream

      public static OutputStream writeDocumentToStream(Node node, OutputStream os, Source xslt) throws IOException
      Transforms and writes the XML code of the designated node to the designated output stream using the DEFAULT_ENCODING.
      Parameters:
      node - The node to be transformed.
      os - The output stream to write the transformed XML code to. The caller is responsible for closing.
      xslt - The XSLT style sheet that should be used for the transformer.
      Returns:
      The designated output stream.
      Throws:
      IOException - Thrown if an unrecoverable error occurs during the course of the transformation.

    • writeDocumentToStream

      public static OutputStream writeDocumentToStream(Node node, OutputStream os, Source xslt, boolean intend) throws IOException
      Transforms and writes the XML code of the designated node to the designated output stream using the DEFAULT_ENCODING.
      Parameters:
      node - The node to be transformed.
      os - The output stream to write the transformed XML code to. The caller is responsible for closing.
      xslt - The XSLT style sheet that should be used for the transformer.
      intend - Whether to intend child nodes and text content. Use with care! Text content may contain whitespace and linebreaks afterwards!
      Returns:
      The designated output stream.
      Throws:
      IOException - Thrown if an unrecoverable error occurs during the course of the transformation.

    • writeDocumentToFile

      public static void writeDocumentToFile(Node node, File file, Schema schema) throws IOException, XMLFormatException
      Exports a DOM node to a file, validates the node before the export, if a schema type is provided.
      Parameters:
      node - The DOM node to be exported.
      file - The target file.
      schema - The schema for validation, or null for storing w/o validation.
      Throws:
      IOException
      XMLFormatException - Thrown, if the validation fails.

    • writeDocumentToFile

      public static void writeDocumentToFile(Node node, File file, Schema schema, boolean intend) throws IOException, XMLFormatException
      Exports a DOM node to a file using the DEFAULT_ENCODING, validates the node before the export, if a schema type is provided.
      Parameters:
      node - The DOM node to be exported.
      file - The target file.
      schema - The schema for validation, or null for storing w/o validation.
      intend - Whether to intend child nodes and text content. Use with care! Text content may contain whitespace and linebreaks afterwards!
      Throws:
      IOException
      XMLFormatException - Thrown, if the validation fails.

    • writeDocumentToFile

      public static void writeDocumentToFile(Node node, File file, Schema schema, boolean intend, String encoding) throws IOException, XMLFormatException
      Exports a DOM node to a file using the designated encoding. Before exporting the node will be validated if a schema type is provided.
      Parameters:
      node - The DOM node to be exported.
      file - The target file.
      schema - The schema for validation, or null for storing w/o validation.
      intend - Whether to intend child nodes and text content. Use with care! Text content may contain whitespace and linebreaks afterwards!
      encoding - The encoding used for writing the designated node. This will be used for the output stream as well as in the XML-header.
      Throws:
      IOException
      XMLFormatException - Thrown, if the validation fails.

    • writeDocumentToWriter

      public static void writeDocumentToWriter(Node node, Writer out) throws IOException
      Writes the node to the designated writer with no indentation and the DEFAULT_ENCODING.
      Parameters:
      node - The DOM node which to write to the designated writer.
      out - The writer to which to write the XML for the designated node.
      Throws:
      IOException

    • writeDocumentToWriter

      public static void writeDocumentToWriter(Node node, Writer out, boolean intend) throws IOException
      Writes the node to the designated writer with DEFAULT_ENCODING.
      Parameters:
      node - The DOM node which to write to the designated writer.
      out - The writer to which to write the XML for the designated node.
      intend - Whether to intend child nodes and text content. Use with care! Text content may contain whitespace and linebreaks afterwards!
      Throws:
      IOException

    • writeDocumentToWriter

      public static void writeDocumentToWriter(Node node, Writer out, boolean intend, String encoding) throws IOException
      Writes the node to the designated writer with the designated encoding. Please set this encoding in the stream appropriately.
      Parameters:
      node - The DOM node which to write to the designated writer.
      out - The stream to which to write the designated node to. Set the encoding appropriately!
      intend - Whether to intend child nodes and text content. Use with care! Text content may contain whitespace and linebreaks afterwards!
      encoding - The encoding used for writing the designated node. This has to conform to the encoding of the designated stream and will be set in the XML-header.
      Throws:
      IOException

    • getParsedID

      public static int getParsedID(Node node)
      Strips off the leading character and parses the integer value.
      Parameters:
      node - The node whose text content will be parsed.
      Returns:
      The integer value of the ID.

    • getParsedID

      public static int getParsedID(String nodeValue)
      Strips off the leading character and parses the integer value.
      Parameters:
      nodeValue - The input string.
      Returns:
      The integer value of the ID.

    • hasTagName

      public static boolean hasTagName(Node n, String... names)
      This method checks, whether the (local) tag name of the given element matches one of the designated names.
      Parameters:
      n - The node, whose tag name should be checked.
      names - The names, against the tag name should be checked.
      Returns:
      Whether the tag name of the given element equals the given name.

    • hasTagName

      public static boolean hasTagName(Element e, String... names)
      This method checks, whether the (local) tag name of the given element matches one of the designated names.
      Parameters:
      e - The element, whose tag name should be checked.
      names - The names, against the tag name should be checked.
      Returns:
      Whether the tag name of the given element equals the given name.

    • getTagName

      protected static String getTagName(Element e)
      This method returns the tag name of the given element. In case the tag name is prefixed with a name space, the local name will be returned.
      Parameters:
      e - The element, whose tag name should be returned.
      Returns:
      The tag name of the given element.

    • nextElement

      public static Element nextElement(Node node, String name)
      Find the next element that actually contains data, with the given name.
      NOTE: If the current node is an element that matches the name it will be returned!
      Parameters:
      node - The current node.
      name - The name of the next node.
      Returns:
      The next node of type ELEMENT_NODE with the given name.

    • nextElement

      public static Element nextElement(Node node)
      Find the next element that actually contains data.
      Parameters:
      node - The current node.
      Returns:
      The next node of type ELEMENT_NODE.

    • getElement

      public static Element getElement(Node node)
      Finds an DOM Element for a given Node. If the given DOM Node is an Element, it is returned as Element. Else its next sibling is returned recursively as element.
      Parameters:
      node - the DOM object
      Returns:
      A DOM Element.