Dan Orlando provides an introduction to the AWS Toolkit for Eclipse and walks through the basic steps for deploying a Java web application to Amazon EC2.

By Dan Orlando

The new AWS Toolkit for Eclipse is the latest Amazon innovation for the Amazon Elastic Compute Cloud (Amazon EC2) platform, and it streamlines the workflow for Java developers using Apache Tomcat with Amazon EC2. In simple terms, Amazon EC2 is a distributed network infrastructure that is "elastic" in the sense that resources are allocated dynamically with Amazon Machine Instances (AMIs). An AMI is basically like a virtual machine (VM), and the specific properties of the AMI that will run on all instances of an Amazon EC2 cluster are defined when you set the cluster up (as you will see later in this article). More information on Amazon EC2 is available through the AWS web site. You can also find an extensive amount of material on Amazon EC2 in the documentation section of the AWS control panel. (Note that in order to gain access to the AWS control panel, you must first set up an AWS account.)

The environment of choice for most programmers currently developing Java web applications with Tomcat is the Eclipse integrated development environment (IDE) in conjunction with the built-in Web Tools Platform (WTP) that comes with most distributions of Eclipse for Java Platform, Enterprise Edition (Java EE) development. In the past, developing these Java web applications with Tomcat and deploying them through Amazon EC2 was a considerably irritating process that involved multiple steps and a number of separate tools. In other words, there was no simple, streamlined solution. As a result, developers had to find or build their own AMI, use a different tool to start an instance based on that AMI, write their own deployment script, then configure Tomcat on Amazon EC2 so that it connected to the debugging session. Then, after perfecting the application, developers had to use different tools to bundle the AMI.

The AWS Toolkit for Eclipse solves this problem by moving all those tasks into Eclipse. It also automates most of the steps required, making it easier to develop, deploy, debug, and bundle Java applications in Amazon EC2. It is important to note that the toolkit is very well documented. After installing it, I strongly encourage you to explore the documentation. Simply access it by clicking Help > Help Contents in Eclipse. If you have installed the toolkit properly, you will find a new topic in the left pane of the Eclipse Help titled AWS Toolkit User Guide.

AWS Toolkit Installation and Setup

Setting up the AWS Toolkit for Amazon EC2 may be slightly different based on the version of the Eclipse IDE you are running on your local machine, but the differences are typically minor. After downloading the tool from the AWS web site, fire up Eclipse, and open the software updates panel by clicking Help > Software Updates in Eclipse. Click the Available Software tab, click Add Site, and in the next window, click Local to bring up a file-selection window. Navigate to the directory that holds the AWS tool after extracting it, then select it. It should be called server-root. You should then see a new entry in the Available Software window that shows the path to the directory you just selected. Select the check box next to the directory, and you should see something that looks similar to Figure 1. With the check box selected, click Install to display a new window, then click Finish. The tool is now installed, and you will be prompted to restart Eclipse.

Figure 1. The Available Software window after adding the AWS Development Tools

After you've restarted Eclipse, the first thing you will probably notice is a new default workbench. Click X to close that tab. Now, click Window > Show View > Other in Eclipse. Click the arrow next to Amazon EC2 to reveal the names of the four tabs that come with the AWS Toolkit. Click the first tab—EC2 AMIs—then click OK. Repeat this process for each of the other three children in the Amazon EC2 drop-down list. You'll probably find yourself wanting to quickly switch between tabs periodically, so it's worth leaving all four of them available in your default workspace.

I also encourage you to open the Help Contents in Eclipse and explore the comprehensive documentation that has been provided along with the AWS Toolkit that you just installed. The documentation will reside under a new entry to your Eclipse Help Contents with the title, AWS Toolkit User Guide.

Here is a brief description of each of the four views that come with the AWS Toolkit:

• EC2 AMIs. This view provides a list of all available AMIs. You can also search for AMIs, launch Amazon EC2 instances from AMIs, and delete AMIs that are registered to you from here. For the list to be populated, you must configure your AWS account within Eclipse, which you will do next.
• EC2 Elastic Block Storage. This view allows you to manage your Amazon Elastic Block Store (EBS) volumes and snapshots. I do not discuss EBS volumes in great detail in this article, but you can easily find out more about them from the tool's Help documentation.
• EC2 Instances. This is the tab that you will most likely have selected most of the time while working with AWS from Eclipse. This view provides a list of all the Amazon EC2 instances currently running under your account and allows you to manage them directly from here.
• EC2 Security Groups. This view allows you to easily manage your Amazon EC2 security groups. The neatest thing about this view is that it allows you to quickly and easily add and remove groups as well as add and remove permissions for each security group. I don't go into too much detail about Amazon EC2 security groups in this article, but the tool's comprehensive documentation as well as the AWS web site provide plenty of information on Amazon EC2 security groups.

Configure Your Account in Eclipse

Figure 2 shows the bottom section of the Eclipse IDE with all four Amazon EC2 views open. You should be seeing something similar at this point. Notice the AWS account not configured correctly link above the data table in Figure 2: Click this link in your local Eclipse IDE. Now, make sure that AWS Toolkit is selected in the left navigation pane in the window that pops up. This is your Amazon Account Preferences window for the Eclipse AWS tool. If you have not yet created an AWS account or need to find your account information, links to the respective pages on the AWS site have been conveniently placed at the top of the preferences form.

Figure 2. All four tabs of the AWS tool are open, but the AWS account configuration has not yet been set within the Eclipse AWS tool.

Starting a Tomcat Cluster

At this point, the dirty work is more or less done, so breathe a sigh of relief, because now comes the fun stuff. You are about to start a cluster of Tomcat servers from within Eclipse. First, click Window > Show View, and then click Servers. In the Servers pane, right-click inside the white space, then click New Server. In the New Server dialog box, in the Server's host name box, type EC2. Doing so should automatically filter your options in the server type pane, which should now look like Figure 3. Expand Apache, which should reveal a single entry: Amazon EC2 Tomcat v6.0 Cluster. Select this entry, then type a name by which to identify your cluster in the Server name box. If this is your first time creating a cluster, you might be prompted to specify the location of a local Tomcat runtime. If you do not have a local Tomcat runtime, you can download one here. Clicking the Configure runtime environment link brings up a list of your local Tomcat runtime environments. In most cases, you will not need to modify anything here, but it is worth remembering where to find it in case you need to access it. Now, click Finish. 

Figure 3. Typing EC2 in the Server's host name box filters out unnecessary values in the server type pane. Expand the Apache directory to reveal the Amazon EC2 entry.

You should now see a dialog box similar to Figure 4.

Figure 4. Cluster configuration settings

Perform the following steps to configure your cluster:

1. In the Cluster Size box, type the number of instances you want your cluster to contain.
2. Right-click in the Key Pair area, then click New Key Pair. 
3. Name your key pair Tomcat.
4. Select a directory for your private key, then click Finish.
5. Right-click in the Security Group area, then click New Security Group.
6. Type default for the Name and Description columns, then click Finish.
7. Right-click in the Elastic IP area, then click New Elastic IP.
   You should now see an entry in the Elastic IP column. 
8. Select each of the three new entries you just created in the three areas displayed, then click Finish.

Note: Elastic IP addresses are dynamically remappable IP addresses that fit better into the cloud computing paradigm than the static IP addresses used with traditional hosting solutions. For instance, using elastic IP addresses, you could deploy a new application release on a separate Amazon EC2 instance, assign a new elastic IP address to it, and—when testing on the new release is complete—remap the original elastic IP address to the Amazon EC2 instance that holds the new release.

The New Servers dialog box should now display the cluster you just created. Double-click the entry to view the details of the server as well as to change configuration settings like Multipurpose Internet Mail Extension (MIME) types and server ports. It is also noteworthy to point out the new Servers directory in Project Explorer: This directory provides quick and easy access to advanced configuration files that hold settings for your cluster, such as:

• catalina.policy. The catalina policy file holds permissions policies and security restrictions.
• catalina.properties. The catalina properties file holds configuration settings for the Tomcat server.
• context.xml. This file defines monitored resources.
• server.xml. This file defines connection points for services running on the server.
• tomcat-users.xml. This is the user definitions file for Tomcat.
• web.xml. This file define system-wide default values for all web applications that are to run on the server.

Deploying an Application

You can now create a simple JavaServer Pages (JSP) application and deploy it on the cluster you just created. To do so, perform the following steps:

1. Create a new dynamic web project, and name it HelloEC2World using the New Project Wizard from Eclipse.
2. In Eclipse, click File > New > Servlet to create a new servlet called HelloWorld.
   If you do not see the Servlet command in the New menu, you can create it by clicking File > New > Other. Then, in the dialog box that appears, click Web > Servlet.
3. In Class Name, type HelloClient, then click Finish.
4. In the HelloClient.java class now displayed, change the body of the doGet() method as follows:

   protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
   	response.getWriter().println("Hello EC2 world!");
   	}
   

At this point, you are nearly ready to deploy an application to the cluster. Simply start the server cluster you just created by right-clicking it in the Servers pane, then click Start. The State value should now change from Stopped to Starting. You will also see its progress on the Eclipse task bar.

Note: The first time you start the cluster, it may take a bit longer than normal.

When the State value changes to Started, right-click it, then click Add or Remove Projects. The window that appears displays the projects in the current workspace open on the left and the applications that you want running on the cluster on the right. Select your HelloEC2World application from the box on the left, click Add, then click Finish. The project you selected will now begin publishing to the server cluster. Finally, right-click the HelloEC2World main application folder in the Eclipse Project Explorer, then click Run As > Run on Server.

Debugging Your Application

One of the greatest features of the AWS Eclipse tool is the ability to remotely debug applications on your Amazon EC2 cluster. Begin by adding a breakpoint, and debug your HelloClient.java class directly on the server. To do so, perform the following steps:

1. With your HelloClient.java class open in Eclipse, add a breakpoint by double-clicking the gray border on the left side of the code view window at line 26.

   You should now see a blue dot at line 26, as shown in Figure 5.

   
   Figure 5. Place a breakpoint at line 26 in the code view of the HelloClient.java class.

2. Right-click the HelloClient.java class in Project Explorer, then click Debug as > Debug on Server.

   Make sure the correct server is selected, as seen in Figure 6, then click Finish.

   >
   Figure 6. The Eclipse Debug On Server dialog box

   If you are not already running in Debug mode, a prompt appears informing you that the server is not running in Debug mode, as seen in Figure 7.

   
   Figure 7. If you are not running in Debug mode, you will be prompted to switch modes, which restarts the server in Debug mode, if necessary.

3. Select Switch mode (will restart if necessary), then click OK.

   Selecting this option automatically connects to Tomcat's debug port on your cluster and runs the application in Debug mode from the server.

   When the server hits the breakpoint you inserted, you may be prompted to allow Eclipse to open the Debug perspective.

4. Click OK to display the Debug perspective.
5. Use the arrows at the top of the Debug window (as shown in Figure 8) to step into or over the breakpoint.
   
   
   Figure 8. The Debug window on the Debug perspective.

Conclusion

The necessity of the AWS Toolkit for Eclipse is quite clear, considering the amount of time saved by bringing what used to be a painful multi-step process into a streamlined workflow within Eclipse. Additionally, the more you use the toolkit, the more you will likely be impressed not only by how powerful the plug-in is but also by the robust code and the attention to detail with regard to implementing a developer-friendly user interface for the toolkit. I have experimented with quite a few pre-release and first-release Eclipse plug-ins and toolkits, and they are typically still somewhat buggy. Amazon deserves some major kudos not just for fulfilling a significant need but also for the quality of the code that makes up this tool.

About the Author

Dan Orlando is a published author on rich application development in the enterprise and has been featured  in such magazines and web sites as PHP Architect, IBM DeveloperWorks, and the Adobe Developer Connection.