OpenShift QuickStarts & Cartridges make the Getting Started experience for Spring developers really simple. After forking the existing OpenShift Spring QuickStart to use as a starting point, we'll show you how to replace the sample application source with your own Spring application - allowing you to quickly produce your own reusable QuickStart application which can be cloned, hosted, and shared with your community, all in a few simple steps.
Spring is a popular programming and configuration model for Java-based applications that focuses on the "plumbing" so that developers can focus on application-level business logic, without unnecessary ties to specific deployment environments. This makes Spring applications very portable and, when combined with Maven's project object model (POM) concept, which enables you to manage a project's build, reporting and documentation from a central piece of information, - it's makes deploying Spring almost effortless on OpenShift.
But, when if comes to deploying a highly transactional enterprise Java application in the Cloud, you'll most likely need to include a Java EE6 application server such as JBoss Enterprise Application Platform 6 or JBoss AS 7.1 (both available on OpenShift), enabling support for popular development frameworks such as Seam, CDI, Weld, and Spring.
Building an application stack for a Spring application in the cloud may sound a bit daunting at first. But with OpenShift, there's a zero-effort way to do it - while ensuring that your application can scale automatically.
It all starts with two basic concepts - Cartridges & QuickStarts.
Quickstarts provide a simple way to assemble a new technology stack with code and libraries preconfigured and allow you to easily launch a new application on OpenShift by combining code and one or more cartridges. QuickStarts can be created by anyone and shared with the community. Note: QuickStarts are not maintained by the OpenShift team, so you're responsible for updating the core libraries for security updates.
Cartridges are the components of an OpenShift application and can include databases, build systems, and management capabilities. Adding a cartridge to an application provides the desired capability without requiring you to administer or update the included feature. There are two types of cartridges available with OpenShift: standalone and embedded. Standalone cartridges allow you to choose from a variety of programming languages and frameworks for developing your application. Every application requires a framework cartridge such as Spring, PHP, JBoss, and Ruby. Embedded cartridges provide extended functionality to OpenShift applications such as MySQL, MongoDB, and phpMyAdmin.
The existing Spring QuickStart uses the JBoss Enterprise Application Platform 6.1.0 cartridge. And while the example uses an H2 database configured and deployed by the application, you can easily change it to MySQL or PostgreSQL (each of which are available on OpenShift in a single step, as a pluggable cartridge).
Clone and modify the sample Spring QuickStart
First, you'll need to create an OpenShift Online account and follow the Getting Started guide, and install the rhc command-line tool.
That should allow you to create a JBoss Enterprise Application Platform 6 app using our existing Spring Quickstart application template:
The QuickStart application can also be initialized via a web-based workflow: https://openshift.redhat.com/app/console/application_type/quickstart!12725
After the build completes, you should be able to view your copy of our default spring application at:
Easy, Right? In the next section, we'll learn a bit about this project's application structure, and find out how to import an existing Spring application into our Spring Quickstart example project.
Anatomy of a Maven Application
It's good to know what's going on under the hood before you start editing your own forked version of this code - so let's step through the structure of the existing Spring QuickStart. The example application includes a sample Maven 3 project to help you get your foot in the door with Spring on JBoss Enterprise Application Platform 6 or JBoss AS 7.1 (deployable on OpenShift).
The sample project setup allows you to create a compliant Spring 3.1 application using Spring MVC, JPA 2.0 and Bean Validation 1.0. It includes a persistence unit and some sample persistence and transaction code to introduce you to database access in Enterprise Java.
Here's an overview of the existing Spring project structure:
src/main/java: This is the place for your Java source files. All the application business logic resides in this source folder.
The src/main/java source folder has three packages :
org.jboss.tools.example.springmvc.domain : This package houses all the Java code related to our domain model. We are using JPA 2 to define our domain model. 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 Member.java class is our domain entity. It 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 @NotNull , @NotEmpty , @Size are all bean validation annotations.
org.jboss.tools.example.springmvc.repo : This package houses code required to access the database. Again we are using JPA 2 API. The Spring managed EntityManager is injected into the dao class using @Autowired annotation.
org.jboss.tools.example.springmvc.mvc : This package has two classes -- MemberController and MemberRestController. Both of the classes are standard Spring controller. The difference is that MemberRestController exposes the REST API to list and find the members and renders json whereas MemberController renders jsp views.
src/main/resources: Configuration files.
The Spring Quickstart uses JPA which is configured under META-INF/persistence.xml. In JPA, entities are managed within a persistent context. Within persistence context, entities are managed by entity manager. In Spring applications , entity manager is managed by Spring container. The configuration of entity manager is defined in an xml file called persitence.xml.
src/main/webapp: public files, template files, web.xml and some more configuration files.
Place your application's public files like stylesheets, javascripts and images here.
If your app requires additional servlet configurations, place them in WEB-INF/web.xml.
The Spring Quickstart is configured to automatically scan annotated classes. If you need to change this behavior (or need to set up any Spring module not used in the QuickStart) just do it in WEB-INF/jboss-as-spring-mvc-context.xml.
This QuickStart uses jsp templates located in the WEB-INF/views folder.
Usually, you just need to copy all your jsp's to that folder. You will also notice a few more configuration files under WEB-INF. They all follow the Spring defaults. It isn't likely that you'll need to change them.
Forking our Spring Application QuickStart to wrap your own project code
Remember: Forking is not a sin, as long as you remember to share.
First, log into your github account and fork the existing Spring QuickStart to point to make your own repository. Then use git clone REPO_URL to obtain a local copy of the code to work with.
The Spring QuickStart follows the default Maven 3 project conventions, so if your application makes use of Spring and Maven, you shouldn't need to change much:
Copy your spring project files into the related folders inside your clone of the Spring QuickStart source, making sure to follow the Maven project structure.
Review the project's pom.xml file, ensuring that it is configured to use the version of Spring that your project is written for, and that any additional project dependencies are specified.
Commit your changes, and make sure to push them back over to GitHub (or another available git-hosting service).
If your application needs to set up a Spring module that was not originally used in this quickstart, or if it needs any additional configuration, just follow the Spring and Maven standards. There aren't any other OpenShift-specific sections that need to be configured.
Ready for launch!
Modify the following URL to include the address of your new git repo, which should now contain your modified clone of our Spring Quickstart in addition to your Spring application's project source:
You can also quickly spin up a copy of your application from the command line, by modifying the --from-code flag to contain your new repo address url:
Now spread the word, and help others to effortlessly clone and host their own copies of your Spring application on OpenShift!
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.