Having recently spent time working on the IBM Worklight platform, I thought it would only be fair if I documented some of my findings. No disrespect to the IBM’ers, but its reasonably fair to say that documentation is a little sparse in places, so lets give a little back to the community by discussing some of the hurdles. Lets not dwell on what Worklight is, Andy has already covered this well in a previous post; but lets just dive right into some of the technical aspects.
General Thoughts
Development on the whole is a relatively straightforward process, even for someone like myself that often steers well clear of anything that involves web presentation technologies (it reminds me of dark nights at the university labs spending hours trying to get a button to align correctly, the night before coursework submission *shudder*).
The Worklight eclipse plugin provides a good drag & drop GUI builder, but with support only for dojo. I opted to drop dojo and go for jQuery. jQuery is very well documented, and is easy to get help should you require it. One of the main things I like about jQuery is its showcase and examples, they are documented very well and the learning curve is generally quite small, but also the themeroller, it becomes incredibly easy to customise the default colour scheme and drop the generated CSS into your app. It always amazes me how excited the marketing guys will get if you can add in the corporate colour scheme to your app (thanks Joseph!).
Continuous Integration
We’re big fans of CI here, so I was quite keen to understand how easy it would be to have our Worklight apps built from the command line, and ultimately on a Jenkins CI box. The chaps over at IBM have done a fantastic job of exposing an array of Ant tasks that help with building and deploying apps, you’ll almost certainly want to read through module 42 on the getting started page that covers these tasks:
- adapter-builder – Use this task to build your adapter and create the .adapter file
- adapter-deployer – Use this to deploy a .adapter file to a Worklight server (very useful for deploying to a remote AWS instance)
- war-builder – Use this to build the server .war file that you will deploy to the application server (some manual tweaks are required)
- app-builder – Use this to build the .wlapp files that you will deploy into your Worklight container
- app-deployer – Use this to deploy your .wlapp files onto a Worklight server (useful again for remote deployments)
Lets have a closer look at each of those targets, and how we’re using them here at Smart421:
Getting the party started, with init
Firstly, grab the worklight ant jar (you’ll need to have purchased the WL Enterprise edition for this) and add it into your ant context like so :
<target name="init">
<echo message="Loading ANT Tool"/>
<taskdef resource="com/worklight/ant/defaults.properties">
<classpath>
<pathelement location="./build-config/worklight-ant.jar"/>
</classpath>
</taskdef>
<property environment="env"/>
</target>
Now you’re free to use the ant tasks anywhere in your build script.
Building & Deploying WL Adapters
You need to build each adapter individually, and then deploy each one. You can create the following ant targets to do that for you:
<target name="buildAdapters" depends="init">
<echo message="Building all adapters"/>
<adapter-builder
folder="./adapters/TwitterAdapter"
destinationfolder="./bin"/>
<!-- Build your other adapters here, same as above-->
</target>
<target name="deployAdapters" depends="init">
<property name="WLSERVERHOST" value="http://my_aws_ip_here:8080/SmartConf"/>
<echo message="Deploying all adapters"/>
<adapter-deployer
worklightServerHost="${WLSERVERHOST}"
deployable="./bin/TwitterAdapter.adapter"/>
<!-- Deploy your other adapters here, same as above-->
</target>
Building the Server WAR
You can build the server war file using the war-builder task, as shown below. It is important to note however, that I needed to do some tweaking to the war file to avoid any post-installation configuration tasks. According to the Worklight forums, there doesn’t appear to be a way to include files in the WEB-INF when the war is created, which means that once you’ve expanded the war on the application server you’d need to manually replace the default web.xml and context.xml files (to set your datasources), this can be quite frustrating, so in true Blue Peter fashion, I’m updating the war file with files I created earlier.
<target name="warBuilder" depends="init">
<echo message="Building the war file"/>
<war-builder
projectfolder="./"
destinationfolder="./bin"
warfile="./bin/SmartConf.war"
classesFolder="./bin/classes"/>
</target>
<target name="updateWar">
<echo message="Updating the war file"/>
<war destfile="./bin/SmartConf.war" update="true" webxml="./build-config/web.xml">
<metainf dir="./build-config" includes="context.xml"/>
</war>
</target>
Building & Deploying the WL Apps
You’ll also want to automate the building and deploying of the wlapp files, you can do this with the following :
<target name="buildApps">
<echo message="Building all WL Apps"/>
<app-builder
applicationFolder="./apps/Smartconf"
nativeProjectPrefix="SmartConf"
outputfolder="./bin"/>
</target>
<target name="deployApps">
<property name="WLSERVERHOST" value="http://my_aws_ip_here:8080/SmartConf"/>
<echo message="Deploying all WL Apps"/>
<app-deployer
worklightServerHost="${WLSERVERHOST}"
deployable="./bin/SmartConf-all.wlapp"/>
</target>
Building the Native Application Distributable Binaries You’ve survived this far, and I’m thankful to you for that, however we’re not quite finished yet. Worklight will generate the native projects for you, but its your own responsibility to take those project directories and build the Android APK, or the iOS IPA etc. IBM will draw the line at this point, so you need to build them yourself, you can do this for all of the environments quite easily using additional ant tasks, android is the easiest :
<target name="client-android" depends="buildAndroid">
<!-- Run the android native build, in its own directory -->
<ant antfile="./apps/SmartConf/android/native/build.xml" target="release" useNativeBasedir="true"/>
<!-- Copy up the apk into the bin area, for consistency -->
<copy file="./apps/SmartConf/android/native/bin/SmartConf-release-unsigned.apk" tofile="./bin/SmartConfSmartConfAndroid.apk" overwrite="true"/>
</target>
Building Blackberry and iOS apps from the command line is slightly more involved, and I feel they warrant their own blog post on that, alternatively, get in touch and we’d be glad to offer some assistance. Bear in mind you will need an Apple MAC to build iOS, for which we’ve installed a shared box in our build environment.
Other Gotchas
As with taking on board any emerging technology, there will always be plenty of head-scratching moments where the documentation is thin, and Uncle Google doesn’t provide much help, fortunately for you, we’re a nice bunch of guys here at Smart421 so we’ll share some of the things that had us pondering over a coffee:
- The trailing “/” in the Worklight server host URL is required, don’t ask why, it just is.
- The versioning conventions for Worklight are a little strange, 5.0.0.270 = v5.0 GA, but the developer edition is 5.0.2.407-developer-edition = 5.0.0.3.
- If you have an existing 5.0.0.2 WL server installation, don’t upgrade it to 5.0.0.3, it fails to upgrade all components and leaves you with some obscure error messages that are hard to trace. The best plan of action is to uninstall, install again, but make sure you check for updates at time of installing, via the wizard
- App crashes with Unreachable host? When you build and deploy the app to your device, it has the WL server IP hardcoded into it. The next day when you arrive at the office and hop onto the Wifi, DHCP gives you a different IP address…It’s a classic schoolboy error, but catches us out from time to time. A simple solution if you don’t have a spare box lying around is to install the Worklight server on AWS and deploy to the cloud, bearing in mind that it needs to be open to your mobile devices over the Internet in a real-life installation anyway.
- Results is undefined on adapter call. A subtle difference here, HTTP adapters use invocationResult.results, whereas SQL adapters use invocationResults.result. That last character makes all the difference.
- Response cannot be parsed, please contact support; this is an annoying error that you often see in the developer preview, just make sure you set the body onload to WL.Client.init() as mentioned here.
- Unable to use geolocation services on android? You’re probably seeing Caught security exception registering for location updates from the system, this should only happen in DumpRenderTree. Make sure you have the geolocations permission in your android manifest as detailed here.
Conclusion
On the whole, I was very impressed with Worklight, they are offering a lot of functionality over and above the standard Cordova project. Some of the errors I’ve encountered have been a little frustrating, as often my only source of help was the forums, but I can accept that it is a product in its early stages of adoption, and will probably go very far. I’m looking forward to working with it in the future.
If you’d like to have a look at some of the apps we’re creating, or generally just want a chat about Worklight and some of its capabilities, or Mobility in general, we’d love to hear from you.
. As you can see from the photo below, our team (Neil Miles, the MD, and two colleagues from Business Services) are very smiley after knocking back a few cocktails…and Red Hat’s marketing approach at the event clearly worked!
DATABASE at Postmasters, March 2009
Benjamin Baumguertel
abudd1
Adam Dunn
adobson421
ahaskell2012
amangroo
gbbailey
georginatownsend
James Elsey
Joseph Spear
Mark Stancombe-Duhm
Mark Want
Martin Brazill
muralian
Paul Russell
philhimself
rdoyle421
R Featherstone
rhudsonsolutionarchitect
Richard Latham
Robin Meehan
sallyhopperx
Steve Williams
smart421
smaley
Steve Maher
taylordr
