Java API

If you are working with a Java environment we provide a Java package that provides library functions to make interacting with the CloudTables API as simple as initializing a class and a method call. Using the library you can easily embed data sets securely into your pages, get information about data sets and the data of a specified dataset.

Installing

The CloudTables libraries are available for download on Bitbucket.

You will also need a JDK and a JRE to use these libraries if you do not have one already. Instructions on how to install a JDK and a JRE can be found here.

Use

To import the CloudTables API into your project use the following line.

import CloudTablesApi.*;

Initialisation

Once imported into your application, an instance can be created using:

CloudTableApi api = new CloudTablesApi("sub-domain", "{apiKey}")
    .clientId("Unique client id")  // Client id (e.g. a login id) - optional
    .clientName("Name");           // Client's name - optional

Where:

• {apiKey} should be replaced by the API key that you want to use for the access.
• The clientId and clientName parameters are optional, but we strongly recommend they are used when integrating with your own login system as it allows the identification of each client's actions in CloudTables' auditing features. Typically the clientId would be set to your login system's user id and clientName the user's username or full name.

A new CloudTablesApi instance should be created for each access request, as it will cache and reuse the access token if one is required.

Embedding data sets

There are two methods provided by the library which can be used to embed a data set into your HTML page. The end result is a <script> tag which includes an access token. This can be called directly from your JSP page as follows.

Fully automatic script tag

The scriptTag method can be used to get an access token (based on the initialisation options) for a data set, and will return a String that contains the full <script> tag that should be inserted into your HTML:

String script = api.scriptTag("{data-set-id}");

Where:

• {data-set-id} is the ID of the data set you wish to embed into the page. The data set ID can be found in the Inspector for the data set on the Data tab.

Custom script tag

Alternatively, you can also build your own <script> tag based on a token:

String token = api.token();
String script = "<script src=\"https://sub-domain.cloudtables.io/loader/{data-set-id}/table/d\" data-token=\"" + token + "\"></script>";

API Reference

Constructor

new CloudTablesApi(String subdomain, String key)

Creates a new instance of the CloudTables API libraries.

• Parameters:
  1. String - The application sub-domain for your CloudTables (i.e. the part before .cloudtables.com).
  2. String - The API key to be used.
• Returns: API instance

Methods

public DatasetData data(String dataset)

Get the data and columns for a given dataset.

• Parameters:
  1. String dataset - ID of the data set to get the data of. See the Data page for the data set to get its ID, or use the .datasets() method.
• Returns: Instance of DatasetData containing data and columns array lists. Please refer to the API documentation for a full description of the structure returned.

public Datasets datasets()

Get summary information about the available datasets (note that the roles applied in the constructor can restrict access so certain data sets will not be shown).

• Returns: Instance of Datasets with property datasets which is an array containing information about the available data sets in the form of DatasetInfo. Please refer to the API documentation for a full description of the structure returned.

public String scriptTag(String dataset)
public String scriptTag(String token, String dataset)
public String scriptTag(String token, String dataset, String style)

Get a <script> tag for a specific dataset to be displayed as a table. Insert this script tag where you want the table to appear in your HTML.

• Parameters: *. String dataset - ID (UUID) of the dataset to be shown *. String token - Secure access token (from .token()) *. String style - The styling framework to use for this table. Can be one of:
  • d - Default
  • auto - Auto detect
  • bs - Bootstrap 3
  • bs4 - Bootstrap 4
  • dt - CloudTables / DataTables default styling
  • zf - Zurb Foundation
  • ju - jQuery UI
  • se - Semantic UI
  • no - No styling
• Returns: <script> tag to use.

public String scriptTagAsync(String dataset, String style)

Get a <script> tag for a specific dataset to be displayed as a table. Insert this script tag where you want the table to appear in your HTML. This is the same as scriptTag, but it will retrieve the secure access token for you.

• Parameters:
  1. String dataset - ID (UUID) of the dataset to be shown
  2. String style - The styling framework to use for this table. See the scriptTag method for valid values.
• Returns: <script> tag to use.

public String token()

Get an access token. Note that this value is cached per API instance. It will only be obtained from the CloudTables server's once.

• Returns: Access token to be used with the <script> tag to access a data set.

Configuration methods

Methods used to configure the Api instance for access.

clientId

A unique id for the client accessing the table on your system. While this is optional it is a recommended parameter as it is useful for tracking requests in CloudTables’ analytics.

Api clientId(String value)

• Parameters:
  1. String value - Client ID to use.
• Returns this for chaining.

clientName

A label that can help identify a user - e.g. a name or e-mail address.

Api clientName(String value)

• Parameters:
  1. String value - Client name to use.
• Returns this for chaining.

condition

Condition(s) to apply to data being fetched. Please see the embedding conditions documentation for full details. Requires Cloudtables.Api 1.1 or newer. Note that this method can be called multiple times to add additional conditions to the access request. They will then be combined with AND logic.

Please see below for a full description of the CloudTables.Condition class and its methods.

Api condition(Condition cond)

• Parameters:
  1. Condition cond - Condition to apply to the data access.
• Returns this for chaining.

domain

Host domain for the CloudTables instance. Used for self-hosted installs of CloudTables.

Api domain(String value)

• Parameters:
  1. String value - Domain name or IP address.
• Returns this for chaining.

duration

Access token’s idle time out (defaults to 20 minutes).

Api duration(int value)

• Parameters:
  1. int value - Idle time out value (seconds).
• Returns this for chaining.

role

Per roles but for a single role only.

Api role(String value)

• Parameters:
  1. String value - role to assign.
• Returns this for chaining.

roles

The name of the role that should be used for the generated access token (if assigned to the API key - if the role is not available for the API key no access will be granted). If not provided then all roles available to the API key will be used.

Api roles(IEnumerable<String> value)

• Parameters:
  1. ArrayList<String> value - roles to assign.
• Returns this for chaining.

ssl

Use https or http connections. Used for self-hosted installs of CloudTables.

Api ssl(String value)

• Parameters:
  1. boolean value - SSL flag
• Returns this for chaining.

Condition Class Reference

Constructors

Creates a new condition instance which can be applied to a data access request, limiting the data that will be returned by the server. See the embedding conditions documentation for full details.

new Condition();

new Condition(String id, String value);

• Namespace CloudTablesApi
• Parameters:
  1. String - The id of the data point the condition should be applied to.
  2. String - The value to use.

Methods

Id

Set the id of the data point to perform the condition on. The ids can be found from your data set's Data page and click on the item in question. The id will be shown in the item inspector on the right. It will start dp- for a regular data point. Conditions on computed values (c-) and links (l-) are not currently supported.

Condition id(String id)

• Parameters:
  1. String id - The id of the data point to perform the condition on.
• Returns this for chaining.

Name

Set the name of the data point to perform the condition on. This can be given as an alternative to the id option as it is easier to remember. However, while the id is static, the name can be changed in the application.

Condition name(String name)

• Parameters:
  1. String id - The data point's name that the condition should be performed upon.
• Returns this for chaining.

Op

Set the conditional operator.

Condition op(String op)

• Parameters:
  1. String op - Conditional operator - it may be one of =, !=, <, <=, >=, >.
• Returns this for chaining.

Set

Mark the value to be set (default) or not when creating a new row.

Condition set(boolean set)

• Parameters:
  1. boolean set - When a new record is created, the API can set the data point to a specific value (defined by setValue or value if the former is not specified).
• Returns this for chaining.

SetValue

The value that will be written to the database if Set is enabled. Note that Value will be used by default, and this method can override it with a new value to be set. It must be specified if Op is not set to =.

Condition setValue(String setValue)

• Parameters:
  1. String setValue - Value to set when a new record is created.
• Returns this for chaining.

Value

The value that will be used for the conditional matching, and for writing to new records, unless SetValue is specified. The formatting must follow these rules:

• date - ISO 8601 (date only)
• datetime - ISO 8601
• number - Unformatted number
• text - Plain text
• time - ISO 8601 (time only).

Condition value(String value)

• Parameters:
  1. String Value - Value to set when a new record is created.
• Returns this for chaining.

Source

Our API libraries for CloudTables are open source under the MIT license. The Java source is available here and pull requests or suggestions for it are welcome.