Day 28: OpenShift Eclipse Integration for Java Developers

Today for my 30 days challenge I’m learning about OpenShift Eclipse integration. The application runs on OpenShift and uses the OpenShift Eclipse plugin to fully develop and deploy the application. We will be using Eclipse Kepler for most of the series, please download Eclipse Kepler before moving ahead. Lets gets started!


  1. Basic Java knowledge is required.

  2. Install the latest Java Development Kit (JDK) on the operating system. We can either install OpenJDK 7 or Oracle JDK 7. OpenShift supports both OpenJDK 6 and 7. In this blog post, we will be using JDK 7.

  3. Download the latest Eclipse package for your operating system from the official Eclipse website. At the time of writing this blog, the latest Eclipse package is Kepler.

Download Eclipse

It is very easy to install eclipse, just extract the downloaded package, and we are done. On linux or mac machines, open a new command line terminal and type the command mentioned below.

$ tar -xzvf eclipse-jee-kepler-R-*.tar.gz 

On windows, you can extract the zip file using winzip or 7-zip or any other software.
After we have extracted the Eclipse, there will be a folder named eclipse in the directory where we extracted Eclipse. We can optionally create a shortcut of the executable file.

Step 1 : Install OpenShift Eclipse Plugin

After downloading and extracting the Eclipse Kepler IDE for Java EE, open Eclipse and navigate to the project workspace. Go to Help > Eclipse Marketplace and we will see a screen as shown below.

Navigate to Eclipse Marketplace

In the search box, type “jboss tools” and then press the Go button.

Eclipse Marketplace Search

After pressing the Go button, we will see “JBoss Tools(Kepler)” as the first result.

Eclipse Marketplace Search Results

Now press the install button, we will get a list of plugins which we can install. As the purpose of this blog is to demonstrate OpenShift, we will only choose “JBoss OpenShift Tools” from the list. After selecting “JBoss OpenShift Tools”, press the “Confirm” button.

Choose OpenShift JBoss Tools Integration

Now accept the license, by clicking “I accept the terms of the license agreement” radio button, and then press the Finish button.

Accept License Agreement

Eclipse will show a security warning as the plugin is unsigned. Press the OK button, and finally, we will have to restart Eclipse for the changes to take effect. Press the Yes button to restart Eclipse.

Restart Eclipse

Step 2 : Create an OpenShift application

Now that we’ve installed the OpenShift Eclipse plugin, we have everything required to start building the application. Create a new OpenShift application by going to File > New > Other > OpenShift Application.

Create New OpenShift Application

After pressing the ‘Next’ button, we will have to provide the OpenShift account credentials. If you do not have an OpenShift account, you can click the sign up here link on the wizard to create a new OpenShift account.

Sign in to OpenShift

When we click the sign up here link, the Eclipse internal browser will open the OpenShift sign up page. We can change the default browser by going to Windows > Preferences on Windows or Eclipse > Preferences.

Change Default Browser

We can change the default browser to Chrome or FireFox by first choosing “Use external browser”, and then clicking the New button. Enter the details of your favorite modern web browser.

Add External Browser

Next we will choose the newly added Google Chrome browser as the default web browser. Finally, click the Apply button and then press the Ok button.

Choose Google Chrome as Default Web Browser

Now again go to File > New > Other > OpenShift Application. This time if we click the sign up here link, then the url will open in the chrome browser.

After the sign up, we will get a verification email that we have to verify. This is required before we can work with OpenShift.

Once we have successfully verified the account, we can create a new OpenShift connection by entering the account username and password. Check the ‘Save password’ checkbox so that we do not have to enter the password with every command. Press the Next button after entering the details.

Create New OpenShift Connection

When we press the Next button, we can enter additional information for password recovery. I choose “No”, but we can choose Yes, as well.

OpenShift Secure Storage

After we press the “No” button, we will have to create a new OpenShift domain. We will only have to create a new domain if we do not already have an OpenShift domain associated with the account. The domain name is the unique namespace, and all the user applications will exist under this namespace. No two users can have the same domain name. The domain name can be any alpha-numeric name less than 32 characters. It forms part of application url. For example, if the application name is sharemylocation and domain name is onppenshiftcloud, then my full application name will be

Enter Domain Name

Next, it will render a view where we have to upload the ssh keys to OpenShift. OpenShift requires SSH:

  1. To perform Git operations.
  2. To remotely access the application gear.

We can either upload the existing SSH keys or create a new SSH key by clicking the New button. We will create a new key so click on the New button.

Add New SSH Keys

We need to provide a name of the key and a name of the private and public key file name. I have used my name as the key name and file name.

OpenShift SSH Key Details

Next we will be directed to the application creation wizard where we have to enter the application details. The details include the name of the application, the type of application, gear profile(whether we want small instance or medium instance. For FreeShift users, we can only use small instances), scalable application or non scalable application, and whether we want to embed any or multiple cartridges like MySQL, PostgreSQL, MongoDB, and others. We will embed a MongoDB cartridge in the application.

OpenShift Application Details

Next we have to setup a sharemylocation application and configure the server adapter settings. Choose the default and click next.

Setup OpenShift Application

The next screen will ask us to specify the location where we want to clone the git repository and name of the git remote.

Import Application Settings

Finally, press the finish button and the application creation process will start. This will create an application container for us, called a gear, and setup all of the required SELinux policies and cgroup configuration. OpenShift will install the MongoDB cartridge on the application gear, and the JBoss tools OpenShift plugin will show an information box with MongoDB details.

MongoDB Cartridge Details

OpenShift will also setup a private git repository for us and clone the repository to the local machine file system. Next, OpenShift will propagate the DNS to the outside world. Finally, the project is imported as a Maven project in the Eclipse workspace.

After importing the application to Eclipse, we will be asked if we want to publish uncommitted changes.

Publish sharemylocation Application

You might start wondering that you have not made any change to the application, yet it is asking you to publish changes. The reason is that when the project is imported into Eclipse, JBoss tools create a new file under the .settings folder called .jsdtscope. As the file is not ignored, OpenShift Eclipse plugin asks us for a deployment. We can easily ignore this file by navigating to Git Staging View. Go to Window > Show View > Other > Git > Git Staging.

Git Staging View

Right click on the .jsdtscope file under Git Staging view, and then choose ignore.

Ignore File

We can view the application running online by navigating to the OpenShift explorer view. To open the OpenShift Explorer view, go to Window > Show View > Other > JBoss Tools > OpenShift Explorer. This will open up a new view.

Open OpenShift Explorer View

Now right click on the application, and then click the “Web browser”. This will open up the template application in the default browser.

Open Web Browser

Step 3 : Understanding Development Workflow

Before we move forward, we have to understand how the development workflow will work.

  1. We write code for a functionality, and then we commit the code to a Git local repository using the Git Staging view. The Git Staging view gives a graphical view to the changes, and we can easily compare and look at all the files we have changed.

  2. In the Git Staging View, we have two options. Either we can commit the changes to the local repository, or we can do a commit and push together. When we do git commit and push together, the code is pushed to a git remote called origin. The origin remote points to a private git repository created by OpenShift. When the code is pushed to the remote repository, OpenShift will kick off the build. The problem with Git Staging View “Commit and Push” is that we will not be able to monitor the application build logs. To view the application build logs, we will use the Server view publication mechanism. We will use a server configured for the sharemylocation OpenShift application. We will publish the changes by right clicking on the application server and clicking Publish. This internally does a git push. The advantage of this approach is that it will open up a new console view where we can monitor the application build progress.

Step 4 : Making our first change

Let’s make a small change to the application to better understand the development workflow I discussed in the last step. Open the index.html, and then make the following changes.

    Welcome to OpenShift, JBossEAP6.0 Cartridge


    OpenShift MongoDB Backbone.js Tutorial

Go to the “Git Staging view”, and we will see the change.

Git Staging View-First Change

Next drag the change to the “Staged Changes”, and then write the commit message.

Git Staging View-Drag to Staged Changes

Now commit the change by clicking the “Commit” button. As I mentioned before, do not use “Commit and Push” as that will trigger application deployment and will not show the build log. The build log is very useful as it can help us when build fails.

Go to the Server view, and we will see a server configured for the sharemylocation application.

sharemylocation Server View

Right click on the application server, and then click “Publish”.

Publish Application

We will get a dialog where we have to confirm whether we want to publish changes or not.

Publish Confirmation

Press “Yes”, and it will open a new console view where we can track the build progress.

Application Build Progress

To view the log files of the JBoss EAP application server, right click on the sharemylocation server in Server view, and then click Tail files.

OpenShift Tail Files

Next we will configure to tail only server.log files. By default, it will tail all the log files which includes database log files as well.

Configure Tail Server Log Files

It will open up another console view where it will tail only the JBoss EAP server.log file.

Tail JBoss EAP Server Log Files

Finally, we can view the change in the browser by right clicking sharemylocation server, and then Show In > Web Browser.

Show OpenShift Server View in Web Browser

This will open up the default web browser where we can view the change that we made in index.html.

View Application Change in Browser

Step 5 : Enable Hot Deployment

The default behavior is that whenever we publish the application or do a git push, OpenShift will first stop all the cartridges (MongoDB and the JBoss EAP server), then do a maven build, and then after the build success it will start the cartridges and deploy the war. This takes a lot of time and is not ideal for rapid development. We can speed up this process by enabling hot deployment. Hot deployment does not stop the cartridges and only replaces the war file.

To enable Hot deployment, right click on the project, and then navigate to OpenShift > Configure Markers.

Configure Markers

Then we will see a view where we can configure which OpenShift markers we want to enable for the application. As we can see, by default, the java7 marker is enabled. This will make sure Java 7 is used for the application. If we disable this marker, then Java 6 will be used.

Configure OpenShift Markers

We will choose the Hot Deploy marker. This will create a new empty file called hot_deploy in the .openshift/markers folder.

Enable Hot Deployment Marker

Next we can go to the Git Staging view, and we will see the hot_deploy file in “Unstaged Changes”.

Commit Hot Deploy in Git Staging View

Drag the hot_deploy file to “Staged Changes”, and then write a commit message. Press the “Commit” button after entering the commit message.

 Enable Hot Deployment

Go to the “Server view” and publish the change. Now the build log will clearly show that cartridges are not stopped as hot deploy is enabled.

Not stopping cartridge jbosseap because hot deploy is enabled
Not stopping cartridge mongodb because hot deploy is enabled
Building jbosseap cartridge
Scaling down Maven heap settings due to presence of hot_deploy marker
Found pom.xml... attempting to build with 'mvn -e clean package -Popenshift -DskipTests'
Apache Maven 3.0.3 (r1075437; 2011-06-20 13:22:37-0400)
Maven home: /etc/alternatives/maven-3.0
Java version: 1.7.0_45, vendor: Oracle Corporation
Java home: /usr/lib/jvm/java-1.7.0-openjdk-
Default locale: en_US, platform encoding: ANSI_X3.4-1968
OS name: "linux", version: "2.6.32-358.23.2.el6.x86_64", arch: "i386", family: "unix"
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building sharemylocation 1.0
[INFO] ------------------------------------------------------------------------
[INFO] Using 'UTF-8' encoding to copy filtered resources.
[INFO] skip non existing resourceDirectory /var/lib/openshift/526f931ce0b8cd94f300003f/app-root/runtime/repo/src/test/resources
[INFO] --- maven-compiler-plugin:2.3.2:testCompile (default-testCompile) @ sharemylocation ---
[INFO] Packaging webapp
[INFO] Assembling webapp [sharemylocation] in [/var/lib/openshift/526f931ce0b8cd94f300003f/app-root/runtime/repo/target/sharemylocation]
[INFO] Processing war project
[INFO] Building war: /var/lib/openshift/526f931ce0b8cd94f300003f/app-root/runtime/repo/deployments/ROOT.war
[INFO] WEB-INF/web.xml already added, skipping
[INFO] ------------------------------------------------------------------------
Starting application sharemylocation
Not starting cartridge mongodb because hot deploy is enabled
Deploying jbosseap cartridge
Not starting cartridge jbosseap because hot deploy is enabled

Similarly, the server log file will show that it just replaced the WAR file. It took less than one second to do it.

2013/10/30 03:31:57,174 INFO  [] (MSC service thread 1-2) JBAS015877: Stopped deployment ROOT.war (runtime-name: ROOT.war) in 260ms
2013/10/30 03:31:57,200 INFO  [] (MSC service thread 1-1) JBAS015876: Starting deployment of "ROOT.war" (runtime-name: "ROOT.war")
2013/10/30 03:31:57,316 INFO  [org.jboss.web] (ServerService Thread Pool -- 67) JBAS018210: Register web context: 
2013/10/30 03:31:57,630 INFO  [] (DeploymentScanner-threads - 2) JBAS018565: Replaced deployment "ROOT.war" with deployment "ROOT.war"

This is awesome. It makes it very quick to get feedback on the application code changes. This saves a lot of time and makes us more productive.

Step 6 : Update to Java 7

Although OpenShift is using Java 7 to build the project, the Maven project is still using Java 6. To update to Java 7 update the following properties in the pom.xml file.


After making this change, right click on the project, and go to Maven > Update Project.

Update Maven Project

This will update the project to Java 7.

Step 7 : Delete Template Files

From Java EE 6 onwards, the web.xml file is optional. We can use annotations to configure most of the components. We will delete all the template files except index.html created by OpenShift. Delete the web.xml, health.jsp, snoop.jsp, and image folder. The git staging view will show the changes, and we can commit the changes.

Delete Template Files

Step 8 : Update Maven War plugin

If we publish these changes, the build will fail as the maven war plugin configured in pom.xml expect web.xml in web project. The latest version of Maven war plugin adds a configuration property. The failOnMissingWebXml property informs the war plugin that build should not fail if web.xml is not present.


Now commit the changes using the Git Staging view, and then publish them using the sharemylocation server as covered in previous steps.

Update Maven War Plugin

Step 9 : Write PingResource

We will finish this blog by writing a simple RESTful resource which will return "{'ping': 'pong'}" as a response when a request is made to /api/v1/ping. I like to write a ping service to make sure everything is configured properly.

We will use JAX-RS to write RESTful web services. JAX-RS defines annotation-driven API for writing RESTful services.

Before writing PingResource, we have to activate JAX-RS in the application. To enable JAX-RS, create a class which extends the Application and specify the application path using annotation as shown below.

public class RestInitializer extends Application {

Finally, we will write the PingResource which will respond to ‘/api/v1/ping’ request.

public class PingResource {
    @Produces(value = "application/json")
    public String ping() {
        return "{'ping': 'pong'}";

Now commit the changes using Git Staging view, and then publish them using sharemylocation server as covered in previous steps.

Ping Resource Demo

That is it for today. Keep giving feedback.

Next Steps

Java, OpenShift Online
Comments are closed.