Getting Started with Azure Management Libraries for Java

Beginning with the 0.5.0 release of the Microsoft Azure SDK for Java, we added support for service management in the Java SDK. Service management is an area already rich in the Azure SDK for .NET and Azure SDK for Node.js but it was a new area for our Java SDK we were excited to release. Like the .NET and Node.js SDKs and the Storage team’s Java SDK, the Java SDK for service management is also open-source on GitHub. In this post, I’ll introduce you to the management libraries for Java and walk you through the process of getting an Eclipse project up and running that you can extend and use to create and manage your own Azure subscription and resources within it.

What are the Management Libraries for Java?

Simply put, these libraries provide your Java applications the ability to automate the setup, teardown, provisioning, and routine management tasks for Azure resources. Our team’s mantra is pretty simple; we want to enable a developer the ability to execute operations on their Azure subscriptions in their code that they’d otherwise have to do using the management portal. Our libraries enable automation of Azure resources (and in fact, our libraries enable our own PowerShell and XPlat CLI experiences today). You can use any of our team’s management libraries to do things like:

• Create, delete, and update settings for resources like web sites, SQL databases, cloud services, scheduler job collections, virtual machines, and storage
• Start and stop web sites
• Back up databases to storage accounts
• Automate the creation of virtual machines

The management libraries for Java are available on Maven, so they’re easily available in most modern Java development tools. This post will focus on developing using Eclipse.

Creating an Eclipse Maven Project

This area of the post will discuss this process assuming the audience has little or no experience using Eclipse to develop using Maven and the Azure libraries and will summarize at a very basic level how to get going from ground zero, so if you’re truly experienced in the arts of Java/Maven/Eclipse, some of this may seem like child’s play to you. I’m relatively new to Java, having been a long-time .NET developer, but my interest in extending the Azure SDK has given me the opportunity to get reacquainted with the language. To put it bluntly, I’m a great candidate for a getting started post in this area (the team’s sure to have a joke here).

I’ll create a new workspace to get started collecting these tutorials, so I’ll make a new folder here:

Once my workspace has been created and I’ve got the Eclipse IDE set up the way I want it, I create a new Maven project.

I don’t have a need for selecting archetypes, so I’ll skip this part and opt in for the “simple project” approach.

Since I’m actually creating an Eclipse Maven project here (you can create any type of project you want so long as you can pull in the Azure Maven packages) I’ll need to provide some information about my app so that when I publish it to a repository consumer will see what my package does. I’ll provide some basic information here to flag this to consumers that this is demo code.

Now that I’ve got an Eclipse project set up with support for Maven packages, I need to find the Azure packages and install them.

Installing the Management Libraries using Maven

I’ll click my pom.xml file to see the list of packages the project has installed in it currently. There shouldn’t be any, as this is a new project. I need to add a Maven package to my project, so I’ll click the Add button here.

If you’re experienced with Maven and Eclipse this may not be news to you. I noted that, when I searched for the packages I knew were in Maven with our name, I couldn’t find any. Instead, I could only find projects that were within my own workspace.

Rebuilding my local development workstation’s index of the central Maven repository will repair my inability to search the online repository for packages. To do this, I need to find the list of Maven repositories my instance of Eclipse knows how to find. So I’ll open the Maven Repositories view in Eclipse.

Once the Maven Repositories view is open I’ll find the central Maven repository in the list. On that item’s context menu I’ll click the Rebuild Index item to build my local index. This will take some time; Maven has a large number of packages that will need to be searched and downloaded so be patient as it’ll take a few minutes.

Once the index is rebuilt I can see the Microsoft Azure packages in the central Maven repository.

Now, searching for the Azure Maven packages results with success, too. I can see the packages I’m after, so I’ll go ahead and select the base management package for now.

Now the base Azure management package is selected as a dependency.

I’ll add a new Java class file to the project. The code I’ll write at first will just call the Azure API to get a list of potential regions into which I can deploy my code and write those regions’ names to the console. Not much, but it’ll give me proof that my code is connecting to the Azure API properly and that I’m ready to go.

Writing Java Code to Access the Azure APIs

Now that I’ve referenced the Azure SDK I’m ready to write some code. To start, I’ll add a new Java class file to my project.

Once the new class dialog opens I’ll make sure I check the static void main checkbox, as this will add the main method to my Java class that’ll provide an entry point to the application I’m writing (which again, is admittedly simple, but just provides me confidence I’m authenticating and connecting to the Azure API correctly).

I’ll add the following imports to the file to make sure I get all the appropriate namespaces for the functionality I’ll need. The namespaces I’ll pull in will give me access to classes in the management libraries for consuming Azure API endpoints.

import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;
import java.util.ArrayList;
import javax.print.event.PrintJobAttributeEvent;
import javax.xml.parsers.ParserConfigurationException;
import org.xml.sax.SAXException;
import com.microsoft.windowsazure.core.utils.KeyStoreType;
import com.microsoft.windowsazure.exception.ServiceException;
import com.microsoft.windowsazure.management.*;
import com.microsoft.windowsazure.Configuration;
import com.microsoft.windowsazure.management.configuration.ManagementConfiguration;
import com.microsoft.windowsazure.management.models.LocationsListResponse;
import com.microsoft.windowsazure.management.models.LocationsListResponse.Location;

Now that I’ve included all the appropriate namespaces I’ll go ahead and set up a management certificate in my subscription that I can use for authenticating the management libraries via the API.

Authenticating to the Azure API Using Certificates

The Java SDK makes it pretty simple to call out to the API. There are a few pieces of information I’ll need to provide the API for it to work against my subscriptions. One of the attributes I’ll need to provide the API is a management certificate. I’ve got the CER file already uploaded into my Azure subscription as shown below in the portal screen shot.

I’ve also got a PFX file representing my client certificate on my local development workstation. I’ll need to convert that PFX into a JKS file, since that’s what Java uses to authenticate via certificates. To perform this conversion I’ll run the command below on a machine with the JDK installed.

c:\java\bin\keytool.exe -importkeystore -srckeystore c:\certificates\AzureJavaDemo.pfx -destkeystore c:\certificates\AzureJavaDemo.jks -srcstoretype pkcs12 -deststoretype JKS

Once I’ve got my JKS file on my desktop I can use that file’s path in the code that will reach out to the Azure API using the management libraries. The boilerplate code for this is below. Note the comments, which highlight the areas specific to the JKS file I just created. I’ll populate the other variables momentarily.

public class Program {
  static String uri = "https://management.core.windows.net/";
  static String subscriptionId = "";
  static String keyStoreLocation = "c:\\certificates\\AzureJavaDemo.jks";
  static String keyStorePassword = "my-cert-password";

  public static void main(String[] args) 
    throws IOException, URISyntaxException, ServiceException, ParserConfigurationException, SAXException {
    Configuration config = ManagementConfiguration.configure(
      new URI(uri), 
        subscriptionId,
        keyStoreLocation, // the file path to the JKS
        keyStorePassword, // the password for the JKS
        KeyStoreType.jks // flags that I'm using a JKS keystore
    );
  }
}

For now, the Java SDK provides authentication to the Azure APIs via management certificates, but we’re working with the Azure Active Directory team to enable Active Directory authentication in a future release of the Java SDK. In the 0.6.0 release of the Java SDK, the method of authenticating will be management certificates.

Calling the Azure API to Get a List of Regions

Next I’ll add some code to set the value of the subscriptionId field in my code and author some additional Java code that will actually make the API call to Azure to get the list of geographic regions. Once I’ve got that list I’ll simply output the names of the regions to the console. This will demonstrate that I’ve successfully authenticated to the Azure Management API and done some work.

public class Program {
  static String uri = "https://management.core.windows.net/";
  static String subscriptionId = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX";
  static String keyStoreLocation = "c:\\certificates\\AzureJavaDemo.jks";
  static String keyStorePassword = "my-cert-password";

  public static void main(String[] args) throws IOException, URISyntaxException, ServiceException, ParserConfigurationException, SAXException {
    Configuration config = ManagementConfiguration.configure(
      new URI(uri), 
      subscriptionId,
      keyStoreLocation, // the file path to the JKS
      keyStorePassword, // the password for the JKS
      KeyStoreType.jks // flags that I'm using a JKS keystore
    );

    // create a management client to call the API
    ManagementClient client = ManagementService.create(config);

    // get the list of regions
    LocationsListResponse response = client.getLocationsOperations().list();
    ArrayList locations = response.getLocations();

    // write them out
    for( int i=0; i
When I debug the code in Eclipse I can see the expected output, confirming that everything’s in working order and functioning as desired. This proves that I was able to get my management certificate from my subscription successfully converted to JKS format, loaded it into my application’s runtime, and used the management libraries to call out to the API.
Summary and Next Steps
Hopefully this post demonstrates the ease of getting the Java SDK via Maven and of using it to authenticate up to Azure’s API and do some simple work. The SDK can do a lot more than just list regions – create cloud services you could then use the Eclipse Java Toolkit to deploy code to, virtual machines to use as developer workstations or self-maintained servers, Websites that can run your Java code, or storage accounts to house all your stuff. I’ll be investigating some of the options available in the Java SDK on the Azure blog in coming weeks so stay tuned – the 0.6.0. SDK release has a huge swath of new functionality useful for Azure service automation and provisioning.
Along with the Storage SDK for Java and a series of other SDKs available on the Azure home page, it’s easy to see that the opportunities for Java development in Azure are continuing to evolve. We hope you try these new tools and SDKs out and let us know if you have any feedback.
Happy coding!