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 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