Page History
The BellaDati Java SDK is an easy-to-use implementation to access the REST API using Java. All data is made available in Java objects, eliminating the need to manually parse and interpret JSON responses from the server.
Setting up the SDK
The SDK consists of several parts:
...
The SDK source is available on GitHub.
Dependencies
Dependencies for the SDK depend on the implementation you are planning to use:
Regular Java VM
- Jackson 2.2.x core, annotations and databind libraries
- Signpost 1.2.x core and Commons HTTP implementation
- Apache HttpClient 4.3.x and its dependencies (jars fluent-hc and httpmime are not needed)
Android
- Jackson 2.2.x core, annotations and databind libraries
- Signpost 1.2.x core
- Re-packaged Apache HttpClient for Android provided by BellaDati
Server Setup
In order to access data from BellaDati, you need to enable API access in your domain. To do so, open your domain settings and click Configure under OAuth Settings.
...
You can optionally set a callback URL that will be opened when a user successfully authorizes an OAuth request - more on that in the example below. Finally, if your application environment doesn't allow using a web browser for authentication, you can enable xAuth to authenticate with username and password from within your client application.
Usage Example
In this example, we will use the SDK to authenticate using OAuth or xAuth and retrieve some data visible to our example user.
Authentication
Before we can read data through the SDK, we have to authenticate as a valid user. In this example, let's assume that we have set up a domain with a consumer key sdkKey and a consumer secret sdkSecret. The first step is to connect to our server:
...
Code Block | ||
---|---|---|
| ||
BellaDatiConnection connection = BellaDati.connect("https://belladati.example.com"); // connect to a custom BellaDati server |
OAuth
The recommended form of authentication is OAuth. Using this protocol, the SDK requests a token from the server that the user then has to authorize using their web browser. The advantage of this mechanism is that the user sends their credentials directly to the server, reducing the risk of them getting intercepted on the computer running the SDK.
...
Code Block | ||
---|---|---|
| ||
BellaDatiService service = oauth.requestAccess(); // request access from the server |
xAuth
For some applications, it is not possible or feasible to use a web browser for authentication. In these situations, you can use xAuth to have the user enter their credentials directly into your application and use them as follows:
Code Block | ||
---|---|---|
| ||
BellaDatiService service = connection.xAuth( "sdkKey", "sdkSecret", "user@example.com", "reallysecurepassword"); // directly request access using xAuth |
Retrieving Data
After successful authentication, we now have an instance of the BellaDatiService interface. This interface offers several methods to get data from the server. In our example, let's first get a list of reports along with thumbnail images to display to the user.
...
This Report object contains more details about the report, most importantly a list of its Views. Each chart, table, KPI etc. inside a report is represented by such a View. We can iterate over the views and display them:
Code Block | ||
---|---|---|
| ||
for (View view : report.getViews()) {
switch (view.getType()) {
case CHART: // this means we're getting a JSON chart
displayChart((JsonNode) view.loadContent());
break;
case KPI: // this means we're getting JSON KPI
displayKPI((JsonNode) view.loadContent());
break;
case TEXT: // this means we're getting JSON text
displayText((JsonNode) view.loadContent());
break;
case TABLE: // this tells us that we're getting a Table object
displayTable((TableView.Table) view.loadContent());
break;
}
} |
...
In this example, we are loading all views one by one in a single thread, which may be slow. It can easily be done in parallel by using a mechanism similar to what we did for thumbnail images above, but we decided to omit it here for clarity.
General Advice
Try not to make many calls to the server in sequence to avoid causing long loading times for your users. When loading multiple items, consider loading them in parallel. It's easy to recognize which methods should better be run in parallel: Any methods named loadSomething() are making a call to the server.
...