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

com.ibm.streamsx.rest

## Interface StreamingAnalyticsService

-     public interface StreamingAnalyticsService

  Access to a Streaming Analytics service on IBM Cloud.
  Since:
    1.8

- - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `Result<java.util.List<java.io.File>,com.google.gson.JsonObject>` | `build(java.io.File archive, java.lang.String buildName, com.google.gson.JsonObject buildConfig)` Submit an archive to build against Streaming Analytics service.
    `Result<Job,com.google.gson.JsonObject>` | `buildAndSubmitJob(java.io.File archive, com.google.gson.JsonObject jco, java.lang.String buildName, com.google.gson.JsonObject buildConfig)` Submit an archive to build and run on the Streaming Analytics service.
    `Result<Job,com.google.gson.JsonObject>` | `buildAndSubmitJob(java.io.File archive, com.google.gson.JsonObject jco, java.lang.String buildName)` Submit an archive to build and run on the Streaming Analytics service.
    `Result<StreamingAnalyticsService,com.google.gson.JsonObject>` | `checkStatus(boolean requireRunning)` Check the status of this Streaming Analytics Service.
    `Instance` | `getInstance()` Gets the `IBM Streams Instance` object for the Streaming Analytics service.
    `java.lang.String` | `getName()` Get the service name.
    `static StreamingAnalyticsService` | `of(com.google.gson.JsonElement vcapServices, java.lang.String serviceName)` Access to a Streaming Analytics service from service name and VCAP services.
    `static StreamingAnalyticsService` | `of(com.google.gson.JsonObject serviceDefinition)` Access to a Streaming Analytics service from a service definition.
    `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.

- - ### Method Detail

    - #### of

          static StreamingAnalyticsService of(com.google.gson.JsonElement vcapServices,
                                              java.lang.String serviceName)
                                       throws java.io.IOException

      Access to a Streaming Analytics service from service name and VCAP services.
      When specified `vcapServices` may be one of:
      - An object representing VCAP service definitions.
      - A string representing the serialized JSON VCAP service definitions.
      - A string representing a file containing VCAP service definitions.
      If `vcapServices` is `null` then the environment variable `VCAP_SERVICES` must either contain the valid service definitions and credentials or point to a file containing the definitions and credentials.
      If `serviceName` is `null` then the environment variable `STREAMING_ANALYTICS_SERVICE_NAME` must contain the name of the required service.
      The service named by `serviceName` must exist in the defined VCAP services.
      Parameters:
        `vcapServices` - JSON representation of VCAP service definitions.
        `serviceName` - Name of the Streaming Analytics service to access.
      Returns:
        `StreamingAnalyticsService` for `serviceName`.
      Throws:
        `java.io.IOException` - Error connecting to the service.

    - #### of

          static StreamingAnalyticsService of(com.google.gson.JsonObject serviceDefinition)
                                       throws java.io.IOException

      Access to a Streaming Analytics service from a service definition. A service definition is a JSON object describing a Streaming Analytics service and may be one of:
      - The service credentials copied from the Service credentials page of the service console (not the Streams console). Credentials are provided in JSON format. The JSON snippet lists credentials, such as the API key and secret, as well as connection information for the service.
      - A JSON object of the form: `{ "type": "streaming-analytics", "name": "`service-name`": "credentials": { ... } }` with the service credentials as the value of the `credentials` key.
      Parameters:
        `serviceDefinition` - Definition of the service to access.
      Throws:
        `java.io.IOException` - Error connecting to the service.
      Since:
        1.8

    - #### getName

          java.lang.String getName()

      Get the service name. If the name is unknown then `service` is returned.
      Returns:
        Service name or `service` if it is unknown.

    - #### checkStatus

          Result<StreamingAnalyticsService,com.google.gson.JsonObject> checkStatus(boolean requireRunning)
                                                                            throws java.io.IOException

      Check the status of this Streaming Analytics Service.

      The returned `Result` instance has:

      - `Result.getId()` returning `null`.
      - `Result.getElement()` returning `this`.
      - `Result.getRawResult()` return the raw JSON response.
      - `Result.isOk()` returns `true` if the service is running otherwise `false`.
      Parameters:
        `requireRunning` - If `true` and the service is not running then an `IllegalStateException` is thrown, otherwise the return indicates the status of the service.
      Returns:
        Result of the status check.
      Throws:
        `java.io.IOException` - Error communicating with the service.
        `java.lang.IllegalStateException` - `requireRunning` is `true` and the service is not running.

    - #### submitJob

          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.

    - #### buildAndSubmitJob

          Result<Job,com.google.gson.JsonObject> buildAndSubmitJob(java.io.File archive,
                                                                   com.google.gson.JsonObject jco,
                                                                   java.lang.String buildName,
                                                                   com.google.gson.JsonObject buildConfig)
                                                            throws java.io.IOException

      Submit an archive to build and 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:
        `archive` - The application archive to build.
        `jco` - Job configuration overlay in JSON format.
        `buildName` - A name for the build, or null.
        `buildConfig` - Build configuration, or null.
      Returns:
        Result of the build and job submission.
      Throws:
        `java.io.IOException` - Error communicating with the service.
      Since:
        1.11

    - #### build

          Result<java.util.List<java.io.File>,com.google.gson.JsonObject> build(java.io.File archive,
                                                                                java.lang.String buildName,
                                                                                com.google.gson.JsonObject buildConfig)
                                                                         throws java.io.IOException

      Submit an archive to build against Streaming Analytics service.

      The returned `Result` instance has:

      - `Result.getId()` returning the build identifier.
      - `Result.getElement()` returning a list of the created sab files.
      - `Result.getRawResult()` return the JSON build information.

      Only supported for Streaming Analytics with v2 REST api.

      Parameters:
        `archive` - The application archive to build.
        `buildName` - A name for the build, or null.
        `buildConfig` - Build configuration, or null.
      Returns:
        Result of the build.
      Throws:
        `java.io.IOException` - Error communicating with the service.
      Since:
        1.14

    - #### buildAndSubmitJob

          Result<Job,com.google.gson.JsonObject> buildAndSubmitJob(java.io.File archive,
                                                                   com.google.gson.JsonObject jco,
                                                                   java.lang.String buildName)
                                                            throws java.io.IOException

      Submit an archive to build and run on the Streaming Analytics service. Equivalent to `buildAndSubmitJob(File, JsonObject, String, JsonObject)` passing `null` for build configuration.
      Parameters:
        `archive` - The application archive to build.
        `jco` - Job configuration overlay in JSON format.
        `buildName` - A name for the build, or null.
      Returns:
        Result of the build and job submission.
      Throws:
        `java.io.IOException` - Error communicating with the service.

    - #### getInstance

          Instance getInstance()
                        throws java.io.IOException

      Gets the `IBM Streams Instance` object for the Streaming Analytics service.
      Returns:
        an `IBM Streams Instance` associated with this service.
      Throws:
        `java.io.IOException`