Job (Java Application API for IBM Streams)
Date: 2020-08-07

com.ibm.streamsx.rest

## Class Job

- java.lang.Object
- - com.ibm.streamsx.rest.Element
  - - com.ibm.streamsx.rest.Job

-     public class Job
      extends Element

  An object describing an IBM Streams Job submitted within a specified instance

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Job()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `cancel()` Cancels this job.
    `java.lang.String` | `getApplicationName()` Gets the name of the streams processing application that this job is running
    `java.lang.String` | `getHealth()` Gets the health indicator for this job
    `java.lang.String` | `getId()` Gets the id of this job
    `java.lang.String` | `getJobGroup()` Gets the group this job belongs to
    `java.lang.String` | `getName()` Gets the name of this job
    `java.util.List<Operator>` | `getOperators()` Gets a list of `operators` for this job
    `java.util.List<ProcessingElement>` | `getPes()` Gets a list of `processing elements` for this job
    `java.util.List<ResourceAllocation>` | `getResourceAllocations()` Gets a list of `resource allocations` for this job.
    `java.lang.String` | `getResourceType()` Identifies the REST resource type
    `java.lang.String` | `getStartedBy()` Identifies the user ID that started this job
    `java.lang.String` | `getStatus()` Describes the status of this job
    `java.util.List<JobSubmitParameters>` | `getSubmitParameters()` Gets the list of `parameters` that were submitted to this job
    `long` | `getSubmitTime()` Gets the Epoch time when this job was submitted
    `java.io.File` | `retrieveLogTrace(java.io.File directory)` Retrieves the application log and trace files of the job and saves them as a compressed tar file.
    `void` | `waitForHealthy(long timeout, java.util.concurrent.TimeUnit unit)` Wait for this job to become healthy.

    - ### Methods inherited from class com.ibm.streamsx.rest.Element

      `getStreamsConnection, refresh, toString`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Job

          public Job()

  - ### Method Detail

    - #### getOperators

          public java.util.List<Operator> getOperators()
                                                throws java.io.IOException

      Gets a list of `operators` for this job
      Returns:
        List of `IBM Streams Operators`
      Throws:
        `java.io.IOException`

    - #### cancel

          public boolean cancel()
                         throws java.lang.Exception,
                                java.io.IOException

      Cancels this job.
      Returns:
        the result of the cancel method
        - true if this job is cancelled
        - false if this job still exists
      Throws:
        `java.io.IOException`
        `java.lang.Exception`

    - #### getApplicationName

          public java.lang.String getApplicationName()

      Gets the name of the streams processing application that this job is running
      Returns:
        the application name

    - #### getHealth

          public java.lang.String getHealth()

      Gets the health indicator for this job
      Returns:
        the health indicator containing one of the following values:
        - healthy
        - partiallyHealthy
        - partiallyUnhealthy
        - unhealthy
        - unknown

    - #### getId

          public java.lang.String getId()

      Gets the id of this job
      Returns:
        the job identifier

    - #### getJobGroup

          public java.lang.String getJobGroup()

      Gets the group this job belongs to
      Returns:
        the job group

    - #### getName

          public java.lang.String getName()

      Gets the name of this job
      Returns:
        the job name

    - #### getPes

          public java.util.List<ProcessingElement> getPes()
                                                   throws java.io.IOException

      Gets a list of `processing elements` for this job
      Returns:
        List of `Processing Elements`
      Throws:
        `java.io.IOException`

    - #### getResourceAllocations

          public java.util.List<ResourceAllocation> getResourceAllocations()
                                                                    throws java.io.IOException

      Gets a list of `resource allocations` for this job.
      Returns:
        List of `resource allocations`
      Throws:
        `java.io.IOException`
      Since:
        1.9

    - #### getResourceType

          public java.lang.String getResourceType()

      Identifies the REST resource type
      Returns:
        "job"

    - #### getStartedBy

          public java.lang.String getStartedBy()

      Identifies the user ID that started this job
      Returns:
        the user ID that started this job

    - #### getStatus

          public java.lang.String getStatus()

      Describes the status of this job
      Returns:
        the job status that contains one of the following values:
        - canceling
        - running
        - canceled
        - unknown

    - #### getSubmitParameters

          public java.util.List<JobSubmitParameters> getSubmitParameters()

      Gets the list of `parameters` that were submitted to this job
      Returns:
        List of (@link JobSubmitParameters job submission parameters}

    - #### getSubmitTime

          public long getSubmitTime()

      Gets the Epoch time when this job was submitted
      Returns:
        the epoch time when the job was submitted as a long

    - #### waitForHealthy

          public void waitForHealthy(long timeout,
                                     java.util.concurrent.TimeUnit unit)
                              throws java.util.concurrent.TimeoutException,
                                     java.lang.InterruptedException,
                                     java.io.IOException

      Wait for this job to become healthy.
      When submitted a Streams job has to reach a `healthy` state before stream processing is started. During this startup time processing elements are started on resources and then connected. This method allows code to wait for the job to become healthy before using the REST api to monitor its elements.

      Note that a job may subsequently become unhealthy after this call returns due to failures of processing or resources.

      Parameters:
        `timeout` - Time to wait for the job to become healthy.
        `unit` - Unit for `timeout`.
      Throws:
        `java.util.concurrent.TimeoutException` - Job did not become healthy in the time allowed.
        `java.lang.InterruptedException` - Thread was interrupted.
        `java.io.IOException` - Error communicating with Streams.

    - #### retrieveLogTrace

          public java.io.File retrieveLogTrace(java.io.File directory)
                                        throws java.io.IOException

      Retrieves the application log and trace files of the job and saves them as a compressed tar file.
      The resulting file name is `job_<id>_<timestamp>.tar.gz` where `id` is the job identifier and `timestamp` is the number of seconds since the Unix epoch, for example `job_355_1511995995.tar.gz`.
      Parameters:
        `directory` - a valid directory in which to save the archive. Defaults to the current directory.
      Returns:
        File obhject representing the created tar file, or `null` if retrieving a job's logs is not supported in the version of IBM Streams to which the job is submitted.
      Throws:
        `java.io.IOException`
      Since:
        1.11