Package io.toro.martini

Class YamlMethods

  • public final class YamlMethods
extends Object
    Contains one-liners for reading and writing to YAML.

    • Constructor Detail

      • YamlMethods

        YamlMethods()

    • Method Detail

      • modelPropertyToYamlString

        @GloopParameter(name="yamlString")
public static String modelPropertyToYamlString​(@GloopParameter(allowNull=false)
                                               GloopObject modelProperty,
                                               @GloopParameter(defaultValue="false")
                                               boolean includeRoot,
                                               @GloopParameter(defaultValue="false")
                                               boolean includeNulls)

        Marshals a data model property to a YAML string.

        Parameters:
        modelProperty - the data model property to marshal
        includeRoot - if modelProperty is a model, this flag determines whether to include the model's name in the root node of the YAML document
        includeNulls - if true, null properties will be marshaled
        Returns:
        a YAML representation of the provided data model property
        Since:
        2.8

      • yamlStringToModelProperty

        @GloopParameter(name="modelProperty")
public static GloopObject yamlStringToModelProperty​(@GloopParameter(allowNull=false)
                                                    String yamlString)

        Unmarshal a YAML string into a data model property.

        Parameters:
        yamlString - the YAML string to unmarshal
        Returns:
        a data model property equivalent of the provided YAML string
        Since:
        2.8.0

      • yamlStringToGloopObject

        @Deprecated(since="2.8.0")
public static GloopObject yamlStringToGloopObject​(String yamlString)
        Deprecated.
        This method uses internal naming conventions. Use yamlStringToModelProperty(String) instead.

        Unmarshal a YAML string to a Gloop object.

        Parameters:
        yamlString - YAML to convert
        Returns:
        Gloop object representation of the YAML string
        Since:
        1.0

      • inputStreamToModelProperty

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

        Unmarshal a reader containing YAML data to a model property.

        Reads YAML 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 first. Prefer the string variant only when the YAML is already held in a string variable.

        Parameters:
        yamlInputStream - the stream containing the YAML data to unmarshal
        Returns:
        a model property equivalent of the provided YAML data
        Since:
        2.8.0

      • inputStreamToGloopObject

        @Deprecated(since="2.8.0")
public static GloopObject inputStreamToGloopObject​(InputStream yamlStream)
        Deprecated.
        This method uses internal naming conventions. Use inputStreamToModelProperty(InputStream) instead.

        Unmarshal a YAML stream to a Gloop object.

        Parameters:
        yamlStream - YAML to convert
        Returns:
        Gloop object representation of the YAML stream
        Since:
        1.0

      • readerToModelProperty

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

        Unmarshal a reader containing YAML data to a model property.

        Reads YAML 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 YAML is already held in a string variable.

        Parameters:
        yamlReader - the reader containing the YAML data to unmarshal
        Returns:
        a model property equivalent of the provided YAML data
        Since:
        2.8.0

      • readerToGloopObject

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

        Unmarshal a YAML string from a Reader to a Gloop object.

        Parameters:
        yamlString - reader containing the YAML to convert
        Returns:
        Gloop object representation of the YAML string
        Since:
        1.0

      • writeYaml

        public static void writeYaml​(@GloopParameter(allowNull=false)
                             Writer writer,
                             @GloopParameter(allowNull=false)
                             GloopObject gloopObject,
                             @GloopParameter(defaultValue="false")
                             boolean includeNulls)

        Marshals a data model property and writes the resulting YAML 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 - where the YAML string will be written to
        gloopObject - the data model property to marshal
        includeNulls - whether to include null properties
        Since:
        1.0

      • printYaml

        public static void printYaml​(@GloopParameter(allowNull=false)
                             IndentPrinter printer,
                             @GloopParameter(allowNull=false)
                             GloopObject gloopObject,
                             @GloopParameter(defaultValue="false")
                             boolean includeNulls)

        Marshals a data model property and writes the resulting YAML to the given printer. Use this instead of the string variant when another step in your flow already provides an `IndentPrinter` — for example, when assembling a larger formatted output document — to write directly into it without producing an intermediate string. Prefer the string variant only when the result needs to be stored in a string variable.

        Parameters:
        printer - where the YAML string will be written to
        gloopObject - the data model property to marshal
        includeNulls - whether to include null properties
        Since:
        1.0

      • openYamlFileInputCursor

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

        Opens a cursor for streaming through a large YAML 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 yamlNodeNames argument to specify which nodes you want to extract from the JSON file. Use $yamlRoot for root arrays.

        This one-liner will return a data model cursor. Every record in the cursor will point to a YAML object that has the same name as any of the properties specified via yamlNodeNames.

        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 YAML data
        encoding - the encoding used by the YAML file; default value is UTF-8
        yamlNodeNames - the names of the YAML objects 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 YAML data, whose names match the names provided in yamlNodeNames
        Throws:
        FileNotFoundException
        UnsupportedEncodingException
        Since:
        2.8.0

      • getInputCursorFromFile

        @Deprecated(since="2.8.0")
@GloopObjectParameter("gloopYamlCursor{\n  gloopYamlCursor[]{\n    nodeName\n    cursorRecord:object\n  }\n}")
public static GloopCursor getInputCursorFromFile​(String filename,
                                                 List<String> yamlNodeNames,
                                                 GloopExecutionContext context)
                                          throws FileNotFoundException
        Deprecated.
        This method uses outdated naming conventions and cannot specify encoding. Use openYamlFileInputCursor(String, String, List, GloopExecutionContext) instead.

        Return a Gloop input cursor for reading the entries of a large YAML file.

        Use the yamlNodeNames property to specify which nodes you want to extract from the YAML file. Use $yamlRoot for root arrays.

        Parameters:
        filename - the name of the large XML file to read
        yamlNodeNames - the element names the cursor should be seeking
        context - the Gloop execution context (automatically mapped by Gloop)
        Returns:
        an input cursor that can iterate over all elements found in the XML, where the element names are in the yamlNodeNames parameter
        Throws:
        FileNotFoundException - if the file does not exist, is a directory rather than a regular file, or for some other reason cannot be opened for reading
        Since:
        1.0

      • openYamlStreamInputCursor

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

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

        Use the yamlNodeNames argument to specify which nodes you want to extract from the YAML file. Use $yamlRoot for root arrays.

        This one-liner will return a data model cursor. Every record in the cursor will point to a YAML object that has the same name as any of the properties specified via yamlNodeNames.

        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 YAML data to read
        encoding - the encoding used by the YAML input stream; default value is UTF-8
        yamlNodeNames - the names of the YAML objects 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 YAML data, whose names match the names provided in yamlNodeNames
        Throws:
        UnsupportedEncodingException
        Since:
        2.8.0

      • getInputCursorFromInputStream

        @Deprecated(since="2.8.0")
@GloopObjectParameter("gloopYamlCursor{\n  gloopYamlCursor[]{\n    nodeName\n    cursorRecord:object\n  }\n}")
public static GloopCursor getInputCursorFromInputStream​(InputStream inputStream,
                                                        List<String> yamlNodeNames,
                                                        GloopExecutionContext context)
        Deprecated.
        This method uses outdated naming conventions and cannot specify encoding. Use openYamlStreamInputCursor(InputStream, String, List, GloopExecutionContext) instead.

        Return a Gloop input cursor for reading the entries of a large YAML stream.

        Use the yamlNodeNames property to specify which nodes you want to extract from the YAML stream. Use $yamlRoot for root arrays.

        Parameters:
        inputStream - input stream containing the YAML to read
        yamlNodeNames - the element names the cursor should be seeking
        context - the Gloop execution context (automatically mapped by Gloop)
        Returns:
        an input cursor that can iterate over all elements found in the XML, where the element names are in the yamlNodeNames parameter
        Since:
        1.0

      • openYamlOutputCursor

        @GloopObjectParameter("output{\nyamlCursorOutput{\nindentPrinter:object:printer used to write the yaml out to::::groovy.util.IndentPrinter\nyamlOutputCursor[]*{\n}\n}\n}")
public static GloopModel openYamlOutputCursor​(@GloopParameter(defaultValue="true")
                                              boolean printStartDocument,
                                              String name,
                                              @GloopParameter(allowNull=false,defaultValue="  ")
                                              String indent,
                                              @GloopParameter(defaultValue="true")
                                              boolean closeDestination,
                                              Object destination,
                                              GloopExecutionContext context)
                                       throws IOException

        Opens a cursor for streaming YAML 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 YAML 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:
        printStartDocument - set to true if the cursor will print a --- at the start of the document
        name - name to print before declaring the array; should be null if there is no name
        indent - indent to use if pretty printing; default is 2 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