There are many ways of developing mobile web applications. This article is going to show you how to get started quickly with one approach we call Plain Old HTML5 (POH5). This approach uses a pure HTML5 based front end which interactions with server side content through RESTful endpoints.
If you are new to the mobile web, or want more information before you get started take a look at these links:
This guide will walk you through creating a new POH5 mobile application using a Maven archetype, deploying it to JBoss Application Server 7, executing server/client test suites, and give an overview basic behavior of the application. This will include both command line, and JBoss Tools instructions.
- Java 6.0 (Java SDK 1.6)+
- Maven 3+
- JBoss Application 7
- JBoss Tools 3.3 (optional)
Using JBoss tools is optional. Any IDE that can generate and consume projects from Maven archetypes will work. Even standard Maven command line tools are fine.
An HTML5 compatible browser is also required such as Chrome 14+, Safari 5+, Firefox 5+, or IE 9+, and note that some behaviors will vary slightly (ex. validations) based on browser support, especially IE 9.
Mobile web support is limited to Android and iOS devices however it should run on HP, and Black Berry devices as well. Windows Phone, and others will work as jQuery Mobile announces support.
As was mentioned before there are multiple ways to create this application from the Maven archetype. The archetype is located in the Maven central repository so there is no need to follow any special Maven setup steps.
Move to a the directory you wish to create the project in. Then execute the following Maven archetype command:
mvn archetype:generate \ -DarchetypeArtifactId=jboss-html5-mobile-archetype \ -DarchetypeGroupId=org.jboss.aerogear.archetypes \ -DarchetypeVersion=1.0.0.M1
Maven will download the archetype, and its dependencies then ask you some questions:
- GroupId, the base package for the project
- ArtifactId, the name of the project ( NOTE: do not use any special characters for the timing being, i.e. "-", ".", "_" )
- This restriction has been removed in SNAPSHOT & will be released in M2
- See comments in Error deploying when project name contains "-"
- Version, the starting version of project
- Package, if you want it different from the groupId
Select whatever values you wish, and when Maven asks to proceed just type "Y". You'll then have the project generated in a directory named whatever you chose for the artifactId. The "README.md" files contains a lot of great information to get you started.
First you need to start the JBoss container. To do this, run
or if you are using windows
Note: Adding "-b 0.0.0.0" to the above commands will allow external clients (phones, tablets, desktops, etc...) connect through your local network.
$JBOSS_HOME/bin/standalone.sh -b 0.0.0.0
To deploy the application, you first need to produce the archive to deploy using the following Maven goal:
You can now deploy the artifact by executing the following command:
The application will be running at the following URL http://localhost:8080/<artifactId>/. Where <artifactId> is what ever you entered above.
To undeploy run this command:
By default, tests are configured to be skipped. The reason is that the sample test is an Arquillian test, which requires the use of a container.
To run the test in JBoss, first start the container instance. Then, run the test goal with the following profile activated:
mvn clean test -Parq-jbossas-remote
For more information on QUnit tests see http://docs.jquery.com/QUnit
With JBoss Tools it is even easier to create, deploy, test, and develop this application than using the command line alone. The instructions below assume you've already installed JBoss Tools, and JBoss AS 7 as a server in the IDE.
Starting with JBoss Tools 3.3 there is a new splash screen called JBoss Central. This gives you quick access to loads of JBoss quickstarts, tutorials, news, and more.
We are going to select the HTML5 Project link which is tied to this archetype. Following the wizard below enter the project name, package, target runtimes, etc... then click the Next button.
NOTE: do not use any special characters for project name / artifactId for the timing being, i.e. "-", ".", "_"
- This restriction has been removed in SNAPSHOT & will be released in M2 (end of Feb)
- See comments in Error deploying when project name contains "-"
The next page should be pre-populated with values from the previous screen, and you can update as needed. When finished click the Finish button.
JBoss Tools will then create the application and import it as a new project in your workspace!
Getting the application deployed to JBoss AS7 is snap. Assuming you followed the JBoss AS7 setup instructions above you should have a server tab that looks like this:
Right click on the "JBoss 7.0 Runtime Server" and select "Add and Remove...". You should see the following screen:
Using this wizard select your application on the left and choose to add it to the right. Click the Finished button when ready.
You can then start, stop, republish, and debug your application right from here:
Go ahead and start the server, and when completed (super fast because it's JBoss AS7) you can access your application at:
Arquillian's in container tests can be executing like any other JUnit test in eclipse. The only thing is that for our configuration we'll need to have our JBoss container started following the JBoss Tools instructions above.
Then navigate to MemberRegistrationTest.java as shown below:
Right click on the file, and select Run As --> JUnit Test. The JUnit tab should appear, and the console should show you the tests being deployed and executed. If all goes according to plan you should see something like this:
If you run into deployment trouble with the test, please be sure to check that the "arq-jbossas-remote" maven profile is active in your projects configuration.
Navigate to the QUnit index.html file as shown below, right click on this and choose to Open With --> Web Browser.
Your default browser should launch, loading, and executing the QUnit tests in the process. The browser window should look something like this:
This is showing you the results of the tests that were executed.
Application in Action
Now that we've seen how to get this application running lets review some of the application screens, on both desktop and mobile devices.
Below is the application's main page when viewed with a desktop browser:
You can create new members using the form, and you will see all current members in a table at the bottom of the page. The interesting part is what is going on behind the sceens. We're using jQuery to help us make JAX-RS requests to the JBoss AS7 server, handling POST and GET requests/responses, and handling errors. We're also taking advantage of new HTML5 form and page elements to help with client side validation (Chrome, FireFox only), and more.
Looking at this same page from an iPhone or Android device results is something quite different:
Diving in Deeper
In this article we've shown you how to get started with your own HTML5 based application for both desktop and mobile clients on JBoss. This is the just tip of the iceberg though! To dig deeper in the code, and inner workings of this application please following the links below:
- HTML5 Mobile Quickstart & Archetype Deep Dive
- Testing HTML5 Applications
- Deploying HTML5 Applications To Openshift
You can also watch a webinar where Jay Balunas presented this archetype, and discussed some of the inner workings in more detail: