public class Command<ResponseType extends CommandResponse>
extends java.lang.Object
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.
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.
|
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
CONTENT_TYPE_JSON
A constant for the official JSON content type ("application/json")
|
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.
|
Modifier and Type | Method and Description |
---|---|
protected Command.Response |
_execute(Connection connection,
java.lang.String folderPath) |
protected void |
checkThrowError(Command.Response response) |
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.
|
public static final java.lang.String CONTENT_TYPE_JSON
public Command(java.lang.String controllerName, java.lang.String actionName)
controllerName
- The name of the controller from which the action is exposedactionName
- The name of the action to callpublic Command(Command<ResponseType> source)
source
- A source Commandpublic java.lang.String getControllerName()
public java.lang.String getActionName()
public java.util.Map<java.lang.String,java.lang.Object> getParameters()
public void setParameters(java.util.Map<java.lang.String,java.lang.Object> parameters)
parameters
- The parameter map to usepublic java.lang.Integer getTimeout()
public void setTimeout(java.lang.Integer timeout)
timeout
- The new timeout setting, with null meaning defer to the Connection and 0 meaning wait indefinitely.public ResponseType execute(Connection connection, java.lang.String folderPath) throws java.io.IOException, CommandException
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.
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).CommandException
- Thrown if the server returned a non-success status code.java.io.IOException
- Thrown if there was an IO problem.protected Command.Response _execute(Connection connection, java.lang.String folderPath) throws CommandException, java.io.IOException
CommandException
java.io.IOException
protected void checkThrowError(Command.Response response) throws java.io.IOException, CommandException
java.io.IOException
CommandException
protected ResponseType createResponse(java.lang.String text, int status, java.lang.String contentType, org.json.simple.JSONObject json)
Override this method to create an instance of a different class that extends CommandResponse
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).protected org.apache.http.client.methods.HttpUriRequest getHttpRequest(Connection connection, java.lang.String folderPath) throws CommandException, java.net.URISyntaxException
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.
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.CommandException
- Thrown if there is a problem encoding or parsing the URLjava.net.URISyntaxException
- Thrown if there is a problem parsing the base URL in the connection.protected org.apache.http.client.methods.HttpUriRequest createRequest(java.net.URI uri)
HttpGet
.uri
- the uri to convertprotected java.net.URI getActionUrl(Connection connection, java.lang.String folderPath) throws java.net.URISyntaxException
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"
connection
- The connection to use.folderPath
- The folder path to use.java.net.URISyntaxException
- if the uri constructed from the parameters is malformedprotected java.lang.String getQueryString() throws CommandException
The parameters in the query string should be encoded to avoid parsing errors on the server.
CommandException
- Thrown if there is a problem encoding the query string parameter names or valuesprotected java.lang.String getParamValueAsString(java.lang.Object param, java.lang.String name)
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()
.
param
- The parameter valuename
- The parameter namepublic double getRequiredVersion()
public void setRequiredVersion(double requiredVersion)
requiredVersion
- The new required versionpublic Command copy()