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. 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)
MessageLogger	getMessageLog() Get the message logger.
String	getOutputEncoding()
String	getProjectId() Get the project ID
URL	getProxy()
String	getUserDomain()
String	getUserLogin()
OntologyClient	ONT()
Document	parseXML(InputStream in)
PMClient	PM() Get the PM cell client services.
void	setAuthorisation(Credentials credentials)
void	setAuthorisation(String user, String password, String domain) Set login credentials for password based authentication.
void	setAuthorisation(String user, String password, String domain, boolean isToken) Set login credentials for password based authentication.
void	setCRC(String uri)
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

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

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

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

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

setAuthorisation

public void setAuthorisation(Credentials credentials)

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

parseXML

public Document parseXML(InputStream in)
                  throws IOException

Throws:

IOException