Deploying a Java application to Windows Azure with Eclipse

Author: Ben Lobaugh <a-beloba@microsoft.com>

Date: Thursday, February 17, 2011, 12:00:00 AM

Tags:

Table of Contents

Updated: 03/22/2011 - Added "UPDATE NOTE" about the Windows Azure Plugin for Eclipse
Updated: 03/10/2011 - Updated "Build the package" to reflect changes to project structure
Updated: 04/15/2011 - Updated article to reflect the Windows Azure Plugin for Eclipse with Java April 2011 CTP
Updated: 06/22/2011 - Updates article to reflect the Windows Azure Plugin for Eclipse with Java, June 2011 CTP

Recommended Reading

Whether you are building a brand new application, or already have something built and wish to take advantage of the high availability and scalability of the Windows Azure cloud, this tutorial will show you how to package and deploy your application and runtime elements using the Windows Azure Plugin for Eclipse with Java, April 2011 CTP.

Tutorial Screencast

In addition to this tutorial we are also providing a screencast showing the creation and deployment of this project. You can find the video on Channel 9 here: http://channel9.msdn.com/posts/Screencast-Windows-Azure-Plugin-for-Eclipse-with-Java-June-2011-CTP

Download and Install Eclipse

The plugin was designed to work in the Eclipse integrated development environment (IDE), to make it easy for a large range of Java developers to easily get up and running on the Windows Azure cloud.

For the purpose of this tutorial, we used Eclipse IDE for Java EE Developers, which can be obtained at http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/heliossr1. Installation is as simple as running the downloaded file, however if you would like there is documentation available on the Eclipse website.

Install the Eclipse Plugin

The plugin adds to Eclipse a set of wizards and dialogs which guide the Java developer through the configuration of key projects settings. The plugin builds on top of the Windows Azure Starter Kit for Java (a command-line toolset) which is a simple template project including the typical files that constitute a Java project, as well as the required elements to package and deploy your application for Windows Azure.

To install using the Eclipse "Available Software" wizard:

1. Open Eclipse

2. Select Help->Install New Software…
clip_image002

3. In the "Work with" textbox, enter the URL http://webdownload.persistent.co.in/windowsazureplugin4ej/and press Enter

4. In the available software list check Windows Azure Plugin for Eclipse with Java and click Next -Tip: If your install process is slow uncheck "Contact all update sites during install to find required software"
clip_image004

5. During the install you may be prompted by a security warning about unsigned binaries. Accept the warning to continue
clip_image005

6. Restart Eclipse
clip_image007

Create a new Windows Azure Project

The plugin makes creating a new Windows Azure project trivial. In the Java EE or Java perspective, simply Click File->New and select Windows Azure Project

NOTE: If you do not see the "Windows Azure Project entry" in the menu in the Java EE or Java perspectives, reset the perspective via Windows > Reset Perspective… If using a different perspective, then go to File > New > Project… and under the Windows Azure Project node, select Windows Azure Project.

clip_image009

In the dialog box enter a name for your project. You may now also enter information about your project roles. If you do not require have any extra roles, or are unsure if you need to change anything here, simply click Finish to create your new project with the default settings, that are be good to start with.

clip_image011

Inside the Windows Azure Eclipse Plugin for Java

If you look in your Package Explorer you will find the typical files that constitute a Java project, as well as several files we built that will help you test, package and deploy your application to Windows Azure.

clip_image013

The main elements of the project directory are:

  • .cspack.jar: Contains the Java implementation of the windowsazurepackage Ant builder task tag referenced in package.xml.
  • ServiceConfiguration.cscfg: This is a sample Azure service configuration file. See the "Advanced Topics" section for more details.
  • ServiceDefinition.csdef: This is a sample Azure service definition file. See the "Advanced Topics" section for more details.
  • HelloWorld.zip: This Zip is provided as a very simple sample deployment payload. Its only purpose is to serve as a placeholder that helps show where to put files to deploy and how to reference them from util\startup.cmd. Since we want to build a snazzy web application we can safely delete this file.
  • cert\SampleRemoteAccessPrivate.pfx - the sample private-key containing certificate used by the default "out-of-the-box" remote access configuration of a new Windows Azure project. This is provided for educational purposes only, as this key's password is publicly known (Password1). You should replace it with your own cert using the functionality in the Remote Access page of the project properties dialog (in the Windows Azure section). In general, your PFX file is the certificate that you need to upload to Windows Azure to take advantage of remote desktop connectivity.
  • cert\SampleRemoteAccessPublic.cer -this based on the same cert as SampleRemoteAccessPrivate.pfx, but it only includes the public key. You will want to replace this with your own, as mentioned earlier. The CER file is what the plugin uses to encrypt your remote access credentials inside of the CSDEF file.
  • util\startup.cmd: The sample project is configured to run this Windows script each time your Worker Role starts. Here you will define anything that needs to take place on startup, such as starting a Java server, or firing off a background service.
  • util\unzip.vbs: Simple script provided to make it easy to unzip zipped archives in startup.cmd
  • util\download.vbs - a simple utility script for downloading files from URL locations into the approot as part of startup.cmd. This helps avoid the need to embed certain types of files, for example large and rarely changing files (such as the Java runtime, or a server distribution) into the deployment package itself, making it much smaller and faster to upload. The URL could point to any download that does not require additional authentication (such as public websites, or Windows Azure blobs with anonymous access enabled) or one where all the authentication information needed is embedded in the URL (such as Windows Azure blobs with shared access signature authentication enabled.)
  • util\log.cmd - a simple utility script for logging the output of your startup script commands into a log.txt file inside the approot directory. The way you'd use it is instead of executing a command directly in your startup.cmd, you call log.cmd instead and pass the command as a parameter. For example (as shown in the default startup.cmd file):
    util\log.cmd cscript "util\unzip.vbs" "HelloWorld.zip" "%ROLEROOT%\approot"
    While you're learning how to work with Windows Azure, it's best not to delete the util folder, because its contents are referenced by other files within the sample project.

(The .templates, .project, .externalToolBuilders and .WorkerRoleEntryPoint.dll are used by the plugin and they are not meant to be user-modifiable)

Select the Java server environment

The project template is designed to work with multiple Java server environments.

As we progress through this tutorial I will show you how to setup two servers, Tomcat and Jetty. You are definitely not limited to using only these two servers, in fact it should be possible to deploy any server or other Java application that can be successfully deployed using Windows commandline only using this approach

Download the server distribution (e.g. as a ZIP file) and copy it into the approot folder of the role directory within your project where you want to deploy it.. We do not have to extract the server from the archive file just yet, we will do that with the startup.cmd script.

The packages I am using can be found at

;

Using Tomcat server

Using Jetty server

clip_image015

clip_image017

;

Author note: I have placed each archive in it's own directory because I feel it is easier to quickly find files in the file tree this way. You are not forced to repeat this in your project. You may place the files wherever you like in your approot folder, just be sure to update the startup.cmd script with the correct paths.

Select the Java Runtime Environment

Tip: For more information on this issue see this stackoverflow article http://stackoverflow.com/questions/1619662/where-can-i-get-the-latest-jre-jdk-as-a-zip-file-i-mean-no-exe-installer

As with the server, feel free to choose whatever Java runtime environment you are comfortable with using. For this sample, I will be using the Java Runtime Environment (JRE) shipped by Oracle. Download the JRE and copy it in the approot folder. You do not have to extract the JRE.

The Oracle JRE can be found at http://www.oracle.com/technetwork/java/javase/downloads/index.html

Unfortunately there is not a Zip version of the JRE, only the installer. The solution therefore seems to be creating your own Zip. I created mine by zipping C:\Program Files\Java\jre6

clip_image019

Build a simple JSP Hello World app

Go ahead and delete the HelloWorld.zip file.

Note: Do not delete the util folder! This folder contains needed project files.

Right click on HelloWorld.zip in the Package Explorer and click Delete

clip_image021

Click Ok

clip_image023

Now create a simple HelloWorld.jsp in the approot folder. Later you can expand the application by copying in your current application, or creating the application code directly in the approot folder.

From the File menu choose New and click Other

clip_image025

Under the Web folder choose JSP File then click Next

clip_image027

Select the approot folder under WorkerRole1 and use the file name "HelloWorld.jsp" then click Finish

clip_image029

Use the following content inside the HelloWorld.jsp file you just created.

<%@ page language="java" contentType="text/html; charset=ISO-8859-1" pageEncoding="ISO-8859-1"%>

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
    <title>Insert title here</title>
</head>
<body>

<%!
    public String GetString() {
        return "\"Look! I work!\"";
    }
%>

The Java Server is Running = <%= GetString() %>

</body>
</html>

Modify startup.cmd

The next step is to edit the startup.cmd with the appropriate commands relative to the server environment.

Open startup.cmd inside the approot/util folder and replace the content with the following commands, for either Jetty or Tomcat.

Tomcat

@REM unzip Tomcat
cscript /B /Nologo util\unzip.vbs Tomcat\apache-tomcat-7.0.6-windows-x64.zip "%ROLEROOT%\approot"

@REM unzip JRE
cscript /B /Nologo util\unzip.vbs JRE\jre6.zip "%ROLEROOT%\approot"

@REM copy project files to server
md "%ROLEROOT%\approot\apache-tomcat-7.0.6\webapps\myapp"
copy HelloWorld.jsp "%ROLEROOT%\approot\apache-tomcat-7.0.6\webapps\myapp"

@REM start the server
cd "%ROLEROOT%\approot\apache-tomcat-7.0.6\bin"
set JRE_HOME=%ROLEROOT%\approot\jre6
startup.bat

Jetty

@REM unzip Jetty
cscript /B /Nologo util\unzip.vbs Jetty\jetty-distribution-7.2.2.v20101205.zip "%ROLEROOT%\approot"

@REM unzip JRE
cscript /B /Nologo util\unzip.vbs JRE\jre6.zip "%ROLEROOT%\approot"

@REM copy project files to server
md "%ROLEROOT%\approot\jetty-distribution-7.2.2.v20101205\webapps\myapp"
copy HelloWorld.jsp "%ROLEROOT%\approot\jetty-distribution-7.2.2.v20101205\webapps\myapp"

@REM start the server
cd "%ROLEROOT%\approot\jetty-distribution-7.2.2.v20101205"
start "%ROLEROOT%\approot\jre6\bin\java.exe -jar start.jar"

I referenced specific file names above for the versions I used while writing this tutorial. Be sure you change the file names to match your own version.

Configure an endpoint (port number) for the server

Next, we will tell Windows Azure to make a public endpoint (an input port) available for your Java server to listen to.

Make sure your project is selected in the project explorer in Eclipse and select Project > Properties in the main menu, then expand the Windows Azure entry in the list and select the Roles sub-entry. You will see this dialog:

clip_image031

In the roles list, select the role where you want to deploy the server and click Edit… The Windows Azure Role details dialog will show up, showing a list of currently configured end points (empty by default):

clip_image033

Click Add to configure a new endpoint. The Endpoint details dialog will show up, where you will enter the details for your endpoint:

clip_image035

  1. Assign some name to the endpoint (for example "MyHttpPort")
  2. leave the Type set to Input, the default setting that makes the endpoint publicly accessible
  3. Set Public Port to 80
  4. Set Private Port to 8080
  5. Click OK

These settings tell the Windows Azure load balancer to forward port 80 traffic to port 8080 on the machine running the Windows Azure role instance. The configuration is the same for either Jetty or Tomcat.

Build the package for emulator testing

Building a project is relatively painless in Eclipse. You can click the Build All toolbar button, choose Build All from the Project menu, or use the CTRL+B keyboard shortcut.

clip_image037 ; clip_image039

NOTE: If the build process reports success in the Console view, but you do not see the deploy folder in your project, refresh the Package Explorer.

In your Package Explorer you will now see a folder called "deploy". This folder contains the files and directories necessary for deploying your package to Windows Azure cloud or the development fabric emulator (default), among them an exact replica of the approot directory for each role of your role folders. When the package is built for the emulator, it's not a single file but rather a directory structure. This enables you to see the file system modifications that occur when your application starts running within the emulator, as the files in that directory are "live".

clip_image041

Testing in the local Windows Azure emulator

The easiest way to deploy your package to the Windows Azure compute emulator running on your computer is by taking advantage of the Windows command script shortcuts in the emulatorTools directory, which gets generated when your project is configured for local deployment to the emulator, i.e. when the "Build For" setting in the Windows Azure page of the project properties is set to "Testing in emulator: "

clip_image043

The emulatorTools folder contains a few simple scripts that make it quicker and easier to display and reset the Windows Azure compute emulator and run your service in it:

  • DisplayEmulatorUI.cmd
    • Quick and easy way to start the Compute Emulator UI without leaving Eclipse
  • RunInEmulator.cmd
    • This script will start up the local Windows Azure development cloud and deploy your project to it. (If you're familiar with the first release of the Windows Azure Starter Kit for Java, this script originally existed as "csrun.cmd" in the "deploy" folder)
      Note: If you are using development storage you will still need to start the Storage Emulator manually.
  • ResetEmulator.cmd
    • Removes any running instances of your application from the Compute Emulator and unlocks the files in use by the emulator. This is helpful when you're about to rebuild but your previous build is still running in the emulator. Unless you remove your older deployment from the emulator, the emulator will keep a lock on the files in the "deploy" folder preventing you from a successful rebuild. This script helps you quickly get that taken care of before you rebuild.

Note: if you open one of these files in Eclipse with Text Editor, Eclipse will remember that and double-clicking on them will not run them but instead open them as text files again. To run them, you need to Open With | System Editor.

To deploy your package to the compute emulator and watch its progress, follow these steps:

  1. Double-click DisplayEmulator.cmd and watch the emulator UI pop up
  2. Double-click RunInEmulator.cmd to deploy your package (and switch over to the compute emulator UI windows to watch its progress)

When done, and before you rebuild your project, remember to double-click ResetEmulator.cmd to clear the compute emulator and release the file locks that it holds on files in your deploy directory (thus preventing a successful rebuild).

TIP: There are also Windows UI and command line-based ways of starting the emulator. To learn more, search online for csrun.exe.

Verifying it works

How do you know that your deployment worked?

First of all, check the emulator UI. You need to verify that when you select your role node in the emulator UI, the last statement reported is "Role state Started".

clip_image045

To verify that the server is actually working, in your web browser, navigate to: http://localhost:8080/myapp/HelloWorld.jsp

TIP: When you refresh the approot folder inside the deploy folder in Eclipse, you will also notice new files listed as a result of your deployment steps in startup.cmd.

Packaging the application for deployment on Windows Azure

By default, your Windows Azure project will be built in a way that allows the emulator to run it on your machine. If you are ready to start testing your deployment in the Windows Azure cloud, you need to change the setting that controls the package type by going to the project properties dialog, selecting the Windows Azure section, and changing the Build For setting to "Deployment to cloud":

clip_image047

Deploying your application to the Windows Azure cloud

Deploying your application to the Windows Azure cloud is as simple as logging in to the Windows Azure Portal and uploading the .cspkg and .cscfg files creating when you built your package for the cloud. For your convenience, there is a direct shortcut to the Windows Azure portal included in your deploy folder, when your package is built for deployment to the cloud:

clip_image049

Note about the pre-configured remote access

Your project is pre-configured with remote desktop access turned on, to enable easier troubleshooting in the cloud. But that means that in addition to the *.cspkg and the *.cscfg files, you also need to upload a remote access certificate, otherwise the Windows Azure portal will reject your upload. A sample certificate "SampleRemoteAccessPrivate.pfx" is included in the cert folder for your convenience, so you can upload that if all you're doing is learning and deploying to staging and not production. But this cert is intended for educational purposes only and its private key password is publicly known (Password1). So if plan to take more regular advantage of remote access, you should either use an authority-issued certificate, or create a self-signed certificate of your own, using the Remote Access page of the Windows Azure section of the project properties dialog:

clip_image050

Alternatively, you can disable remote access altogether for the time being using that dialog.

More on remote access in an upcoming tutorial…

For specific details on deploying please see the following articles:
http://msdn.microsoft.com/en-us/library/gg433027.aspx
http://msdn.microsoft.com/en-us/windowsazure/ff798117.aspx

Advanced

The plugin also includes several advanced features that are available to you after creating your project.

Adding and Removing Roles from an Existing Project

Frequently you will find yourself building projects that need multiple roles, be it for additional background processing or more instances of your web interface, the plugin has a convenient way to create new roles and/or remove existing roles.

Open your project properties. Locate and expand Windows Azure in the left menu and select Roles. New roles will need to be setup with their own copies of Java (This is a great time to think about storing your environment in a blob and using the download tool to minimize package overhead.) The rest should be self-explanatory:

clip_image052

Updating the Service Name

The easiest way to change the service name of your deployment is through the project properties. Open the project properties. Select Windows Azure from the left menu. Update your service name to whatever you require.

clip_image054

Advanced Topics

· Windows Azure SDK Schema Reference (Detailed usage of the .cscfg and .csdef files)

 
blog comments powered by Disqus