public class Connection
extends java.lang.Object
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.
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.
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.
|
Modifier and Type | Method and Description |
---|---|
Connection |
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) |
protected org.apache.http.impl.client.HttpClientBuilder |
clientBuilder()
Create the HttpClientBuilder based on this Connection's configuration options.
|
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()
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.
|
Connection |
setAcceptSelfSignedCerts(boolean acceptSelfSignedCerts)
Sets the accept self-signed certificates option.
|
Connection |
setProxy(java.lang.String host,
java.lang.Integer port)
Sets the proxy host and port for this Connection.
|
Connection |
setTimeout(java.lang.Integer timeout)
Set a default timeout for Commands that have not established their own timeouts.
|
public Connection(java.lang.String baseUrl, CredentialsProvider credentialsProvider)
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.
baseUrl
- The base URLcredentialsProvider
- A credentials providerpublic Connection(java.lang.String baseUrl) throws java.net.URISyntaxException, java.io.IOException
baseUrl
- The base URLjava.net.URISyntaxException
- if the given url is not a valid URIjava.io.IOException
- if there are problems reading the credentialsConnection(String, CredentialsProvider)
public Connection(java.lang.String baseUrl, java.lang.String email, java.lang.String password)
This is equivalent to calling Connection(baseUrl, new BasicAuthCredentialsProvider(email, password))
.
baseUrl
- The base URLemail
- The user email address to pass for authenticationpassword
- The user password to send for authenticationConnection(String, CredentialsProvider)
public java.lang.String getBaseUrl()
public org.apache.http.impl.client.CloseableHttpClient getHttpClient()
protected org.apache.http.impl.client.HttpClientBuilder clientBuilder()
protected void beforeExecute(org.apache.http.HttpRequest request)
protected void afterExecute()
public org.apache.http.impl.client.CloseableHttpClient ensureAuthenticated() throws java.io.IOException, CommandException
java.io.IOException
- if there is an IO problem executing the command to ensure loginCommandException
- if the server returned a non-success status code.public Connection setTimeout(java.lang.Integer timeout)
timeout
- the length of the timeout waiting for the server response, in millisecondspublic int getTimeout()
public Connection setProxy(java.lang.String host, java.lang.Integer port)
host
- the proxy hostport
- the proxy portpublic boolean isAcceptSelfSignedCerts()
public Connection setAcceptSelfSignedCerts(boolean acceptSelfSignedCerts)
acceptSelfSignedCerts
- set to false to not accept self-signed certificatespublic Connection addCookie(java.lang.String name, java.lang.String value, java.lang.String domain, java.lang.String path, java.util.Date expiry, boolean isSecure)
name
- The cookie namevalue
- The cookie valuedomain
- The domain to which the cookie is visiblepath
- The path to which the cookie is visibleexpiry
- The cookie's expiration dateisSecure
- Whether the cookie requires a secure connection