Package de.aristaflow.adept2.util.xml

Class XMLHelperTools

  • public class XMLHelperTools
extends Object
    Contains important function for both, XML import and export.

    • Constructor Detail

      • XMLHelperTools

        public XMLHelperTools()

    • Method Detail

      • 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.