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

Interface FileParameterRuntime

  • All Superinterfaces:
    FileParameter
    public interface FileParameterRuntime
extends FileParameter
    Runtime interface to File parameters from RedwoodScript.

    File 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 FileParameterType reference, and source depends on type, as specified in JobParameter.setOutValueFileParameter(String).
    • The content: a stream of bytes.

    While the content is typically stored in a JobFile, there is one other case to consider:

    Due to the nature of file 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 file 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 getOutput*() 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

      • getInputStream

        InputStream getInputStream()
                    throws IOException,
                           com.redwood.scheduler.api.exception.FileParameterSourceUnavailableException,
                           JobFileException
        Get an InputStream to read the In content of an In or InOut parameter.
        Returns:
        an InputStream for the content.
        Throws:
        com.redwood.scheduler.api.exception.FileParameterValueNotFoundRuntimeException - if the input cannot be found.
        IOException - if there is an I/O error opening the content.
        com.redwood.scheduler.api.exception.FileParameterSourceUnavailableException - if there is an I/O error opening the content.
        JobFileException - if the parameter references a job file that can't be opened (transient errors are automatically retried).

      • getOutputStream

        OutputStream getOutputStream()
                      throws IOException,
                             com.redwood.scheduler.api.exception.FileParameterSourceUnavailableException,
                             SchedulerAPIPersistenceException
        Get an OutputStream 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 getOutputStream(JobFile),
        3. persisting jcsSession, and,
        4. refreshing jcsJob.
        Returns:
        an OutputStream for the content.
        Throws:
        SchedulerAPIPersistenceException - if the session cannot be persisted.
        IOException - if there is an I/O error opening the content.
        com.redwood.scheduler.api.exception.FileParameterSourceUnavailableException - if there is an I/O error opening the content.

      • getOutputStreamToStandardOutput

        OutputStream getOutputStreamToStandardOutput()
                                      throws IOException,
                                             com.redwood.scheduler.api.exception.FileParameterSourceUnavailableException,
                                             SchedulerAPIPersistenceException
        Get an OutputStream to write the Out content of an Out or InOut parameter to stdout.<ext>, 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 Format to the default output format for the job definition,
        3. Setting its Name attribute to stdout.<extension from format>,
        4. Passing it to getOutputStream(JobFile),
        5. Persisting jcsSession, and,
        6. Refreshing jcsJob.
        Returns:
        an OutputStream for the content.
        Throws:
        SchedulerAPIPersistenceException - if the session cannot be persisted.
        IOException - if there is an I/O error opening the content.
        com.redwood.scheduler.api.exception.FileParameterSourceUnavailableException - if there is an I/O error opening the content.

      • getOutputStream

        OutputStream getOutputStream​(JobFile jobFile)
                      throws IOException,
                             com.redwood.scheduler.api.exception.FileParameterSourceUnavailableException
        Get an OutputStream 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. This is the same as calling getOutputStream(JobFile, String) with null as the second parameter.
        Parameters:
        jobFile - the job file to use.
        Returns:
        an OutputStream for the content.
        Throws:
        IOException - if there is an I/O error opening the content.
        com.redwood.scheduler.api.exception.FileParameterSourceUnavailableException - if there is an I/O error opening the content.

      • getOutputStream

        OutputStream getOutputStream​(JobFile jobFile,
                             Format format)
                      throws IOException,
                             com.redwood.scheduler.api.exception.FileParameterSourceUnavailableException
        Get an OutputStream 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. This is the same as calling getOutputStream(JobFile, String) with format.getExtension() as the second parameter, and then setting the Format on the JobFile to the specified format.
        Parameters:
        jobFile - the job file to use.
        format - the format to use (required, null will result in an exception).
        Returns:
        an OutputStream for the content.
        Throws:
        IOException - if there is an I/O error opening the content.
        com.redwood.scheduler.api.exception.FileParameterSourceUnavailableException - if there is an I/O error opening the content.

      • getOutputStream

        OutputStream getOutputStream​(JobFile jobFile,
                             String extension)
                      throws IOException,
                             com.redwood.scheduler.api.exception.FileParameterSourceUnavailableException
        Get an OutputStream 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>.<extension>. If extension is null, no dot or extension
        • FileOrder will be set to the next available value starting at JobFile.CUSTOMER_ORDER_START.
        • Format will be set to to the GLOBAL.OctetStream.
        • 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.
        extension - the extension to use.
        Returns:
        an OutputStream for the content.
        Throws:
        IOException - if there is an I/O error opening the content.
        com.redwood.scheduler.api.exception.FileParameterSourceUnavailableException - if there is an I/O error opening the content.

      • getInValueFileParameterType

        FileParameterType getInValueFileParameterType()
        Get the type part of the In reference of an In or InOut parameter.
        Returns:
        the FileParameterType part of the InValueString attribute of the JobParameter.
        Throws:
        com.redwood.scheduler.api.exception.FileParameterValueRuntimeException - if the value is invalid.

      • getInValueSource

        String getInValueSource()
        Get the source part of the In reference of an In or InOut parameter.
        Returns:
        the source part of the InValueString attribute of the JobParameter.
        Throws:
        com.redwood.scheduler.api.exception.FileParameterValueRuntimeException - if the value is invalid.

      • getOutValueFileParameterType

        FileParameterType getOutValueFileParameterType()
        Get the type part of the Out reference of an Out or InOut parameter.
        Returns:
        the FileParameterType part of the OutValueString attribute of the JobParameter.
        Throws:
        com.redwood.scheduler.api.exception.FileParameterValueRuntimeException - if the value is invalid.

      • getOutValueSource

        String getOutValueSource()
        Get the source part of the Out reference of an Out or InOut parameter.
        Returns:
        the source part part of the OutValueString attribute of the JobParameter.
        Throws:
        com.redwood.scheduler.api.exception.FileParameterValueRuntimeException - if the value is invalid.

      • setOutValueString

        void setOutValueString​(FileParameterType type,
                       String source)
        Manually override the Out reference of an Out or InOut parameter. The recommended way to set this data is by using one of the getOutputStream*() methods, like getOutputStream() or getOutputStream(JobFile).
        Parameters:
        type - the output type.
        source - the output source.

      • 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 getOutputStream*() methods, like getOutputStream() or getOutputStream(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.

      • 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 FileParameter
        Returns:
        information identifying this parameter for use in error messages.