Goals

In this workshop you will learn about the following:

  • How to create an application in Bluemix
  • How to bind a service from the Bluemix Service Catalog to your application in Bluemix
  • How to setup a local Eclipse development environment with the IBM Liberty Profile beta
  • How to deploy new code to your application in Bluemix
  • How to view the logs of your application running in Bluemix
Prerequisites
Setting Up Your Liberty Server In Eclipse
  • Open the Servers view in Eclipse
  • Right click in the view and select New -> Server
  • In the New Server dialog expand IBM, select Websphere Application Server Liberty Profile and click Next
  • In the New Server dialog select the Install from an archive or repository option
  • Select Next
  • In the Liberty Profile Runtime Environment dialog select a destination to install the Liberty runtime, you can pick any folder you would like
  • Select the Download and install a new runtime environment from ibm.com option
  • Make sure the Liberty Repository is selected, and select Liberty v9 Beta with Java EE 7 Runtime. Click Next.
  • From the add-ons list, click the Install button next to the Liberty Profile Beta Extended Package. Click Next.
  • Select I accept the terms of all the license agreements. Click Next.
  • In the New Liberty Profile Server dialog, leave the defaults and click Next.
  • In the Add and Remove dialog select Finish
  • Once the download finishes you will see a dialog telling you it was successful, click OK.
Watch Demonstration
Creating A Java App In Bluemix
  1. Go to bluemix.net
  2. Login with the ID and password you used to register for Bluemix with
  3. In the header, select the "Catalog" link
  4. In the Catalog select the Liberty for Java runtime
  5. In the resulting dialog, give your application the name "java-todo"
  6. The hostname will match the application name by default, you will need to change it to be unique. For example, you can append your name to "java-todo", ie "ryan-java-todo".
  7. Make sure the Domain drop down is set to mybluemix.net
  8. Click "Create" to create your application
Watch Demonstration
Viewing The Default App
  • You will be brought to the Start Coding screen once the app is created. Click the "Overview" link in the left-hand navigator to go to the application dashboard.
  • While your application is now created in Bluemix, it is not yet deployed. Keep an eye on the status indicator in the upper right-hand corner, it will update as the application goes through the deployment process.
  • After about 30 seconds your application should be up and running. Select the route to launch the app in your browser.
  • The application you see is what Bluemix deploys by default when you create an application from the Java Liberty runtime, we will replace this application with our ToDo app.
Watch Demonstration
Getting The Code
  1. In Eclipse go to Window -> Open Perspective -> Other...
  2. In the dialog select Git and click OK
  3. In the Git Repositories view select Clone a Git repository
  4. In the Clone A Git Repository dialog enter https://github.com/IBM-Bluemix/bluemix-workshops.git in the URI field and select Next
  5. Make sure master is checked off in the branch selection dialog and click Next
  6. In the Local Destination dialog enter a directory to clone the Git repository to and click Finish
  7. Go back to the Java EE perspective in Eclipse
  8. Go to File -> Import -> Maven -> Existing Maven Projects
  9. In the resulting dialog navigate to bluemix-workshops/todo/java/starter and click OK.
  10. You should now see the CloudantToDos project listed inside the import dialog, click "Finish" to import the project into your workspace.
Watch Demonstration
Building The App
  1. In Eclipse, expand the CloudantToDos project
  2. Right click on the pom.xml file and select Run As -> Maven Build...
  3. In the Goals field in the Configuration dialog enter "package"
  4. In the configuration dialog, click "Run"
  5. The Console view in Eclipse should open and the build should complete successfully
  6. Right click on the CloudantToDos project in Eclipse and select "Refresh"
  7. You should now see a new file in the target folder in the project called CloudantToDos-0.0.1-SNAPSHOT.war
Watch Demonstration
Logging Into Bluemix From The Command Line

You should already have the Cloud Foundry Command Line Tools installed, if not go to the prerequisites slide and follow the link to the install instructions.

  1. Open a terminal window
  2. Issue the cf login command

    /Users/bluemix/todos

    • $ cf login -a api.ng.bluemix.net
  3. The cf login command will prompt you for your username and password. Enter the same username and password you use to login to Bluemix.
Deploy The ToDo App
  1. Open a terminal window and change your directory to the target directory of the ToDo app

    /Users/bluemix/todos

    • $ cd bluemix-workshops/todo/java/starter/CloudantToDos/target
  2. Deploy the application to Bluemix using the Cloud Foundry CLI by running the following command

    /Users/bluemix/todos

    • $ cf push java-todo -p CloudantToDos-0.0.1-SNAPSHOT.war

After about 30 seconds your app should be deployed to Bluemix. Refresh the browser to see the new UI or go back to Bluemix and select the URL to launch it again. You should now see the ToDo UI instead of the sample application.

Watch Demonstration
Not Working As Expected

While our ToDo application successfully deployed to Bluemix you will notice that it is not functioning properly yet. Open your browsers developer console and reload the page, you will notice there is an error. This is because the web application is making a request to a URL that does not exist yet.

Watch Demonstration
REST APIs

There are several REST APIs that need to be implemented in order to make our ToDo application work.

  • GET /api/todos - This API should return a JSON array of all ToDo objects
  • POST /api/todos - This API can be used to create a new ToDo. The POST body should contain the JSON representation of a ToDo. The API should return the same JSON ToDo object from the POST body but with a unique id to identify it.
  • PUT /api/todos/{id} - This API can be used to update an existing ToDo. The id in the path represents the id of the ToDo you would like to update. The PUT body should include a JSON representation of the ToDo with the updated values. The API should return the updated JSON ToDo.
  • DELETE /api/todos/{id} - This API can be used to delete a ToDo. The id in the path represents the id of the ToDo to delete. This API should not return anything.
ToDo JSON Representation

The JSON representation of a ToDo looks like this

Adding A Cloudant Service

We are going to want to persist our ToDos in a database so when a user comes back to the application or refreshes the page they will see the same ToDos. In our application we will choose to use Cloudant.

  1. From the application dashboard in Bluemix select the "Add A Service or API" button. This will bring you back to the Bluemix catalog.
  2. In the data management section of the catalog select the Cloudant NoSQL service.
  3. In the service dialog give the service the name "todo-cloudant" and click "Create".
  4. You will be asked to restage the application, click cancel for now.
  5. You should now see a tile for Cloudant in your application dashboard, click the arrow next to the words "Show Credentials". These are the credentials your application will use to access Cloudant.
Watch Demonstration
More About Service Credentials
  • The credentials for the Cloudant service is actually an important part of building applications on Bluemix
  • Every service you bind to an application in Bluemix will provide you with credentials
  • These credentials are made available to your application at runtime via an environment variable called VCAP_SERVICES
  • Applications running on Bluemix are expected to parse the JSON in the VCAP_SERVICES environment variable, extract the credentials for the services they need, and then use those credentials to make a connection to the service
  • This is such a common pattern that there have been libraries developed to make this process easier, we will use one of these libraries later on in the workshop
  • You can read more about VCAP_SERVICES here
Creating A Cloudant DB

We are going to need a DB in Cloudant to actually use in our application, so lets create one.

  1. From the application dashboard in Bluemix, select the Cloudant service you bound to your application.
  2. In the resulting page select the "Launch" button in the top left. This will bring you to the Cloudant dashboard.
  3. In the header select "Add New Database".
  4. Enter the name "todos" and click "Create".
Watch Demonstration
Creating A ToDo POJO
  • Since we are good Java developers we probably want to create a Java object to represent a ToDo. Besides being good practice, we can take advantage of Jackson to serialize and deserialize our POJO to and from JSON.
  • In Eclipse create a new class by right clicking on the src/main/java folder within the Java Resources in the CloudantToDos project
  • In the package field of the New Java Class dialog enter "net.bluemix.todos"
  • In the name field of the New Java Class dialog enter "ToDo"
  • Copy the following code into the resulting class file
Generating Getters and Setters
  • In order for Jackson to do serialization we need to provide getters and setters for our private variables.
  • We can use Eclipse to generate our getters and setters. Go to Source -> Generate Getters and Setters...
  • Click the Select All button in the resulting dialog, then click OK
  • Save the class file
Watch Demonstration
Persisting Data To Cloudant
  • Cloudant is based upon Apache CouchDB and therefore conforms to all the CouchDB REST APIs
  • This means we can use open source CouchDB client libraries to persist data to Cloudant
  • In this example we will use the Ektorp CouchDB client libraries for Java
Bluemix Cloud Connectors
  • One of the problems we face is that in Bluemix our Cloudant credentials are made available to our application at runtime via the VCAP_SERVICES environment variable, yet we may also want to run our application outside of Bluemix, for example locally during development
  • We could come up with some logic in our code to detect if the environment variable is set and do something different when it is not...or we could set it locally...but this gets messy
  • Ideally our code would be agnostic of where the application is deployed
  • The Bluemix Cloud Connectors project does exactly this
  • The Bluemix Cloud Connectors project offers a connector for Cloudant/CouchDB that allows you to write code that works the same whether running your app in Bluemix or outside of Bluemix
  • Within Bluemix the Cloud Connectors project will use the VCAP_SERVICES environment variable to find connection information for services your app uses
  • Outside of Bluemix the Cloud Connectors project uses an external properties file to connection information for services your app uses
Add The Bluemix Cloud Connectors Dependencies
  • Open the pom.xml file from the CloudantToDos project in Eclipse
  • Add the following dependencies to the dependencies section within the POM file and save the file
Interfacing With Cloudant
  • The CouchDbRepositorySupport class from the Ektorp library can be used to perform all CRUD operations on our Cloudant DB
  • Using a class like this will make our lives easier when implementing our REST APIs
  • Create a new class called ToDoRepository in the net.bluemix.todos package and add the following code
  • Save the class file
Creating Our REST Controller
  • At this point we are ready to implement our REST APIs
  • Create a class called ToDoRestController and add the following code to it
  • Save the class file
  • The @Path annotation tells JAX-RS that the endpoint for this class is at /todos (we have configured JAX-RS in the web.xml to tell it that all endpoints are prepended with the /api)
  • We inject the ToDoRespository created by our CloudantBean into our controller so we can interface with the database
Implementing GET /api/todos

Now we are ready to implement our GET request. Add the following method to ToDoRestController

The @GET annotation tells JAX-RS to call the getAll method of this class when a GET request is made to endpoint /api/todos. See how simple this code becomes when using our repository class and Jackson to serialize our POJO?

Implementing POST /api/todos

Add the following code to ToDoRestController to implement the POST method.

The @POST annotation tells JAX-RS to call the create method when a POST request is made to /api/todos. The td parameter in the method is the serialized JSON object from the POST body. We then just use our repository to save that object to our Cloudant DB.

Implementing PUT /api/todos/{id}

Add the following code to ToDoRestController to implement the PUT method.

We first get the ToDo from the DB that is specified in the id path parameter, then we update it with the data from the ToDo JSON from the PUT body. Finally we insert the ToDo back into the DB and return the JSON back to the client.

Implementing DELETE /api/todos/{id}

Add the following code to ToDoRestController to implement the DELETE method.

We first get the ToDo from the DB with the ID that is specified in the path parameter. Then we use the repository to delete the ToDo from the DB.

Creating A Cloudant Connector Bean
  • Lets create a bean that will connect to our database and we can use in our repository
  • This bean will have the added benefit in that is can be injected into other classes and will be created by the runtime for us
  • Create a class called CloudantBean in the package net.bluemix.todos with the following code
Pointing Our App At The DB

The last thing we need to do is let our app know where the DB is located

  • When the app runs in Bluemix the Bluemix Cloud Connectors libraries will automatically check for the VCAP_SERVICES environment variable
  • When the app runs locally and the VCAP_SERVICES environment variable is not set the Bluemix Cloud Connectors project looks for a file called spring-cloud-bootstrap.properties on the classpath
Creating spring-cloud-bootstrap.properties
  • Right click on the src/main/resources folder of the CloudantToDos project and select New -> Other
  • In the New dialog expand General and select File and click Next
  • In the New File dialog give the file the name spring-cloud-bootstrap.properties
  • Click Finish
  • Within the file add the following property
Creating spring-cloud.properties
  • Create a new file called spring-cloud.properties in a folder called cloudant-todos in your user's home directory
  • Add the following properties to the file
  • Replace cloudantuser with the username from the VCAP_SERVICES environment variable for Cloudant in Bluemix
  • Replace cloudantpw with the password from the VCAP_SERVICES environment variable for Cloudant in Bluemix
  • Replace cloudanthostanme with the hostname from the VCAP_SERVICES environment variable for Cloudant in Bluemix
Watch Demonstration
Testing It Out
  • We have implementations for all APIs at this point so lets try out the application
  • In the Servers view in Eclipse right click on the Websphere Application Server and select Add and Remove...
  • In the Add and Remove dialog select the CloudantToDos app from the Available column and click Add >
  • Click Finish
  • Right click on the Websphere Application Server again and select Publish
  • Right click on the Websphere Application Server again and select Start
  • Head to http://localhost:9080/CloudantToDos/ and you should be able to add update and delete ToDos without any errors.
  • You should be able to verify ToDos are being placed in the DB by going back to your Cloudant dashboard in Bluemix, selecting the todo DB and opening some of the documents in there.
Watch Demonstration
Simple and Consistent Deployments

We can use a manifest file to specify parameters for our deployment to Bluemix. Manifests make our cf push command simple and consistent by taking all the parameters we would normally specify on the command line and putting them in a file.

  1. In Eclipse right click on the CloudantToDos project and select New -> File and click Finish
  2. In the New File dialog give the file the name "manifest.yml"
  3. Copy the below code into the editor and save the file

If you would like an easy way of generating these files check out the CF Manifest Generator.

What Is This Environment Variable In The Manifest?

The Liberty buildpack, which is used by default when running a Java application in Bluemix, contains a feature called auto-configuration. For certain service in Bluemix, like Cloudant, the auto-configuration feature will detect the Cloudant service is bound to the application and try and provide our application with jars it thinks we will need to leverage the service. In our case we don't need these jars because they are included with our application. You can opt out of auto-configuration by using an environment variable. For more information see the documentation.

Deploying Working ToDo App
  • Lets build our application war and deploy it to Bluemix
  • Right click on the CloudantToDos project in Eclipse and select Run As -> Maven Build
  • We are ready to do our deployment, but wouldn't it be nice to see the logs of our application while we deploy the application?
  • Open a new terminal window. You should now have 2 terminals open.
  • In one run the following command

    /Users/bluemix/todos

    • $ cf logs java-todo
  • The cf logs command tails the log files of your application so you can see them right in your command prompt window. This tool is very useful for debugging problems that might be occurring during deployment or during runtime.
  • In the other terminal window run the following command from bluemix-workshops/todo/java/starter/CloudantToDos

    /Users/bluemix/todos

    • $ cf push

Notice we don't need to specify any parameters to cf push. That is because it will automatically look for, and use the manifest.yml file if it finds one. In about 30 seconds your deployment should finish and your application should be deployed. Head to your application URL and try it out.

Watch Demonstration

/