Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.labkey.remoteapi
Class Command<ResponseType extends CommandResponse>

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

Direct Known Subclasses:
  AssayListCommand, BaseQueryCommand, 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
`static class` | `Command.CommonParameters` An enum of common parameter names used in API URLs.

Field Summary
`static java.lang.String` | `CONTENT_TYPE_JSON` A constant for the official JSON content type ("application/json")

Constructor Summary
`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
`Command` | `copy()` Returns a copy of this object.
`protected org.apache.commons.httpclient.HttpMethod` | `createMethod()` Creates the appropriate HttpMethod 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 and the HTTP status code.
`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.lang.String` | `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.commons.httpclient.HttpMethod` | `getHttpMethod(Connection connection, java.lang.String folderPath)` Returns the appropriate, initialized HttpMethod 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.
`int` | `getTimeout()` Returns the current command timeout setting in milliseconds (defaults to 60000).
`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(int timeout)` Sets the current command timeout setting.

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 int getTimeout()

  Returns the current command timeout setting in milliseconds (defaults to 60000).

  Returns:
    The current command timeout setting.

### setTimeout

    public void setTimeout(int timeout)

  Sets the current command timeout setting. The value of the timeout parameter should be the maximum number of milliseconds this command should wait for a response from the server. By default, this is set to 60000 (60 seconds). To wait indefinitely, set this value to 0.

  Parameters:
    `timeout` - The new timeout setting

### execute

    public final 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 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.
    `org.apache.commons.httpclient.HttpException` - Thrown if the HttpClient library generated an exception.
    `java.io.IOException` - Thrown if there was an IO problem.

### 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 and the HTTP status code.

  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.

### getHttpMethod

    protected org.apache.commons.httpclient.HttpMethod getHttpMethod(Connection connection,
                                                                     java.lang.String folderPath)
                                                              throws CommandException,
                                                                     org.apache.commons.httpclient.URIException

  Returns the appropriate, initialized HttpMethod 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 `createMethod()` call. Extended classes should override that method to change which type of HttpMethod gets created, and this one to change how it gets initialized.

  Parameters:
    `connection` - The Connection against which the method 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 HttpMethod instance.
  Throws:
    `CommandException` - Thrown if there is a problem encoding the URL
    `org.apache.commons.httpclient.URIException` - Thrown if there is a problem parsing the base URL in the connection.

### createMethod

    protected org.apache.commons.httpclient.HttpMethod createMethod()

  Creates the appropriate HttpMethod instance. Override to create something other than `GetMethod`.

  Returns:
    The HttpMethod instance.

### getActionUrl

    protected java.lang.String getActionUrl(Connection connection,
                                            java.lang.String folderPath)

  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

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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD