Using Java

Getting the SDK

The easiest way to use the IBM Analytics Engine Java SDK is to use Maven to manage library dependencies. If you aren't familiar with Maven, see Maven in 5-Minutes.

Maven uses a file that is called pom.xml to specify the libraries and their versions needed for a Java project. Here is an example of the pom.xml file for using the IBM Analytics Engine Java SDK to connect to IBM Analytics Engine.

<dependency>
  <groupId>com.ibm.cloud</groupId>
  <artifactId>ibm-analytics-engine-api</artifactId>
  <version>0.4.2</version>
</dependency>

Creating a client and sourcing credentials

When you connect to IBM Analytics Engine, a client is created and configured using the credential information (API key and service instance ID) that you provide. If you don't provide this information manually, these credentials can be sourced from a credentials file or from environment variables.

You can retrieve the service instance ID when you create service credentials or through the CLI. See Retrieving service endpoints.

To use the IBM Analytics Engine Java SDK, you need the following values:

• IAM_API_KEY: The API key generated when creating the service credentials. You can retrieve by viewing the service credentials on the IBM Cloud dashboard.

• instance_guid: The value in resource_instance_id generated when the service credentials are created. You can get the value by viewing the service credentials on the IBM Cloud dashboard.

• IAE_ENDPOINT_URL : The service endpoint URL including the https:// protocol. See Service endpoints.

Initializing the configuration

The Java SDK allows you to construct the service client in one of two ways by:

• By setting the client options programmatically

  You can construct an instance of the IBM Analytics Engine service client by specifying various client options, like the authenticator and service endpoint URL, programmatically:

  import com.ibm.cloud.iaesdk.ibm_analytics_engine_api.v3.IbmAnalyticsEngineApi;
  import com.ibm.cloud.iaesdk.ibm_analytics_engine_api.v3.model.*;
  import com.ibm.cloud.sdk.core.http.Response;
  import com.ibm.cloud.sdk.core.security.*;
  import java.util.HashMap;
  
  private static IbmAnalyticsEngineApi ibmAnalyticsEngineApiService;
  
  private static String IAM_API_KEY = "{apikey}";
  private static String IAE_ENDPOINT_URL = "{url}";
  private static String API_AUTH_URL = "{api auth url}";
  
  public static void main(String[] args)
  {  
     HashMap<String, String> config = new HashMap<String, String>();
     config.put("APIKEY",IAM_API_KEY );
     config.put("AUTH_URL", API_AUTH_URL);
  
     try {
        // Create an IAM authenticator.
        Authenticator authenticator = IamAuthenticator.fromConfiguration(config);
        // Construct the service client.
        ibmAnalyticsEngineApiService = new IbmAnalyticsEngineApi(IbmAnalyticsEngineApi.DEFAULT_SERVICE_NAME, authenticator);
        // Set our service URL.
        ibmAnalyticsEngineApiService.setServiceUrl(IAE_ENDPOINT_URL);
        }
        catch (Exception e) {
        System.out.println("Exception");
        }
  }
  

• By using external configuration properties

  To avoid hard-coding sourcing credentials, you can store these values in configuration properties outside of your application.

  To use configuration properties:

  1. Define the configuration properties to be used by your application. These properties can be implemented as:

     • Exported environment variables

     • Values stored in a credentials file

       The following example shows using environment variables. Each environment variable must be prefixed by IBM_ANALYTICS_ENGINE_API.

       export IBM_ANALYTICS_ENGINE_API_URL=<IAE_ENDPOINT_URL>
       export IBM_ANALYTICS_ENGINE_API_AUTH_TYPE=iam
       export IBM_ANALYTICS_ENGINE_API_APIKEY=<IAM_API_KEY>
       

       IBM_ANALYTICS_ENGINE_API is the default service name for the IBM Analytics Engine API client which means that the SDK will by default look for properties that start with this prefix.

  2. Build the service client:

     import com.ibm.cloud.iaesdk.ibm_analytics_engine_api.v3.IbmAnalyticsEngineApi;
     import com.ibm.cloud.iaesdk.ibm_analytics_engine_api.v3.model.*;
     import com.ibm.cloud.sdk.core.http.Response;
     import com.ibm.cloud.sdk.core.security.*;
     import java.util.HashMap;
     
     private static IbmAnalyticsEngineApi ibmAnalyticsEngineApiService;
     
     private static String IAM_API_KEY = "{apikey}";
     private static String IAE_ENDPOINT_URL = "{url}";
     private static String API_AUTH_URL = "{api auth url}";
     
     public static void main(String[] args)
     {
        HashMap<String, String> config = new HashMap<String, String>();
          config.put("APIKEY",IAM_API_KEY );
          config.put("AUTH_URL", API_AUTH_URL);
     
        try {
           // Create an IAM authenticator.
           Authenticator authenticator = IamAuthenticator.fromConfiguration(config);
           // Construct the service client.
           ibmAnalyticsEngineApiService = new IbmAnalyticsEngineApi(IbmAnalyticsEngineApi.DEFAULT_SERVICE_NAME, authenticator);
           // Set our service URL.
           ibmAnalyticsEngineApiService.setServiceUrl(IAE_ENDPOINT_URL);
     
        } catch (Exception e) {
           System.out.println("Exception");
        }
     }
     

Code Samples

In addition to the sample code snippets in this section, you can work with Java code samples from the IBM Analytics Engine V3 API reference.

The following code samples show you how to:

• Access the IBM Analytics Engine service instance:

  import com.ibm.cloud.iaesdk.ibm_analytics_engine_api.v3.IbmAnalyticsEngineApi;
  import com.ibm.cloud.iaesdk.ibm_analytics_engine_api.v3.model.*;
  import com.ibm.cloud.sdk.core.http.Response;
  import com.ibm.cloud.sdk.core.security.*;
  import java.util.HashMap;
  
  private static IbmAnalyticsEngineApi ibmAnalyticsEngineApiService;
  
  private static String IAM_API_KEY = "{apikey}";
  private static String IAE_ENDPOINT_URL = "{url}";
  private static String API_AUTH_URL = "{api auth url}";
  
  public static void main(String[] args)
  {  
     HashMap<String, String> config = new HashMap<String, String>();
   	config.put("APIKEY",IAM_API_KEY );
   	config.put("AUTH_URL", API_AUTH_URL);
  
     try {
        // Create an IAM authenticator.
        Authenticator authenticator = IamAuthenticator.fromConfiguration(config);
        // Construct the service client.
        ibmAnalyticsEngineApiService = new IbmAnalyticsEngineApi(IbmAnalyticsEngineApi.DEFAULT_SERVICE_NAME, authenticator);
        // Set our service URL.
        ibmAnalyticsEngineApiService.setServiceUrl(IAE_ENDPOINT_URL);
  
     } catch (Exception e) {
        System.out.println("Exception");
     }
  }
  

• Retrieve the details of a single instance.:

  ServiceCall<Instance> getInstance(GetInstanceOptions getInstanceOptions)
  

  Example request:

  // Construct an instance of the GetInstanceOptions model
  GetInstanceOptions getInstanceOptionsModel = new GetInstanceOptions.Builder()
  .instanceId("dc0e9889-eab2-4t9e-9441-566209499546")
  .build();
  
  // Invoke operation with valid options model (positive test)
  Response<Instance> response = ibmAnalyticsEngineApiService.getInstance(getInstanceOptionsModel).execute();
  Instance responseObj = response.getResult();
  System.out.println(String.valueOf(responseObj));
  

• Deploy a Spark application on a given serverless Spark instancet:

  ServiceCall<ApplicationResponse> createApplication(CreateApplicationOptions createApplicationOptions)
  

  Example request:

  // Construct an instance of the ApplicationRequestApplicationDetails model
  ApplicationRequestApplicationDetails applicationRequestApplicationDetailsModel = new ApplicationRequestApplicationDetails.Builder()
  .application("cos://ae-bucket-do-not-delete-dc0e9889-eab2-4t9e-9441-566209499546.s3.us-south.cloud-object-storage.appdomain.cloud/my_spark_application.py")
  .xClass("IbmAnalyticsEngineApi")
  .arguments(new java.util.ArrayList<String>(java.util.Arrays.asList("/opt/ibm/spark/examples/src/main/resources/people.txt")))
  .conf(new java.util.HashMap<String, Object>() { { put("spark.app.name", "MySparkApp"); } })
  .env(new java.util.HashMap<String, Object>() { { put("SPARK_ENV_LOADED", "2"); } })
  .build();
  
  // Construct an instance of the CreateApplicationOptions model
  CreateApplicationOptions createApplicationOptionsModel = new CreateApplicationOptions.Builder()
  .instanceId("dc0e9889-eab2-4t9e-9441-566209499546")
  .applicationDetails(applicationRequestApplicationDetailsModel)
  .build();
  
  // Invoke operation with valid options model (positive test)
  Response<ApplicationResponse> response = ibmAnalyticsEngineApiService.createApplication(createApplicationOptionsModel).execute();
  ApplicationResponse responseObj = response.getResult();
  System.out.println(String.valueOf(responseObj));
  

• Retrieve all Spark applications run on a given instance:

  ServiceCall<ApplicationCollection> listApplications(ListApplicationsOptions listApplicationsOptions)
  

  Example request:

  // Construct an instance of the ListApplicationsOptions model
  ListApplicationsOptions listApplicationsOptionsModel = new ListApplicationsOptions.Builder()
  .instanceId("dc0e9889-eab2-4t9e-9441-566209499546")
  .build();
  
  // Invoke operation with valid options model (positive test)
  Response<ApplicationCollection> response = ibmAnalyticsEngineApiService.listApplications(listApplicationsOptionsModel).execute();
  ApplicationCollection responseObj = response.getResult();
  System.out.println(String.valueOf(responseObj));
  

• Retrieve the details of a given Spark application:

  ServiceCall<ApplicationGetResponse> getApplication(GetApplicationOptions getApplicationOptions)
  

  Example request:

  // Construct an instance of the GetApplicationOptions model
  GetApplicationOptions getApplicationOptionsModel = new GetApplicationOptions.Builder()
  .instanceId("dc0e9889-eab2-4t9e-9441-566209499546")
  .applicationId("db933645-0b68-4dcb-80d8-7b71a6c8e542")
  .build();
  
  // Invoke operation with valid options model (positive test)
  Response<ApplicationGetResponse> response = ibmAnalyticsEngineApiService.getApplication(getApplicationOptionsModel).execute();
  ApplicationGetResponse responseObj = response.getResult();
  System.out.println(String.valueOf(responseObj));
  

• Stop a running application identified by the app_id identifier. This is an idempotent operation. Performs no action if the requested application is already stopped or completed.

  ServiceCall<Void> deleteApplication(DeleteApplicationOptions deleteApplicationOptions)
  

  Example request:

  // Construct an instance of the DeleteApplicationOptions model
  DeleteApplicationOptions deleteApplicationOptionsModel = new DeleteApplicationOptions.Builder()
  .instanceId("dc0e9889-eab2-4t9e-9441-566209499546")
  .applicationId("db933645-0b68-4dcb-80d8-7b71a6c8e542")
  .build();
  
  // Invoke operation with valid options model (positive test)
  Response<Void> response = ibmAnalyticsEngineApiService.deleteApplication(deleteApplicationOptionsModel).execute();
  Void responseObj = response.getResult();
  System.out.println(String.valueOf(responseObj));
  

• Return the state of an application:

  ServiceCall<ApplicationGetStateResponse> getApplicationState(GetApplicationStateOptions getApplicationStateOptions)
  

  Example request:

  // Construct an instance of the GetApplicationStateOptions model
  GetApplicationStateOptions getApplicationStateOptionsModel = new GetApplicationStateOptions.Builder()
  .instanceId("dc0e9889-eab2-4t9e-9441-566209499546")
  .applicationId("db933645-0b68-4dcb-80d8-7b71a6c8e542")
  .build();
  
  // Invoke operation with valid options model (positive test)
  Response<ApplicationGetStateResponse> response = ibmAnalyticsEngineApiService.getApplicationState(getApplicationStateOptionsModel).execute();
  ApplicationGetStateResponse responseObj = response.getResult();
  System.out.println(String.valueOf(responseObj));