Contents


Bluemix fundamentals: Deploy a sample Java application to the cloud

Intro to Java web application development on IBM Bluemix

Comments

This tutorial series was written using a previous version of the IBM Bluemix® interface. Given the rapid evolution of technology, some steps and illustrations may have changed. We are now in the process of updating this tutorial. In the meantime, be sure to check out the newly updated Bluemix essentials course on developerWorks.

Overview

Get started working in the cloud using the language and tooling you're already familiar with as a Java™ developer. In this tutorial, learn how to run, modify, test, and deploy a simple web app to the cloud using the Java language and the IBM Bluemix® Tools for Eclipse. Once you deploy the app to Bluemix, IBM's cloud development platform, anyone on the Internet can access it.

This tutorial is part of the "Bluemix fundamentals" tutorial series on developerWorks.

 

What you'll do in this tutorial

Step 1. Download the code

Step 2. Deploy the WAR file to Bluemix

Step 3. Import the app into your Eclipse workspace

Step 4. Examine the code structure

Step 5. Run the app with Eclipse on Liberty Profile

Step 6. Run JUnit tests

Step 7. Modify the code and rerun the app

Step 8. Rerun the JUnit tests

Step 9. Deploy the changed code to Bluemix

Quiz time!

What's next?

Let's get started

IBM Bluemix is where enterprise developers build, run, scale, and manage applications. Ready to start creating your own apps on Bluemix? This tutorial walks you through the steps for hosting a Java web application. You start with a sample Java web app, run it on your local system, modify the code, and then deploy the app to Bluemix so that anyone who's online can use it.

If you're unsure about Bluemix terms and status messages you may see, head over to the Glossary and status messages section of this tutorial.

Here's a quick overview of how you'll work with Bluemix in this tutorial:

Overview diagram showing relationship between local and cloud components for deploying the sample app
Overview diagram showing relationship between local and cloud components for deploying the sample app

You run your own instance of the Liberty profile server in the cloud. Once the Liberty profile is deployed successfully, it runs continuously and is not shared by anyone.

You run the Eclipse IDE on your computer and load the app's source code via an Eclipse project archive file. A local instance of the Liberty profile runs in Eclipse. With this setup you can quickly test and debug your app without connecting to the Internet and uploading code every time you make a change.

After you get your code running on the local server and are satisfied that it's ready for prime time, you package your server and send it to the cloud (the process represented by the solid arrows in the diagram). Your app is then available through Bluemix and accessible over the Internet by anyone with a browser.

The dotted arrows in the diagram represent an alternative way to deploy a web app to Bluemix. If you have the Java Enterprise Edition (JEE) compatible WAR file containing the app, you can deploy it directly to Bluemix within minutes — even without installing Java (or Eclipse) on your computer. The tutorial shows you this alternative method first.

Knowledge that you need for this tutorial

  • Working knowledge of Java programming, including JavaServer Pages (JSP) technology
  • General knowledge of client/server system basics and terminology

Software that you need for this tutorial

Step 1. Download the sample Java web app

  1. Click this button to download the code for the sample Java web app, javatutorial1_code_0803.zip:
  2. Save javatutorial1_code_0803.zip to your computer and extract its contents, which consists of:
    • lauren.war: A standard Java EE WAR file, containing the servlets, JSP, and web.xml file that constitute the application
    • lllproject.zip: An Eclipse project archive, containing the complete Eclipse project for this tutorial

Step 2. Deploy the WAR file to Bluemix

You can deploy the lauren.war file directly to JEE-compatible servers such as a Liberty profile server running either on your own computer or in the Bluemix cloud. You'll deploy it now to Bluemix:

  1. If you're not already logged in to Bluemix, run these Cloud Foundry commands from your OS command prompt to log in:

    cf api https://api.ng.bluemix.net/
    cf login

  2. Deploy lauren.war to Bluemix by running this command:

    cf push your app name -p lauren.war

    The name you choose for your application must be unique on Bluemix — not used by any other Bluemix user. You'll get an error if the name (called a route) is taken.

    The command that you just ran:

    1. Uploads the WAR file to Bluemix
    2. Runs the Liberty profile buildpack in Bluemix
    3. Starts your Liberty profile server instance in Bluemix
    4. Deploys the app in your Liberty Profile server instance
    5. Maps a route to your running app, enabling the app to be accessed over the Internet at the URL https://your app name.mybluemix.net/
  3. Open https://your app name.mybluemix.net/ in your browser to try out the app — a simple web store called Lauren's Lovely Landscapes. The store currently sells three prints; each print's page displays the associated name, image, and price.
  4. Stop and reflect. You just finished deploying a working web application to the cloud! The cf command-line tool and a Bluemix account were all you needed.

Later in this tutorial, in Glossary and status messages, you'll learn more about how the buildpack works together with Bluemix to stage and deploy your app.

Starting with the next step, you'll begin to examine and modify the code. The Eclipse IDE makes it easy to work with the code and navigate the big project directories tree when you develop Java web applications.

Step 3. Import the app into your Eclipse workspace

  1. Start your Eclipse IDE and select File > Import. Then select General > Existing Projects into Workspace: Screenshot of selecting to import an existing project
    Screenshot of selecting to import an existing project
  2. Click the Select archive file option: Screenshot of selecting the project file to import
    Screenshot of selecting the project file to import
  3. Browse to and select the lllproject.zip file.
  4. Click Finish.

The LaurenLandscapesJava project is now imported into your workspace. You can see its structure in the Enterprise Explorer pane on the left. The next step familiarizes you with the project and the code.

Step 4. Examine the code structure

With your project open in Eclipse, take a look at the Enterprise Explorer pane on the left:

Screenshot of the Enterprise Explorer in Eclipse
Screenshot of the Enterprise Explorer in Eclipse

Expand Java Resources to see the Java source code files. Expand WebContent to see the four JSP files that make up the website:

This diagram shows how the app works:

Diagram of the application flow
Diagram of the application flow

Web requests for a page of the Lauren's Lovely Landscapes store first go through the DispatchServlet and then are forwarded to one of the JSP pages. The DispatchServlet attaches an instance of the WebsiteTitle POJO (Plain Old Java Object) to the request. The request is passed on to the JSP page. The JSP page uses the WebsiteTitle to set the title to Lauren's Lovely Landscapes.

If you examine the DispatchServlet source code, you can see the servlet path mapping specified with the @WebServlet annotation:

@WebServlet({ "/home", "/antarctica", "/alaska", "/arctic", "/australia"})
public class DispatchServlet extends HttpServlet {
...

In this case, all four paths —/home, /antarctica, /alaska, and /australia— map to DispatchServlet. The Liberty profile hands the request for these paths first to the DispatchServlet.

In DispatchServlet, you can also see the code that attaches an instance of WebsiteTitle as an attribute of the request:

request.setAttribute("myapp", myapp);

If you examine one of the JSP files — alaska.jsp, for instance — you can see the Expression Language (EL) code that fetches the title:

<head>
	<title> ${myapp.title} </title>
...

Step 5. Run the app on the Liberty profile with Eclipse

You're now ready to run the app locally on an instance of the Liberty profile that's managed by Eclipse:

  1. Select the project in the Enterprise Explorer, right-click, and select RunAs > Run on Server... to open a server-selection dialog box.
  2. Expand the localhost folder and select the local Liberty profile server: Screenshot of selecing the Liberty profile server
    Screenshot of selecing the Liberty profile server
  3. The selection you just made starts the local instance of the Liberty profile, loads the app, and points the Eclipse internal browser to the running application: Screenshot of the app running the the built-in Eclipse browser
    Screenshot of the app running the the built-in Eclipse browser
  4. Try out this instance of the application and see if you notice any difference from the Bluemix-hosted one. Because you're looking at the same app, produced with the same code, there should be no noticeable differences between the two.

Step 6. Run JUnit tests

It's good Java coding practice to write unit tests for your classes.

The WebsiteTitle class comes with two unit tests. To run the tests, follow this sequence:

  1. Stop the app by clicking the square red button in the server pane.
  2. Select the project in the Enterprise Explorer.
  3. Right-click and select Run As > JUnit Tests.

You can see both tests being run. Green status indicates that all unit tests were successful:

Screenshot of successful unit test run
Screenshot of successful unit test run

Step 7. Modify the code and rerun the app

In this step, you'll modify the price of a print and see it updated on the locally running website right away.

  1. In the Enterprise Explorer in Eclipse, click the antarctica.jsp file and look for the price in the source code.
  2. Change the price from 100.00 to 99.99 and save the file. The changed code should look like:
    <div id="price">99.99</div>
  3. Run the app on the local Liberty Profile server again by selecting the project and right-clicking Run as > Run on server.
  4. Use the built-in browser in Eclipse to browse to the app.
  5. Select the Antarctica print and note the print's changed price.

Step 8. Rerun the JUnit tests

To ensure that your code changes don't break anything, get into the habit of running unit tests every time an app is modified.

To rerun the unit tests:

  1. Make sure the server has stopped running the app.
  2. Select the project in the Enterprise Explorer.
  3. Right-click and select Run As... > JUnit Tests.

Once again, you see the green status, indicating that all unit tests were successful.

When you develop Java code in a team environment, you want to run all unit tests every single time you commit (modify and contribute) your code to the team's repository. Bluemix offers open toolchains and IBM Bluemix Continuous Delivery that can be configured to run the unit tests automatically as part of the workflow to build the project. You'll learn much more about open toolchains and IBM Bluemix Continuous Delivery in the next tutorial in this series.

Step 9. Deploy the changed code to Bluemix

To let everyone on the Internet know about the Antarctica print's new price, you'll deploy the changed app to Bluemix. In this step, you see an even easier way to deploy the project to Bluemix than using a WAR file — namely, using the IBM Eclipse Tools for Bluemix to package up your Liberty profile server instance and deploy it on Bluemix:

  1. In Eclipse, stop the local Liberty profile server instance by clicking the square red button. Now you can see the stopped status associated with the server: Screenshot of the server listed with stopped status
    Screenshot of the server listed with stopped status
  2. Right-click the Liberty profile server in the Servers pane and select Utilities > Package Server to IBM Bluemix. You may need to add the Bluemix server: Click the Add Server... link in the Select IBM Bluemix Server dialog and follow the instructions.
  3. Log in to your Bluemix account when prompted.
  4. Provide a name for the application. You can either reuse the existing app name or create a new one: Screenshot of the Application details dialog box
    Screenshot of the Application details dialog box
  5. In the Launch deployment dialog box, you can increase the memory limit if you like, but for this app 512MB is sufficient: Screenshot of the Launch deployment dialog box
    Screenshot of the Launch deployment dialog box
  6. Click Finish to start the deployment. You see a series of status messages, and the server is deployed and started on Bluemix.

After successful deployment, try out the app by pointing any web browser to:

https://your app name.mybluemix.net/

Glossary and status messages

Let's review some terms and status messages you're likely to encounter as you use Bluemix.

Glossary

Familiarize yourself with the following important terms, which you'll often see in documentation and status messages when you work with Bluemix.

  • Droplet— A bundle ready to run in the cloud, including everything needed (for instance, a bundle with JVM, Liberty profile server, and your app) except an operating system.
  • Buildpack— An executable that takes the code or packaged server that you push, and bundles it up into a droplet.
  • Manifest— An optional file, named manifest.yml, that you can add to your project. The manifest file configures various parameters that affect the deployed server — including memory size, buildpack to use during deployment, services that are required, the disk space consumed, and so on. For simple Java web apps, you don't need a manifest; the system automatically detects and uses the Liberty profile buildpack and applies a default configuration.

  • Staging— The process handled by the buildpack, bundling what you uploaded with system components and dependencies into a valid droplet
  • Droplet Execution Agent (DEA)— The system piece that's responsible for reconstituting the droplet and running your app in the cloud
  • Warden— A mechanism to ensure that your app is isolated and secured from other running apps

Status messages

When you issue the cf push CLI command or deploy via the IBM Tools for Eclipse, you see a series of status messages. If you examine them carefully, you'll see the following sequential phases:

  1. Your push successfully uploaded the WAR or packaged server to the staging area.
  2. If an existing instance of your app is already running, it's stopped before staging begins.
  3. The buildpack starts the staging process, which can include:
    1. Downloading and installing various system components
    2. Downloading and installing compilers (the JVM, for example)
    3. Putting your app into place
    4. Setting up the environment
    5. Bundling everything up to create the droplet
    To speed up these steps, staging makes heavy use of cache, so you might also see some reuse-from-cache messages in the mix.
  4. The DEA tries to start your app from the droplet, running under supervision of a warden (container).

For the more advanced readers, Liberty expert Tom Banks shows how to develop an app first in the Liberty profile on a laptop, and then in the cloud using WebSphere developer tools for Eclipse:

Quiz

Test your knowledge of what you've learned in this tutorial. Answers are below.

 

  1. You must install the Eclipse IDE on your system before deploying Java web applications to Bluemix.
    1. True
    2. False
  2. To deploy a web app bundled in a Java EE 6 WAR file to Bluemix, you need:
    1. The Cloud Foundry CLI : cf
    2. IBM Eclipse Tools for Bluemix
    3. Cloud Foundry Integration for Eclipse
    4. All of the above
    5. Any one of a) to c)
  3. The application name you choose for your Lauren's Lovely Landscape Bluemix deployment must be:
    1. Long and important sounding
    2. Short and concise
    3. Unique among all your other apps
    4. Unique among all apps at the same data center
    5. Unused by any other Bluemix user in the entire world
  4. The ready-to-run bundle created by Bluemix after you push your application is called a:
    1. Bluemix dropping
    2. Mullet
    3. Droplet
    4. Ready-to-run bundle
    5. Bluemix zip file

Answers to quiz

1. b, 2. e, 3. e, 4. c

What's next?

In this tutorial, you:

  • Deployed a Java EE 6 web app to Bluemix by pushing a WAR file using the Cloud Foundry CLI
  • Used the Eclipse IDE to examine, code, compile, and unit-test a web app
  • Used the Liberty profile server managed by Eclipse to run and test your app locally
  • Used IBM Eclipse Tools for Bluemix to package and deploy a local Liberty profile server instance to Bluemix

Now, continue learning "Bluemix fundamentals" on developerWorks with this next tutorial. You'll learn how to set up team collaboration and automated deployments for your Java app:

More Bluemix resources

For a steady stream of tutorials and other technical resources to help you learn, develop, and connect with Bluemix, see the Bluemix page on developerWorks.


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Cloud computing, Java development, Web development
ArticleID=1010776
ArticleTitle=Bluemix fundamentals: Deploy a sample Java application to the cloud
publish-date=12072015