Package com.redwood.scheduler.api.model.interfaces

Interface TableParameterRuntime

  • All Superinterfaces:
    TableParameter
    public interface TableParameterRuntime
extends TableParameter
    Runtime interface to Table parameters from RedwoodScript.

    Table parameters consist of two parts:

    • The reference: stored in the JobParameter object's InValueString and/or OutValueString attributes, depending on direction. This is stored in the form <type:source>, where type is from the TableParameterType reference, and source depends on type, as specified in JobParameter.setOutValueTableParameter(String).
    • The content: in Redwood Table XML (RTX) format.

    While the content is typically stored in a JobFile, there are two other cases to consider:

    • TableParameterType.Inline where the content is stored directly in the JobParameter object's InValueString and/or OutValueString. This is supported for all parameter directions.
    • TableParameterType.Table where the content is stored in a Table object. This is only supported for In parameters.

    Due to the nature of table parameters, and the normal rules around parameter values, not all methods are valid in all contexts:

    • Writing output values of parameters is only allowed if they are for the currently running job.
    • Reading output values of parameters is allowed in general, with special exceptions for parameters of the currently running job.

    It is possible to create conflicts in values or content by calling certain sequences of methods from this interface and other interfaces, especially when combined with creating JobFile objects externally. Users should take care to ensure that there is only one way of writing to a JobFile. It is recommended that this interface be used exclusively when dealing with table parameters. Creating JobFile objects and String values directly is likely to lead to bugs or incompatibilities with future features.

    When using InOut parameters, different references should be used, except in the case where the Out value is exactly the same as the In value, where using the same value is required to reference the same content.

    For RedwoodScript jobs, there is also a distinction between the internal value and the database value of a parameter. The internal value is the value available via the variable named after the parameter, in the current job. The database value is the value visible from a SchedulerSession (from the database). When the job finishes, the internal value will be written to the database (overwriting updates made by any other means). This is the case for all parameters.

    When calling methods that set the OutValueString of an attribute (ie. most of the getRTXWriter*() methods, and all the setOutValue*() methods) these changes will be reflected in the internal value immediately, and will be visible externally when the job finishes

    • Method Detail

      • getRTXWriter

        RTXWriter getRTXWriter()
                throws IOException,
                       RTXException,
                       com.redwood.scheduler.api.exception.SchedulerAPIPersistenceException
        Get an RTXWriter to write the Out content of an Out or InOut parameter. This method is the equivalent of:
        1. creating a new JobFile from jcsJob,
        2. passing it to getRTXWriter(JobFile),
        3. persisting jcsSession, and,
        4. refreshing jcsJob.
        Returns:
        an RTXWriter for the content.
        Throws:
        RTXParameterDirectionRuntimeException - if the parameter direction is not Out or InOut.
        com.redwood.scheduler.api.exception.SchedulerAPIPersistenceException - if the session cannot be persisted.
        IOException - if there is an I/O error opening the content.
        RTXException - if there is an RTX I/O error opening the content.

      • getRTXWriterToStandardOutput

        RTXWriter getRTXWriterToStandardOutput()
                                throws IOException,
                                       RTXException,
                                       com.redwood.scheduler.api.exception.SchedulerAPIPersistenceException
        Get an RTXWriter to write the Out content of an Out or InOut parameter to stdout.rtx, and set the reference to it. This method is the equivalent of:
        1. Getting the JobFile with order JobFile.STANDARD_OUTPUT_ORDER from jcsJob,
        2. Setting its Name attribute to stdout.rtx,
        3. Setting its Format to GLOBAL.System_RTX,
        4. Passing it to getRTXWriter(JobFile),
        5. Persisting jcsSession, and,
        6. Refreshing jcsJob.
        Returns:
        an RTXWriter for the content.
        Throws:
        RTXParameterDirectionRuntimeException - if the parameter direction is not Out or InOut.
        com.redwood.scheduler.api.exception.SchedulerAPIPersistenceException - if the session cannot be persisted.
        IOException - if there is an I/O error opening the content.
        RTXException - if there is an RTX I/O error opening the content.

      • getRTXWriter

        RTXWriter getRTXWriter​(JobFile jobFile)
                throws IOException,
                       RTXException
        Get an RTXWriter to write the Out content of an Out or InOut parameter to the specified (potentially partially populated, but not necessarily persisted) JobFile, and set the reference to it. The JobFile can be from any session. The following JobFile attributes will be set if not already set:
        • Name will be set to <JobParameter.Name>.rtx
        • FileOrder will be set to the next available value starting at JobFile.CUSTOMER_ORDER_START.
        • Format will be set to GLOBAL.System_RTX
        • Type will be set to @{link JobFileType#Output}
        FileName will be set by always calling JobFile.setFileNameAutomatic(). The session will not be persisted, the caller must persist the session for changes to be visible.
        Parameters:
        jobFile - the job file to use.
        Returns:
        an RTXWriter for the content.
        Throws:
        RTXParameterDirectionRuntimeException - if the parameter direction is not Out or InOut.
        IOException - if there is an I/O error opening the content.
        RTXException - if there is an RTX I/O error opening the content.

      • getRTXWriterInline

        RTXWriter getRTXWriterInline()
                      throws RTXException
        Get an RTXWriter to write the Out content of an Out or InOut parameter, using the Inline type, setting the reference implicitly when the writer is closed. This should only be used for relatively small content (< 10Kb).
        Returns:
        an RTXWriter for the content.
        Throws:
        RTXParameterDirectionRuntimeException - if the parameter direction is not Out or InOut.
        RTXException - if there is an I/O error opening the content.

      • setOutValue

        void setOutValue​(Object o)
        Manually override the Out reference of an Out or InOut parameter. The recommended way to set this data is by using one of the getRTXWriter*() methods, like getRTXWriter() or getRTXWriter(JobFile). This method is intended for use by the runtime framework, it is not recommended for customer use.
        Parameters:
        o - the reference to use as a source.
        Throws:
        RTXParameterDirectionRuntimeException - if the parameter direction is not Out or InOut.

      • getErrorNameEN

        String getErrorNameEN()
        Get information to identify this parameter in error messages. This is intended for error messages only, the value may change between versions and must not be parsed.
        Specified by:
        getErrorNameEN in interface TableParameter
        Returns:
        information identifying this parameter for use in error messages.