You can build ,deploy, and manage your OpenShift Java applications right from within the Eclipse IDE using the JBoss Tools OpenShift plugin. This blog will guide you through installation, setup, application creation, and managing your application from within Eclipse. During this post, we will develop a Java EE 6 PostgreSQL 9.2 application and deploy it on the JBoss EAP 6(JBoss Enterprise Application Platform 6) application server running on OpenShift.
OpenShift has best in class Java support with Tomcat 6 , Tomcat 7 , JBoss AS7, and JBoss EAP 6 servers bundled with it. You can also run Jetty or GlassFish servers on it using DIY cartridges. OpenShift also provides support for Jenkins continuous integration server as well.
In this blog, we will use four Java EE 6 specifications -- JPA , Bean Validation , CDI , and JAX-RS to build a todo application.
Prerequisite
Basic Java knowledge is required.
Install the latest Java Development Kit (JDK) on your operating system. You can either install OpenJDK 7 or Oracle JDK 7. OpenShift supports OpenJDK 6 and 7.
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 called Kepler.
It is very easy to install eclipse , just extract the downloaded package and you are done. On linux or mac machines , open a new command line terminal and type command shown 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 you have extracted the Eclipse, there will be a folder named *eclipse in the directory where you extracted Eclipse. You can optionally create a shortcut of the executable file.
Sign up for an OpenShift Account. It is free and instant. Red Hat gives every user three free Gears on which to run your applications. At the time of this writing, the combined resources allocated for each user is 1.5 GB of memory and 3 GB of disk space.
Step 1 : Install JBoss Developer Tools Eclipse Plugin
Once you have downloaded and extracted the Eclipse Kepler IDE for Java EE, open Eclipse and navigate to your project workspace. Go to Help > Eclipse Marketplace and you will see a screen as shown below.
In the search box, type "jboss tools" and press the Go button.
After pressing the Go button, you will see "JBoss Tools(Kepler)" as the first result as shown below.
Now press the install button, and you will get a list of plugins which you can install. As the purpose of this blog is to demonstrate OpenShift, we will only choose "JBoss OpenShift Tools" as shown below. After selecting "JBoss OpenShift Tools" press the "Confirm" button.
Next you will be asked to accept the license. Click "I accept the terms of the license agreement" radio button and press the Finish button as shown below.
Eclipse will next show security warning as plugin is unsigned. Press OK button and you will be asked to restart the Eclipse so that changes can be applied. Press Yes to restart Eclipse.
Step 2 : Create SSH Keys
OpenShift requires SSH for :
Performing Git operations.
Remote access your application gear.
So we need to create a RSA key to deploy the work with OpenShift. Eclipse makes it very easy to create RSA keys. To create keys, follow the steps mentioned below.
Access the menu: Window> Preferences.
With the preferences window still open, go to: General> Network Connection> SSH2
Click on Tab Key Management and then the button Generate RSA Key ...
Copy the code key
Finally click the Save Private Key and Ok as image below
Step 3: Upload the Generated SSH key to OpenShift
After creating the ssh keys in the previous step, we need to upload the public key to OpenShift. Go to https://openshift.redhat.com/app/console/keys/new and add a new ssh key as shown below. You can find the public key in .ssh folder under your user home directory. The file will have a name id_rsa.pub. You can add multiple keys like one for your office and one for your home.
Step 4 : Create OpenShift Application
After we have uploaded the SSH keys to OpenShift account , we are ready to create OpenShift applications using JBoss Tools OpenShift support. Go to your eclipse and click File > New > Other > OpenShift Application as shown below and click next as shown below.
After pressing the 'Next' button, you will be asked to provide your OpenShift account credentials. If you have not signed up for OpenShift account, you can click the sign up here link on the wizard to create your OpenShift account. Enter your OpenShift account username and password. Check the 'Save password' checkbox so that you don't have to enter password with every command and click 'Next'.
Next you will be asked to create an OpenShift domain name. Every account needs to have one domain name which should be unique among all OpenShift users. One account can have only one domain name. Domain name forms part of the url that OpenShift assigns to an application. For example, if your application name is awesomeapp and namespace is onopenshiftcloud, then the url of application will be http://awesomeapp-onopenshiftcloud.rhcloud.com. Enter your unique domain name and press finish.
After domain is created, you will be directed to the application creation wizard. You will be asked to enter the details required to create an application like name of the application, type of application, gear profile(whether you want small instance or medium instance.For FreeShift users,you can only create small instances), scaled application or non scaled application, and whether you want to embed any or multiple cartridges like mysql, postgresql, mongodb etc. We will create an application named todoapp which uses jbosseap-6 and postgresql-9.2 cartridges.
Next you will be asked to set up todoapp and configure server adapter settings. Choose the default and click next as shown below.
The next screen will ask you to specify the location where you want to clone the git repository and name of the git remote. This is shown below.
Finally, press the finish button and you are done. 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 PostgreSQL 9.2 cartridge on the application gear and JBoss tools OpenShift plugin will show an information box with details as shown below.
OpenShift will also setup a private git repository for you and clone the repository to your local system. Next, OpenShift will propagate the DNS to the outside world. Finally, the project will be imported in your eclipse workspace as shown below.
You can view the application running online by going to the following url: http://todoapp-{domain-name}.rhcloud.com. Please replace {domain-name} with your OpenShift account domain name.
Step 5 : Look at Generated Code
Now we will take a look at the template project created by OpenShift. Below is the listing of all the content in todoapp project created by OpenShift.
Lets take a look them :
1 .git is your local git repository which contains all the information required by git. Git does not create .git folder in ever sub-directory like svn.You can refer to this article for more information about what's in the .git directory.
2 .gitignore is a file used to specify which all files or file types you want to ignore so that they are not committed to the git repository. This can include files like .classpath, .project, etc.
3 .openshift is an OpenShift specific folder which exists in every OpenShift application. This folder has four sub-directories -- action_hooks,config, cron, and markers as shown below.
The action_hooks folder hosts scripts which developer can use to hook into application life cycle and do things like create a database before starting the application, expose an environment variable, or install a Maven dependency etc. The config folder contains a JBoss configuration file called standalone.xml and modules folder to put your own jars and property files in the classpath. The cron folder contains files which can be used to run cron jobs on application gear. The cron functionality is only enabled when you embed Cron cartridge in to the application. The markers folder is used to define marker files. Currently you can have the following files in the markers folder. Adding marker files with the following names to this directory will have the following effects:
enable_jpda - Will enable the JPDA socket based transport on the java virtual machine running the JBoss AS 7 application server. This enables you to remotely debug code running inside the JBoss AS 7 application server.
skip_maven_build - Maven build step will be skipped
force_clean_build - Will start the build process by removing all non
essential Maven dependencies. Any current dependencies specified in
your pom.xml file will then be re-downloaded.
hot_deploy - Will prevent a JBoss container restart during build/deployment.
Newly build archives will be re-deployed automatically by the JBoss HDScanner component.
java7 - Will run JBoss EAP with Java7 if present. If no marker is present then the baseline Java version will be used (currently Java6)
4 README.md file contains information about the project layout. You can over-write this file with useful information about your project.
5 deployments folder is for binary deployment i.e. war or ear file instead of source deployment. So, if you want to deploy war rather than pushing source code, then add war or ear file in this folder, add it to git repository, commit it, and then finally push the war file.
6 pom.xml is a standard Maven project object model file. The pom.xml contained in template project include Java EE 6 dependencies. This makes writing Java EE 6 applications very easy. The most important thing specified in pom.xml is a Maven profile named "openshift". This is the profile which is invoked when you do deploy the code to OpenShift.
7 src folder is where you will write your application source code. It follows the same convention as followed by every maven project.
Step 6: Make your First Change
Let's make our first change to the application in order to understand development workflow with with OpenShift. Open index.html and change heading as shown below.
Go to servers view , then right click on todoapp OpenShift server, and click Publish as shown below.
When we clicked Publish, it performed a couple different tasks. First, it committed the changes to local git repository and then pushed the changes to todoapp application gear. After changes have been pushed, OpenShift invokes the maven build by executing "mvn -e clean package -Popenshift -DskipTests" command. This builds a war file with name ROOT and deploy the WAR in JBoss EAP 6. You can view the change by opening browser and visiting http://todoapp-{domain-name}.rhcloud.com. Please replace {domain-name} with your OpenShift account domain name.
The disadvantage of using Publish is that you will not be able to give your commit messages. It will use "Commit from JBoss Tools" as commit message. It is a quick way to test your changes.
Step 7 : View Logs
Logs are very useful for debugging errors in case something goes wrong on the server. OpenShift Eclipse tooling makes it very easy to tail the log files. In the server view, right click on the todoapp server , and then go to OpenShift Tail files.
You can view the logs in console view.
Step 8 : Define Todo Model class
We will start developing our application by creating domain model for our Todo application. JPA specification defines an API for the management of persistence and object/relational mapping using a Java domain model. It defines a mapping between database table and Entity class. Entity is a POJO with public no-arg constructor which is used to define mapping with relation database table.
The application will have a single entity called Todo. Create a new package( File > New > Other > Package) com.todoapp.domain under src/main/java source folder. Next, create a new class( File > New > Other > Class) called Todo in com.todoapp.domain package. Each entity class is annotated with @Entity annotation and has instance variables which represent persistent state of the entity. Each instance variable corresponds to a column in a table.
The entity shown below is a JPA entity with JPA and bean validation annotations. Bean Validation JSR 303 provides a class-level constraint declaration and validation facility for Java applications.
The code shown above:
The entity class shown above has a public no-arg constructor.
The Todo class in annotated with @Entity annotation and has four instance variables. The identity field is defined by the id field and is annotated with @Id.
The @NotNull and @Size are bean validation annotation. They make sure that values are not null and size of todo field is between 10 and 40 characters.
The @ElementCollection annotation signifies that tags field are listed in a different table. This annotation defines a collection of instances of a basic type or embeddable class.
Step 9 : Create persistence.xml file
In JPA, entities are managed within a persistent context. Within persistence context, entities are managed by entity manager. In Java EE , entity manager is managed by Java EE container. The configuration of entity manager is defined in an xml file called persitence.xml.
So we have to create persistence.xml file. The persistence.xml file is a standard configuration file in JPA. It needs to be included in the META-INF directory inside the JAR file that contains the entity beans. The persistence.xml file must define a persistence-unit with a unique name. Create a META-INF folder under src/main/resources and then create a persistence.xml file as shown below.
In the xml shown above :
The name of persistence unit is todos.
The transaction type attribute is JTA. This means JTA datasource will be used. The JTA datasource will be defined using jta-data-source element.
The provider element specifies the name of persistence provider. We will be using hibernate as persistence provider.
The class element specifies the entity class to be managed. To specify multiple entity classes you can use multiple class elements.
The properties element is used to specify standard JPA and vendor specific properties.
Step 10 : Create TodoService
Next we will create a TodoService class in com.todoapp.service package which will perform CRUD operation using EntityManager as shown below.
In the code shown above :
The TodoService class is a Stateless session bean as it defines @Stateless annotation. Stateless session bean does not contain any conversational state.
The container managed EntityManager is injected into the service class using @PersistenceContext annotation.
A new entity is persisted in the database using EntityManager persist method. The entity is persisted into database at transaction commit.
The EntityManager find method is used to find the entity by id.
Step 11 : Enable CDI
CDI or Context and Dependency injection is a Java EE 6 specification which enables dependency injection in a Java EE 6 project. CDI defines type-safe dependency injection mechanism in Java EE. Almost any POJO can be injected as a CDI bean.
To enable CDI in your project, create a beans.xml file in src/main/webapp/WEB-INF folder.
Step 12 : Expose RESTful web service
JAX-RS defines annotation-driven API for writing RESTful services.
Before exposing RESTful web service for Todo entity we have to active JAX-RS in our application. To enable JAX-RS, create a class which extends javax.ws.rs.core.Application and specify the application path using javax.ws.rs.ApplicationPath annotation as shown below.
Next we will create TodoRestService class which will expose two methods to create and read a Todo object. The service will consume and produce JSON.
In the code shown above :
We annotated TodoRestService with @Path annotation. TodoRestService is a POJO class and is published at todos path by adding @Path annotation.
Next we injected TodoService using @Inject annotation. This is enabled by CDI.
The create method is annotated with @POST annotation. This method will be invoked when HTTP post request is made at */todos * url. The @Consumes annotation means that this method will consume data in json format. Container will automatically unmarshall json into Todo object.
The lookupTodoById method is annotated with @GET annotation. This method will be invoked when a HTTP GET is made to todos/id where id can be any number. The method find todo item using TodoService find method and returns todo entity back. The @Produces annotation makes sure that container will marshal the java object into JSON.
Step 13 : Commit and Push changes to OpenShift
Now we need to commit the changes to local git repository and publish changes to application gear. To do that, go to Window > Show View > Other > Git > Git Staging as show below.
You will see a new view called "Git Staging" in the bottom.
Select the todoapp project and you will see unstaged changes for todoapp project.
Select all unstaged changes and drag them to staged changes.
Add a commit message and press "Commit and Push" button.
Finally we can test our REST web service using curl.To create a todo execute the curl command as shown below.
To read the Todo entity execute the curl command as shown below
Conclusion
In this blog we covered how you can use Eclipse IDE and OpenShift JBoss tooling support to build Java EE applications. OpenShift Eclipse plugin makes it very easy to work with OpenShift. So, if you are a Java (EE) developer looking for a deployment platform then give OpenShift a try.
What's Next?
Sign up for OpenShift Online
Get your own private Platform As a Service (PaaS)
by evaluating OpenShift Enterprise
Need Help? Ask the OpenShift Community your questions in the forums
Showcase your awesome app in the OpenShift Developer Spotlight.
Get in the OpenShift Application Gallery today.