Package org.labkey.remoteapi

Class Connection

java.lang.Object
org.labkey.remoteapi.Connection
public class Connection extends 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://www.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.

  • Field Details

  • Constructor Details

    • Connection

      public Connection(URI baseURI, CredentialsProvider credentialsProvider)
      Constructs a new Connection object given a base URL and a credentials provider.

      The baseURI 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:

      new URI("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.

      Parameters:
      baseURI - Base URI for this Connection
      credentialsProvider - A credentials provider

    • Connection

      public Connection(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

      Parameters:
      baseUrl - The base URL
      credentialsProvider - A credentials provider
      See Also:

    • Connection

      public Connection(String baseUrl) throws 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:
      IOException - if there are problems reading the credentials
      See Also:

    • Connection

      public Connection(String baseUrl, String email, 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)). The email and password should correspond to a valid user email and password on the target server.

      Parameters:
      baseUrl - The base URL
      email - The user email address to pass for authentication
      password - The user password to send for authentication
      See Also:

  • Method Details

    • getBaseURI

      public URI getBaseURI()
      Returns the base URI for this connection.
      Returns:
      The target LabKey instance's base URI

    • getHttpClient

      public org.apache.hc.client5.http.impl.classic.CloseableHttpClient getHttpClient()
      Returns the CloseableHttpClient object to use for this connection.
      Returns:
      The CloseableHttpClient object to use.

    • beforeExecute

      protected void beforeExecute(org.apache.hc.core5.http.HttpRequest request)
      If first request, prime the Connection by forcing authentication and populating CSRF and session info.
      Parameters:
      request - HttpRequest that is about to be executed

    • afterExecute

      protected void afterExecute()

    • logout

      public void logout() throws IOException, CommandException
      Invalidates the current HTTP session on the server, if any
      Throws:
      IOException - if there is an IO problem executing the command to ensure logout
      CommandException - if the server returned a non-success status code.

    • impersonate

      public Connection impersonate(String email) throws IOException, CommandException
      For site-admins only, start impersonating a user.

      Admins may impersonate other users to perform actions on their behalf. Site admins may impersonate any user in any project. Project admins must provide a projectPath and may only impersonate within the project in which they have admin permission.

      Parameters:
      email - The user to impersonate
      Returns:
      this connection
      Throws:
      IOException - Thrown if there was an IO problem.
      CommandException - if the server returned a non-success status code.
      See Also:

    • impersonate

      public Connection impersonate(String email, String projectPath) throws IOException, CommandException
      For site-admins or project-admins only, start impersonating a user.

      Admins may impersonate other users to perform actions on their behalf. Site admins may impersonate any user in any project. Project admins must provide a projectPath and may only impersonate within the project in which they have admin permission.

      Parameters:
      email - The user to impersonate
      projectPath - The project path within which the user will be impersonated.
      Returns:
      this connection
      Throws:
      IOException - Thrown if there was an IO problem.
      CommandException - if the server returned a non-success status code.
      See Also:

    • stopImpersonating

      public Connection stopImpersonating() throws IOException, CommandException
      Stop impersonating a user.
      Returns:
      this connection
      Throws:
      IOException - Thrown if there was an IO problem.
      CommandException - if the server returned a non-success status code.

    • stopImpersonate

      @Deprecated public Connection stopImpersonate() throws IOException, CommandException
      Deprecated.
      Throws:
      IOException
      CommandException

    • setTimeout

      public Connection setTimeout(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. NOTE: Changing this setting will force the underlying http client to be recreated.
      Parameters:
      timeout - the length of the timeout waiting for the server response, in milliseconds
      Returns:
      this connection

    • 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

    • setProxy

      public Connection setProxy(String host, Integer port)
      Sets the proxy host and port for this Connection.
      NOTE: Changing this setting will force the underlying http client to be recreated.
      Parameters:
      host - the proxy host
      port - the proxy port
      Returns:
      this connection

    • 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 Connection 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.
      NOTE: Changing this setting will force the underlying http client to be recreated.
      Parameters:
      acceptSelfSignedCerts - set to false to not accept self-signed certificates
      Returns:
      this connection

    • getUserAgent

      public String getUserAgent()

    • setUserAgent

      public void setUserAgent(String userAgent)

    • addCookie

      public Connection addCookie(String name, String value, String domain, String path, 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
      Returns:
      this connection