Class: DSILibrary

Create an instance of the DSILibrary class to interact with the Mobile Enterprise Platform server.

To interact with the Mobile Enterprise Platform server, create an instance of the DSILibrary class, call logonUser with a full-access user with an appropriate role (for example, Mobile Client User) and call the methods for the required interactions. Call logoffUser to end the user session.

Constant

Constant: FunctionCall_Connector_WebServices

Constructors

To return an initialized library instance, use one of the following constructors.

Methods

Constant: FunctionCall_Connector_WebServices

(FunctionCall method - The Web Services connector is defined as the constant DSILibrary_FunctionCall_Connector_WebServices for convenience)

[Body Empty]

Constructor: DSILibrary(ContextWrapper contextWrapper, String deviceId, String hostNameOrAddress, short hostPort)

Constructs an instance of the library with default response and reply timeouts. The default response timeout is 5 seconds. The default reply timeout is 30 seconds.

Declaration

public DSILibrary(ContextWrapper contextWrapper, String deviceId, String hostNameOrAddress, short hostPort)

Parameters

Parameter	Value
contextWrapper	A ContextWrapper for the calling Android application's context.
deviceId	The Device ID for this device. If null or an empty string is passed for this argument, a Device ID will be generated. This value should be retrieved and stored in preferences so it can be reused.
hostNameOrAddress	The host name or address for contacting the Mobile Enterprise Platform communications agent.
hostPort	The port for the Mobile Enterprise Platform communications agent.

Returns

An initialized Library instance.

Exceptions

None

Constructor: DSILibrary(ContextWrapper contextWrapper, String deviceId, String hostNameOrAddress, short hostPort, int responseTimeout, int replyTimeout)

Constructs an instance of the library if you do not want to use the default response and reply timeouts. The default response timeout is 5 seconds. The default reply timeout is 30 seconds .

Declaration

public DSILibrary(ContextWrapper contextWrapper, String deviceId, String hostNameOrAddress, short hostPort,                   int responseTimeout, int replyTimeout)

Parameters

Parameter	Value
contextWrapper	A ContextWrapper for the calling Android application's context.
deviceId	The Device ID for this device. If null or an empty string is passed for this argument, a Device ID will be generated. This value should be retrieved and stored in preferences so it can be reused.
hostNameOrAddress	The host name or address for contacting the Mobile Enterprise Platform communications agent.
hostPort	The port for the Mobile Enterprise Platform communications agent.
responseTimeout	The response timeout for messages to the server. This is the amount of time the library waits for the server to make an initial acknowledgment that a message has been received. This value must be less than the reply timeout.
replyTimeout	The reply timeout for messages to the server. This is the amount of time the library waits for the server to reply to the message. This value must be greater than the response timeout.

Returns

An initialized Library instance.

Exceptions

Exception type	Reason
IllegalArgumentException	The contextWrapper is null. The hostNameOrAddress is null or an empty string. The hostPort is less than 1. The responseTimeout is less than 1. The responseTimeout is greater than the replyTimeout.

Method: getDeviceID

Gets the Device ID that is being used for this device. Use this method to get the Device ID when you have passed null to the constructor to generate a Device ID for this device, and you are saving the generated Device ID for future use.

Declaration

public String getDeviceId()

Parameters

None

Returns

Returns the Device ID for this device.

Exceptions

None

Method: isUserLoggedOn

Determine if the user is currently logged on with the server.

Declaration

public boolean isUserLoggedOn()

Parameters

None

Returns

Returns true if the user is currently logged on with the server.

Exceptions

None

Method: ping

Contacts the server to make sure you can connect.

Declaration

public boolean ping() throws CommunicationException, ServerReplyException

Parameters

None

Returns

Returns true if a connection to the server could be made, or if the server does not reply within the timeout specified.

Exceptions

Exception type	Reason
ServerReplyException	The server returned an error.

Method: getServerVersion

Gets the version of the server.

Declaration

public String getServerVersion() throws CommunicationException, ServerReplyException

Parameters

None

Returns

Returns the version string from the server.

Example: 8.5.3

Exceptions

Exception type	Reason
CommunicationException	Communication with the server cannot be made, or if the server did not reply within the timeout specified.
ServerReplyException	The server returns an error.

Method: logonUser

Verifies the user credentials with the server and starts a session.

Declaration

public void logonUser(String userId, String password)         throws CommunicationException, LogonException, PasswordExpiredException, ServerReplyException

Parameters

Parameter	Value
userId	The ID of the user to verify with the server.
password	The user's password.

Returns

None

Exceptions

Exception type	Reason
CommunicationException	Communication with the server cannot be made, or the server does not reply within the timeout specified
IllegalArgumentException	The userId is null/empty or the password is null.
LogonException	The verification with the server failed. The exception reason will contain the reason the verification failed.
com.dsiglobal.clientlib.PasswordExpiredException	The verification with the server succeeded, but the user's password has expired, and the user needs to change the password before logon can be successful.
ServerReplyException	The server returned an error unrelated to user verification.

Method: changePasswordForUser

Changes the password for a user and logs the user on.

Declaration

public void changePasswordForUser(String userId, String oldPassword, String newPassword)         throws CommunicationException, LogonException, ServerReplyException

Parameters

Parameter	Value
userID	The ID of the user whose password should be changed.
oldPassword	The old password for the user.
newPassword	The new password for the user.

Returns

None

Exceptions

Exception type	Reason
CommunicationException	Communication with the server cannot be made, or if the server did not reply within the timeout specified.
IllegalArgumentException	The userId is null or empty, or the oldPassword or newPassword are null.
LogonException	Verification with the server failed. The exception message contains the reason for the failure.
ServerReplyException	The server returned an error.

Method: logoffUser

Terminates the user session if the session exists. If no user is logged on, logoffUser has no effect.

Declaration

public void logoffUser()

Parameters

None

Returns

None

Exceptions

None

Method: getFile

Downloads a file from the server.

Declaration

public void getFile(String sourceFileServerPath, String destinationFilePath) throws CommunicationException, ServerReplyException, SessionException

Parameters

Parameter	Value
sourceFileServerPath	The server path to the file to download.
destinationFilePath	The local path to which the file should be downloaded.

Returns

None

Exceptions

Exception type	Reason
CommunicationException	Communication with the server cannot be made, or if the server does not reply within the timeout specified.
IllegalArgumentException	The sourceFileServerPath or destinationFilePath are null or empty.
ServerReplyException	The server returned an error.
SessionException	The user hasn't successfully logged in, or has already logged out.

Method: sendFile

Sends a file to the server.

Declaration

public void sendFile(String localFilePath, String destinationFileName) throws CommunicationException, ServerReplyException, SessionException

Parameters

Parameter	Value
localFilePath	The local path to the file to send.
destinationFileName	The server destination file to which the content should be saved.

Returns

None

Exceptions

Exception type	Reason
CommunicationException	Communication with the server cannot be made, or the server doesn't reply in the timeout specified
IllegalArgumentException	The localFilePath string or destinationFileName is null or empty, or the localFilePath points to a file that doesn't exist or is a directory.
ServerReplyException	The server returned an error.
SessionException	The user hasn't successfully logged in or has already logged out.

Method: download

Downloads data from a table registered on the server.

Declaration

public String[][] download(String sqlStatement, String[] replacementValues, String connectionId,                                              String environment) throws CommunicationException, ServerReplyException, SessionException

Parameters

Parameter	Value
sqlStatement	The SQL statement to execute to download the data.
replacementValues	The replacement values for parameters in the SQL statement (can be null or empty if there are no parameters in the SQL statement).
connectionId	The registered connection ID on which to execute the SQL statement.
environment	The environment in which to execute the SQL statement.

Returns

Return the rows downloaded from the table. Each item in the array is a row in the table. Each row array contains the table column values.

Exceptions

Exception type	Reason
CommunicationException	Communication with the server cannot be made, or if the server does not reply within the timeout specified.
IllegalArgumentException	The sqlStatement, connectionId, or environment are null or empty.
ServerReplyException	The server returned an error.
SessionException	The user hasn't successfully logged in or has already logged out.

Method: executeSqlStatement

Executes a SQL statement on the server.

Declaration

public int executeSqlStatement(String sqlStatement, String[] replacementValues, String connectionId,                                String environment, String trackingReference) throws CommunicationException, ServerReplyException, SessionException

Parameters

Parameter	Value
sqlStatement	The SQL statement to execute to insert/update/delete records.
replacementValues	The replacement values for parameters in the SQL statement (can be null or empty if there are no parameters in the SQL statement).
connectionId	The registered connection ID on which to execute the SQL statement.
environment	The environment in which to execute the SQL statement.
trackingReference	The tracking reference string for the transaction log entry for this transaction (null if you aren't using tracking reference).

Returns

Returns the number of rows affected by the transaction.

Exceptions

Exception type	Reason
CommunicationException	Communication with the server cannot be made, or if the server did not reply within the timeout specified.
IllegalArgumentException	The sqlStatement, connectionId, or environment are null or empty.
ServerReplyException	The server returned an error.
SessionException	The user hasn't successfully logged on or has already logged out.

Method: callFunction

Executes a Function Call on the server.

Declaration

public FunctionCallStatus callFunction(String functionName, String functionDefinitionVersion, String connectorName,                                        String environment, boolean isSynchronous, boolean isQueueable,                                        int timeout, boolean storeInTransactionLog, String trackingReference,                                        FunctionCallField[] inputData, FunctionCallField[] outputFields) throws CommunicationException, FunctionCallException, ServerReplyException, SessionException

Parameters

Parameter	Value
functionName	The name of the function to call.
functionDefinitionVersion	The version of the function to call.
connectorName	The name of the connector for the function. Note:The Web Services connector is defined as the constant DSILibrary.FunctionCall_Connector_WebServices for convenience.
environment	The environment for the function call.
isSynchronous	True if the function call should be executed synchronously.
isQueueable	True if the function call is queueable. Note:A function call cannot be queueable if it is synchronous.
timeout	The timeout for this function call, in seconds.
storeInTransactionLog	True if a record of this function call should be stored in this transaction log on the server.
trackingReference	The tracking reference for this function call to be stored in the transaction log. This is not applicable if the call will not be stored in the transaction log. It can be null, even if a transaction log, even if a transaction log record is being written (the tracking reference value will be blank).
inputData	The list of input values for the function call. If the function has no required input, this can be null.
outputFields	The requested output fields.

Returns

None

Exceptions

Exception type	Reason
CommunicationException	Communication with the server cannot be made, or the server does not reply within the timeout specified
FunctionCallException	The function call returns error messages, an unexpected status, or the returned structure does not match the requested data.
ServerReplyException	The server returns an error.
SessionException	The user hasn't successfully logged on or has already logged out.

Method: replicateDatabase

Replicates data from the server to a local SQLite database based on server replication rules for the current user. Requires that logonUser be called first.

Declaration

public String replicateDatabase(String environmentName, boolean forceFullReplication) throws DatabaseReplicationException, SessionException

Parameters

Parameter	Value
environmentName	Name of the environment to replicate.
forceFullReplication	True to force a full replication to replace the current existing database instead of a partial replication.

Returns

Returns the full path name to the database file that was created.

Exceptions

Exception type	Reason
SessionException	User has not successfully logged in, or user has logged out.
DatabaseReplicationException	Replication from the server failed. The exception message contains the reason for the failure.