Connection (LabKey Client API Library for Java Documentation)

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 require a login, you must also configure authentication via one of the supported methods: retrieving email address and password from a .netrc/_netrc file, providing an api key, or providing email address and password directly (which could be obtained from the program's environment, such as via command-line parameters, environment variables, a properties file, etc. See the individual constructors and implementations of CredentialsProvider for more details.

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 with a base URL that attempts authentication via .netrc/_netrc entry, if present.
`Connection(java.lang.String baseUrl, CredentialsProvider credentialsProvider)` Constructs a new Connection object given a base URL and a credentials provider.
`Connection(java.lang.String baseUrl, java.lang.String email, java.lang.String password)` Constructs a new Connection object for a base URL that attempts basic authentication.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addCookie(java.lang.String name, java.lang.String value, java.lang.String domain, java.lang.String path, java.util.Date expiry, boolean isSecure)`
`protected void`	`afterExecute()`
`protected void`	`beforeExecute(org.apache.http.HttpRequest request)`
`org.apache.http.impl.client.CloseableHttpClient`	`ensureAuthenticated()` Ensures that the credentials have been used to authenticate the users and returns a client that can be used for other requests
`java.lang.String`	`getBaseUrl()` Returns the base URL for this connection.
`org.apache.http.impl.client.CloseableHttpClient`	`getHttpClient(int timeout)` Returns the CloseableHttpClient object to use for this connection.
`int`	`getTimeout()` The timeout used 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`	`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,
                  CredentialsProvider credentialsProvider)
```
    Constructs a new Connection object given a base URL and a credentials provider.
    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 deny self-signed SSL certificates. If you want to accept self-signed certificates, use setAcceptSelfSignedCerts(false) to enable 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
    
    credentialsProvider - A credentials provider
  - Connection
```
public Connection(java.lang.String baseUrl)
           throws java.net.URISyntaxException,
                  java.io.IOException
```
    Constructs a new Connection object with a base URL that attempts authentication via .netrc/_netrc entry, if present. If not present, connects as guest.
    
    Parameters:
    
    baseUrl - The base URL
    
    Throws:
    
    java.net.URISyntaxException
    
    java.io.IOException
    
    See Also:
    
    Connection(String, CredentialsProvider)
  - Connection
```
public Connection(java.lang.String baseUrl,
                  java.lang.String email,
                  java.lang.String password)
```
    Constructs a new Connection object for a base URL that attempts basic authentication.
    This is equivalent to calling Connection(baseUrl, new BasicAuthCredentialsProvider(email, password)).
    
    Parameters:
    
    baseUrl - The base URL
    
    email - The user email address to pass for authentication
    
    password - The user password to send for authentication
    
    See Also:
    
    Connection(String, CredentialsProvider)
- Method Detail
  - getBaseUrl
```
public java.lang.String getBaseUrl()
```
    Returns the base URL for this connection.
    
    Returns:
    
    The base URL.
  - 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.http.impl.client.CloseableHttpClient getHttpClient(int timeout)
```
    Returns the CloseableHttpClient object to use for this connection.
    
    Parameters:
    
    timeout - The socket timeout for this request
    
    Returns:
    
    The CloseableHttpClient object to use.
  - beforeExecute
```
protected void beforeExecute(org.apache.http.HttpRequest request)
```
  - afterExecute
```
protected void afterExecute()
```
  - ensureAuthenticated
```
public org.apache.http.impl.client.CloseableHttpClient ensureAuthenticated()
                                                                    throws java.io.IOException,
                                                                           org.apache.http.auth.AuthenticationException,
                                                                           CommandException
```
    Ensures that the credentials have been used to authenticate the users and returns a client that can be used for other requests
    
    Throws:
    
    java.io.IOException
    
    org.apache.http.auth.AuthenticationException
    
    CommandException
  - setTimeout
```
public void setTimeout(java.lang.Integer timeout)
```
    Set a default timeout for Commands that have not established their own timeouts. Null resets the Connection to the default timeout (60 seconds). 0 means the request should never timeout.
    
    Parameters:
    
    timeout - the length of the timeout waiting for the server response, in milliseconds
  - getTimeout
```
public int getTimeout()
```
    The timeout used for Commands that have not established their own timeouts. 0 means the request should never timeout.
    
    Returns:
    
    the length of the timeout waiting for the server response, in milliseconds
  - addCookie
```
public void addCookie(java.lang.String name,
                      java.lang.String value,
                      java.lang.String domain,
                      java.lang.String path,
                      java.util.Date expiry,
                      boolean isSecure)
```
    Parameters:
    
    name - The cookie name
    
    value - The cookie value
    
    domain - The domain to which the cookie is visible
    
    path - The path to which the cookie is visible
    
    expiry - The cookie's expiration date
    
    isSecure - Whether the cookie requires a secure connection

Class Connection

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Connection

Connection

Connection

Method Detail

getBaseUrl

isAcceptSelfSignedCerts

setAcceptSelfSignedCerts

getHttpClient

beforeExecute

afterExecute

ensureAuthenticated

setTimeout

getTimeout

addCookie