edu.cmu.pslc.datashop.webservices

## Class DatashopClient

- java.lang.Object
- - edu.cmu.pslc.datashop.webservices.DatashopClient

-     public class DatashopClient
      extends java.lang.Object

  Client for Datashop Web Services. Provide methods for accessing each web service here.
  Version:
    $Revision: 18843 $
    Last modified by: $Author: hcheng $
    Last modified on: $Date: 2023-06-21 15:21:19 -0400 (Wed, 21 Jun 2023) $
  Author:
    Jim Rankin

- - ### 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
    `DatashopClient(java.lang.String apiToken, java.lang.String secret)` Constructor.
    `DatashopClient(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` | `getApiToken()` Gets the API token.
    `java.lang.String` | `getDataset(java.lang.Integer id)` Convenience method for calling the dataset web service.
    `java.lang.String` | `getDatasetAdd(java.lang.String name, java.lang.Long instanceId)` Convenience method for calling the dataset add web service.
    `java.lang.String` | `getDatasetDelete(java.lang.Integer id)` Convenience method for calling the dataset delete web service.
    `java.lang.String` | `getDatasetSet(java.lang.Integer id, java.lang.String datasetInfo)` Convenience method for calling the dataset set web service.
    `static DatashopClient` | `getDatashopClientForLocalRequests()` Instantiates a Datashop client to be used for remote requests to master DataShop servers.
    `static DatashopClient` | `getDatashopClientForRemoteRequests()` Instantiates a Datashop client to be used for remote requests to master DataShop servers.
    `java.lang.String` | `getDiscourseAdd(java.lang.String name, java.lang.Long instanceId)` Convenience method for calling the discourse add web service.
    `java.lang.String` | `getDiscourseDelete(java.lang.Long id)` Convenience method for calling the discourse delete web service.
    `java.lang.String` | `getDiscourseSet(java.lang.Long id, java.lang.String discourseInfo)` Convenience method for calling the discourse set web service.
    `java.lang.String` | `getHelloWorld()` Hello World is our sanity check, to confirm that web services are up and running.
    `java.lang.String` | `getInstanceAdd(java.lang.String name, java.lang.String url)` Convenience method for calling the instance add web service.
    `java.lang.String` | `getInstanceSet(java.lang.Long instanceId, java.lang.String name, java.lang.String url)` Convenience method for calling the instance set web service.
    `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` | `getPostServiceWithFileUpload(java.lang.String servicePath, java.util.Map<java.lang.String,java.lang.String> postDataPairs, java.lang.String accept, java.lang.String fileName)` Get the results of calling the specified post service with a file to upload.
    `java.lang.String` | `getRootURL()` Returns the root URL.
    `java.lang.String` | `getSample(java.lang.Integer datasetId, java.lang.Integer sampleId)` Convenience method for calling the sample web service.
    `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.
    `static void` | `main(java.lang.String[] args)` Run DatashopClient from the command line.
    `protected void` | `print(java.io.InputStream in, java.io.OutputStream out)` Print the entire contents of in to out.
    `void` | `printDataset(java.lang.Integer id)` Convenience method for calling the dataset web service.
    `void` | `printHelloWorld()` Hello World is our sanity check, to confirm that web services are up and running.
    `void` | `printSample(java.lang.Integer datasetId, java.lang.Integer sampleId)` Convenience method for calling the sample web service.
    `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.
    `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, java.lang.String contentType)` 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

    - #### DatashopClient

          public DatashopClient(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

    - #### DatashopClient

          public DatashopClient(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 DatashopClient getDatashopClientForRemoteRequests()

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

    - #### getDatashopClientForLocalRequests

          public static DatashopClient getDatashopClientForLocalRequests()

      Instantiates a Datashop 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,
                                                         java.lang.String contentType)

      Signed connection to the service specified by path with HTTP method POST.
      Parameters:
        `servicePath` - specifies the service
        `contentType` - mime type of content
      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

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

    - #### getPostServiceWithFileUpload

          public java.lang.String getPostServiceWithFileUpload(java.lang.String servicePath,
                                                      java.util.Map<java.lang.String,java.lang.String> postDataPairs,
                                                      java.lang.String accept,
                                                      java.lang.String fileName)
                                                        throws java.io.IOException

      Get the results of calling the specified post service with a file to upload.
      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

    - #### printDataset

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

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

    - #### getDataset

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

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

    - #### getDatasetAdd

          public java.lang.String getDatasetAdd(java.lang.String name,
                                       java.lang.Long instanceId)
                                         throws java.io.IOException

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

    - #### getDatasetDelete

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

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

    - #### getDatasetSet

          public java.lang.String getDatasetSet(java.lang.Integer id,
                                       java.lang.String datasetInfo)
                                         throws java.io.IOException

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

    - #### getDiscourseAdd

          public java.lang.String getDiscourseAdd(java.lang.String name,
                                         java.lang.Long instanceId)
                                           throws java.io.IOException

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

    - #### getDiscourseDelete

          public java.lang.String getDiscourseDelete(java.lang.Long id)
                                              throws java.io.IOException

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

    - #### getDiscourseSet

          public java.lang.String getDiscourseSet(java.lang.Long id,
                                         java.lang.String discourseInfo)
                                           throws java.io.IOException

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

    - #### getInstanceAdd

          public java.lang.String getInstanceAdd(java.lang.String name,
                                        java.lang.String url)
                                          throws java.io.IOException

      Convenience method for calling the instance add web service.
      Parameters:
        `name` - the instance name
        `url` - the DataShop URL for the instance
      Returns:
        the XML data for the instance as a string
      Throws:
        `java.io.IOException` - thrown if there is a communications problem

    - #### getInstanceSet

          public java.lang.String getInstanceSet(java.lang.Long instanceId,
                                        java.lang.String name,
                                        java.lang.String url)
                                          throws java.io.IOException

      Convenience method for calling the instance set web service.
      Parameters:
        `instanceId` - the remote instance id
        `name` - the instance name
        `url` - the DataShop URL for the instance
      Returns:
        the XML data for the instance as a string
      Throws:
        `java.io.IOException` - thrown if there is a communications problem

    - #### printSample

          public void printSample(java.lang.Integer datasetId,
                         java.lang.Integer sampleId)
                           throws java.io.IOException

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

    - #### getSample

          public java.lang.String getSample(java.lang.Integer datasetId,
                                   java.lang.Integer sampleId)
                                     throws java.io.IOException

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

    - #### main

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

      Run DatashopClient 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 webservices.properties.

Copyright (c) 2015 - Pittsburgh Science of Learning Center