Skip to content

Commit bdbbcb5

Browse files
author
Cristi
committed
added coscale-sdk-java
1 parent 09cda78 commit bdbbcb5

30 files changed

+2852
-0
lines changed

‎README.md‎

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,238 @@
1+
12
# coscale-sdk-java
3+
24
Java SDK for integrating apps with CoScale
5+
6+
Java bindings for the [CoScale API](http://docs.coscale.com/)
7+
8+
- [Installation](#installation)
9+
- [Resources](#resources)
10+
- [Authentication](#authentication)
11+
- [Usage](#usage)
12+
- [Subject](#subject)
13+
- [Error handling](#error-handling)
14+
- [Advanced Configuration](#advanced-configuration)
15+
16+
17+
## Installation
18+
19+
TODO:
20+
[ ![Download](https://url) ](https://url)
21+
22+
The distribution is hosted on [url](https://url).
23+
To use the client, you can add the x repository to your dependencies.
24+
25+
### maven
26+
27+
TODO:
28+
Add x to your repositories in `pom.xml` or `settings.xml`:
29+
30+
```xml
31+
<repositories>
32+
<repository>
33+
<id>x</id>
34+
<url>http://jcenter.bintray.com</url>
35+
</repository>
36+
</repositories>
37+
```
38+
39+
and add the project declaration to your `pom.xml`:
40+
41+
```xml
42+
<dependency>
43+
<groupId>com.coscale.sdk</groupId>
44+
<artifactId>client</artifactId>
45+
<version>1.0.0</version>
46+
</dependency>
47+
```
48+
49+
## Resources
50+
51+
Resources this API supports:
52+
53+
- [Metrics](#metrics)
54+
- [Data](#data)
55+
- [Servers](#servers)
56+
- [Events](#events)
57+
58+
59+
## Authentication
60+
61+
In order to communicate with the CoScale API an authorization token is required.
62+
There are 2 ways to get an authorization token (you have to pick your favorite option):
63+
1. Authenticating with your email and password
64+
2. Authenticating with an access token. You can generate a token by accessing "Users" from the left sidebar and clicking on "Access tokens".
65+
66+
```java
67+
// Authentication with your email and password.
68+
Credentials credentials = Credentials.Password("[email protected]", "passwd");
69+
// Or Authenticating with an access token generated from the CoScale web interface.
70+
Credentials credentials = Credentials.Token("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");
71+
72+
// Instantiate ApiFactory with the Application Id and the credentials.
73+
// The application ID can be retrieved from the URL, it's the UUID after /app
74+
// e.g. https://app.coscale.com/app/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/dashboard/view/-1/
75+
ApiFactory apiFactory = new ApiFactory("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", credentials);
76+
```
77+
78+
79+
## Usage
80+
81+
### Metrics
82+
83+
```java
84+
// Create a metric
85+
MetricsApi metricsApi = apiFactory.getMetricsApi();
86+
MetricInsert metricInsert = new MetricInsert("Client Test Metric",
87+
"Client Test Metric Description", DataType.DOUBLE, SubjectType.APPLICATION,
88+
"req/s", 60);
89+
90+
Metric metric = metricsApi.insert(metricInsert);
91+
92+
93+
// Create a metric group. The last parameter is the parent id which is optional.
94+
MetricGroupInsert insert = new MetricGroupInsert("Name of the metric group",
95+
"The description", "The Type", SubjectType.APPLICATION, null);
96+
MetricGroup metricGroup = metricsApi.insertMetricGroup(insert);
97+
98+
99+
// Add a metric into a metric group.
100+
metricsApi.addMetricToGroup(metric.id, metricGroup.id);
101+
102+
// Add a group into another group.
103+
metricsApi.addGroupToGroup(childMetricGroup.id, parentMetricGroup.id);
104+
105+
// Is possible to filter the Metrics. e.g. filter by metric name:
106+
Options options = new Builder().selectBy("name", "Average subscription rate").build();
107+
metricsApi.all(options);
108+
```
109+
110+
### Data
111+
112+
_Insert data for the metrics._
113+
114+
```java
115+
// DataInsertBuilder is used to Build the InsertData object.
116+
DataInsertBuilder builder = new DataInsertBuilder();
117+
118+
// DataInsertBuilder can store data for multiple metrics. It also supports adding multiple
119+
// values for the same metric but each one should have a different time stamp.
120+
// e.g. builder.addDoubleData(<metric id>, <timestamp>, <value>);
121+
122+
builder.addDoubleData(metric.id, 0, 3.3); // For the given metric, insert value 3.3 at the current timestamp
123+
124+
builder.addDoubleData(metric.id, -120, 4.3); // For the given metric, insert value 4.3 at the timestamp 120 seconds ago
125+
126+
builder.addDoubleData(metric.id, 1462816055, 4.8); // For the given metric, insert value 4.8 at the unix timestamp 1462816055
127+
128+
// Make the insert request. The first parameter is the Subject Id which in this case is "a", meaning that the data
129+
// is inserted for an application. For more details about subjectId check [Subject](#subject) section.
130+
Msg response = apiFactory.getDataApi().insert("a", builder.build());
131+
132+
// The data can be inserted also for a server
133+
String subjectId = "s" + server.id;
134+
Msg response = apiFactory.getDataApi().insert(subjectId, builder.build());
135+
136+
```
137+
138+
### Servers
139+
140+
```java
141+
// Insert a new Server.
142+
ServerInsert serverInsert = new ServerInsert("Server Test Name", "Description", "Type", null);
143+
Server server = apiFactory.getServersApi().insert(serverInsert);
144+
145+
// To get a server by the name we can add a filter.
146+
Options filter = new Builder().selectBy("name", "Ubuntu Server").build();
147+
apiFactory.getServersApi().all(filter);
148+
```
149+
150+
### Events
151+
152+
```java
153+
// Insert a new Event.
154+
EventsApi eventsApi = apiFactory.getEventsApi();
155+
EventInsert eventInsert = new EventInsert("Event name");
156+
Event event = eventsApi.insert(eventInsert);
157+
158+
// Insert data for a event. Subject type "a" means that the event if for the application.
159+
EventDataInsert data = new EventDataInsert("Alert", -120l, 0l, null, "a");
160+
EventData eventData = eventsApi.insertData(event.id, data));
161+
162+
// Notice that the timestamps can be negative meaning seconds ago
163+
// or positive values meaning unix timastamp format. Zero means now.
164+
EventData eventData = eventsApi.allData(event.id, -300l, 0l));
165+
166+
// Get data for a event by id.
167+
EventData eventData = eventsApi.getData(event.id, eventData.id);
168+
169+
// Delete data for a event by ids.
170+
Msg msg = eventsApi.deleteData(event.id, eventData.id);
171+
```
172+
173+
## Subject
174+
175+
A metric or a event is defined on either a "SERVER" or "APPLICATION".
176+
This allows for metric per server or on the whole application.
177+
178+
The Subject Id is used to identify the server or the application. The format should be the following:
179+
```java
180+
// For application.
181+
dataApi.insert("a", data);
182+
// For server is required the server id.
183+
dataApi.insert("s123", data);
184+
185+
// Insert event data for a specific server/application.
186+
String subjectId = "s" + server.id;
187+
EventDataInsert data = new EventDataInsert("Event message", -120l, 0l, null, subjectId);
188+
EventData data = eventsApi.insertData(event.id, data));
189+
```
190+
191+
## Error handling
192+
193+
If there is an unsuccessful response then an CoscaleApiException will be thrown.
194+
The exception will have attached the status code of the response.
195+
196+
```java
197+
try {
198+
Msg response = apiFactory.getDataApi().insert("a", builder.build());
199+
} catch (CoscaleApiException e) {
200+
if (e.statusCode == HttpURLConnection.HTTP_NOT_FOUND) {
201+
System.out.println("Not found. " + e.getMessage());
202+
} else if (e.statusCode == 409) {
203+
// See response message for explanation (e.g. duplicate entries: 2 server with the same name).
204+
} else if (e.statusCode == -1) {
205+
// Get the inner exception.
206+
System.out.println(e.getCause().getLocalizedMessage());
207+
}
208+
}
209+
```
210+
211+
## Advanced Configuration
212+
213+
### Source
214+
215+
The default source for resources is "Java SDK". This can be changed using:
216+
217+
```java
218+
apiFactory.getApiClient().setSource("New Source");
219+
```
220+
221+
### Timeouts
222+
223+
The default connection and request timeouts are set to 15000 ms by default.
224+
These times can be changed using:
225+
226+
```java
227+
apiFactory.getApiClient().setConnectionTimeout(1000);
228+
apiFactory.getApiClient().setReadTimeout(1000);
229+
```
230+
231+
232+
### API Server URL
233+
234+
The API base URI can be changed for testing purposes
235+
236+
```java
237+
apiFactory.getApiClient().setBaseURL("http://new-server.coscale.com");
238+
```

‎pom.xml‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
4+
<modelVersion>4.0.0</modelVersion>
5+
6+
<groupId>com.coscale.sdk-java</groupId>
7+
<artifactId>coscale-sdk-java</artifactId>
8+
<version>1.0.0</version>
9+
<packaging>jar</packaging>
10+
<name>CoScale SDK</name>
11+
<description>Java SDK for integrating apps with CoScale Web Performance Monitoring platform.</description>
12+
<url>http://www.coscale.com</url>
13+
14+
<properties>
15+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
16+
</properties>
17+
18+
<licenses>
19+
<license>
20+
<name>BSD 3-Clause License</name>
21+
</license>
22+
</licenses>
23+
<developers>
24+
<developer>
25+
<name>Cristian Ciutea</name>
26+
<email>[email protected]</email>
27+
<organization>CoScale</organization>
28+
<organizationUrl>http://www.coscale.com</organizationUrl>
29+
</developer>
30+
</developers>
31+
32+
<scm>
33+
<connection>scm:git:[email protected]:CoScale/coscale-sdk-java.git</connection>
34+
<developerConnection>scm:git:[email protected]:CoScale/coscale-sdk-java.git</developerConnection>
35+
<url>[email protected]:CoScale/coscale-sdk-java.git</url>
36+
</scm>
37+
38+
<build>
39+
<plugins>
40+
<plugin>
41+
<groupId>org.apache.maven.plugins</groupId>
42+
<artifactId>maven-compiler-plugin</artifactId>
43+
<version>3.1</version>
44+
<configuration>
45+
<source>1.7</source>
46+
<target>1.7</target>
47+
</configuration>
48+
</plugin>
49+
<plugin>
50+
<groupId>org.apache.maven.plugins</groupId>
51+
<artifactId>maven-gpg-plugin</artifactId>
52+
<version>1.5</version>
53+
</plugin>
54+
<plugin>
55+
<groupId>org.apache.maven.plugins</groupId>
56+
<artifactId>maven-release-plugin</artifactId>
57+
<version>2.4.2</version>
58+
</plugin>
59+
</plugins>
60+
</build>
61+
62+
<dependencies>
63+
<dependency>
64+
<groupId>com.fasterxml.jackson.core</groupId>
65+
<artifactId>jackson-databind</artifactId>
66+
<version>2.4.1.3</version>
67+
</dependency>
68+
<dependency>
69+
<groupId>com.google.guava</groupId>
70+
<artifactId>guava</artifactId>
71+
<version>19.0</version>
72+
</dependency>
73+
<dependency>
74+
<groupId>junit</groupId>
75+
<artifactId>junit</artifactId>
76+
<version>3.8.1</version>
77+
<scope>test</scope>
78+
</dependency>
79+
<dependency>
80+
<groupId>com.google.code.findbugs</groupId>
81+
<artifactId>jsr305</artifactId>
82+
<version>3.0.0</version>
83+
</dependency>
84+
</dependencies>
85+
</project>

0 commit comments

Comments
 (0)