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