-
Notifications
You must be signed in to change notification settings - Fork 0
Home
This is a guide to using iland's Java SDK.
We have many examples of things you are able to do with the Java SDK such as:
Powering on/off and deleting a VM
This is a guide to take you through building your own project from scratch and authenticating iland's API so you can start using the Java SDK.
Understanding the basics of Java is not a required skill but preferable. If you need a refresher on the language, check out this link
If you don't want to build everything from scratch you can just git clone the project and follow along with the tutorial without having to write everything yourself.
To get this example app use this code:
git clone https://github.com/ilanddev/java-sdk.git
The first step in order to setup the project is making sure Java and Maven are installed.
To check if you have Java installed, run this command in the terminal:
$ java -version
If you need to install Java follow this guide. Follow this guide for installing Maven.
Verify that you have installed Maven with this command:
$ mvn -v
Once you have installed Maven and Java we can begin building the app.
To build a basic Java project with maven you run this command:
$ mvn archetype:generate -DgroupId=com.iland.app -DartifactId=create-scratch-vapp -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false
The groupId and artifactId can be whatever you specify. I chose com.iland.app and create-scratch-vapp.
We now have a basic Java project with a pom.xml file and a App.java file.
To confirm you have everything working run these commands.
$ cd create-scratch-vapp
$ mvn clean install
$ java -jar target/create-scratch-vapp-1.0-SNAPSHOT.jar
This will move you into the project's directory, build the project and then run it.
If everything is working you should see Hello World! in your terminal.
Note: If you used different groupId and artifactId then you will have to change the last command to reflect whatever you values you used.
To be able to use the iland Java SDK we will have to edit the pom.xml.
So open up pom.xml file with a text editor and find the <dependencies> tag and add the following under the existing </dependency> tag.
<dependency>
<groupId>com.iland.core</groupId>
<artifactId>iland-sdk</artifactId>
<version>1.0.13</version>
</dependency>
Once you have done that we need to add the repository that the SDK is located at.
So after the </dependencies> tag add the following code.
<repositories>
<repository>
<id>iland-sdk-mvn-repo</id>
<url>https://raw.githubusercontent.com/ilanddev/java-sdk/mvn-repo</url>
<snapshots>
<enabled>true</enabled>
<updatePolicy>always</updatePolicy>
</snapshots>
</repository>
</repositories>
This will tell Maven where to pull iland's Java SDK from.
Lastly we need to tell Maven where to execute the Main class. In the plugin section first remove the tags that contain <pluginManagement> and </pluginManagement>.
Then add the following code to after the last </plugin> tag or just replace all the plugin section:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>2.3</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
<configuration>
<transformers>
<transformer
implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
<mainClass>com.iland.app.App</mainClass>
</transformer>
</transformers>
/configuration>
</execution>
</executions>
</plugin>
Now run mvn clean install again and confirm you can still build successfully.
Now that we have the project and the pom.xml correctly configured we can start playing around with the SDK.
First open the App.java file which will be found in the lowest directory.
Mine is located at /create-scratch-vapp/src/main/java/com/iland/app. If you have used the same groudId and artifactId as me then it will be in the same location.
Before we can start making calls to iland's API with the SDK we must first authenticate our user. To do so we must have four following variables:
- username
- password
- client name
- client secret
You should have a username and password already if you have an account with iland. To get the client secret and client name you must email support@iland.com for these credentials.
So in the App.java before the public static void main(String[] args) function add the following code:
final static String USERNAME = "";
final static String PASSWORD = "";
final static String CLIENT_NAME ="";
final static String CLIENT_SECRET = "";
Fill in these variables with your own credentials.
Now we will sign in so we can use the API.
The first thing we need to is create a Client from our SDK. Below the variables you just created add the following code:
static Client apiClient = new Client(CLIENT_NAME, CLIENT_SECRET);
This will create a client with which we can login into the API and call the resources we need.
Note: I am using an IDE which automatically adds the needed imports to my code. If you are just using a basic text editor you will have to import everything yourself. For example the Client object I just added needs the following line of code import com.iland.core.web.sdk.Client; at the beginning of the App.java file. You will not be able to compile the project without the proper imports. Go to the Common Problems to see how to fix import issues.
Now we need to login. The following code is how you login. Add this into the main function or your own function.
try {
apiClient.login(USERNAME, PASSWORD);
} catch (final OAuthException e) {
System.out.println(e.getMessage());
}
The login() function can throw a OAuthException thus the need to wrap it in a try/catch block.
When you are done using iland's Java SDK it is time to logout. In the main function use this code to logout for the Client
apiClient.logout()
Declaring resources every time you need to use them is tedious and repetitive.
If you know which resources you want to use, you should declare them globally and then instantiate them once so you can re-use them in whatever functions you may creating.
Remember to track whatever you do with TaskResponse and make sure the tasks are synced before performing multiple operations on any resource.
Here I will address common problems that you might face when trying to use iland's Java SDK.
If you don't have all the nescessary imports you might see an error like this
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.8.0:compile (default-compile) on project my-app: Compilation failure: Compilation failure:
[ERROR] /home/user/code/create-vm/my-app/src/main/java/com/mycompany/app/App.java:[36,10] cannot find symbol
[ERROR] symbol: class Client
[ERROR] location: class com.mycompany.app.App
As you can see Maven cannot find the class Client because we have not included the correct imports.
To find the correct package to use in your import you can use this custom Google search engine here to search the Java SDK docs.
After finding the resource or object you need to import look near the top of the page on the left hand side and you should see something like com.iland.core.web.sdk.Client.
Add that to the top of your Java file and re-compile the code to see if that fixes your import error.