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://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 |
---|---|
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.
|
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 boolean isAcceptSelfSignedCerts()
public void setAcceptSelfSignedCerts(boolean acceptSelfSignedCerts)
acceptSelfSignedCerts
- set to false to not accept self-signed certificatespublic org.apache.http.impl.client.CloseableHttpClient getHttpClient(int timeout)
timeout
- The socket timeout for this requestprotected 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 loginfCommandException
- if the server returned a non-success status code.public void setTimeout(java.lang.Integer timeout)
timeout
- the length of the timeout waiting for the server response, in millisecondspublic int getTimeout()
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)
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