Skip to content
This repository was archived by the owner on Jun 12, 2019. It is now read-only.

Commit f88d102

Browse files
he667he667
committed
Initial Commit
0 parents  commit f88d102

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

68 files changed

+9236
-0
lines changed

‎.gitignore

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.classpath
2+
.settings
3+
.project
4+
download.tmp
5+
/bin
6+
/target
7+
/src/test/resources/runabove.properties

‎.travis.yml

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
language: java
2+
jdk:
3+
- openjdk6

‎LICENSE

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
Copyright (c) 2014, OVH
2+
3+
Permission is hereby granted, free of charge, to any person obtaining a copy
4+
of this software and associated documentation files (the "Software"), to deal
5+
in the Software without restriction, including without limitation the rights
6+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7+
copies of the Software, and to permit persons to whom the Software is
8+
furnished to do so, subject to the following conditions:
9+
10+
The above copyright notice and this permission notice shall be included in all
11+
copies or substantial portions of the Software.
12+
13+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
19+
SOFTWARE.
20+
21+
Except as contained in this notice, the name of OVH and or its trademarks (and
22+
among others RunAbove) shall not be used in advertising or otherwise to promote
23+
the sale, use or other dealings in this Software without prior written
24+
authorization from OVH.

‎README.md

+196
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
Java SDK for RunAbove API
2+
=============
3+
4+
5+
This is a Java SDK to use Instances and Object Storage on [RunAbove](https://www.runabove.com). The SDK uses the simple API provided by RunAbove.
6+
7+
Benefits :
8+
- Auth made easy
9+
- Embedded api cryptography process
10+
- All POJO availables
11+
- All services exposed
12+
- Create Instances and Containers in one line
13+
- Play with Openstack Swift through the API or with JOSS Library
14+
15+
The Runabove API Console is available [here](https://manager.runabove.com/console).
16+
17+
18+
Quickstart
19+
----------
20+
21+
The easiest way to start with the SDK is to install clone it from github and package it :
22+
23+
mvn clean install package
24+
25+
RunAbove SDK can then be included in your java programs. Some examples of
26+
applications using the SDK are available in the `examples` directory.
27+
28+
Once build, add this dependency to your project :
29+
30+
31+
```xml
32+
<dependency>
33+
<groupId>com.runabove</groupId>
34+
<artifactId>api</artifactId>
35+
<version>1.0.0</version>
36+
</dependency>
37+
```
38+
39+
40+
41+
Authenticate to RunAbove API
42+
----------------------------
43+
44+
Each **application** that uses RunAbove API needs to be authenticated. For that
45+
you have to register your application, it is very easy and can be done at this
46+
address: https://api.runabove.com/createApp
47+
48+
Then each **user** using your application will be securely authenticated with a
49+
consumer key. Thanks to this mecanism users don't need to give their plain text
50+
password to the application. The first time a user will use your application,
51+
he will be redirected to a web page where he can securely get his **consumer
52+
key**.
53+
54+
55+
How to get a consumer key with the SDK?
56+
---------------------------------------
57+
58+
To communicate with the API, each call made by your application must be signed
59+
and include the consumer key of the user. The signature process is
60+
automatically handled by the SDK. However if the user don't have a valid
61+
consumer key yet you can redirect him to RunAbove authentication page.
62+
63+
64+
65+
How to manage instances?
66+
------------------------
67+
68+
Launching an instance is easy. First get the flavor, image and region where you
69+
want your instance to be created and call `create()`. To
70+
delete an instance just call the `instance.delete()` method:
71+
72+
73+
74+
```java
75+
76+
// initialize configuration
77+
RunAboveConfig config = new RunAboveConfig()
78+
.setErrorHandlder(new SystemOutErrorHandler())
79+
.setApplicationKey(applicationKey)
80+
.setApplicationSecret(applicationSecret);
81+
82+
// request credentials
83+
AuthManager runAboveAuth = new RunAboveBuilder(getConfig()).createAuthManager();
84+
Credential creds = runAboveAuth.credential(new DefaultCredentialParams());
85+
86+
// snip snip
87+
// redirect user to authorization page at creds.getValidationUrl()
88+
// snip snip
89+
90+
// create the manager object that handles all api calls
91+
RunAboveManager runAbove = new RunAboveBuilder(getConfig()).createManager(creds.getConsumerKey());
92+
93+
// create an instance detail
94+
InstanceDetail instanceDetail = new InstanceDetail();
95+
96+
// get a flavor
97+
Flavor[] flavors = runAbove.getFlavor();
98+
instanceDetail.setFlavor(flavors[0]);
99+
100+
// get a region
101+
String[] regions = runAbove.getRegions();
102+
instanceDetail.setRegion(regions[0]);
103+
104+
// get an image
105+
Image[] imgs = runAbove.getImages();
106+
instanceDetail.setImage(imgs[0]);
107+
108+
// create an instance
109+
InstanceDetail resultInstance = runAbove.createInstance(instanceDetail);
110+
111+
// list all the instances
112+
Instance[] listInstances = runAbove.getInstances();
113+
for (Instance instance : listInstances) {
114+
LOG.info("instance id " + instance.getInstanceId());
115+
LOG.info("instance name " + instance.getName());
116+
}
117+
118+
// delete the instance we just created
119+
runAbove.deleteInstance(resultInstance.getInstanceId());
120+
```
121+
122+
How to use storage?
123+
-------------------
124+
125+
```java
126+
// initialize configuration
127+
RunAboveConfig config = new RunAboveConfig()
128+
.setErrorHandlder(new SystemOutErrorHandler())
129+
.setApplicationKey(applicationKey)
130+
.setApplicationSecret(applicationSecret);
131+
132+
// request credentials
133+
RunAboveAuthApi runAboveAuth = new RunAboveBuilder(config).createAuth();
134+
Credential creds = runAboveAuth.credential(new DefaultCredentialParams());
135+
136+
// snip snip
137+
// redirect user to authorization page at creds.getValidationUrl()
138+
// snip snip
139+
140+
// create the manager object that handles all api calls
141+
RunAboveManager runAbove = new RunAboveBuilder(getConfig()).createManager(creds.getConsumerKey());
142+
143+
// storage container creation settings
144+
StorageContainerCreate storageContainer = new StorageContainerCreate();
145+
storageContainer.setContainerName("Container Name");
146+
storageContainer.setContainerRegion("BHS-1");
147+
StorageContainerDetail containerDetail = runAboveApi.createStorageContainer(storageContainer);
148+
149+
// get all available files in all storage containers
150+
StorageContainer[] containers = runAboveApi.getStoreContainers();
151+
for (StorageContainer storageContainer : containers) {
152+
153+
LOG.info("StorageContainer getContainerName " + storageContainer.getName());
154+
LOG.info("StorageContainer getTotalFiles " + storageContainer.getTotalObjects());
155+
156+
StorageContainer detail = runAboveApi.getStoreContainer(storageContainer.getName(), 10, storageContainer.getRegion(), null);
157+
if (detail.getObjects() != null)
158+
for (StorageContainerObject file : detail.getObjects()) {
159+
LOG.info("StorageContainerFile getContentType " + file.getContentType());
160+
LOG.info("StorageContainerFile getLastModified " + file.getLastModified());
161+
LOG.info("StorageContainerFile getName " + file.getName());
162+
LOG.info("StorageContainerFile getSize " + file.getSize());
163+
}
164+
}
165+
```
166+
167+
How to build the documentation?
168+
-------------------------------
169+
170+
Documentation can be generated with the maven command:
171+
172+
mvn site
173+
174+
Also more documentation about the managers can be found in the knowledge base on the Runabove website.
175+
176+
177+
178+
How to run tests?
179+
-----------------
180+
181+
The tests are all mocked with proper responses from the runabove api. Just type :
182+
183+
mvn clean test
184+
185+
186+
187+
188+
License
189+
-------
190+
191+
The SDK code is released under a MIT style license, which means that it should
192+
be easy to integrate it to your application.
193+
Check the [LICENSE](LICENSE) file for more information.
194+
195+
196+

‎examples/MAVEN.md

+125
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
Bootstraping your project with maven
2+
------------------------------------
3+
4+
Requirements:
5+
* a working environnement with maven and a jdk 1.6+ and your favorite ide (Eclipse 4.3+ recommended, Maven 3+, Oracle JDK 1.6+)
6+
* a good understanding of a the runabove authentication that can be found here : https://api.ovh.com/g934.first_step_with_api
7+
8+
9+
10+
Since the Runabove Java SDK is not yet in maven central (submission pending), we need to build it into our local repository :
11+
```
12+
git clone https://github.com/runabove/java-runabove.git
13+
```
14+
15+
Then build and install :
16+
```
17+
mvn clean install
18+
```
19+
20+
Now if everything is ok, you can start to use it directly.
21+
Let's start by creating a new maven project, we'll use the "quickstart" archetype for that.
22+
23+
```
24+
mvn archetype:generate -DgroupId=com.mycompany -DartifactId=simpletest -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
25+
```
26+
27+
We have a simple project with two java files. One name App for our simple test. One called AppTest for testing purposes.
28+
29+
To make it work with our sdk, let's add the sdk dependency to the pom.xml in this very project.
30+
31+
```
32+
<dependency>
33+
<groupId>com.runabove</groupId>
34+
<artifactId>api</artifactId>
35+
<version>1.0.0</version>
36+
</dependency>
37+
```
38+
39+
To ease the development you can import the project into eclipse:
40+
```
41+
mvn eclipse:eclipse
42+
```
43+
44+
Then Import > Existing project into workspace > Select where the pom is and voila.
45+
46+
47+
Making an API Call
48+
------------------
49+
50+
51+
52+
Now we can modify our script to make the two step authentication and make an api call:
53+
- First generate a consumer key
54+
- Validate the consumer key on the web interface
55+
- Then use the validated consumer key to make api calls
56+
57+
In the following code, everything is done in one step.
58+
Replace the XXXXXX with your own application key and application secret.
59+
Once launched, this small programm will display an validation url.
60+
Copy / paste it in your browser, enter your login password and it shoud validate the consummer key.
61+
After the delay, the code will display all available instance in your account.
62+
63+
64+
```java
65+
66+
package com.mycompany;
67+
68+
import com.runabove.api.AuthManager;
69+
import com.runabove.api.RunAboveBuilder;
70+
import com.runabove.api.RunAboveConfig;
71+
import com.runabove.api.RunAboveManager;
72+
import com.runabove.error.SystemOutErrorHandler;
73+
import com.runabove.model.auth.Credential;
74+
import com.runabove.model.auth.DefaultCredentialParams;
75+
import com.runabove.model.instance.Instance;
76+
77+
public class App
78+
{
79+
public static void main( String[] args ) throws InterruptedException
80+
{
81+
String applicationKey = "XXXXXXXXXXXXX";
82+
String applicationSecret = "XXXXXXXXXXXXXXXXXXXXXXXXX";
83+
84+
// initialize configuration
85+
RunAboveConfig config = new RunAboveConfig()
86+
.setErrorHandlder(new SystemOutErrorHandler())
87+
.setApplicationKey(applicationKey)
88+
.setApplicationSecret(applicationSecret);
89+
90+
// request credentials
91+
AuthManager runAboveAuth = new RunAboveBuilder(config).createAuthManager();
92+
Credential creds = runAboveAuth.credential(new DefaultCredentialParams());
93+
94+
// first phase
95+
System.out.println("CK =" + creds.getConsumerKey());
96+
System.out.println("VALIDATION URL = " + creds.getValidationUrl());
97+
98+
// validate the url from validation url you have 20s go go go !!!!
99+
Thread.sleep(20000);
100+
101+
// now let's call the api
102+
// create the manager object that handles all api calls
103+
RunAboveManager runAbove = new RunAboveBuilder(config).createManager(creds.getConsumerKey());
104+
105+
// list all the instances
106+
Instance[] listInstances = runAbove.getInstances();
107+
for (Instance instance : listInstances) {
108+
System.out.println("INSTANCE ID = " + instance.getInstanceId());
109+
System.out.println("INSTANCE NAME = " + instance.getName());
110+
} }
111+
}
112+
113+
```
114+
115+
Here's the result output of the code above :
116+
117+
```
118+
CK =gU6WZHh40OyUaTVGymUEDFZEZEFEZFZHELljOlC81ba0
119+
VALIDATION URL = https://api.runabove.com/login/?credentialToken=I28Eii2XXDn0QDhS3i17eeFNy8IcrQCqJkBdywe9lbDUVytCT6d0X48zJUZDFEZFZEFZfD6bo3
120+
INSTANCE ID = c28d6241-0084-4ca5-af27-eb82f2c06ZEFEZFEZf1c
121+
INSTANCE NAME = myveryowninstance
122+
```
123+
124+
125+

0 commit comments

Comments
 (0)