edu.cmu.learnsphere.webservices

## Class LearnSphereWebServicesClient

- java.lang.Object
- - edu.cmu.learnsphere.webservices.LearnSphereWebServicesClient

-     public class LearnSphereWebServicesClient
      extends java.lang.Object

  Client for LearnShpere Web Services. Provide methods for accessing each web service here.
  Version:
    $Revision: 18929 $
    Last modified by: $Author: hcheng $
    Last modified on: $Date: 2024-07-19 19:01:11 -0400 (Fri, 19 Jul 2024) $
  Author:
    Hui Cheng

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `BUFFER_SIZE` number of bytes to read at a time.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `LearnSphereWebServicesClient(java.lang.String apiToken, java.lang.String secret)` Constructor.
    `LearnSphereWebServicesClient(java.lang.String servicesRoot, java.lang.String apiToken, java.lang.String secret)` Constructor.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String` | `deleteWorkflow(java.lang.Integer id)` Convenience method for calling the workflow delete web service.
    `java.lang.String` | `getApiToken()` Gets the API token.
    `static LearnSphereWebServicesClient` | `getDatashopClientForLocalRequests()` Instantiates a LearnSphere client to be used for remote requests to master DataShop servers.
    `static LearnSphereWebServicesClient` | `getDatashopClientForRemoteRequests()` Instantiates a LearnSphereWeServiceClient to be used for remote requests to master LearnSphere servers.
    `void` | `getFileService(java.lang.String path, java.lang.String accept, java.lang.String outputFileLoc)`
    `java.lang.String` | `getHelloWorld()` Hello World is our sanity check, to confirm that web services are up and running.
    `java.lang.String` | `getPostService(java.lang.String path, java.lang.String postData, java.lang.String accept)` Get the results of calling the specified service as a string.
    `java.lang.String` | `getPostServiceWithFileAttachment(java.lang.String path, java.lang.String postData, java.io.File fileToAttach, java.lang.String accept)` Get the results of calling the specified service as a string.
    `java.lang.String` | `getRootURL()` Returns the root URL.
    `java.lang.String` | `getSecret()` Gets the secret.
    `java.lang.String` | `getService(java.lang.String path, java.lang.String accept)` Get the results of calling the specified service as a string.
    `java.lang.String` | `getWorkflow(java.lang.Integer id)` Convenience method for calling the workflow web service.
    `void` | `getWorkflowFiles(java.lang.Integer id, java.lang.String zipFilePath)` Convenience method for calling the workflow_files web service.
    `java.lang.String` | `getWorkflows()` Convenience method for calling the workflows web service.
    `static void` | `main(java.lang.String[] args)` Run LearnSphereWebServiceClient from the command line.
    `protected void` | `print(java.io.InputStream in, java.io.OutputStream out)` Print the entire contents of in to out.
    `void` | `printHelloWorld()` Hello World is our sanity check, to confirm that web services are up and running.
    `void` | `printService(java.lang.String path, java.lang.String accept)` Print the results of calling the specified service to standard out.
    `protected java.lang.String` | `printToString(java.io.InputStream is)` Return the entire contents of the input stream as a string.
    `void` | `printWorkflow(java.lang.Integer id)` Convenience method for calling the workflow web service.
    `void` | `printWorkflows()` Convenience method for calling the workflows web service.
    `java.lang.String` | `runWorkflow(java.lang.Integer id)` Convenience method for calling the workflow run web service.
    `java.lang.String` | `saveAsNewWorkflow(java.lang.Integer id, java.lang.String newWorkflowName, boolean isGlobal, java.lang.String description)` Convenience method for calling the workflow saveAsNew web service.
    `java.net.HttpURLConnection` | `serviceGetConnection(java.lang.String servicePath)` Signed connection to the service specified by path using HTTP GET method.
    `java.net.HttpURLConnection` | `servicePostConnection(java.lang.String servicePath)` Signed connection to the service specified by path with HTTP method POST.
    `java.net.HttpURLConnection` | `servicePutConnection(java.lang.String servicePath)` Signed connection to the service specified by path with HTTP method PUT.
    `void` | `setApiToken(java.lang.String apiToken)` Sets the API token.
    `void` | `setRootURL(java.lang.String rootURL)` Sets the root URL.
    `void` | `setSecret(java.lang.String secret)` Sets the secret

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

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

- - ### Field Detail

    - #### BUFFER_SIZE

          public static final int BUFFER_SIZE

      number of bytes to read at a time.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### LearnSphereWebServicesClient

          public LearnSphereWebServicesClient(java.lang.String servicesRoot,
                                      java.lang.String apiToken,
                                      java.lang.String secret)

      Constructor.
      Parameters:
        `servicesRoot` - URL prefix for web services
        `apiToken` - public API token for authentication
        `secret` - secret key for authentication

    - #### LearnSphereWebServicesClient

          public LearnSphereWebServicesClient(java.lang.String apiToken,
                                      java.lang.String secret)

      Constructor. Root URL defaults to local host for testing.
      Parameters:
        `apiToken` - public API token for authentication
        `secret` - secret key for authentication

  - ### Method Detail

    - #### getDatashopClientForRemoteRequests

          public static LearnSphereWebServicesClient getDatashopClientForRemoteRequests()

      Instantiates a LearnSphereWeServiceClient to be used for remote requests to master LearnSphere servers.
      Returns:
        the web service client or null if any required properties are missing

    - #### getDatashopClientForLocalRequests

          public static LearnSphereWebServicesClient getDatashopClientForLocalRequests()

      Instantiates a LearnSphere client to be used for remote requests to master DataShop servers.
      Returns:
        the web service client or null if any required properties are missing

    - #### getRootURL

          public java.lang.String getRootURL()

      Returns the root URL.
      Returns:
        the rootURL

    - #### setRootURL

          public void setRootURL(java.lang.String rootURL)

      Sets the root URL.

    - #### getApiToken

          public java.lang.String getApiToken()

      Gets the API token.
      Returns:
        the API token

    - #### setApiToken

          public void setApiToken(java.lang.String apiToken)

      Sets the API token.
      Parameters:
        `apiToken` - the API token

    - #### getSecret

          public java.lang.String getSecret()

      Gets the secret.
      Returns:
        the secret

    - #### setSecret

          public void setSecret(java.lang.String secret)

      Sets the secret
      Parameters:
        `secret` - the secret

    - #### serviceGetConnection

          public java.net.HttpURLConnection serviceGetConnection(java.lang.String servicePath)

      Signed connection to the service specified by path using HTTP GET method.
      Parameters:
        `servicePath` - specifies the service to GET
      Returns:
        a newly created, signed GET connection to the specified web service

    - #### servicePutConnection

          public java.net.HttpURLConnection servicePutConnection(java.lang.String servicePath)

      Signed connection to the service specified by path with HTTP method PUT. TODO this is a place holder for unit tests for now, but a real PUT method will need a message payload to deliver
      Parameters:
        `servicePath` - specifies the service to PUT
      Returns:
        a newly created, signed PUT connection to the specified web service

    - #### servicePostConnection

          public java.net.HttpURLConnection servicePostConnection(java.lang.String servicePath)

      Signed connection to the service specified by path with HTTP method POST.
      Parameters:
        `servicePath` - specifies the service
      Returns:
        a newly created, signed POST connection to the specified web service

    - #### printService

          public void printService(java.lang.String path,
                          java.lang.String accept)
                            throws java.io.IOException

      Print the results of calling the specified service to standard out.
      Parameters:
        `path` - the path indicating which web service to call.
        `accept` - mime type we expect in return, such as text/xml (should we allow multiple values here?)
      Throws:
        `java.io.IOException` - thrown if there is a communications problem

    - #### getService

          public java.lang.String getService(java.lang.String path,
                                    java.lang.String accept)
                                      throws java.io.IOException

      Get the results of calling the specified service as a string.
      Parameters:
        `path` - the path indicating which web service to call.
        `accept` - mime type we expect in return, such as text/xml (should we allow multiple values here?)
      Returns:
        the results of calling the specified service as a string
      Throws:
        `java.io.IOException` - thrown if there is a communications problem

    - #### getFileService

          public void getFileService(java.lang.String path,
                            java.lang.String accept,
                            java.lang.String outputFileLoc)
                              throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### getPostService

          public java.lang.String getPostService(java.lang.String path,
                                        java.lang.String postData,
                                        java.lang.String accept)
                                          throws java.io.IOException

      Get the results of calling the specified service as a string.
      Parameters:
        `path` - the path indicating which web service to call.
        `postData` - the content
        `accept` - mime type we expect in return, such as text/xml
      Returns:
        the results of calling the specified service as a string
      Throws:
        `java.io.IOException` - thrown if there is a communications problem

    - #### getPostServiceWithFileAttachment

          public java.lang.String getPostServiceWithFileAttachment(java.lang.String path,
                                                          java.lang.String postData,
                                                          java.io.File fileToAttach,
                                                          java.lang.String accept)
                                                            throws java.io.IOException

      Get the results of calling the specified service as a string.
      Parameters:
        `path` - the path indicating which web service to call.
        `postData` - the content
        `accept` - mime type we expect in return, such as text/xml
      Returns:
        the results of calling the specified service as a string
      Throws:
        `java.io.IOException` - thrown if there is a communications problem

    - #### print

          protected void print(java.io.InputStream in,
                   java.io.OutputStream out)
                        throws java.io.IOException

      Print the entire contents of in to out.
      Parameters:
        `in` - the input stream
        `out` - the output stream
      Throws:
        `java.io.IOException` - if something goes wrong

    - #### printToString

          protected java.lang.String printToString(java.io.InputStream is)
                                            throws java.io.IOException

      Return the entire contents of the input stream as a string.
      Parameters:
        `is` - the input stream
      Returns:
        the entire contents of the input stream as a string
      Throws:
        `java.io.IOException` - if something goes wrong

    - #### printHelloWorld

          public void printHelloWorld()
                               throws java.lang.Exception

      Hello World is our sanity check, to confirm that web services are up and running.
      Throws:
        `java.lang.Exception` - if something goes wrong

    - #### getHelloWorld

          public java.lang.String getHelloWorld()
                                         throws java.lang.Exception

      Hello World is our sanity check, to confirm that web services are up and running.
      Returns:
        "Hello World!" if all goes well
      Throws:
        `java.lang.Exception` - if something goes wrong

    - #### printWorkflow

          public void printWorkflow(java.lang.Integer id)
                             throws java.io.IOException

      Convenience method for calling the workflow web service.
      Parameters:
        `id` - the workflow id
      Throws:
        `java.io.IOException` - thrown if there is a communications problem

    - #### getWorkflow

          public java.lang.String getWorkflow(java.lang.Integer id)
                                       throws java.io.IOException

      Convenience method for calling the workflow web service.
      Parameters:
        `id` - the workflow id
      Returns:
        the XML data for the workflow as a string
      Throws:
        `java.io.IOException` - thrown if there is a communications problem

    - #### runWorkflow

          public java.lang.String runWorkflow(java.lang.Integer id)
                                       throws java.io.IOException

      Convenience method for calling the workflow run web service.
      Parameters:
        `id` - the workflow id
      Returns:
        the XML message for the workflow as a string
      Throws:
        `java.io.IOException` - thrown if there is a communications problem

    - #### deleteWorkflow

          public java.lang.String deleteWorkflow(java.lang.Integer id)
                                          throws java.io.IOException

      Convenience method for calling the workflow delete web service.
      Parameters:
        `id` - the workflow id
      Returns:
        the XML message for the workflow as a string
      Throws:
        `java.io.IOException` - thrown if there is a communications problem

    - #### saveAsNewWorkflow

          public java.lang.String saveAsNewWorkflow(java.lang.Integer id,
                                           java.lang.String newWorkflowName,
                                           boolean isGlobal,
                                           java.lang.String description)
                                             throws java.io.IOException

      Convenience method for calling the workflow saveAsNew web service.
      Parameters:
        `id` - the workflow id
      Returns:
        the XML verbose description of the new workflow as a string
      Throws:
        `java.io.IOException` - thrown if there is a communications problem

    - #### printWorkflows

          public void printWorkflows()
                              throws java.io.IOException

      Convenience method for calling the workflows web service.
      Throws:
        `java.io.IOException` - thrown if there is a communications problem

    - #### getWorkflows

          public java.lang.String getWorkflows()
                                        throws java.io.IOException

      Convenience method for calling the workflows web service.
      Returns:
        the XML data for the workflows as a string
      Throws:
        `java.io.IOException` - thrown if there is a communications problem

    - #### getWorkflowFiles

          public void getWorkflowFiles(java.lang.Integer id,
                              java.lang.String zipFilePath)
                                throws java.io.IOException

      Convenience method for calling the workflow_files web service.
      Parameters:
        `id` - the workflow id
      Throws:
        `java.io.IOException` - thrown if there is a communications problem

    - #### main

          public static void main(java.lang.String[] args)

      Run LearnSphereWebServiceClient from the command line.
      Parameters:
        `args` - Arguments are alternating keys and values. Valid keys are apitoken - the user's public token secret - the user's secret key root - the root URL for the web service host path - the path indicating which web service to call. file - name of the file to upload to the server ALTERNATIVE: a single argument is taken to be a complete web services URL to call, with the credentials provided in learnsphere_webservices.properties.

Copyright (c) 2015 - Pittsburgh Science of Learning Center