The target audience for this tutorial are those individuals who do not yet have a great deal of experience with:

This tutorial sets the stage for the creation of TicketMonster - our sample application that illustrates how to bring together the best features of Java EE 6 + HTML5 + JBoss to create a rich, mobile-optimized and dynamic application.

TicketMonster is developed as an open source application, and you can find it at github.

If you prefer to watch instead of read, a large portion of this content is also covered in video form.

In this tutorial, we will cover the following topics:

The first order of business is to get your development environment setup and JBoss Developer Studio v8 installed. JBoss Developer Studio is Eclipse Luna (e4.4) for Java EE Developers plus select JBoss Tools and is available for free. Visit http://www.jboss.org/products/devstudio/download to download it. You may also choose to install JBoss Tools 4.2 into your existing Eclipse for Java EE Developers installation. This document uses screenshots depicting JBoss Developer Studio.

You must have a Java Development Kit (JDK) installed. Java 7 JDK is recommended - whilst a JVM runtime will work for most use cases, for a developer environment it is normally best to have the full JDK.

The JBoss Developer Studio installer has a (very long!) name such as jboss-devstudio-8.0.0.GA-v20141020-1042-B317-installer-standalone.jar where the latter portion of the file name relates to build date and version information and the text near the front related to the target operating system. The "universal" installer is for any operating system. To launch the installer you may simply be able to double-click on the .jar file name or you may need to issue the following from the operating system command line:

We recommend using the "universal" installer as it handles Windows, Mac OS X and Linux - 32-bit and 64-bit versions.

The rest of the steps are fairly self explanatory. If you run into trouble, please consult the videos above as they explore a few troubleshooting tips related to JRE/JDK setup.

You can skip the step in the installation wizard that allows you to install JBoss Enterprise Application Platform 6.3 as we will do this in the next step.

Once installed, launch JBoss Developer Studio. Please make sure to say Yes to the prompt that says "Will you allow JBoss Tools team to receive anonymous usage statistics for this Eclipse instance with JBoss Tools?". This information is very helpful to us when it comes to prioritizing our QA efforts in terms of operating system platforms. More information concerning our usage tracking can be found at http://www.jboss.org/tools/usage

Now that everything is properly installed, configured, running and verified to work, let’s build something "from scratch".

We recommend that you switch to the JBoss Perspective if you have not already.

First, select Start from scratch → Java EE Web Project in JBoss Central. Under the covers, this uses a Maven archetype which creates a Java EE 6 web application (.war), based around Maven. The project can be built outside of the IDE, and in continuous integration solutions like Hudson/Jenkins.

You will be prompted with a dialog box that verifies that JBoss Developer Studio is configured correctly. If you are in a brand new workspace, the application server will not be configured yet and you will notice the lack of a check mark on the server/runtime row.

To add JBoss Enterprise Application Platform, click on the Install…​ button, or if you have not yet downloaded and unzipped the server, click on the Download and Install…​ button.

Selecting Install…​ will pop up the JBoss Runtime Detection section of Preferences. You can always get back to this dialog by selecting Preferences → JBoss Tools → JBoss Tools Runtime Detection.

Select the Add button which will take you to a file browser dialog where you should locate your unzipped JBoss server.

Select Open and JBoss Developer Studio will pop up the Searching for runtimes…​ window.

Simply select OK. You should see the added runtime in the Paths list.

Select OK to close the Preferences dialog, and you will be returned to the New Project Example dialog, with the the server/runtime found.

The Target Runtime allows you to choose between JBoss Enterprise Application Platform and JBoss AS 7. If it is left empty, JBoss AS 7 will be elected.

Proceed to select the EAP 6.3 runtime, you just created.

You may see a warning (like the one in the screenshot), if you do not have the JBoss Enterprise Maven repository configured in your environment. Should this be the case, select the repository link in the warning, to open the JBoss Maven Integration wizard. The wizard dialog will prompt you to add the JBoss Enterprise Maven repository.

Click Ok.

You’ll now be shown the proposed changes to your Maven settings.xml file. Click Finish after reviewing the proposed updates.

You’ll be prompted to confirm the update. Click Yes.

The updates will now be persisted, and you’ll be returned to the original wizard.

Now, select Next in the New Project wizard to proceed to the next step.

The default Project name is jboss-javaee6-webapp. If this field appears blank, it is because your workspace already contains a "jboss-javaee6-webapp" in which case just provide another name for your project. Change the project name to ticket-monster, and the package name to org.jboss.examples.ticketmonster.

Select Finish.

JBoss Tools/JBoss Developer Studio will now generate the template project and import it into the workspace. You will see it pop up into the Project Explorer and a message that asks if you would like to open the cheatsheet file associated with the project.

Select Finish

Using the Project Explorer, open up the generated project, and double-click on the pom.xml.

The generated project is a Maven-based project with a pom.xml in its root directory.

JBoss Developer Studio and JBoss Tools include m2e and m2e-wtp. m2e is the Maven Eclipse plug-in and provides a graphical editor for editing pom.xml files, along with the ability to run maven goals directly from within Eclipse. m2e-wtp allows you to deploy your Maven-based project directly to any Web Tools Project (WTP) compliant application server. This means you can drag & drop, use Run As → Run on Server and other mechanisms to have the IDE deploy your application.

The pom.xml editor has several tabs along its bottom edge.

For this tutorial, we do not need to edit the pom.xml as it already provides the Java EE 6 APIs that we will need (e.g. JPA, JAX-RS, CDI). You should spend some time exploring the Dependencies and the pom.xml (source view) tabs.

One key element to make note of is <version.jboss.bom.eap>6.3.2.GA</version.jboss.bom.eap> which establishes the version of the JBoss Enterprise Application Platform dependencies. The BOM (Bill of Materials) specifies the versions of the Java EE (and other) APIs defined in the dependency section.

If you are using community version of the JBoss Application Server and you selected that as your Target Runtime, you will find a different property as the version string.

Using the Project Explorer, drill-down into src/main/java under Java Resources.

The initial project includes the following Java packages:

Now, let’s explore the resources in the project.

Under src you will find:

In src/main/webapp/WEB-INF, you will find three key files:

There are several ways to add a new JPA entity to your project:

For the purposes of this tutorial, we will take advantage of Forge to add a new JPA entity. This requires the least keystrokes, and we do not yet have a RDBMS schema to reverse engineer. There is also an optional section for adding an entity using New → Class.

Select the project in the Project Navigator view of JBoss Developer Studio and enter the Ctrl + 4 (in Windows/Linux) or Cmd + 4 (Mac) key combination. This will launch Forge if it is not started already.

The list of commands that you can execute in Forge will be visible in the Forge quick action menu.

Forge is a multi-faceted rapid application development tool that allows you to enter commands that generate classes and code. You could use either a GUI within your IDE that offers a familar wizard and dialog based UI, or a shell-like interface to perform operations. It will automatically update the IDE for you. A key feature is "contentual command activation", launched by running the Forge shortcut (Ctrl + 4 or Cmd + 4). For instance, launching Forge on a selected project activates different commands, than launching it in isolation, or for that matter launching Forge with a selected Java source file.

We’ll generate an entity using the Forge GUI. Let’s work through this, step by step.

We start by selecting the TicketMonster project. Launch Forge through the shortcut (Ctrl + 4 or Cmd + 4). Type jpa in the command filter textbox located in the menu. The menu will filter out irrelevant entries, leaving you with JPA-specific commands.

Select the "JPA: New Entity" entry in the menu. Click it or hit the Enter key to execute the command. You will be presented with a dialog where you can provide certain inputs that control how the new entity would be generated, like the package where the entity would be created, the name of the JPA entity/class, the primary-key strategy used for the entity etc.

Specify the value of the entity as Event and click Finish. The defaults for other values are sufficient - note how Forge intelligently constructs the value for the package field from the Maven group Id and artifact Id values of the project.

You should see a notification bubble in Eclipse when Forge completes the action.

Forge would have created a JPA entity as instructed, and it would also open the Java source file in Eclipse. Note that it would have created not only a new class with the @Entity annotation, but also created a primary-key field named id, a version field, along with getters and setters for both, in addition to equals, hashCode and toString methods.

Let’s add a new field to this entity. Select the Event class in the project navigator and launch the Forge menu once again. Filter on jpa as usual, and launch the "JPA: New Field" command. Specify the field name as name, to store the name of the event. The defaults are sufficient for other input fields. Click Finish or hit the Enter button as usual.

You will now notice that the Event class is enhanced with a name field of type String, as well as a getter and setter, along with modifications to the toString method.

Let’s now add Bean Validation (JSR-303) capabilities to the project. Launch the Forge menu, and filter for the "Constraint: Setup" command. Execute the command.

You’ll be presented with a choice on what Bean Validation providers you’d like to setup in the project. The defaults are sufficient - we’ll use the Bean Validation provider supplied by the Java EE application. Click Finish or hit Enter to setup Bean valdiation.

We’ll now add a constraint on the newly added name field in the Event class. Select the Event class in the project navigator and proceed to launch the "Constraint: Add" command from the Forge menu. Note that selecting the Event class allows Forge to provide commands relevant to this class in the action menu, as well as populating this class in input fields where it is fit to populate them.

This launches a wizard where one can add Bean Validation constraints. The class to operate on will default to the currently selected class, i.e. Event. If you want to switch to a different class, you can do so in the wizard. There is no need to re-launch the wizard.

Proceed to select the name field, on which we add a NotNull constraint. Click Finish or hit Enter.

Similarly, add a Size constraint with min and max values of 5 and 50 respectively on the name field.

From this point forward, we will assume you have the basics of using Forge’s menu and the commands executed thus far. Add a new field description to the Event class.

Add a Size constraint on the description field to the event class, with min and max values of 20 and 1000 respectively.

Add a new boolean field major. Note - you will need to change the type to boolean from the default value of String.

Add another field picture to the Event class.

The easiest way to see the results of Forge operating on the Event.java JPA Entity is to use the Outline View of JBoss Developer Studio. It is normally on the right-side of the IDE when using the JBoss Perspective.

Alternatively, you could perform the same sequence of operations in the Forge Console, using these commands:

By default, the entity classes generate the database schema, and is controlled by src/main/resources/persistence.xml.

The two key settings are the <jta-data-source> and the hibernate.hbm2ddl.auto property. The datasource maps to the datasource defined in src\main\webapp\ticket-monster–ds.xml.

The hibernate.hbm2ddl.auto=create-drop property indicates that all database tables will be dropped when an application is undeployed, or redeployed, and created when the application is deployed.

The import.sql file contains SQL statements that will inject sample data into your initial database structure. Add the following insert statements:

Alternatively, we can add an entity with JBoss Developer Studio or JBoss Tools.

First, right-click on the .model package and select New → Class. Enter the class name as Venue - our concerts & shows happen at particular stadiums, concert halls and theaters.

First, add some private fields representing the entities properties, which translate to the columns in the database table.

Now, right-click on the editor itself, and from the pop-up, context menu select Source → Generate Getters and Setters.

This will create accessor and mutator methods for all your fields, making them accessible properties for the entity class.

Click Select All and then OK.

Now, right-click on the editor, from the pop-up context menu select Source → Generate Hibernate/JPA Annotations.

If you are prompted to save Venue.java, simply select OK.

The Hibernate: add JPA annotations wizard will start up. First, verify that Venue is the class you are working on.

Select Next.

The next step in the wizard will provide a sampling of the refactored sources – describing the basic changes that are being made to Venue.

Select Finish.

Now you may wish to add the Bean Validation constraint annotations, such as @NotNull to the fields.

At this point, if you have not already deployed the application, right click on the project name in the Project Explorer and select Run As → Run on Server. If needed, this will startup the application server instance, compile & build the application and push the application into the JBOSS_HOME/standalone/deployments directory. This directory is scanned for new deployments, so simply placing your war in the directory will cause it to be deployed.

Now, deploy the h2console webapp. It can be found in the JBoss EAP quickstarts. You can read more on how to do this in the h2console quickstart.

You need to deploy the h2console.war application, located in the quickstarts, to the JBoss Application Server. You can deploy this application by copying the WAR file to the $JBOSS_HOME/standalone/deployments directory.

The Run As → Run on Server option will also launch the internal Eclipse browser with the appropriate URL so that you can immediately begin interacting with the application.

Now, go to http://localhost:8080/h2console to start up the h2 console.

Use jdbc:h2:mem:ticket-monster as the JDBC URL (this is defined in src/main/webapp/WEB-INF/ticket-monster-ds.xml), sa as the username and sa as the password.

Click Connect

You will see both the EVENT table, the VENUE table and the MEMBER tables have been added to the H2 schema.

And if you enter the SQL statement: select * from event and select the Run (Ctrl-Enter) button, it will display the data you entered in the import.sql file in a previous step. With these relatively simple steps, you have verified that your new EE 6 JPA entities have been added to the system and deployed successfully, creating the supporting RDBMS schema as needed.

The goal of this section of the tutorial is to walk you through the creation of a POJO with the JAX-RS annotations.

Right-click on the .rest package, select New → Class from the context menu, and enter EventService as the class name.

Select Finish.

Replace the contents of the class with this sample code:

This class is a JAX-RS endpoint that returns all Events.

You’ll notice a lot of errors, relating to missing imports. The easiest way to solve this is to right-click inside the editor and select Source → Organize Imports from the context menu.

Some of the class names are not unique. Eclipse will prompt you with any decisions around what class is intended. Select the following:

The following screenshots illustrate how you handle these decisions. The Figure description indicates the name of the class you should select.

You should end up with these imports:

Once these import statements are in place you should have no more compilation errors. When you save EventService.java, you will see it listed in JAX-RS REST Web Services in the Project Explorer.

This feature of JBoss Developer Studio and JBoss Tools provides a nice visual indicator that you have successfully configured your JAX-RS endpoint.

You should now redeploy your project via Run As → Run on Server, or by right clicking on the project in the Servers tab and select Full Publish.

Using a browser, visit http://localhost:8080/ticket-monster/rest/events to see the results of the query, formatted as JSON (JavaScript Object Notation).

Now, it is time to add a HTML5, jQuery based client application that is optimized for the mobile web experience.

There are numerous JavaScript libraries that help you optimize the end-user experience on a mobile web browser. We have found that jQuery Mobile is one of the easier ones to get started with but as your skills mature, you might investigate solutions like Sencha Touch, Zepto or Jo. This tutorial focuses on jQuery Mobile as the basis for creating the UI layer of the application.

The UI components interact with the JAX-RS RESTful services (e.g. EventService.java).

These next steps will guide you through the creation of a file called mobile.html that provides a mobile friendly version of the application, using jQuery Mobile.

First, using the Project Explorer, navigate to src/main/webapp, and right-click on webapp, and choose New HTML file.

Change directory to ticket-monster/src/main/webapp and enter name the file mobile.html.

Select Next.

On the Select HTML Template page of the New HTML File wizard, select New HTML File (5). This template will get you started with a boilerplate HTML5 document.

Select Finish.

The document must start with <!DOCTYPE html> as this identifies the page as HTML 5 based. For this particular phase of the tutorial, we are not introducing a bunch of HTML 5 specific concepts like the new form fields (type=email), websockets or the new CSS capabilities. For now, we simply wish to get our mobile application completed as soon as possible. The good news is that jQuery and jQuery Mobile make the consumption of a RESTful endpoint very simple.

You will now notice the Palette View visible in the JBoss perspective. This view contains a collection of popular jQuery Mobile widgets that can be dragged and dropped into the HTML pages to speed up construction of jQuery Mobile pages.

Let us first set the title of the HTML5 document as:

We shall now add the jQuery and jQuery Mobile JavaScript and CSS files to the HTML document. Luckily for us we can do this by clicking the JS/CSS widget in the palette.

This results in the following document with the jQuery JavaScript file and the jQuery Mobile JavaScript and CSS files being added to the head element.

We shall now proceed to setup the page layout. Click the page widget in the palette to do so. Ensure that the cursor is in the <body> element of the document when you do so.

This opens a dialog to configure the jQuery Mobile page.

Set the page title as "TicketMonster", footer as blank, and the ID as "page1". Click Finish to add a new jQuery Mobile page to the document. The layout is now established.

To populate the page content, remove the paragraph element: <p>Page content goes here.</p> to start with a blank content section. Click the Listview widget in the palette to start populating the content section.

This opens a new dialog to configure the jQuery Mobile listview widget.

Select the inset checkbox to display the list as an inset list. Inset lists do not span the entire widget of the display. Set the ID as "listOfItems". Retain the number of items in the list as three, modify the label values to One, Two and Three respectively, and finally, set the URL values to '#'. Retain the default values for the other fields, and click Finish. This will create a listview widget with 3 item entries in the list. The jQuery Mobile page is now structurally complete.

You might notice that in the Visual Page Editor, the visual portion is not that attractive, this is because the majority of jQuery Mobile magic happens at runtime and our visual page editor simply displays the HTML without embellishment.

Visit http://localhost:8080/ticket-monster/mobile.html.

As soon as the page loads, you can view the jQuery Mobile enhanced page.

One side benefit of using a HTML5 + jQuery-based front-end to your application is that it allows for fast turnaround in development. Simply edit the HTML file, save the file and refresh your browser.

Now the secret sauce to connecting your front-end to your back-end is simply observing the jQuery Mobile pageinit JavaScript event and including an invocation of the previously created Events JAX-RS service.

Insert the following block of code as the last item in the <head> element

Note:

The result is ready for the average mobile phone. Simply refresh your browser to see the results.

JBoss Developer Studio and JBoss Tools includes BrowerSim to help you better understand what your mobile application will look like. Look for a "phone" icon in the toolbar, visible in the JBoss Perspective.

The Mobile BrowserSim has a Devices menu, on Mac it is in the top menu bar and on Windows it is available via right-click as a pop-up menu. This menu allows you to change user-agent and dimensions of the browser, plus change the orientation of the device.

You can also add your own custom device/browser types.

Under the File menu, you will find a View Page Source option that will open up the mobile-version of the website’s source code inside of JBoss Developer Studio. This is a very useful feature for learning how other developers are creating their mobile web presence.

This concludes our introduction to building HTML5 Mobile Web applications using Java EE 6 with Forge and JBoss Developer Studio. At this point, you should feel confident enough to tackle any of the additional exercises to learn how the TicketMonster sample application is constructed.