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

com.ibm.streamsx.rest

## Class Instance

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

-     public class Instance
      extends Element

  An object describing an IBM Streams Instance

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Instance()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `ActiveVersion` | `getActiveVersion()` Gets information about the IBM Streams Installation that was used to start this instance
    `java.lang.String` | `getApplicationConsoleURL()` Streams application console URL.
    `long` | `getCreationTime()` Gets the time in milliseconds when this instance was created
    `java.lang.String` | `getCreationUser()` Gets the user ID that created this instance
    `Domain` | `getDomain()` Get the Streams domain for this instance.
    `java.lang.String` | `getHealth()` Gets the summarized status of jobs in this instance
    `java.lang.String` | `getId()` Gets the IBM Streams unique identifier for this instance
    `Job` | `getJob(java.lang.String jobId)` Gets the `Job` for a given jobId in this instance
    `java.util.List<Job>` | `getJobs()` Gets a list of `jobs` that this instance knows about
    `java.lang.String` | `getOwner()` Gets the user ID that represents the owner of this instance
    `java.util.List<ProcessingElement>` | `getPes()` Gets a list of `processing elements` for this instance.
    `java.util.List<ResourceAllocation>` | `getResourceAllocations()` Gets a list of `resource allocations` for this instance.
    `java.lang.String` | `getResourceType()` Identifies the REST resource type
    `long` | `getStartTime()` Gets the time in milliseconds when the instance was started.
    `java.lang.String` | `getStatus()` Gets the status of the instance
    `static Instance` | `ofEndpoint(java.lang.String endpoint, java.lang.String name, java.lang.String userName, java.lang.String password, boolean verify)` Connect to a Cloud Pak for Data IBM Streams instance.
    `static Instance` | `ofEndpoint(java.lang.String endpoint, java.lang.String name, java.lang.String userName, java.lang.String password)` Connect to a Cloud Pak for Data IBM Streams instance.
    `Result<Job,com.google.gson.JsonObject>` | `submitJob(java.io.File bundle, com.google.gson.JsonObject jco)` Submit a Streams bundle to run on the Streaming Analytics Service.
    `ApplicationBundle` | `uploadBundle(java.io.File bundle)` Upload a Streams application bundle (sab) to the instance.

    - ### 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

    - #### Instance

          public Instance()

  - ### Method Detail

    - #### ofEndpoint

          public static Instance ofEndpoint(java.lang.String endpoint,
                                            java.lang.String name,
                                            java.lang.String userName,
                                            java.lang.String password)
                                     throws java.io.IOException

      Connect to a Cloud Pak for Data IBM Streams instance.

      This call is equivalent to `ofEndpoint(String, String, String, String, boolean)` passing `true` for verify.

      Two configurations are supported:

      Integrated configuration
        The Streams instance is defined using the Cloud Pak for Data deployment endpoint (URL) and the Streams service name.

        The endpoint defaults to the environment variable `CP4D_URL`. An example is @{code https://cp4d_server:31843}.

        The Streams service name is passed in as name, defaulting to the environment variables `STREAMS_INSTANCE_ID`.

      Standalone configuration
        The Streams instance is defined using its Streams REST API endpoint, which is its SWS service.

        The endpoint defaults to the environment variable `STREAMS_REST_URL`. An example is `https://streams_sws_service:34679`.

        No service name is specified thus name should be `null`.

      Parameters:
        `endpoint` - Endpoint defining the Streams instance.
        `name` - Streams instance name for a integrated configuration. This value is ignored for a standalone configuration.
        `userName` - User name, if `null` defaults to environment variable `STREAMS_USERNAME` if set, otherwise the operating user identifier.
        `password` - Password, if `null` defaults to environment variable `STREAMS_PASSWORD`.
      Returns:
        Connection to Streams instance using REST API.
      Throws:
        `java.io.IOException` - Error connecting to instance.
      Since:
        1.13

    - #### ofEndpoint

          public static Instance ofEndpoint(java.lang.String endpoint,
                                            java.lang.String name,
                                            java.lang.String userName,
                                            java.lang.String password,
                                            boolean verify)
                                     throws java.io.IOException

      Connect to a Cloud Pak for Data IBM Streams instance.

      Two configurations are supported:

      Integrated configuration
        The Streams instance is defined using the Cloud Pak for Data deployment endpoint (URL) and the Streams service name.

        The endpoint defaults to the environment variable `CP4D_URL`. An example is @{code https://cp4d_server:31843}.

        The Streams service name is passed in as name, defaulting to the environment variables `STREAMS_INSTANCE_ID`.

      Standalone configuration
        The Streams instance is defined using its Streams REST API endpoint, which is its SWS service.

        The endpoint defaults to the environment variable `STREAMS_REST_URL`. An example is `https://streams_sws_service:34679`.

        No service name is specified thus name should be `null`.

      Parameters:
        `endpoint` - Endpoint defining the Streams instance.
        `name` - Streams instance name for a integrated configuration. This value is ignored for a standalone configuration.
        `userName` - User name, if `null` defaults to environment variable `STREAMS_USERNAME` if set, otherwise the operating user identifier.
        `password` - Password, if `null` defaults to environment variable `STREAMS_PASSWORD`.
      Returns:
        Connection to Streams instance using REST API.
      Throws:
        `java.io.IOException` - Error connecting to instance.
      Since:
        1.13

    - #### getJobs

          public java.util.List<Job> getJobs()
                                      throws java.io.IOException

      Gets a list of `jobs` that this instance knows about
      Returns:
        List of `IBM Streams Jobs`
      Throws:
        `java.io.IOException`

    - #### getPes

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

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

    - #### getResourceAllocations

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

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

    - #### getJob

          public Job getJob(java.lang.String jobId)
                     throws java.io.IOException

      Gets the `Job` for a given jobId in this instance
      Parameters:
        `jobId` - String identifying the job
      Returns:
        a single `Job`
      Throws:
        `java.io.IOException`

    - #### getActiveVersion

          public ActiveVersion getActiveVersion()

      Gets information about the IBM Streams Installation that was used to start this instance
      Returns:
        `ActiveVersion`

    - #### getCreationTime

          public long getCreationTime()

      Gets the time in milliseconds when this instance was created
      Returns:
        the epoch time in milliseconds when the instance was created as a long

    - #### getCreationUser

          public java.lang.String getCreationUser()

      Gets the user ID that created this instance
      Returns:
        the creation user ID

    - #### getHealth

          public java.lang.String getHealth()

      Gets the summarized status of jobs in this instance
      Returns:
        the summarized status that contains one of the following values:
        - healthy
        - partiallyHealthy
        - partiallyUnhealthy
        - unhealthy
        - unknown

    - #### getId

          public java.lang.String getId()

      Gets the IBM Streams unique identifier for this instance
      Returns:
        the IBM Streams unique idenitifer

    - #### getOwner

          public java.lang.String getOwner()

      Gets the user ID that represents the owner of this instance
      Returns:
        the owner user ID

    - #### getResourceType

          public java.lang.String getResourceType()

      Identifies the REST resource type
      Returns:
        "instance"

    - #### getStartTime

          public long getStartTime()

      Gets the time in milliseconds when the instance was started.
      Returns:
        the epoch time in milliseconds when the instance was started as a long

    - #### getStatus

          public java.lang.String getStatus()

      Gets the status of the instance
      Returns:
        the instance status that contains one of the following values:
        - running
        - failed
        - stopped
        - partiallyFailed
        - partiallyRunning
        - starting
        - stopping
        - unknown

    - #### getApplicationConsoleURL

          public java.lang.String getApplicationConsoleURL()

      Streams application console URL. Returns the Streams application console URL with a filter preset to this instance identifier.
      Returns:
        Streams application console URL
      Since:
        1.11

    - #### getDomain

          public Domain getDomain()
                           throws java.io.IOException

      Get the Streams domain for this instance.
      Returns:
        Domain for this instance.ull if no domain is associated with an instance.
      Throws:
        `java.io.IOException` - Error communicating with REST api.
      Since:
        1.8

    - #### uploadBundle

          public ApplicationBundle uploadBundle(java.io.File bundle)
                                         throws java.io.IOException

      Upload a Streams application bundle (sab) to the instance. Uploading a bundle allows job submission from the returned `ApplicationBundle`.
      Note: When an instance does not support uploading a bundle the returned `ApplicationBundle` represents the local file `bundle` tied to this instance. The returned object may still be used for job submission.
      Parameters:
        `bundle` - path to a Streams application bundle (sab file) containing the application to be uploaded
      Returns:
        Application bundle representing the uploaded bundle.
      Throws:
        `java.io.IOException` - Error uploading the bundle.
      Since:
        1.11

    - #### submitJob

          public Result<Job,com.google.gson.JsonObject> submitJob(java.io.File bundle,
                                                                  com.google.gson.JsonObject jco)
                                                           throws java.io.IOException

      Submit a Streams bundle to run on the Streaming Analytics Service.

      The returned `Result` instance has:

      - `Result.getId()` returning the job identifier or `null` if a job was not created..
      - `Result.getElement()` returning a `Job` instance for the submitted job or `null` if a job was not created.
      - `Result.getRawResult()` return the raw JSON response.
      Parameters:
        `bundle` - A streams application bundle
        `jco` - Job configuration overlay in JSON format.
      Returns:
        Result of the job submission.
      Throws:
        `java.io.IOException` - Error communicating with the service.
      Since:
        1.11