de.sekmi.li2b2.client

Class Li2b2Client

java.lang.Object

de.sekmi.li2b2.client.Li2b2Client

public class Li2b2Client
extends Object

Client application to programmatically access any i2b2 server installation.

For simple initialisation/authentication, you can use the convenience method initializeClient(String, String, String, String, String, String) which returns a fully usable client instance.

Detailed initialisation is as follows: To connect to i2b2 webservices, call the following methods: setProxy(URL), setPM(URL), setAuthorisation(String, String, String, boolean) and PM().requestUserConfiguration(). The returned UserConfiguration must then be used for further configuration e.g. set the project via setProjectId(String) and setServices(Cell[]) (with UserConfiguration.getCells()).

To find the values needed for the initial configuration, you can look at the contents of /webclient/i2b2_config_data.js of your target i2b2 server.

For a code example, see src/test/java/de/sekmi/li2b2/client/TestClient.java. See also the file README.md.

Author:

R.W.Majeed

Constructor Summary

Constructors

Constructor and Description
Li2b2Client() Construct a new client instance.

Method Summary

Modifier and Type	Method and Description
QueryClient	CRC()
protected HiveRequest	createRequest(DocumentBuilder builder)
Credentials	getCredentials() Get credentials used for all API calls to the server.
MessageLogger	getMessageLog() Get the message logger.
String	getOutputEncoding()
String	getProjectId() Get the project ID
URL	getProxy()
String	getUserDomain()
String	getUserLogin()
static Li2b2Client	initializeClient(String i2b2_proxy, String i2b2_pm_service, String i2b2_domain, String i2b2_user, String i2b2_pass, String i2b2_project) Convenience method to obtain an initialized client instance.
OntologyClient	ONT()
Document	parseXML(InputStream in)
Document	parseXML(String document)
PMClient	PM() Get the PM cell client services.
void	setAuthorisation(String user, String password, String domain) Deprecated.
void	setAuthorisation(String user, String password, String domain, boolean isToken) Deprecated.
void	setCRC(String uri)
void	setCredentials(Credentials credentials)
void	setCredentials(String domain, String user, String password) Set login credentials for password based authentication.
void	setMessageLog(MessageLogger log) Set a message logger which will receive all sent and received messages.
void	setONT(String uri) Set the Ontology Service URI.
void	setPM(URL pmService) Set the PM service URL.
void	setProjectId(String projectId) Set the project id which will be used during hive communcations.
void	setProxy(URL proxy) Use a reverse proxy configuration (proprietary protocol by i2b2) if the i2b2 webservices are not directly available via network.
void	setServices(Cell[] cells) Initialize services using URIs from the provided Cell[] structure.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Li2b2Client

public Li2b2Client()

Construct a new client instance.

Method Detail

setProjectId

public void setProjectId(String projectId)

Set the project id which will be used during hive communcations.

Parameters:

projectId - project ID

getProjectId

public String getProjectId()

Get the project ID

Returns:

project id

setProxy

public void setProxy(URL proxy)

Use a reverse proxy configuration (proprietary protocol by i2b2) if the i2b2 webservices are not directly available via network.

If the webservices (e.g. /i2b2/services/PMService) are directly available, you don't need to use this method or can set the argument to null.

If the application server (e.g. Wildfly) is listening only to localhost, then you need to specify the reverse proxy script location. In i2b2 installations, this is commonly the PHP script at /webclient/index.php. If this method is used, you can then specify the local webservice address via setPM(URL) (e.g. http://localhost:8080/i2b2/services/PMService/).

Parameters:

proxy - URL to the i2b2 reverse proxy php script

getProxy

public URL getProxy()

getOutputEncoding

public String getOutputEncoding()

getUserLogin

public String getUserLogin()

getUserDomain

public String getUserDomain()

getMessageLog

public MessageLogger getMessageLog()

Get the message logger. If no message logger is defined, null is returned.

Returns:

message logger or null if undefined.

setMessageLog

public void setMessageLog(MessageLogger log)

Set a message logger which will receive all sent and received messages. For console output, use FormattedMessageLogger.consoleLogger().

Parameters:

log - message logger

setAuthorisation

@Deprecated
public void setAuthorisation(String user,
                                          String password,
                                          String domain,
                                          boolean isToken)

Deprecated.

Set login credentials for password based authentication.

Parameters:

user - user name

password - password

domain - server domain name. The official i2b2 server exects this parameter to match the domain name specified at the server.

isToken - whether specified password argument is a server session token or a password. Set this to false if you are using a real password.

setAuthorisation

@Deprecated
public void setAuthorisation(String user,
                                          String password,
                                          String domain)

Deprecated.

Set login credentials for password based authentication. This method is deprecated. Please use setCredentials(String, String, String).

Parameters:

user - user name

password - password

domain - server domain name

setCredentials

public void setCredentials(String domain,
                           String user,
                           String password)

Set login credentials for password based authentication. This method is the same as setAuthorisation(String, String, String, boolean) with the last argument set to false.

Parameters:

user - user name

password - password

domain - server domain name

setCredentials

public void setCredentials(Credentials credentials)

getCredentials

public Credentials getCredentials()

Get credentials used for all API calls to the server.

Returns:

credentials/token information

setPM

public void setPM(URL pmService)

Set the PM service URL. The URL must be a complete URL including protocol scheme.

This url can be behind the reverse proxy if, if the reverse proxy was specified via setProxy(URL). E.g. http://localhost:9090/i2b2/services/PMService/ for some i2b2 demo VMs.

Parameters:

pmService - PM service URL

setONT

public void setONT(String uri)
            throws MalformedURLException

Set the Ontology Service URI. The URI is resolved using the PM service URL. Therefore relative paths or paths without scheme are ok (e.g. /i2b2/services/QueryToolService).

Parameters:

uri - URI to ontology service.

Throws:

MalformedURLException - for invalid URL strings

setCRC

public void setCRC(String uri)
            throws MalformedURLException

Throws:

MalformedURLException

PM

public PMClient PM()

Get the PM cell client services.

Returns:

PM client services

ONT

public OntologyClient ONT()

CRC

public QueryClient CRC()

createRequest

protected HiveRequest createRequest(DocumentBuilder builder)

setServices

public void setServices(Cell[] cells)
                 throws MalformedURLException

Initialize services using URIs from the provided Cell[] structure. XXX URI/URL exceptions are not thrown. instead a warning is logged.

Parameters:

cells - information about available cells

Throws:

MalformedURLException - for invalid cell URL strings

initializeClient

public static Li2b2Client initializeClient(String i2b2_proxy,
                                           String i2b2_pm_service,
                                           String i2b2_domain,
                                           String i2b2_user,
                                           String i2b2_pass,
                                           String i2b2_project)
                                    throws MalformedURLException,
                                           HiveException

Convenience method to obtain an initialized client instance. Parameters i2b2_proxy and i2b2_project are optional. If no proxy is specified, a direct connection to the PM service is attempted. If no project is specified, it is assumed that the user has only a single project available which's id is obtained from the server. If multiple projects are available, this method fails.

Parameters:

i2b2_proxy - i2b2 proxy endpoint. Commonly https://yourserver/webclient/index.php.

i2b2_pm_service - i2b2 project management service endpoint URL.

i2b2_domain - i2b2 domain name, needed for authentication

i2b2_user - i2b2 user name

i2b2_pass - password

i2b2_project - project name to use for further API calls. If not specified, determined from the server.

Returns:

initialized client instance

Throws:

MalformedURLException - malformed URL for i2b2_proxy or i2b2_pm_service

HiveException - communication error with the server

parseXML

public Document parseXML(InputStream in)
                  throws IOException

Throws:

IOException

parseXML

public Document parseXML(String document)
                  throws IOException

Throws:

IOException