org.labkey.remoteapi

Class Connection

java.lang.Object

org.labkey.remoteapi.Connection

public class Connection
extends java.lang.Object

Represents connection information for a particular LabKey Server.

Create an instance of this class for each server you wish to interact with. If the commands you execute reference data that requires a login, you must also set an email address and password to be used for authentication. Typically, developers will obtain these credentials from the program's environment, such as via command-line parameters, environment variables, a properties file, etc.

After creating and initializing the Connection instance, pass it to the Command.execute() method.

Example:

     Connection cn = new Connection("https://labkey.org");
     SelectRowsCommand cmd = new SelectRowsCommand("study", "Physical Exam");
     SelectRowsResponse response = cmd.execute(cn, "Home/Study/demo");
     for(Map<String,Object> row : response.getRows())
     {
         System.out.println(row.get("ParticipantId") + " weighs " + row.get("Weight"));
     }
 

Example using Authentication

     //get the user email and password from command-line arguments,
     //environment variables, a file, or some other mechanism.
     String user = getUser();
     String password = getPassword();

     //create a new connection passing the user credentials
     Connection cn = new Connection("https://localhost:8080/labkey", user, password);
     SelectRowsCommand cmd = new SelectRowsCommand("lists", "People");
     SelectRowsResponse response = cmd.execute(cn, "Api Test");
 

Note that this class is not thread-safe. Do not share instances of Connection between threads.

Version:

1.0

Author:

Dave Stearns, LabKey Corporation

Constructor Summary

Constructors

Constructor and Description
Connection(java.lang.String baseUrl) Constructs a new Connection object given a base URL.
Connection(java.lang.String baseUrl, java.lang.String email, java.lang.String password) Constructs a new Connection object given a base URL and user credentials.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	afterExecute(org.apache.commons.httpclient.HttpClient client, org.apache.commons.httpclient.HttpMethod method, int status)
protected void	beforeExecute(org.apache.commons.httpclient.HttpClient client, org.apache.commons.httpclient.HttpMethod method)
int	executeMethod(org.apache.commons.httpclient.HttpMethod method)
java.lang.String	getBaseUrl() Returns the base URL for this connection.
protected org.apache.commons.httpclient.HttpConnectionManager	getConnectionManager() Returns the connection manager to use when initializing the HttpClient object.
java.lang.String	getEmail() Returns the email address to use for authentication.
org.apache.commons.httpclient.HttpClient	getHttpClient() Returns the HttpClient object to use for this connection.
java.lang.String	getPassword() Returns the password to use for authentication.
java.lang.Integer	getTimeout() The default timeout for Commands that have not established their own timeouts.
boolean	isAcceptSelfSignedCerts() Returns true if the connection should accept a self-signed SSL certificate when using HTTPS, false otherwise.
void	setAcceptSelfSignedCerts(boolean acceptSelfSignedCerts) Sets the accept self-signed certificates option.
void	setEmail(java.lang.String email) Sets the email address to use for authentication.
void	setPassword(java.lang.String password) Sets the password to use for authentication.
void	setTimeout(java.lang.Integer timeout) Set a default timeout for Commands that have not established their own timeouts.

Methods inherited from class java.lang.Object

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

Constructor Detail

Connection

public Connection(java.lang.String baseUrl)

Constructs a new Connection object given a base URL.

This is equivalent to calling Connection(baseUrl, null, null).

Parameters:

baseUrl - The base URL

See Also:

Connection(String, String, String)

Connection

public Connection(java.lang.String baseUrl,
          java.lang.String email,
          java.lang.String password)

Constructs a new Connection object given a base URL and user credentials.

The baseUrl parameter should include the protocol, domain name, port, and LabKey web application context path (if configured). For example in a typical localhost configuration, the base URL would be:

http://localhost:8080/labkey

Note that https may also be used for the protocol. By default the Connection is configured to accept self-signed SSL certificates, which is fairly common for LabKey Server installations. If you do not want to accept self-signed certificates, use setAcceptSelfSignedCerts(false) to disable this behavior.

The email name and password should correspond to a valid user email and password on the target server.

Parameters:

baseUrl - The base URL

email - The user email name to pass for authentication

password - The user password to send for authentication

Method Detail

getBaseUrl

public java.lang.String getBaseUrl()

Returns the base URL for this connection.

Returns:

The base URL.

getEmail

public java.lang.String getEmail()

Returns the email address to use for authentication.

Returns:

The email address.

setEmail

public void setEmail(java.lang.String email)

Sets the email address to use for authentication.

Parameters:

email - The email address to use.

getPassword

public java.lang.String getPassword()

Returns the password to use for authentication.

Returns:

The password.

setPassword

public void setPassword(java.lang.String password)

Sets the password to use for authentication.

Parameters:

password - The password to use.

isAcceptSelfSignedCerts

public boolean isAcceptSelfSignedCerts()

Returns true if the connection should accept a self-signed SSL certificate when using HTTPS, false otherwise. Defaults to true.

Returns:

true or false

setAcceptSelfSignedCerts

public void setAcceptSelfSignedCerts(boolean acceptSelfSignedCerts)

Sets the accept self-signed certificates option. Set to false to disable automatic acceptance of self-signed SSL certificates when using HTTPS.

Parameters:

acceptSelfSignedCerts - set to false to not accept self-signed certificates

getHttpClient

public org.apache.commons.httpclient.HttpClient getHttpClient()
                                                       throws org.apache.commons.httpclient.URIException

Returns the HttpClient object to use for this connection.

Returns:

The HttpClient object to use.

Throws:

org.apache.commons.httpclient.URIException - Thrown if the base URL could not be converted into a legal URI.

beforeExecute

protected void beforeExecute(org.apache.commons.httpclient.HttpClient client,
                 org.apache.commons.httpclient.HttpMethod method)

afterExecute

protected void afterExecute(org.apache.commons.httpclient.HttpClient client,
                org.apache.commons.httpclient.HttpMethod method,
                int status)

executeMethod

public int executeMethod(org.apache.commons.httpclient.HttpMethod method)
                  throws java.io.IOException,
                         org.apache.commons.httpclient.HttpException

Throws:

java.io.IOException

org.apache.commons.httpclient.HttpException

getConnectionManager

protected org.apache.commons.httpclient.HttpConnectionManager getConnectionManager()

Returns the connection manager to use when initializing the HttpClient object. By default, this method returns a MultiThreadedHttpConnectionManager. Override to use a different one.

Returns:

The connection manager to use.

setTimeout

public void setTimeout(java.lang.Integer timeout)

Set a default timeout for Commands that have not established their own timeouts. Null indicates that the Connection doesn't specify a timeout preference. 0 means the request should never timeout.

Parameters:

timeout - the length of the timeout waiting for the server response, in milliseconds

getTimeout

public java.lang.Integer getTimeout()

The default timeout for Commands that have not established their own timeouts. Null indicates that the Connection doesn't specify a timeout preference. 0 means the request should never timeout.

Returns:

the length of the timeout waiting for the server response, in milliseconds