Package com.storedobject.client

Class Client

java.lang.Object

com.storedobject.client.Client

public class Client
extends Object

Client for the SO Platform Connector.

Author:

Syam

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	Client.Data	Structure to wrap an InputStream and its content-type.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	NOT_CONNECTED	Error message when not connected.

Constructor Summary

Constructors

Constructor	Description
Client(String host, String application)	Constructor that defines a secured connection.
Client(String host, String application, boolean secured)	Constructor that defines a secured connection.
Client(String host, String application, int deviceWidth, int deviceHeight)	Constructor that defines a secured connection.
Client(String host, String application, int deviceWidth, int deviceHeight, boolean secured)	Constructor.
Client(String host, String application, String apiKey)	Constructor that defines a secured connection.
Client(String host, String application, String apiKey, boolean secured)	Constructor that defines a secured connection.
Client(String host, String application, String apiKey, int deviceWidth, int deviceHeight)	Constructor that defines a secured connection.
Client(String host, String application, String apiKey, int deviceWidth, int deviceHeight, boolean secured)	Constructor.

Method Summary

Modifier and Type	Method	Description
String	changePassword(String currentPassword, String newPassword)	Change password.
void	close()	Close this instance.
JSON	command(String command, Map<String,Object> attributes)	Send a command and receive a response.
JSON	command(String command, Map<String,Object> attributes, boolean preserveServerState)	Send a command and receive a response.
Client.Data	file(String name)	Retrieve the stream of data for the give file [name].
Throwable	getError()	Get the current error, if any.
static Fault	getFault(JSON json)	Extract fault if any from the given JSON object.
String	login(String clientID)	Login method.
String	login(String username, String password)	Login method.
void	logout()	Logout method.
void	reconnect()	Reconnect the client.
Client.Data	report(String logic)	Run a report and retrieve its output.
Client.Data	report(String logic, Map<String,Object> parameters)	Run a report and retrieve its output.
Client.Data	stream(String name)	Retrieve the stream of data for the [name].
JSON	upload(String mimeType, InputStream data)	Upload new binary content to the server.
JSON	upload(String mimeType, InputStream data, String streamNameOrID)	Upload some binary content to the server.

Methods inherited from class java.lang.Object

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

Field Details

NOT_CONNECTED

public static final String NOT_CONNECTED

Error message when not connected.

See Also:

• Constant Field Values

Constructor Details

Client

public Client(String host,
 String application)

Constructor that defines a secured connection.

Parameters:

host - Host where the SO is hosted.

application - Name of the application (typically, the database name).

Client

public Client(String host,
 String application,
 String apiKey)

Constructor that defines a secured connection.

Parameters:

host - Host where the SO is hosted.

application - Name of the application (typically, the database name).

apiKey - API key (if any).

Client

public Client(String host,
 String application,
 boolean secured)

Constructor that defines a secured connection.

Parameters:

host - Host where the SO is hosted.

application - Name of the application (typically, the database name).

secured - Whether a secured connection (TLS encryption) is required or not.

Client

public Client(String host,
 String application,
 String apiKey,
 boolean secured)

Constructor that defines a secured connection.

Parameters:

host - Host where the SO is hosted.

application - Name of the application (typically, the database name).

apiKey - API key (if any).

secured - Whether a secured connection (TLS encryption) is required or not.

Client

public Client(String host,
 String application,
 int deviceWidth,
 int deviceHeight)

Constructor that defines a secured connection.

Parameters:

host - Host where the SO is hosted.

application - Name of the application (typically, the database name).

deviceWidth - Device width (applicable if you are connecting from a device that has a view-width).

deviceHeight - Device height (applicable if you are connecting from a device that has a view-height).

Client

public Client(String host,
 String application,
 String apiKey,
 int deviceWidth,
 int deviceHeight)

Constructor that defines a secured connection.

Parameters:

host - Host where the SO is hosted.

application - Name of the application (typically, the database name).

apiKey - API key (if any).

deviceWidth - Device width (applicable if you are connecting from a device that has a view-width).

deviceHeight - Device height (applicable if you are connecting from a device that has a view-height).

Client

public Client(String host,
 String application,
 int deviceWidth,
 int deviceHeight,
 boolean secured)

Constructor.

Parameters:

host - Host where the SO is hosted.

application - Name of the application (typically, the database name).

deviceWidth - Device width (applicable if you are connecting from a device that has a view-width).

deviceHeight - Device height (applicable if you are connecting from a device that has a view-height).

secured - Whether a secured connection (TLS encryption) is required or not.

Client

public Client(String host,
 String application,
 String apiKey,
 int deviceWidth,
 int deviceHeight,
 boolean secured)

Constructor.

Parameters:

host - Host where the SO is hosted.

application - Name of the application (typically, the database name).

apiKey - API key (if any).

deviceWidth - Device width (applicable if you are connecting from a device that has a view-width).

deviceHeight - Device height (applicable if you are connecting from a device that has a view-height).

secured - Whether a secured connection (TLS encryption) is required or not.

Method Details

reconnect

public void reconnect()

Reconnect the client.

Note: This will reset everything. However, it knows how to re-log in to the server if required.

getError

public Throwable getError()

Get the current error, if any.

Returns:

Error or null if in any error state.

login

public String login(String clientID)

Login method. One of the login methods should be called first. This method is used when an API key is used to connect.

Parameters:

clientID - Client ID.

Returns:

An empty string is returned if the process is successful. Otherwise, an error message is returned.

login

public String login(String username,
 String password)

Login method. One of the login methods should be called first.

Parameters:

username - Username.

password - Password.

Returns:

An empty string is returned if the process is successful. Otherwise, an error message is returned.

logout

public void logout()

Logout method. This should be invoked if the Client is no more required. If you try to use this instance afterward, it may give unexpected results.

close

public void close()

Close this instance. This should be invoked if the Client is no more required. If you try to use this instance afterward, it may give unexpected results.

Note: This is equivalent to the logout() method.

changePassword

public String changePassword(String currentPassword,
 String newPassword)

Change password.

Parameters:

currentPassword - Current password.

newPassword - New password.

Returns:

An empty string is returned if the password is changed successfully. Otherwise, an error message is returned.

command

public JSON command(String command,
 Map<String,Object> attributes)

Send a command and receive a response.

The [attributes] should contain a map of the parameters. Please refer to the SO Connector documentation for parameter details. Please note that [command] is passed as the first parameter and thus, it need not be specified in the [attributes]. Also, "session" is not required because [Client] will automatically add that.

Parameters:

command - Command.

attributes - Attributes.

Returns:

Response as a JSON instance is returned.

command

public JSON command(String command,
 Map<String,Object> attributes,
 boolean preserveServerState)

Send a command and receive a response.

The [attributes] should contain a map of the parameters. Please refer to the SO Connector documentation for parameter details. Please note that [command] is passed as the first parameter and thus, it need not be specified in the [attributes]. Also, "session" is not required because [Client] will automatically add that. If the optional [preserveServerState] value is true, the "continue" attribute will be set to preserve the server state (See documentation).

Parameters:

command - Command.

attributes - Attributes.

preserveServerState - Whether preserve the server state or not.

Returns:

Response as a JSON instance is returned.

upload

public JSON upload(String mimeType,
 InputStream data)

Upload new binary content to the server.

Parameters:

mimeType - Mime-type should be correctly specified because it will not be verified by the server.

data - Data to be uploaded.

Returns:

If successfully uploaded (Status == "OK"), the "id" attribute will contain the ID of the new content created.

upload

public JSON upload(String mimeType,
 InputStream data,
 String streamNameOrID)

Upload some binary content to the server.

Parameters:

mimeType - Mime-type should be correctly specified because it will not be verified by the server.

data - Data to be uploaded.

streamNameOrID - If not blank or null, the corresponding content will be overwritten. It could be specified as the content-name or the ID of the content.

Returns:

If successfully uploaded (Status == "OK"), the "id" attribute will contain the ID of the content.

getFault

public static Fault getFault(JSON json)

Extract fault if any from the given JSON object.

Parameters:

json - JSON object from which fault needs to be extracted.

Returns:

Fault instance or null.

stream

public Client.Data stream(String name)

Retrieve the stream of data for the [name].

You should have got the [name] from a previous request.

Parameters:

name - Name of the stream. (Mostly as a stringified Id).

Returns:

An instance of Client.Data. This contains an InputStream containing binary data if the Client.Data.error() is null. Client.Data.mimeType() provides the content-type.

file

public Client.Data file(String name)

Retrieve the stream of data for the give file [name].

You should have got the [name] from a previous request, or it could be the name of a file in the SO platform.

Parameters:

name - Name of the stream.

Returns:

An instance of Client.Data. This contains an InputStream containing binary data if the Client.Data.error() is null. Client.Data.mimeType() provides the content-type.

report

public Client.Data report(String logic,
 Map<String,Object> parameters)

Run a report and retrieve its output.

Parameters:

logic - Name of the report logic.

parameters - Parameters for the report.

Returns:

An instance of Client.Data. This contains an InputStream containing binary data if the Client.Data.error() is null. Client.Data.mimeType() provides the content-type.

report

public Client.Data report(String logic)

Run a report and retrieve its output.

Parameters:

logic - Name of the report logic.

Returns:

An instance of Client.Data. This contains an InputStream containing binary data if the Client.Data.error() is null. Client.Data.mimeType() provides the content-type.