Please note that this library is still in beta.
This is a RESTful Java client for accessing Xively API. It uses Apache HttpComponent for handling HTTP requests while remaining decoupled. This fully featured Java library parses domain objects to and from Xively JSON data format.
To get started:
- Update
api.key
insrc/main/res/config.properties
with your Xively API key - Call
XivelyService.instance()
and you will get access to all operations
All configuration for the library is contained within AppConfig
class.
These settings are loaded from config.properties
, which override the defaults defined in AppConfig
.
Simple timeouts and retries can be configured via config.properties
, for example:
http.connectionTimeout=5000
The connection timeout can also be set dynamically by calling:
HttpClientBuilder.getInstance().setConnectionTimeout(5000);
The DomainObject is the model interface for all objects that can be directly accessed/modified via Xively RESTful API. Each model has a equals, hashcode and deepEquals defined to streamline downstream processing.
All CRUD operations on DomaimObject(s) are provided by XivelyService
.
It is designed to be fluent, here are some examples:
XivelyService.instance().feed().create(<Feed object>);
XivelyService.instance().datastream(feedId).create(<Datastream object>);
XivelyService.instance().datastream(feedId).delete(datastreamId);
Each DomainObject has a corresponding requester interface for accessing the API in com.xively.client.http.api
package for all CRUD operations, and the access to these is made fluent via the user of the XivelyService
.
Each of the requester will provide access to all available API endpoints for the corresponding resource.
Method calls take DomainObject(s) as parameters and return DomainObject, therefore downstream application does not need to be concerned about parsing or the underlying HTTP request/response details.
On success, the requester implementation will return the object post CRUD operation:
- create - returns the DomainObject created, fully populated with fields generated post API call
- get (read) - returns the DomainObject retrieved
- update - returns the updated DomainObject
- delete - returns an empty DomainObject with the ID only
On failure, the requester implementation will throw:
InvalidRequestException
, if the request is invalidHttpException
, if the response status is not 2xx
RESTful requests to Xively API are managed by DefaultRequestHandler
and DefaultResponseHandler
handles the responses.
Therefore, this client is fully decoupled from the HTTP client implementation.
Parsing to and from DomainObjects to HTTP request/response body are encapsulated in com.xively.client.http.util.ParseUtil
.
It may throw:
ParseToObjectException
, if the returned response cannot be parse into DomainObject implementationsParseFromObjectException
, if the DomainObject implementation cannot be parse into specified data format (e.g. JSON)
Any exception thrown out of the library is a subclass of XivelyClientException
.
Retrieve a feed:
Feed feed = XivelyService.instance().feed().get(123);
// the returned object will be populate with fields generated by the API
Create several datapoints and then put them into the same datastream:
Datapoint dp1 = new Datapoint();
dp1.setAt("2013-01-01T00:00:00.000000Z");
dp1.setValue("123");
Datapoint dp2 = new Datapoint();
dp2.setAt("2013-01-02T00:00:00.000000Z");
dp2.setValue("456");
// assuming your API key has permission to write
// to the feed:123 and datastream:"test_stream0"
DatastreamRequester requester = XivelyService.instance().datapoint(123, "test_stream-0");
requester.create(dp1, dp2);
dp1.setValue("234");
requester.update(dp1);
Run this to regenerate docs:
javadoc -d doc/ \
-sourcepath src/main/java/ \
-subpackages com.xively.client \
-stylesheetfile src/main/res/doc_stylesheet.css