Package io.toro.martini

Class XmlMethods

  • public final class XmlMethods
extends Object

    Contains one-liners for reading and writing to XML.

    • Constructor Detail

      • XmlMethods

        XmlMethods()

    • Method Detail

      • modelPropertyToXmlString

        @GloopParameter(name="xmlString")
public static String modelPropertyToXmlString​(GloopObject modelProperty,
                                              @GloopParameter(defaultValue="true")
                                              boolean insertHeader,
                                              Map declaredNamespaces)

        Marshals a data model property to an XML string.

        Parameters:
        modelProperty - the data model property to marshal
        insertHeader - flag stating whether to include the <xml version = "1.0">; header
        declaredNamespaces - map of pre-declared namespaces already declared (if any); the key should contain the namespace URIs, and the values should contain their prefixes. A data model can be mapped directly to this parameter, it will be concerted to a map
        Returns:
        XML string representation of the data model property
        Since:
        2.8.0

      • gloopObjectToXmlString

        @Deprecated(since="2.8.0")
@GloopParameter(name="gloopXml")
public static String gloopObjectToXmlString​(GloopObject gloopObject,
                                            @GloopParameter(defaultValue="true")
                                            boolean insertHeader,
                                            Map declaredNamespaces)
        Deprecated.
        This method uses internal naming conventions. Use modelPropertyToXmlString(GloopObject, boolean, Map) instead.

        Marshals a Gloop object to an XML string.

        Parameters:
        gloopObject - the object to marshall
        insertHeader - flag stating whether to include the <xml version = "1.0">; header
        declaredNamespaces - map of pre-declared namespaces already declared (if any); the key should contain the namespace URIs, and the values should contain their prefixes
        Returns:
        XML string representation of the object
        Since:
        1.0

      • inputStreamToModelProperty

        @GloopParameter(name="modelProperty")
public static GloopObject inputStreamToModelProperty​(@GloopParameter(allowNull=false)
                                                     InputStream xmlInputStream)
                                              throws SAXException

        Unmarshal a reader containing XML data to a model property.

        Reads XML from a raw byte stream and unmarshals it into a data model. Use this instead of the string variant when the data is already available as a byte stream — for example, directly from an HTTP response body or a file — to avoid loading the entire payload into memory as a String. Prefer the string variant only when the XML is already held in a string variable.

        Parameters:
        xmlInputStream - the stream containing the XML data to unmarshal
        Returns:
        a model property equivalent of the provided XML data
        Throws:
        SAXException
        Since:
        2.8.0

      • readerToModelProperty

        @GloopParameter(name="modelProperty")
public static GloopObject readerToModelProperty​(@GloopParameter(allowNull=false)
                                                Reader xmlReader)
                                         throws SAXException

        Unmarshal a reader containing XML data to a model property.

        Reads XML from a character stream and unmarshals it into a data model property. Use this instead of the string variant when another step in your flow returns a Reader directly — for example, from a file-reading step — to avoid converting the data to a String unnecessarily. Prefer the string variant when the XML is already held in a string variable.

        Parameters:
        xmlReader - the reader containing the XML data to unmarshal
        Returns:
        a model property equivalent of the provided XML data
        Throws:
        SAXException
        Since:
        2.8.0

      • readerToGloopObject

        @Deprecated(since="2.8.0")
public static GloopObject readerToGloopObject​(Reader xmlString)
                                       throws SAXException
        Deprecated.
        This method uses internal naming conventions. Use readerToModelProperty(Reader) instead.

        Unmarshal an XML string within a reader to a Gloop object.

        Parameters:
        xmlString - the reader containing the XML
        Returns:
        Gloop object representation of the XML string
        Throws:
        SAXException
        Since:
        1.0

      • writeXml

        public static void writeXml​(@GloopParameter(allowNull=false)
                            Writer writer,
                            @GloopParameter(allowNull=false)
                            GloopObject gloopObject,
                            @GloopParameter(defaultValue="false")
                            boolean insertHeader,
                            @GloopParameter(defaultValue="true")
                            boolean includeNamespaces,
                            Map declaredNamespaces,
                            @GloopParameter(defaultValue="false")
                            boolean includeNulls)

        Marshals a data model property and writes the resulting XML directly to the given writer. Use this instead of the string variant when you are writing to a destination that already provides a `Writer` — for example, an HTTP response or a file — to avoid materializing the full payload as a String in memory first. Prefer the string variant only when the result needs to be stored in a string variable.

        Parameters:
        writer - writer to write the XML to
        gloopObject - data model property to marshal
        insertHeader - flag stating whether to include the <xml version = "1.0"> header
        includeNamespaces - flag stating whether to include namespace declarations
        declaredNamespaces - map of pre-declared namespaces already declared (if any); the key should contain the namespace URIs, and the values should contain their prefixes
        includeNulls - flag stating whether to include empty elements for properties that have a null value
        Since:
        1.0

      • openXmlFileInputCursor

        @GloopObjectParameter("cursor{\n  cursor[]{\n    nodeName\n    cursorRecord:object\n  }\n}")
public static GloopCursor openXmlFileInputCursor​(@GloopParameter(allowNull=false)
                                                 String filePath,
                                                 @GloopParameter(defaultValue="UTF-8")
                                                 String encoding,
                                                 @GloopParameter(allowNull=false)
                                                 List<String> xmlNodeNames,
                                                 GloopExecutionContext context)
                                          throws IOException

        Opens a cursor for streaming through a large XML file record by record, without loading the entire file into memory. Use this instead of the string-based unmarshal functions when the file is too large to hold in memory at once.

        Use the xmlNodeNames argument to specify which nodes you want to extract from the XML file.

        This one-liner will return a data model cursor. Every record in the cursor will point to an XML element that has the same name as any of the names specified via xmlNodeNames.

        The cursor can be used in as input array of a repeat node of a workflow or an iterate step of a service. The cursor can only be read once and is automatically closed at the end of the execution.

        Parameters:
        filePath - the path of the file containing the XML data
        encoding - the encoding used by the XML file; default value is UTF-8
        xmlNodeNames - the names of the XML elements to seek to whilst parsing the data
        context - the Gloop execution context (automatically mapped by Gloop)
        Returns:
        a cursor that can be used to iterate over all the records in the provided XML data, whose names match the names provided in xmlNodeNames
        Throws:
        IOException

      • openXmlStreamInputCursor

        @GloopObjectParameter("cursor{\n  cursor[]{\n    nodeName\n    cursorRecord:object\n  }\n}")
public static GloopCursor openXmlStreamInputCursor​(@GloopParameter(allowNull=false)
                                                   InputStream inputStream,
                                                   @GloopParameter(defaultValue="UTF-8")
                                                   String encoding,
                                                   @GloopParameter(allowNull=false)
                                                   List<String> xmlNodeNames,
                                                   GloopExecutionContext context)
                                            throws IOException

        Opens a cursor for streaming through a large XML input stream record by record, without loading the entire XML data into memory. Use this instead of the string-based unmarshal functions when the file is too large to hold in memory at once.

        Use the xmlNodeNames argument to specify which nodes you want to extract from the XML file.

        This one-liner will return a data model cursor. Every record in the cursor will point to an XML element that has the same name as any of the names specified via xmlNodeNames.

        The cursor can be used in as input array of a repeat node of a workflow or an iterate step of a service. The cursor can only be read once and is automatically closed at the end of the execution.

        Parameters:
        inputStream - the input stream containing the XML data to read
        encoding - the encoding used by the XML input stream; default value is UTF-8
        xmlNodeNames - the names of the XML elements to seek to whilst parsing the data
        context - the Gloop execution context (automatically mapped by Gloop)
        Returns:
        a cursor that can be used to iterate over all the records in the provided XML data, whose names match the names provided in xmlNodeNames
        Throws:
        IOException

      • openXmlOutputCursor

        @GloopObjectParameter("output{\n    cursorXmlOutput{\n        writer:object:printer used to write the xml out to::::java.io.Writer\n        outputXmlCursor[]*{\n        }\n    }\n}")
public static GloopModel openXmlOutputCursor​(String elementName,
                                             @GloopParameter(defaultValue="true")
                                             boolean insertHeader,
                                             Map declaredNamespaces,
                                             @GloopParameter(defaultValue="true")
                                             boolean includeNamespaces,
                                             @GloopParameter(allowNull=false,defaultValue="    ")
                                             String indent,
                                             @GloopParameter(defaultValue="true")
                                             boolean closeDestination,
                                             Object destination,
                                             GloopExecutionContext context)
                                      throws IOException

        Opens a cursor for streaming XML output record by record, without accumulating the full document in memory. Use this instead of the other functions when writing a large number of records — for example, serializing a database query result — where building the entire XML string in memory first would be impractical.

        The cursor can be used in as output array of a repeat node of a workflow or an iterate step of a service. The cursor is automatically closed at the end of the execution.

        Parameters:
        elementName - the name given to the XML element that this cursor will write
        insertHeader - whether to print the XML header <xml version = "1.0">
        declaredNamespaces - map of declared namespaces for this XML
        includeNamespaces - whether to include the namespaces in the XML elements
        indent - indent to use if pretty printing; default is 4 spaces
        closeDestination - set to true if the cursor will close the underlying destination after printing closing text
        destination - where to write the data to; must be a StringBuffer, Writer, OutputStream, Path, or File
        context - the Gloop execution context (automatically mapped by Gloop)
        Returns:
        an output cursor that can be used to append data models to
        Throws:
        IOException
        Since:
        1.0

      • setCursorElementName

        public static void setCursorElementName​(GloopXmlOutputCursor gloopCursor,
                                        String elementName)
        Sets the element name of an XML output cursor.
        Parameters:
        gloopCursor - XML output cursor
        elementName - element name
        Since:
        1.0