org.labkey.remoteapi

## Class Command<ResponseType extends CommandResponse>

- java.lang.Object
- - org.labkey.remoteapi.Command<ResponseType>

- Direct Known Subclasses:
    AssayListCommand, BaseQueryCommand, CheckForStudyReloadCommand, EnsureLoginCommand, FileNotificationCommand, GetContainersCommand, GetGroupPermsCommand, GetQueriesCommand, GetQueryDetailsCommand, GetSchemasCommand, GetUsersCommand, PostCommand, StartSearchCommand

      public class Command<ResponseType extends CommandResponse>
      extends java.lang.Object

  Base class for all API commands. Typically, a developer will not use this class directly, but will instead create one of the classes that extend this class. For example, to select data, create an instance of `SelectRowsCommand`, which provides helpful methods for setting options and obtaining specific result types.

  However, if future versions of the LabKey Server expose new HTTP APIs that are not yet supported with a specialized class in this library, the developer may still invoke these APIs by creating an instance of the Command object directly, providing the controller and action name for the new API. Parameters may then be specified by calling the `setParameters()` method, passing a populated parameter `Map<String, Object>`

  Note that this class is not thread-safe. Do not share instances of this class or its descendants between threads, unless the descendant declares explicitly that it is thread-safe.

  Version:
    1.0
  Author:
    Dave Stearns, LabKey Corporation

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Command.CommonParameters` An enum of common parameter names used in API URLs.
    `protected static class` | `Command.Response` Response class allows clients to get an InputStream, consume lazily, and close the connection when complete.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `CONTENT_TYPE_JSON` A constant for the official JSON content type ("application/json")

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Command(Command<ResponseType> source)` Constructs a new Command from an existing command
    `Command(java.lang.String controllerName, java.lang.String actionName)` Constructs a new Command object for calling the specified API action on the specified controller.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected Command.Response` | `_execute(Connection connection, java.lang.String folderPath)` NOTE: Internal experimental API for handling streaming commands.
    `Command` | `copy()` Returns a copy of this object.
    `protected org.apache.http.client.methods.HttpUriRequest` | `createRequest(java.net.URI uri)` Creates the appropriate HttpUriRequest instance.
    `protected ResponseType` | `createResponse(java.lang.String text, int status, java.lang.String contentType, org.json.simple.JSONObject json)` Creates an instance of the response class, initialized with the response text, the HTTP status code, and parsed JSONObject.
    `ResponseType` | `execute(Connection connection, java.lang.String folderPath)` Executes the command in the given folder on the specified connection, and returns information about the response.
    `java.lang.String` | `getActionName()` Returns the action name specified when constructing this object.
    `protected java.net.URI` | `getActionUrl(Connection connection, java.lang.String folderPath)` Returns the portion of the URL before the query string for this command.
    `java.lang.String` | `getControllerName()` Returns the controller name specified when constructing this object.
    `protected org.apache.http.client.methods.HttpUriRequest` | `getHttpRequest(Connection connection, java.lang.String folderPath)` Returns the appropriate, initialized HttpUriRequest implementation.
    `java.util.Map<java.lang.String,java.lang.Object>` | `getParameters()` Returns the current parameter map, or null if a map has not yet been set.
    `protected java.lang.String` | `getParamValueAsString(java.lang.Object param, java.lang.String name)` Returns an appropriate string encoding of the parameter value.
    `protected java.lang.String` | `getQueryString()` Returns the query string portion of the URL for this command.
    `double` | `getRequiredVersion()` Returns the required version number of this API call.
    `java.lang.Integer` | `getTimeout()` Returns the current timeout setting in milliseconds for this Command.
    `void` | `setParameters(java.util.Map<java.lang.String,java.lang.Object> parameters)` Sets the current parameter map.
    `void` | `setRequiredVersion(double requiredVersion)` Sets the required version number for this API call.
    `void` | `setTimeout(java.lang.Integer timeout)` Sets the timeout for this Command.

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

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

- - ### Field Detail

    - #### CONTENT_TYPE_JSON

          public static final java.lang.String CONTENT_TYPE_JSON

      A constant for the official JSON content type ("application/json")
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Command

          public Command(java.lang.String controllerName,
                         java.lang.String actionName)

      Constructs a new Command object for calling the specified API action on the specified controller.
      Parameters:
        `controllerName` - The name of the controller from which the action is exposed
        `actionName` - The name of the action to call

    - #### Command

          public Command(Command<ResponseType> source)

      Constructs a new Command from an existing command
      Parameters:
        `source` - A source Command

  - ### Method Detail

    - #### getControllerName

          public java.lang.String getControllerName()

      Returns the controller name specified when constructing this object.
      Returns:
        The controller name.

    - #### getActionName

          public java.lang.String getActionName()

      Returns the action name specified when constructing this object.
      Returns:
        The action name.

    - #### getParameters

          public java.util.Map<java.lang.String,java.lang.Object> getParameters()

      Returns the current parameter map, or null if a map has not yet been set. Derived classes will typically override this method to provide a parameter map based on data members set by specialized setter methods.
      Returns:
        The current parameter map.

    - #### setParameters

          public void setParameters(java.util.Map<java.lang.String,java.lang.Object> parameters)

      Sets the current parameter map.
      Parameters:
        `parameters` - The parameter map to use

    - #### getTimeout

          public java.lang.Integer getTimeout()

      Returns the current timeout setting in milliseconds for this Command.
      Returns:
        The current command timeout setting. Null means defer to Connection timeout. 0 means no timeout.

    - #### setTimeout

          public void setTimeout(java.lang.Integer timeout)

      Sets the timeout for this Command. The value of the timeout parameter should be the maximum number of milliseconds this command should wait for a response from the server.
      Parameters:
        `timeout` - The new timeout setting, with null meaning defer to the Connection and 0 meaning wait indefinitely.

    - #### execute

          public ResponseType execute(Connection connection,
                                      java.lang.String folderPath)
                               throws java.io.IOException,
                                      CommandException

      Executes the command in the given folder on the specified connection, and returns information about the response.

      The `folderPath` parameter must be a valid folder path on the server referenced by `connection`. To execute the command in the root container, pass null for this parameter. Note however that executing commands in the root container is typically useful only for administrator level operations.

      The command will be executed against the server, using the credentials setup in the `connection` object. If the server is invalid or the user does not have sufficient permissions, a `CommandException` will be thrown with the 403 (Forbidden) HTTP status code.

      Note that the command is executed synchronously, so the calling code will block until the entire response has been read from the server. To execute a command asynchronously, use a separate thread.

      If the server returns an error HTTP status code (>= 400), this method will throw an instance of `CommandException`. Use its methods to determine the cause of the error.

      Parameters:
        `connection` - The connection on which this command should be executed.
        `folderPath` - The folder path in which to execute the command (e.g., "My Project/My Folder/My sub-folder"). You may also pass null to execute the command in the root container (usually requires site admin permission).
      Returns:
        A CommandResponse (or derived class), which provides access to the returned text/data.
      Throws:
        `CommandException` - Thrown if the server returned a non-success status code.
        `java.io.IOException` - Thrown if there was an IO problem.

    - #### _execute

          protected Command.Response _execute(Connection connection,
                                              java.lang.String folderPath)
                                       throws CommandException,
                                              java.io.IOException

      NOTE: Internal experimental API for handling streaming commands.
      Throws:
        `CommandException`
        `java.io.IOException`

    - #### createResponse

          protected ResponseType createResponse(java.lang.String text,
                                                int status,
                                                java.lang.String contentType,
                                                org.json.simple.JSONObject json)

      Creates an instance of the response class, initialized with the response text, the HTTP status code, and parsed JSONObject.

      Override this method to create an instance of a different class that extends CommandResponse

      Parameters:
        `text` - The response text from the server.
        `status` - The HTTP status code.
        `contentType` - The Content-Type header value.
        `json` - The parsed JSONObject (or null if no JSON was returned).
      Returns:
        An instance of the response object.

    - #### getHttpRequest

          protected org.apache.http.client.methods.HttpUriRequest getHttpRequest(Connection connection,
                                                                                 java.lang.String folderPath)
                                                                          throws CommandException,
                                                                                 java.net.URISyntaxException

      Returns the appropriate, initialized HttpUriRequest implementation. Extended classes may override this to change the way the HTTP method is initialized

      Note that this method initializes the object created by the `createRequest()` call. Extended classes should override that method to change which type of HttpUriRequest gets created, and this one to change how it gets initialized.

      Parameters:
        `connection` - The Connection against which the request will be executed.
        `folderPath` - The folder path in which the command will be executed. This and the base URL from the connection will be used to construct the first part of the URL.
      Returns:
        The constructed HttpUriRequest instance.
      Throws:
        `CommandException` - Thrown if there is a problem encoding or parsing the URL
        `java.net.URISyntaxException` - Thrown if there is a problem parsing the base URL in the connection.

    - #### createRequest

          protected org.apache.http.client.methods.HttpUriRequest createRequest(java.net.URI uri)

      Creates the appropriate HttpUriRequest instance. Override to create something other than `HttpGet`.
      Returns:
        The HttpUriRequest instance.

    - #### getActionUrl

          protected java.net.URI getActionUrl(Connection connection,
                                              java.lang.String folderPath)
                                       throws java.net.URISyntaxException

      Returns the portion of the URL before the query string for this command.

      Note that the URL returned should not be encoded, as the calling function will encode it.

      For example: "http://localhost:8080/labkey/MyProject/MyFolder/selectRows.api"

      Parameters:
        `connection` - The connection to use.
        `folderPath` - The folder path to use.
      Returns:
        The URL
      Throws:
        `java.net.URISyntaxException`

    - #### getQueryString

          protected java.lang.String getQueryString()
                                             throws CommandException

      Returns the query string portion of the URL for this command.

      The parameters in the query string should be encoded to avoid parsing errors on the server.

      Returns:
        The query string
      Throws:
        `CommandException` - Thrown if there is a problem encoding the query string parameter names or values

    - #### getParamValueAsString

          protected java.lang.String getParamValueAsString(java.lang.Object param,
                                                           java.lang.String name)

      Returns an appropriate string encoding of the parameter value.

      Extended classes may wish to override this method to do special string encoding of particular parameter data types. This class will simply return the results of `param.toString()`.

      Parameters:
        `param` - The parameter value
        `name` - The parameter name
      Returns:
        The string form of the parameter value.

    - #### getRequiredVersion

          public double getRequiredVersion()

      Returns the required version number of this API call.
      Returns:
        The required version number

    - #### setRequiredVersion

          public void setRequiredVersion(double requiredVersion)

      Sets the required version number for this API call. By default, the required version is 8.3, meaning that this call requires LabKey Server version 8.3 or higher. Set this to a higher number to required a later version of the server.
      Parameters:
        `requiredVersion` - The new required version

    - #### copy

          public Command copy()

      Returns a copy of this object. Derived classes should override this to copy their own data members
      Returns:
        A copy of this object