Package org.labkey.remoteapi

Class Command<ResponseType extends CommandResponse,RequestType extends org.apache.hc.client5.http.classic.methods.HttpUriRequest>

java.lang.Object

org.labkey.remoteapi.Command<ResponseType,RequestType>

All Implemented Interfaces:

HasRequiredVersion

Direct Known Subclasses:

GetCommand, PostCommand

public abstract class Command<ResponseType extends CommandResponse,RequestType extends org.apache.hc.client5.http.classic.methods.HttpUriRequest>
extends Object
implements HasRequiredVersion

Abstract base class for all API commands. Developers interact with concrete 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.

If a developer wishes to invoke actions that are not yet supported with a specialized class in this library, the developer may invoke these APIs by creating an instance of the SimpleGetCommand or SimplePostCommand classes, providing the controller and action name for the API, and setting parameters or JSON to send.

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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	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	Description
static final String	CONTENT_TYPE_JSON	A constant for the official JSON content type ("application/json")

Constructor Summary

Constructors

Constructor	Description
Command(String controllerName, String actionName)	Constructs a new Command object for calling the specified API action on the specified controller.

Method Summary

Modifier and Type	Method	Description
protected Command.Response	_execute(Connection connection, String folderPath)
protected Map<String,Object>	createParameterMap()	Returns a new, mutable parameter map.
protected abstract RequestType	createRequest(URI uri)	Creates the appropriate HttpUriRequest instance.
protected ResponseType	createResponse(String text, int status, String contentType, org.json.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, String folderPath)	Executes the command in the given folder on the specified connection, and returns information about the response.
String	getActionName()	Returns the action name specified when constructing this object.
String	getControllerName()	Returns the controller name specified when constructing this object.
protected RequestType	getHttpRequest(Connection connection, String folderPath)	Returns the appropriate, initialized HttpUriRequest implementation.
final Map<String,Object>	getParameters()	Makes an immutable copy of the parameter map used for building the URL available to callers.
protected String	getParamValueAsString(Object param, String name)	Returns an appropriate string encoding of the parameter value.
double	getRequiredVersion()	Returns the required version number of this API call.
Integer	getTimeout()	Returns the current timeout setting in milliseconds for this Command.
void	setRequiredVersion(double requiredVersion)	Sets the required version number for this API call.
void	setTimeout(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 Details

CONTENT_TYPE_JSON

public static final String CONTENT_TYPE_JSON

A constant for the official JSON content type ("application/json")

See Also:

• Constant Field Values

Constructor Details

Command

public Command(String controllerName,
 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

Method Details

getControllerName

public String getControllerName()

Returns the controller name specified when constructing this object.

Returns:

The controller name.

getActionName

public String getActionName()

Returns the action name specified when constructing this object.

Returns:

The action name.

getParameters

public final Map<String,Object> getParameters()

Makes an immutable copy of the parameter map used for building the URL available to callers. Typically used for logging and testing.

Returns:

An immutable map of parameters used when building the URL.

createParameterMap

protected Map<String,Object> createParameterMap()

Returns a new, mutable parameter map. Derived classes will typically override this method to put values passed to specialized setter methods into the map.

Returns:

The parameter map to use when building the URL.

getTimeout

public 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(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,
 String folderPath)
                     throws 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.

IOException - Thrown if there was an IO problem.

_execute

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

Throws:

CommandException

IOException

createResponse

protected ResponseType createResponse(String text,
 int status,
 String contentType,
 org.json.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 RequestType getHttpRequest(Connection connection,
 String folderPath)
                              throws 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:

URISyntaxException - Thrown if there is a problem parsing the base URL in the connection.

createRequest

protected abstract RequestType createRequest(URI uri)

Creates the appropriate HttpUriRequest instance. Override to create HttpGet, HttpPost, etc.

Parameters:

uri - the uri to convert

Returns:

The HttpUriRequest instance.

getParamValueAsString

protected String getParamValueAsString(Object param,
 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.

Specified by:

getRequiredVersion in interface HasRequiredVersion

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 require a later version of the server.

Parameters:

requiredVersion - The new required version