Work Light

V8.
WebSphere Education Solutions Team offering - Early release material
cover
Front cover
Mobile Application
Development with IBM
Worklight V6 - Early
Education
(Course code WU506)
Student Notebook
ERC 1.1
Student Notebook
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International
Business Machines Corp., registered in many jurisdictions worldwide.
The following are trademarks of International Business Machines Corporation, registered in
many jurisdictions worldwide:
AIX
Cast Iron
Domino
Lotus
Rational
AS/400
DB
FileNet
Notes
Redbooks
BigFix
DB2
Lotus Notes
PureApplication
WebSphere
Intel and Pentium are trademarks or registered trademarks of Intel Corporation or its
subsidiaries in the United States and other countries.
Lenovo and ThinkPad are trademarks or registered trademarks of Lenovo in the United
States, other countries, or both.
Linux is a registered trademark of Linus Torvalds in the United States, other countries, or
both.
Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other
countries, or both.
Java and all Java-based trademarks and logos are trademarks or registered trademarks
of Oracle and/or its affiliates.
VMware and the VMware "boxes" logo and design, Virtual SMP and VMotion are registered
trademarks or trademarks (the "Marks") of VMware, Inc. in the United States and/or other
jurisdictions.
Worklight is a trademark or registered trademark of Worklight, an IBM Company.
Other product and service names might be trademarks of IBM or other companies.
June 2013 edition

The information contained in this document has not been submitted to any formal IBM test and is distributed on an as is basis without
any warranty either express or implied. The use of this information or the implementation of any of these techniques is a customer
responsibility and depends on the customers ability to evaluate and integrate them into the customers operational environment. While
each item may have been reviewed by IBM for accuracy in a specific situation, there is no guarantee that the same or similar results will
result elsewhere. Customers attempting to adapt these techniques to their own environments do so at their own risk.
Copyright International Business Machines Corporation 2013.

This document may not be reproduced in whole or in part without the prior written permission of IBM.
US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
V8.1
Student Notebook
TOC
Contents
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii
Course description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv
Agenda . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvii
Unit 1. Mobile overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
1.1. Becoming a mobile enterprise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Becoming a mobile enterprise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
Why go mobile? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7
Demand for mobility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8
Mobile platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9
1.2. Challenges of mobile application development, management and security . . . . . 1-11
Challenges of mobile application development, management and security . . . . . 1-12
Considerations for mobile (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13
Considerations for mobile (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14
Advantages of mobile communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-15
Characteristics of mobile interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-16
1.3. Types of mobile applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-17
Types of mobile applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-18
The choice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-19
Development approaches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20
Native compared to hybrid applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21
Web standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-22
SOA to mobile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-23
1.4. Overview of IBM mobile strategy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-25
Overview of IBM mobile strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-26
IBM MobileFirst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-27
IBM MobileFirst portfolio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-28
1.5. IBM Mobile Foundation V6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-29
IBM Mobile Foundation V6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-30
IBM MobileFirst platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-31
IBM Mobile Foundation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-33
IBM Worklight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-34
WebSphere Cast Iron Hypervisor Edition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-36
IBM Endpoint Manager for Mobile Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-37
Checkpoint questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-38
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-39
Checkpoint answers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-40
Unit 2. Designing mobile solutions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Copyright IBM Corp. 2013
Contents
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
iii
Student Notebook
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-3
Three approaches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-4
Web, hybrid, native... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-5
2.1. Approaches to mobile design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-7
Approaches to mobile design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-8
Native applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-9
Creating a native application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-10
Mobile-web Applications - HTML5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-11
Mobile-web Applications - CSS3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-12
Mobile-web Applications - JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-13
Mobile web applications - mobile web sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-14
Hybrid applications (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-15
Hybrid applications (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-17
2.2. Comparison of mobile application designs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-19
Comparison of mobile application designs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-20
Native - advantages and disadvantages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-21
Web application - advantages and disadvantages . . . . . . . . . . . . . . . . . . . . . . . . .2-22
Hybrid applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-23
Comparison of features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-24
2.3. Choosing the right approach. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-25
Choosing the right approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-26
Scenario - the native approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-27
Scenario - the web approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-28
Scenario - the hybrid approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-29
Checkpoint questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-30
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-31
Checkpoint answers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-32
Unit 3. Introduction to IBM Worklight v6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-2
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-3
3.1. IBM Worklight component architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-5
IBM Worklight component architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-6
Worklight components - overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-7
Worklight Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-8
Worklight Studio plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-9
Worklight Studio design perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-10
Shell components and inner applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-11
Worklight server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-12
Server customization components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-13
worklight.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-14
authenticationConfig.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-15
Deploying applications and adapters to the server . . . . . . . . . . . . . . . . . . . . . . . . .3-16
Device runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-17
Application distribution and update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-19
Push notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-20
Worklight console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-21
Worklight console - catalog tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-22
iv
Mobile Application Development with IBM Worklight V6

V8.1
Student Notebook
TOC
Worklight console - mobile browser simulator . . . . . . . . . . . . . . . . . . . . . . . . . . .

Mobile browser simulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Application Center architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2. Code optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Code optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Code optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The basis of optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How does optimization work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Optimization - CSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Optimization - images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Optimization - JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Optimization - HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3. Client-side development:
the Worklight JavaScript SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Client-side development: the Worklight JavaScript SDK . . . . . . . . . . . . . . . . . . . .
Overview of client-side development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Common controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Apache Cordova . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Calls between native and web pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Offline access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Encrypted cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Globalizing strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UI frameworks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4. Server-side development. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Server-side development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Integration adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5. Secure authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Secure authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6. Application management and reporting capabilities . . . . . . . . . . . . . . . . . . . . . . .
Application management and reporting capabilities . . . . . . . . . . . . . . . . . . . . . . .
Push notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Direct update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Remote server application deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7. Mobile team development capabilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Mobile team development capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Shell development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Application Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enhancements to Worklight in version 6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Checkpoint answers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3-23
3-24
3-25
3-27
3-28
3-29
3-30
3-31
3-32
3-33
3-34
3-35
3-37
3-38
3-39
3-40
3-41
3-42
3-43
3-44
3-45
3-46
3-48
3-49
3-50
3-51
3-53
3-54
3-55
3-57
3-58
3-59
3-60
3-61
3-63
3-64
3-65
3-66
3-67
3-68
3-69
3-70
Unit 4. Overview of Worklight Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.1. IBM Worklight Studio installation and configuration . . . . . . . . . . . . . . . . . . . . . . . .
Contents
4-1
4-2
4-3
4-5
v
Student Notebook
4.2.
4.3.
4.4.
4.5.
4.6.
vi
IBM Worklight Studio installation and configuration . . . . . . . . . . . . . . . . . . . . . . . . .4-6

IBM Worklight Studio: Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-7
IBM Worklight Studio installation: Prerequisites (1 of 2) . . . . . . . . . . . . . . . . . . . . . .4-8
IBM Worklight Studio installation: Prerequisites (2 of 2) . . . . . . . . . . . . . . . . . . . . . .4-9
IBM Worklight Studio installation methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-10
Installing IBM Worklight Studio using the Eclipse Update Site (1 of 4) . . . . . . . . . .4-11
IBM Worklight Studio installation and configuration . . . . . . . . . . . . . . . . . . . . . . . .4-15
Android development environment setup steps . . . . . . . . . . . . . . . . . . . . . . . . . . .4-17
Installing the Android SDK: Core tools installation . . . . . . . . . . . . . . . . . . . . . . . .4-18
Installing the Android SDK: SDK platform and platform tools installation . . . . . . .4-19
Installing the ADT plug-in for Eclipse (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-20
Creating an Android Virtual Device (AVD) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-23
Starting an Android Virtual Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-24
iOS development environment setup steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-27
Developing for iOS: Register as an Apple developer . . . . . . . . . . . . . . . . . . . . . . .4-28
Developing for iOS: Download and install Xcode . . . . . . . . . . . . . . . . . . . . . . . . . .4-29
Developing for iOS: Worklight Studio and Xcode integration . . . . . . . . . . . . . . . . .4-31
Overview of mobile development steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-33
Overview of mobile development steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-34
Worklight Studio mobile application development lifecycle . . . . . . . . . . . . . . . . . .4-35
Creating a project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-37
Creating a project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-38
Worklight project creation wizard: Invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-39
Worklight project creation wizard: Project name and type . . . . . . . . . . . . . . . . . . .4-40
Worklight project creation wizard: Hybrid application UI framework selection . . . .4-42
Worklight project structure overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-43
Worklight project structure: Application folder . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-45
Worklight project structure: Application folder additional environments . . . . . . . . .4-47
Worklight project structure: Server folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-48
Worklight project structure: bin folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-49
Worklight application descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-50
Worklight application descriptor: Basic information . . . . . . . . . . . . . . . . . . . . . . . .4-51
Worklight application descriptor: Environments . . . . . . . . . . . . . . . . . . . . . . . . . . .4-52
Writing your code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-53
Writing your code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-54
Constructing the UI: Main HTML document (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . .4-55
Constructing the UI: Main HTML document (3 of 3) . . . . . . . . . . . . . . . . . . . . . . . .4-56
Constructing the UI: Rich Page Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-57
Coding the business logic: Main JavaScript document . . . . . . . . . . . . . . . . . . . . .4-58
Adding a new environment (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-59
V8.1
Student Notebook
TOC
Adding a new environment (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-60

Android environment generated folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-61
Android environment folder structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-62
iPhone environment generated folders (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-64
iphone environment folder structure (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-65
4.7. Building your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-67
Building your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-68
Building an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-69
4.8. Previewing and testing your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-71
Previewing and testing your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-72
Application preview and test tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-73
4.9. Previewing your application in the browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-75
Previewing your application in the browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-76
Previewing as a common resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-77
Previewing in the Mobile Browser Simulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-78
Mobile Browser Simulator: Android device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-79
Mobile Browser Simulator: iPhone device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-80
4.10. Testing on a simulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-81
Testing on a simulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-82
Testing on the Android emulator (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-83
Testing on the Android emulator (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-84
Testing on the iPhone simulator: Pre-requisites (1 of 2) . . . . . . . . . . . . . . . . . . . . 4-85
Testing on the iPhone simulator: Pre-requisites (2 of 2) . . . . . . . . . . . . . . . . . . . . 4-86
Testing on the iPhone simulator: Building and running an application (1 of 2) . . . 4-87
Testing on the iPhone simulator: Building and running your application (2 of 2) . 4-88
Testing on a device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-89
Testing on an Android device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-90
Testing on an iOS device: Pre-requisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-91
Testing on an iOS device pre-requisite: Enroll in the iOS Developer Program . . . 4-92
Testing on an iOS device pre-requisite: Provision your device . . . . . . . . . . . . . . . 4-93
Testing on an iOS device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-95
Publishing your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-96
Publishing your application: Preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-97
Publishing your Android application in Google Play . . . . . . . . . . . . . . . . . . . . . . . 4-98
Publishing your iPhone application in the App Store . . . . . . . . . . . . . . . . . . . . . . . 4-99
Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-100
Checkpoint answers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-101
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-102
Exercise 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-103
Exercise objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-104
Unit 5. Client-side core APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1. Client-side basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Client-side basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Application sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Worklight initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents
5-1
5-2
5-3
5-5
5-6
5-7
5-8
vii
Student Notebook
5.2.
5.3.
5.4.
5.5.
viii
jQuery JavaScript framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-9

Worklight client JavaScript API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-10
The WL namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-11
WL.Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-12
WL.Logger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-13
WL.Logger - example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-14
Building a multi-page application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-15
Building a multi-page application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-16
Working with pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-17
Splitting code between HTML pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-19
Design considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-20
Loading an external HTML file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-21
Loading an external HTML file - example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-22
Implementing page navigation with history (1 of 4) . . . . . . . . . . . . . . . . . . . . . . . .5-23
Common controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-27
Common controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-28
What is a common control? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-29
WL.BusyIndicator (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-30
WL.SimpleDialog (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-33
WL.TabBar (1 of 5) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-36
WL.TabBar (2 of 5) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-37
WL.TabBar (3 of 5) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-38
WL.TabBar (4 of 5) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-39
WL.TabBar (5 of 5) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-40
WL.OptionsMenu (1 of 4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-41
Skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-45
Skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-46
Skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-47
Skin use cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-48
Skin creation and packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-49
Applying skins at run time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-50
Skin Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-51
Offline access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-53
Offline access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-54
Working in Offline Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-55
Explicit detection: using methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-57
Implicit Detection: offline/online events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-58
isConnected() and connect() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-60
V8.1
Student Notebook
TOC
getNetworkInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Foreground event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Worklight heartbeat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.6. String translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
String translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction to translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enabling translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Translating system messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Multi-language translation: set up the Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Multi-language translation: selecting the language . . . . . . . . . . . . . . . . . . . . . . . .
Detecting device locale and language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Checkpoint questions (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Checkpoint questions (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exploring IBM Worklight client-side APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exercise objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5-61
5-63
5-64
5-65
5-66
5-67
5-69
5-71
5-72
5-73
5-74
5-76
5-77
5-78
5-79
5-80
5-81
Unit 6. Local storage APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3
6.1. Encrypted cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5
Encrypted cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6
What is encrypted cache? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7
Supported Browsers and Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8
Creating or opening encrypted cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9
Encrypted cache status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-11
Opening encrypted cache example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12
Reading and writing data with encrypted cache . . . . . . . . . . . . . . . . . . . . . . . . . . 6-13
Reading and removing data from encrypted cache . . . . . . . . . . . . . . . . . . . . . . . . 6-14
Closing encrypted cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-15
Destroying encrypted cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-16
Changing the encryption key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17
6.2. JSONStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-19
JSONStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-20
What is JSONStore? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-21
Comparison of storage technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-22
JSONStore terminology: document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-24
JSONStore terminology: collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-26
JSONStore terminology: search field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-27
JSONStore terminology: query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-29
Store internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-30
Error object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-31
JSONStore architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-32
Sending data back . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-33
JSONStore API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-34
Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-35
Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-37
Contents
ix
Student Notebook
Handling data locally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-38

Add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-39
Find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-40
Sample app Find buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-41
Replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-42
Remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-43
Remove collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-44
Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-45
Advanced features: Security (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-46
Advanced features: Security (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-47
Advanced features: multiple user support (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . .6-48
Advanced features: multiple user support (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . .6-49
Advance features: adapter integration (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-50
Pushing and pulling changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-54
Example: getPushRequired . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-56
Example: push . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-57
Example: enhance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-58
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-59
Exercise 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-64
Exercise objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-65
Unit 7. Working with UI frameworks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-2
The need for an application toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-3
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-5
7.1. Working with UI frameworks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-7
Working with UI frameworks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-8
Working with UI frameworks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-9
7.2. Using jQuery Mobile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-11
Using jQuery Mobile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-12
jQuery Mobile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-13
Working with jQuery Mobile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-14
Adding jQuery to the Worklight application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-15
jQuery Mobile basic structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-16
jQuery Mobile widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-17
jQuery Mobile application screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-18
7.3. Sencha Touch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-19
Sencha Touch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-20
Working with Sencha Touch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-21
Adding Sencha Touch components to an application . . . . . . . . . . . . . . . . . . . . . . .7-22
Working with Sencha Touch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-23
x

V8.1
Student Notebook
TOC
7.4. Dojo Mobile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Dojo Mobile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
What is Dojo? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Addind Dojo Toolkit package to a project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deployment configuration with Ant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating custom layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using a Dojo Mobile HTML template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Checkpoint (objective only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7-25
7-26
7-27
7-28
7-29
7-30
7-31
7-32
7-33
7-34
Unit 8. Apache Cordova . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3
8.1. Apache Cordova overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5
Apache Cordova overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6
What is Apache Cordova? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7
Apache Cordova referenced in the HTML file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8
Apache Cordova library files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9
Apache Cordova API basics: Cordova objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10
Apache Cordova usage example: Displaying a native alert . . . . . . . . . . . . . . . . . 8-11
Apache Cordova usage example: Retrieving information . . . . . . . . . . . . . . . . . . . 8-12
8.2. Creating a plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-13
Creating a plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-14
Apache Cordova Plugin Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-15
Apache Cordova plugin architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-17
8.3. Creating a native plugin class for Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-19
Creating a native plugin class for Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-20
Implementing a plugin: Java class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-21
Plugin class execute() method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-22
8.4. Creating a native plugin class for iOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-23
Creating a native plugin class for iOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-24
Implementing the plugin: Objective-C class creation . . . . . . . . . . . . . . . . . . . . . . 8-25
Plugin class method: Input parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-26
8.5. Creating a plugin JavaScript wrapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-27
Creating a plugin JavaScript wrapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-28
Implementing the plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-29
Invoking the plugin from JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-31
HelloWorldPlugin example screen shots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-32
8.6. WebViewOverlay plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-33
WebViewOverlay plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-34
WebViewOverlay plugin: Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-35
WebViewOverlay plugin: Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-36
WebViewOverlay case study: Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-37
WebViewOverlay plugin: Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-38
WebViewOverlay Java implementation (1 of 4) . . . . . . . . . . . . . . . . . . . . . . . . . . 8-39
Contents
xi
Student Notebook
WebViewOverlay Cordova plugin (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-42

WebViewOverlay JavaScript implementation (1 of 2) . . . . . . . . . . . . . . . . . . . . . . .8-51
WebViewOverlay JavaScript implementation (2 of 2) . . . . . . . . . . . . . . . . . . . . . . .8-52
Modification to the code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-53
WebViewOverlay case study: Examining the result . . . . . . . . . . . . . . . . . . . . . . . .8-54
Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-55
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-56
Exercise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-58
Exercise objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-59
Apache Cordova additional resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-60
Unit 9. Integration adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-2
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-3
9.1. Adapters overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-5
Adapters - overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-6
Adapters: overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-7
Benefits of using adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-8
IBM Worklight Adapter Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-9
Anatomy of a Worklight adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-11
Adapter procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-12
Creating an adapter (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-13
Adapter deployment (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-16
Adapter deployment (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-17
Testing adapter procedures (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-18
Testing adapter procedures (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-19
Adapter structure: XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-20
Adapter structure: JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-22
9.2. SQL adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-23
SQL adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-24
Worklight SQL adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-25
Creating a Worklight SQL adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-26
XML file database connectivity settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-27
JavaScript file procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-29
JavaScript file SQL query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-30
JavaScript file stored SQL procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-32
WL adapters invocation result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-33
9.3. HTTP adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-35
HTTP adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-36
Worklight HTTP adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-37
Create an HTTP adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-38
XML file connectivity settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-39
JavaScript file procedure implementation overview . . . . . . . . . . . . . . . . . . . . . . . .9-41
xii

V8.1
Student Notebook
TOC
Procedure declarations in the XML file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

JavaScript file procedures implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSL transformation filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.4. Using HTTP adapters with SOAP services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using HTTP adapters with SOAP services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a SOAP-based Service Request overview . . . . . . . . . . . . . . . . . . . . . . .
Creating a SOAP-based Service Request (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . .
Creating a SOAP-based Service Request (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . .
Service request invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Full SOAP-based service invocation procedure example . . . . . . . . . . . . . . . . . . .
9.5. Cast Iron adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Cast Iron adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Worklight Cast Iron adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a Cast Iron adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JavaScript file procedures implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.6. JMS adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JMS adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Java Message Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Worklight JMS adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Implementing procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Connection properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JMS adapter methods: reading messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JMS adapter methods: writing messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.7. Invoking Java code from an adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Invoking Java code from an adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding custom Java classes to a project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding custom Java classes to a project (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . .
Adding a custom Java class to your project (2 of 2) . . . . . . . . . . . . . . . . . . . . . . .
Invoking custom Java classes from adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.8. The InvocationData object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The InvocationData object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
invocationData object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Options object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Bringing it all together . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Invocation result (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Invocation result (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.9. Invoking adapter procedures from Java code . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Invoking adapter procedures from Java code . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Invoking from Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.10. Server side scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Server side scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Server-side scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Server-side API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Mashups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents
9-43
9-44
9-46
9-47
9-48
9-49
9-50
9-51
9-52
9-53
9-55
9-56
9-57
9-58
9-59
9-61
9-62
9-63
9-64
9-65
9-66
9-67
9-68
9-69
9-70
9-71
9-72
9-73
9-74
9-75
9-77
9-78
9-79
9-80
9-82
9-84
9-85
9-87
9-88
9-89
9-91
9-92
9-93
9-94
9-95
9-96
9-97
9-98
xiii
Student Notebook

Exercise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-100
Exercise objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-101
Unit 10. Native and web page integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-2
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-3
10.1. Overview of native and web page integration . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-5
Overview of native and web page integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-6
Limitations of web technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-7
Combining native and web pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-8
How does it work? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-9
10.2. Combining native and web pages on Android . . . . . . . . . . . . . . . . . . . . . . . . . .10-11
Combining native and web pages on Android . . . . . . . . . . . . . . . . . . . . . . . . . . .10-12
Native on Android: Activity class and manifest definition . . . . . . . . . . . . . . . . . . .10-13
Native on Android: Receiving data from the web page . . . . . . . . . . . . . . . . . . . . .10-14
Native on Android: Returning control to the web page . . . . . . . . . . . . . . . . . . . . .10-15
Native on Android: Animating transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-16
Web page on Android: Invoking the native page . . . . . . . . . . . . . . . . . . . . . . . . .10-17
10.3. Combining native and web pages on iOS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-19
Combining native and web pages on iOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-20
Native on iOS: UIViewController subclass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-21
Native on iOS: Receiving data from the web page . . . . . . . . . . . . . . . . . . . . . . . .10-22
Native on iOS: Returning control to the web page . . . . . . . . . . . . . . . . . . . . . . . .10-23
Native on iOS: Animating web to native transitions . . . . . . . . . . . . . . . . . . . . . . .10-24
Web page on iOS: Invoking the native page . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-25
Web page on IOS: Receiving data from the native page . . . . . . . . . . . . . . . . . . .10-26
Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-27
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-28
Checkpoint answers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-29
Exercise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-30
Unit 11. Using Worklight native APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-2
Worklight native API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-3
Why use native API capabilities? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-4
Creating a Worklight native API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-5
11.1. Android native API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-7
Android native API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-8
Android native API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-9
Editing wlclient.properties (Android) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-10
Configure an Android native application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-12
Initializing the WLClient - Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-13
MyConnectListener - Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-14
Invoking a procedure - Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-15
Processing a response: Android - MyInvokeListener . . . . . . . . . . . . . . . . . . . . . .11-16
Processing a response: Android - MyConnectListener . . . . . . . . . . . . . . . . . . . . .11-17
xiv

V8.1
Student Notebook
TOC
11.2. iOS native API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

iOS native API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iOS native API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Editing worklight.plist (iOS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configure an iOS native application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Initializing the WLClient - iOS (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Invoking a procedure - iOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Processing a response: iOS - MyInvokeListener . . . . . . . . . . . . . . . . . . . . . . . .
Checkpoint questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Checkpoint answers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11-19
11-20
11-21
11-22
11-24
11-25
11-26
11-27
11-28
11-29
11-30
11-31
11-32
Unit 12. Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1

Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3
Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-4
Authentication sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-6
Authentication entities: challenge handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-7
Authentication entities: authenticator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-8
Authentication entities: login module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-9
Authentication entities: authentication realms . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-10
Authentication entities: security tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-11
Authentication concepts and entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-12
Defining realms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-16
Defining login modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-17
Defining authenticators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-18
Defining security tests (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-20
Defining security tests (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-21
webSecurityTest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-22
mobileSecurityTest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-23
customSecurityTest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-24
Protecting adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-25
Protecting applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-26
Protecting static resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-28
12.1. Adapter-based authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-29
Adapter-based authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-30
Adapter-based authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-31
Adapter-based authentication process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-32
Configuring a realm on authenticationConfig.xml . . . . . . . . . . . . . . . . . . . . . . . . 12-33
Configuring a login module on authenticationConfig.xml . . . . . . . . . . . . . . . . . . 12-34
Configuring authenticationConfig.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-35
Server-side authentication: components overview . . . . . . . . . . . . . . . . . . . . . . . 12-36
Server-side authentication components (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . 12-37
Contents
xv
Student Notebook
Server-side authentication components (2 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . .12-38

Server-side authentication components (3 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . .12-39
Invoking the protected function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-41
Client-side authentication : HTML AppDiv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-42
Client-side authentication : HTML AuthDiv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-43
Client-side authentication : challengeHandler . . . . . . . . . . . . . . . . . . . . . . . . . . .12-44
More challengeHandler functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-45
Creating client-side authentication components (8 of 11) . . . . . . . . . . . . . . . . . . .12-46
Create the Handler function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-47
Binding the AuthSubmitButton to a function . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-48
12.2. Custom login modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-49
Custom login modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-50
Session scope and additional modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-51
Custom authenticator overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-52
Configuring authenticationConfig.xml (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-53
Configuring authenticationConfig.xml (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-54
Authenticator API (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-55
Authenticator API (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-56
Creating a custom Java authenticator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-57
Server library dependency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-58
Custom Java Authenticator: init() and clone() . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-59
Creating a custom Java Authenticator: overview . . . . . . . . . . . . . . . . . . . . . . . . .12-60
Custom Java Authenticator: processRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-61
processRequest: verify URL and credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-62
processRequest: authenticationData object . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-63
processRequest: problem response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-65
processRequest: authentication not needed . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-66
processRequest: credentials required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-67
The login module API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-68
Creating a custom Java login module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-69
Login module: init and clone methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-70
Login module: login method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-71
Login module: createIdentity method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-72
Login module: logout and abort methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-73
Examining the Result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-74
12.3. WebSphere LTPA-based authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-75
WebSphere LTPA-based authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-76
WebSphere LTPA-based authentication introduction . . . . . . . . . . . . . . . . . . . . . .12-77
Understanding server-side authentication options . . . . . . . . . . . . . . . . . . . . . . . .12-78
Server-side authentication options: option 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-79
Server-side authentication options: option 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-80
Understanding server-side authentication options . . . . . . . . . . . . . . . . . . . . . . . .12-81
Worklight invokes WAS security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-82
Authentication through WebSphere Application Server . . . . . . . . . . . . . . . . . . . .12-83
Server-side authentication options: summary . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-84
Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-85
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-86
xvi

V8.1
Student Notebook
TOC
Unit 13. Push notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-1

Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2
What are push notifications? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3
Device support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-5
Notification architecture terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-6
Notification architecture: subscription (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-7
Sending notifications: overview (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-10
Sending notifications: overview ( of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-11
Sending notifications (1 of 4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-12
Subscription management: user subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-16
Subscription management: device subscription . . . . . . . . . . . . . . . . . . . . . . . . . 13-17
Notification API: server side (1 of 10) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-18
Notification API: server side (10 of 10) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-27
Notification API: client side (1 of 4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-28
Setup: Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-33
Setup: iOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-34
Setup: Windows Phone 8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-35
Edit application-descriptor.xml (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-36
Edit application-descriptor.xml (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-37
PushBackendEmulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-38
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-39
Checkpoint questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-40
Checkpoint (objective only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-42
Exercise 8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-44
Exercise objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-45
Unit 14. Device analytics reporting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Device analytics introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents
14-1
14-2
14-3
14-4
xvii
Student Notebook
Introducing reports and analytics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-5

Enabling raw data reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-6
Device analytics: raw data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-7
APP_ACTIVITY_REPORT table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-8
APP_ACTIVITY_REPORT ACTIVITY column . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-9
Device usage reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-10
activities_cube table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-11
Notification_report table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-12
proc_report table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-13
Summary: relationship of the tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-14
Processing interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-15
BIRT reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-16
BIRT reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-17
Installing BIRT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-18
Exploring BIRT in Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-19
Viewing reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-20
Report types: environment access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-21
Report types : daily visits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-22
Report types : unique devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-23
Checkpoint questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-24
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-25
Unit 15. Direct update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-2
What is direct update? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-3
The advantages of direct update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-4
The restrictions of direct update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-5
Version detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-6
Direct update: distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-7
Disabling old app versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-8
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-10
Unit 16. Migrating an application from development to production . . . . . . . . . . . .16-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-2
16.1. Overview of application management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-3
Overview of application management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-4
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-5
Steps in the process of remote deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-6
Architecture of deployment (1 of 6) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-7
Architecture of deployment (4 of 6) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-10
16.2. Worklight Apache Ant utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-13
xviii Mobile Application Development with IBM Worklight V6
V8.1
Student Notebook
TOC
Worklight Apache Ant utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Worklight Apache Ant utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Apache Ant basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding a reference to Worklight Ant jar file . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Ant task: application builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Ant task: application deployer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.3. IBM Worklight Server installation and configuration overview. . . . . . . . . . . . . .
IBM Worklight Server installation and configuration overview . . . . . . . . . . . . . . .
Worklight Server overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Worklight Server runtime architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IBM Worklight Server installation: Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring Worklight Server resources in WebSphere Application Server . . . .
16.4. Application migration: Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Application migration: Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Application migration overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Application migration process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.5. Application migration: Preparing your application . . . . . . . . . . . . . . . . . . . . . . .
Application migration: Preparing your application . . . . . . . . . . . . . . . . . . . . . . . .
Adjusting the worklight.properties file: Database settings . . . . . . . . . . . . . . . . . .
Adjusting the worklight.properties file: Server access settings . . . . . . . . . . . . . .
Adjusting configuration files: Best practice . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Building the project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.6. Application migration: Deploying your application . . . . . . . . . . . . . . . . . . . . . . .
Application migration: Deploying your application . . . . . . . . . . . . . . . . . . . . . . . .
Deploying the applications Worklight server WAR file . . . . . . . . . . . . . . . . . . . .
Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Checkpoint answers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16-14
16-15
16-16
16-17
16-18
16-19
16-21
16-22
16-23
16-24
16-25
16-26
16-27
16-28
16-29
16-31
16-33
16-34
16-35
16-36
16-37
16-38
16-39
16-40
16-41
16-42
16-43
16-44
Unit 17. Shell development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1

Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-2
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-3
17.1. shell component concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-5
shell component concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-6
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-7
Architecture of a shell-based application (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . 17-9
Architecture of a shell-based application (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . 17-11
Creating a shell component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-12
shell component file structure (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-13
shell component file structure (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-14
shell-descriptor.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-16
17.2. Creating and using a shell component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-17
Creating and using a shell component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-18
Using the shell component in a test application (1 of 3) . . . . . . . . . . . . . . . . . . . 17-19
Using the shell component in a test application (2 of 3) . . . . . . . . . . . . . . . . . . . 17-20
Using the shell component in a test application(3 of 3) . . . . . . . . . . . . . . . . . . . . 17-21
Creating and using a shell bundle (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-22
Creating and using a shell bundle (2 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-23
Contents
xix
Student Notebook
Creating and using a shell Bundle (3 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17-24

17.3. Android shell development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17-25
Android shell development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17-26
Adding an Android environment to the shell component . . . . . . . . . . . . . . . . . . .17-27
Android shell component file structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17-28
Adding an Android environment to shell component . . . . . . . . . . . . . . . . . . . . . .17-29
Adding custom Java code to shell component (1 of 5) . . . . . . . . . . . . . . . . . . . . .17-31
Using the NativeEmptyApp Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17-36
Using the NativeEmptyApp Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17-37
17.4. iOS shell development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17-39
iOS shell development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17-40
Adding an iOS environment to shell component . . . . . . . . . . . . . . . . . . . . . . . . . .17-41
Adding Objective-C code to shell component (1 of 5) . . . . . . . . . . . . . . . . . . . . .17-45
Using the nativeEmptyApp Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17-50
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17-53
Unit 18. IBM Application Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-2
What is IBM Worklight Application Center? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-3
Typical scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-4
Application Center architecture (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-5
Application Center architecture (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-7
Application Center configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-8
Application Center user configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-9
Applications view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-10
Application details view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-11
Available applications view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-13
Feedback and rating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-14
Setting access control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-15
Registered devices view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-16
Application Center client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-17
Installing an application from the mobile client (1 of 2) . . . . . . . . . . . . . . . . . . . . .18-18
Installing an application from the mobile client (2 of 2) . . . . . . . . . . . . . . . . . . . . .18-19
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-20
Exercise 9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-21
xx

V8.1
Student Notebook
TOC
Unit 19. Course summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Course learning objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
19-1
19-2
19-3
19-4
19-5
Appendix 20. List of abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-1
Contents
xxi
Student Notebook
xxii

V8.1
Student Notebook
TMK
Trademarks
The reader should recognize that the following terms, which appear in the content of this
training document, are official trademarks of IBM or other companies:
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International
Business Machines Corp., registered in many jurisdictions worldwide.
The following are trademarks of International Business Machines Corporation, registered in
many jurisdictions worldwide:
AIX
Cast Iron
Domino
Lotus
Rational
AS/400
DB
FileNet
Notes
Redbooks
BigFix
DB2
Lotus Notes
PureApplication
WebSphere
Intel and Pentium are trademarks or registered trademarks of Intel Corporation or its
subsidiaries in the United States and other countries.
Lenovo and ThinkPad are trademarks or registered trademarks of Lenovo in the United
States, other countries, or both.
Linux is a registered trademark of Linus Torvalds in the United States, other countries, or
both.
Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other
countries, or both.
Java and all Java-based trademarks and logos are trademarks or registered trademarks
of Oracle and/or its affiliates.
VMware and the VMware "boxes" logo and design, Virtual SMP and VMotion are registered
trademarks or trademarks (the "Marks") of VMware, Inc. in the United States and/or other
jurisdictions.
Worklight is a trademark or registered trademark of Worklight, an IBM Company.
Other product and service names might be trademarks of IBM or other companies.
Trademarks
xxiii
Student Notebook
xxiv Mobile Application Development with IBM Worklight V6

V8.1
Student Notebook
pref
Course description
Mobile Application Development with IBM Worklight V6 - Early
Education
Duration: 4 days
Purpose
In this 4-day instructor-led course, you learn how to use IBM Worklight
V6 to develop mobile applications that run on an Android or iOS*
environment.
Audience
This course is designed for application developers who want to create,
manage, and deploy mobile applications to Android and iOS* mobile
environments by using IBM Worklight V6.
Prerequisites
Before taking this course, you should have experience in Java or web
development with Eclipse, and a good knowledge of the following web
technologies:
HTML5
JavaScript
Cascading Style Sheets (CSS) 3
Web UI frameworks, such as Dojo or jQuery
Representational State Transfer (REST) services
Web services
A basic knowledge of a mobile web UI framework, such as Dojo
Mobile, is helpful.
Objectives
After completing this course, you should be able to:
Identify a mobile application design type suitable for your
application
Develop a mobile application to run on an Android or iOS platform
using the IBM Worklight hybrid coding approach
Course description
xxv
Student Notebook
Use IBM Worklight client-side APIs for cross-platform portability

Use the Apache Cordova framework to access native device
functions
Use IBM Worklight server-side APIs for back-end integration
Include the Dojo Mobile, jQuery Mobile or Sencha Touch UI
frameworks in an application
Secure a mobile application using different IBM Worklight
authentication techniques
Manage application updates and versions
Curriculum relationship
VU506 Mobile Application Development with IBM Worklight V6 Early Education (online)
ZU506 Mobile Application Development with IBM Worklight V6 Early Education (self-paced)
xxvi Mobile Application Development with IBM Worklight V6

V8.1
Student Notebook
pref
Agenda
Day 1
Welcome
Unit 1 - Mobile overview
Unit 2 - Designing mobile solutions
Unit 3 - Introduction to IBM Worklight V6
Unit 4 - Overview of Worklight Studio
Exercise 1- Installing IBM Worklight Studio and developing your first
application
Unit 5 - IBM Worklight client-side development: Core APIs
Day 2
Exercise 2 - Exploring client-side core APIs
Unit 6 - IBM Worklight client-side development: Local storage APIs
Exercise 3 - Exploring local storage APIs
Unit 7 - Working with UI frameworks
Unit 8 - Apache Cordova
Exercise 4 - Using Apache Cordova to access native device functions
Unit 9 - Worklight integration adapters
Day 3
Exercise 5 - Developing a Worklight integration adapter
Unit 10 - Native and web page integration
Exercise 6 - Combining native and web pages
Unit 11 - Using Worklight native APIs
Unit 12 - Security
Exercise 7 - Securing an application
Unit 13 - Push notification
Agenda
xxvii
Student Notebook
Day 4
Exercise 8 - Exploring the push notification API
Unit 14 - Device analytics reporting
Unit 15 - Direct update
Unit 16 - Migrating an application from development to production
Unit 17 - Shell development
Unit 18 - IBM Worklight Application Center
Exercise 9 - Exploring the Application Center
xxviii Mobile Application Development with IBM Worklight V6

V8.1
Student Notebook
Uempty
Unit 1. Mobile overview

What this unit is about
This unit explains the challenges of mobile development and
describes how IBM mobile solution offerings address them. In
particular, you learn about the IBM Mobile Foundation offering, which
has IBM Worklight V6.0 at its core, and its value-proposition.
What you should be able to do

After completing this unit, you should be able to:
Explain the challenges of mobile application development,
management, and security
Describe the goal of IBM mobile solution offerings
Identify IBM Worklight V6 as a key part of the mobile solutions
strategy that IBM offers
How you will check your progress

Checkpoint
References
IBM MobileFirst strategy http://www.ibm.com/mobilefirst/us/en/
Whitepaper: The New Workplace - Are you Ready?
ftp://public.dhe.ibm.com/software/info/mobile/CIW03077USEN.pdf
The 2012 IBM Tech Trends Report
ftp://public.dhe.ibm.com/common/ssi/ecm/en/xie12346usen/XIE12346
USEN.pdf

1-1
Student Notebook
Unit objectives
Describe what it means to become a mobile enterprise
Describe the goal of IBMs mobile solution offerings
Identify IBM Worklight V6.0 as a key part of IBMs mobile solutions
strategy
Copyright IBM Corporation 2013
Figure 1-1. Unit objectives
WU5061.1
Notes:
1-2

V8.1
Student Notebook
Uempty
Topics
Becoming a mobile enterprise
Challenges of mobile application development, management, and
security
Types of mobile applications
Overview of IBM mobile strategy
IBM Mobile Foundation V6.0
Figure 1-2. Topics
WU5061.1
Notes:

1-3
Student Notebook
1-4

V8.1
Student Notebook
Uempty
1.1. Becoming a mobile enterprise

1-5
Student Notebook
Becoming a mobile
enterprise
Figure 1-3. Becoming a mobile enterprise
WU5061.1
Notes:
1-6

V8.1
Student Notebook
Uempty
Why go mobile?
Take advantage of new opportunities present with mobile
Attract new customers through mobile
Deliver engaging apps; delight customers
Increase collaboration & productivity among employees
Provide a consistent brand experience across channels
Optimize for multiple devices and BYOD*
Use technologies to meet increased demands
Gain new insights that you can get only through mobile
*Bring your own device

Figure 1-4. Why go mobile?
WU5061.1
Notes:
Note
*BYOD: bring your own device.

1-7
Student Notebook
Demand for mobility

As of 2013, there are 4 billion mobile phones; 9.6
billion connected devices (the Internet of things)
1 billion smart phones
3 billion SMS enabled
90 percent of all phones in Africa are mobile

18 million people use mobile phones as a bank
Mobility can be business-to-consumer (B2C) or
business-to-employee (B2E)
Also B2B, C2C, and many others
B2C: Offers easier purchase and support options, online
banking, and so forth
B2E: Provides access to internal systems for employees
Over the next two years, nearly 70 percent of

organizations are increasing their investments in
mobile technology*
Figure 1-5. Demand for mobility
WU5061.1
Notes:
*The 2012 IBM Tech Trends Report
ftp://public.dhe.ibm.com/common/ssi/ecm/en/xie12346usen/XIE12346USEN.pdf
1-8

V8.1
Student Notebook
Uempty
Mobile platforms
Android emerged as the main platform for mobile development,
followed by iOS*
Android
74.4%
iOS
18.2%
Windows Phone
2.9%
BlackBerry
3%
Others
1.6%
Figure 1-6. Mobile platforms
WU5061.1
Notes:
*Gartner report - Market Share Analysis: Mobile Phones, Worldwide, 1Q13.
http://www.gartner.com/document/2482415?ref=QuickSearch&sthkw=G00252860

1-9
Student Notebook
1-10 Mobile Application Development with IBM Worklight V6

V8.1
Student Notebook
Uempty
1.2. Challenges of mobile application development,

management and security

1-11
Student Notebook
Challenges of mobile
application
development,
management, and
security
Figure 1-7. Challenges of mobile application development, management and security
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Considerations for mobile (1 of 2)

User experience
Different mobile platforms have different capabilities
It is tempting to use a highest-common-factor approach where only those
elements common to all platforms are used
Native, web, hybrid: which can be developed in the least time?
Native gives the best performance but
It limits the results to one platform
Development requires specialized knowledge
Authentication and security

Smaller devices are more portable and therefore can be lost or stolen more
easily
The device might be logged on to a secure internal company area
The device might have sensitive data that was decrypted at the moment the
device is lost
Figure 1-8. Considerations for mobile (1 of 2)
WU5061.1
Notes:

1-13
Student Notebook
Considerations for mobile (2 of 2)

Manage mobile applications
The applications sit on remote devices: how to update them to new versions?
An application might no longer have backend support: how to warn the user?
If a business-to-employee application is the preferred way for the

employee to interact with the company who pays for, and owns, the
device?
Traditionally, the company owns the laptop that the employee uses
The latest trend is BYOD: bring your own device
Development lifecycles are more complicated

There are now new issues to deal with:
The number of platforms that must be accommodated is greater than before
The download of given information might depend on the geographic location of
the device
Figure 1-9. Considerations for mobile (2 of 2)
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Advantages of mobile communication

B2C
Increased ease for the customer to do business such as banking, or stock
trading
B2E
Mobile access makes employees more productive
What do you think?
M2M
Machine to machine
For example:
Truck on the road transmits and receives information from a central point
Car sends an automatic request for assistance in case of accident or driver
illness
Airplane exchanges information with ground computers
Figure 1-10. Advantages of mobile communication
WU5061.1
Notes:

1-15
Student Notebook
Characteristics of mobile interactions

Usually short and focused
Get on, get information, get off
Screen display is compact, and so the user interface must be intuitive

Minimal typing should be necessary
Devices are most often touch based, and so conveniences such as
hover and the pointing finger are not available
Many applications can function even when the user is out of wireless
coverage
A cell phone can operate even if the user is moving, but not if they move out of
range
A wireless notebook connection is specific to one location (which might be an
entire building)
Figure 1-11. Characteristics of mobile interactions
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
1.3. Types of mobile applications

1-17
Student Notebook
Types of mobile
applications
Figure 1-12. Types of mobile applications
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
The choice
Web application
HTML5
CSS3
JavaScript
Native
code
HTML5
CSS3
JavaScript
Native
code
Hybrid
application
Native
application
Figure 1-13. The choice
WU5061.1
Notes:

1-19
Student Notebook
Development approaches
Web
application
Mobile web
application
Desktop and
mobile using
open standards
programming
model
Targets mobile
devices that
use open
standards web
client
programming
model
No devicespecific
function
Offline
capabilities
Hybrid mobile
application
Mobile only
Application runs
on the device
Uses of an open
web client model
with a JavaScript
bridge to access
native device
features
<--Mobile browser execution-->
Native mobile
application
Mobile using
only native
languages
Native
appearance,
device
capabilities, and
performance
<--App store download-->
Richer presentation possibilities

Greater portability
Increasing maintenance costs
Figure 1-14. Development approaches
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Native compared to hybrid applications

Native:
Available only through the App Store for a particular platform
Development technologies specific to the device
Requires a licensing agreement
Hybrid:
Uses web technologies
HTML5 for the layout
CSS3 for the style
JavaScript for functionality and to access native features of the device
For example, camera, vibrate, location, events
Some knowledge of the specific platform is needed
Distributed through an App Store
Requires a licensing agreement
Figure 1-15. Native compared to hybrid applications
WU5061.1
Notes:

1-21
Student Notebook
Web standards
HTML5
A major update from HTML 4.2
Aimed at standard web applications and offline applications
Greatly extended audio and video capabilities
Canvas
Form validation
CSS3
The focus is on putting style information into the Cascading Style Sheet rather
than into the page
Many html style attributes are deprecated in favor of using CSS
JavaScript
Standard way to define functions for an interactive web page, plus some new
features targeting mobile:
Geolocation
Web storage
Figure 1-16. Web standards
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
SOA to mobile
SOA
BPM
JEE
Enterprise
services
Business
services
RESTful
services
Business
process
JAX-RS
Components
Java EE
Process
data
Application
data
Mobile
web 2.0
Services
Enterprise
data
Figure 1-17. SOA to mobile
WU5061.1
Notes:

1-23
Student Notebook

V8.1
Student Notebook
Uempty
1.4. Overview of IBM mobile strategy

1-25
Student Notebook
Overview of IBM mobile

strategy
Figure 1-18. Overview of IBM mobile strategy
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
IBM MobileFirst
Mobile is becoming the first point of contact between an individual and
an organization
Mobile interactions must be instant, seamless, and insightful
The systems that users interact with must be designed around mobile
first
Figure 1-19. IBM MobileFirst
WU5061.1
Notes:

1-27
Student Notebook
IBM MobileFirst portfolio

Provides end-to-end solutions
Strategy and design services
Platform:
IBM Worklight
IBM Mobile Development Lifecycle Solution
Management:
IBM Endpoint Manager for Mobile Devices
Mobile Enterprise Services for Managed Mobility
Security
Analytics:
IBM Tealeaf CX Mobile
IBM Digital Analytics
Development and integration services
Figure 1-20. IBM MobileFirst portfolio
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
1.5. IBM Mobile Foundation V6.0

1-29
Student Notebook
IBM Mobile Foundation

V6.0
Figure 1-21. IBM Mobile Foundation V6.0
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
IBM MobileFirst platform

IBM Worklight
IBM WebSphere Cast Iron
IBM MessageSight
IBM Rational Test Workbench
IBM Web Experience Solutions
IBM Lotus Domino Designer
IBM WebSphere MQ
Figure 1-22. IBM MobileFirst platform
WU5061.1
Notes:
IBM Mobile Foundation Enhanced
Delivers a range of application development, connectivity and management capabilities.
Bundled with IBM Worklight, IBM WebSphere Cast Iron, and IBM Endpoint Manager for
Mobile Devices.
IBM Worklight Enhanced
An open, mobile application platform for smartphones and tablets. Develop, run and
manage HTML5, hybrid, and native applications.
IBM WebSphere Cast Iron
An integration framework that enables you to rapidly connect your hybrid world of public
clouds, private clouds, and on-premise applications.
IBM MessageSight
Messaging appliance specifically designed for machine-to-machine (M2M) and mobile
environments that is optimized for message throughput.

1-31
Student Notebook

Deliver faster and improve team productivity with collaborative, integrated capabilities for
mobile app development.
IBM Rational Test Workbench
Automated testing for high-quality mobile apps.
IBM Web Experience Solutions
Create personalized, content-rich multichannel experiences for customers and employees
easily and cost-effectively.
IBM Lotus Domino Designer
Provides a Web and mobile app development platform that enables IBM Lotus Notes
applications to be used with browser clients on mobile devices.
IBM WebSphere MQ
A universal messaging backbone, enables rapid, reliable, and secure transport of
messages and data between applications, systems, services and extended devices.

V8.1
Student Notebook
Uempty

Brings together key mobile capabilities into a single integrated package
that includes:
IBM Worklight: An application platform for smartphones and tablets that helps
organizations to develop, run and manage HTML5, hybrid and native mobile
applications
IBM Endpoint Manager: Built on BigFix * technology that addresses the issues of
security, complexity, and BYOD policies that are required to support an
increasingly mobile workforce
WebSphere Cast Iron Hypervisor Edition: An integration framework that enables
companies to rapidly connect their hybrid world of public clouds, private clouds,
and on-premise applications
Figure 1-23. IBM Mobile Foundation
WU5061.1
Notes:
Worklight was acquired by IBM in 2011.
BigFix was the name of a company acquired by IBM in July 2010.
Cast Iron was acquired by IBM in May 2010.

1-33
Student Notebook
IBM Worklight
Supports multiple mobile operating environments and devices by using
a single, shared code base
Standards-based platform
Build once, deploy to many platforms
Faster deployment across multiple channels
Eases connectivity and synchronization with enterprise data,

applications, and cloud services
Provides security at the device, application, and network layer
Allows governance of mobile app portfolio from a central interface
Application distribution and version management
Direct update
Manage push notifications
Monitor usage through analytics and reporting
High availability and private cloud deployment options (WebSphere Application
Server, PureApplication Systems)
Figure 1-24. IBM Worklight
WU5061.1
Notes:
Supports multiple mobile operating environments and devices with the simplicity of
a single, shared code base
Standards-based platform allows you to leverage the growing ecosystem of third-party
libraries and frameworks
Build once, deploy to many platforms
Create mobile and omni-channel applications more quickly using any combination of
HTML5, native and hybrid development methods
Support Android, iOS, Blackberry, Windows Phone, Windows 8, Java ME, mobile Web
and desktop Web environments
Runtime skins optimize the user experience for hundreds of different devices
Easily connect and synchronize with enterprise data, applications and cloud
services

V8.1
Student Notebook
Uempty
Connect to back-end data, applications and cloud services more easily, making the
most of standards-based technologies
Transform enterprise data into mobile-friendly, JSON format that can be synchronized,
encrypted, and stored locally on mobile devices
Leverage advanced mobile middleware for caching, data synchronization, and
end-to-end encryption of data
Safeguard mobile security at the device, application, and network layer
Protect sensitive information from malware attacks and device theft
Ensure timely propagation and adoption of critical security updates to the entire install
base
Enforce multi-factor authentication, single sign-on (SSO) and device SSO while
integrating with existing authentication and security approaches
Enable secure delivery and operation of mobile apps for employee-owned devices or
device types not allowed on the corporate network
Manage approved and rejected devices for controlled mobile-application installation
and remote application disablement
Govern their mobile app portfolio from one central interface.
Govern app distribution and version management
Direct Update for enforced version upgrades
Manage push notifications through a single, central interface
Create a secure, hardened shell to enforce common branding, security and data access
standards
Monitor usage through analytics and usage reporting
High availability and private cloud deployment options (WebSphere Application Server
Network Deployment, PureApplication Systems)

1-35
Student Notebook
WebSphere Cast Iron Hypervisor Edition

Cloud and Software as a Service (SaaS) to on-premise application and
mobile application integration in days
Installation on your organization's preferred hardware to conform to
your data center's virtualization strategy
A graphical, configuration-not-coding interface approachrather than
custom coding, on-demand tooling, or traditional middlewareto help
you integrate applications quickly and simply
Reduced error recovery procedures (ERP) licensing costs by
eliminating the need for cloud users to log in to back-office applications
Available in Development, Enterprise and Standard editions, with fixed
term or license options
Figure 1-25. WebSphere Cast Iron Hypervisor Edition
WU5061.1
Notes:
IBM Redbooks - Hybrid Cloud Integration and Monitoring with WebSphere Cast Iron
https://www14.software.ibm.com/webapp/iwm/web/signup.do?source=swg-castiron&S_PK
G=ov11090&S_TACT=109KA5IW&S_CMP=web_opp_ibm_ws_appint_hero_castiron-hype
r

V8.1
Student Notebook
Uempty
IBM Endpoint Manager for Mobile Devices

Helps you address the issues of security, complexity, and bring your
own device (BYOD) policies that challenge support for an increasingly
mobile workforce
Safeguards enterprise data with advanced security and compliance
features
Provides enterprise visibility with a consolidated inventory of employeeand corporate-owned devices
Provides a unified management infrastructure by using a single
platform to manage all your enterprise devices
Figure 1-26. IBM Endpoint Manager for Mobile Devices
WU5061.1
Notes:
IBM Endpoint Manager for Mobile Devices provides a completely integrated approach for
managing, securing, and reporting on laptops, desktops, servers, smartphones, tablets,
and even specialty devices such as point-of-sale terminals. This provides customers with
unprecedented real-time visibility and control over all devices employees use in their daily
job functions; reducing costs, increasing productivity, and improving compliance.

1-37
Student Notebook
Checkpoint questions
1. Which mobile platforms are the top 2?
2. What is the difference between a web application, a hybrid
application, and a native application?
3. List the three parts of IBM Mobile Foundation
Figure 1-27. Checkpoint questions
WU5061.1
Notes:
Write your answers here:

V8.1
Student Notebook
Uempty
Unit summary
Having completed this unit, you should be able to:
Describe what it means to become a mobile enterprise
Describe the goal of IBMs mobile solution offerings
Identify IBM Worklight V6.0 as a key part of IBMs mobile solutions
strategy
Figure 1-28. Unit summary
WU5061.1
Notes:

1-39
Student Notebook
Checkpoint answers
1. Of the six mobile platforms that are mentioned at the beginning of this
module, which are the top 2?
Android, iOS
2. What is the difference between a web application, a hybrid
application, and a native application?
Web uses only HTML5, CSS, JavaScript; native uses coding specific
to the device; hybrid mixes the two.
3. List the three parts of IBM Mobile Foundation
Worklight, Endpoint Manager, Cast Iron
Figure 1-29. Checkpoint answers
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Unit 2. Designing mobile solutions

This unit describes the different approaches used for building mobile
applications. It explains the available technology and design options,
and identifies the situations appropriate for each option.

Compare the advantages and disadvantages of different mobile
application designs
Identify a mobile application design suitable for an application

Checkpoint
References
IBM Worklight V6 documentation:
http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp
Whitepaper - Native, web or hybrid mobile-app development ftp://public.dhe.ibm.com/software/pdf/mobile-enterpris
e/WSW14182USEN.pdf

2-1
Student Notebook
Unit objectives
application designs
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
2-2

V8.1
Student Notebook
Uempty
Topics
Approaches to mobile design
Comparison of mobile application designs
Choosing the right approach
Figure 2-2. Topics
WU5061.1
Notes:

2-3
Student Notebook
Three approaches
Native
application
Web
application
Hybrid
application
100101010101
110100010100
100101011101
000100010010
Mobile
browser
WEB CODE
<!DOCTYPE ht
<html>
<head>
<title>Web App
</title></head>
<body onload =
native
container
WEB CODE
<!DOCTYPE ht
<html>
<head>
Device APIs
Device APIs
Figure 2-3. Three approaches
WU5061.1
Notes:
All of these approaches are commonly used, but this course concentrates on the third,
hybrid approach. This is what Worklight is principally intended to develop.
2-4

V8.1
Student Notebook
Uempty
Web, hybrid, native

The decision as to which mobile strategy to develop is based on many
parameters:
Budget
Timeframe
Target audience
Required functionality
Each approach has advantages and disadvantages

The challenge is to balance the pros and cons
This module does not identify any recommended approach but looks at
the reasons for each, and lists the good and the less good
Figure 2-4. Web, hybrid, native...
WU5061.1
Notes:
There is no particular order to the list given on the slide. Maybe the target audience is the
governing factor because the application is intended for employees, or is specifically
intended for BlackBerry users; maybe it is the timeframe constraint that overrides
everything else because the application must be available next week and there are no
programmers in-house with experience enough in native technologies. The choice of
strategy is going to be made on a case by case basis.
IBM Whitepaper Native, web or hybrid mobile-app development ftp://public.dhe.ibm.com/software/pdf/mobile-enterprise/WSW14182USEN.pdf

2-5
Student Notebook
2-6

V8.1
Student Notebook
Uempty
2.1. Approaches to mobile design

2-7
Student Notebook
Approaches to mobile
design
Figure 2-5. Approaches to mobile design
WU5061.1
Notes:
2-8

V8.1
Student Notebook
Uempty
Native applications
Binary executable file that is stored locally on the device
Usually downloaded from an App Store
Apple App Store
Android Market, Google Play
BlackBerry App World
And others
Specific to a type of device

After downloading, the application interfaces directly with the device
operating system
The application can access all native APIs of the device
Figure 2-6. Native applications
WU5061.1
Notes:
Native apps have binary executable files that are downloaded directly to the device and
stored locally. The installation process can be initiated by the user or, in some cases, by the
IT department of the organization. The most popular way to download a native app is by
visiting an app store, such as Apples App Store, Androids Marketplace or BlackBerrys
App World, but other methods exist and are sometimes provided by the mobile vendor.
Once the app has been installed on the device, the user launches it like any other service
the device offers. Upon initialization, the native app interfaces directly with the mobile
operating system, without any intermediary or container. The native app is free to access
all of the APIs that are made available by the OS vendor and, in many cases, has unique
features and functions that are
typical of that specific mobile OS.
IBM Whitepaper Native, web or hybrid mobile-app development ftp://public.dhe.ibm.com/software/pdf/mobile-enterprise/WSW14182USEN.pdf

2-9
Student Notebook
Creating a native application

The source code for the application is written in a high-level language:
Apple iOS
Objective-C, C, C++
Android:
Java
BlackBerry: Java
Windows Phone: C#, VB,.NET
The source is compiled into an executable binary file

The OS vendor usually provides the tools to do this
Called the Software Development Kit (SDK)
The SDK is platform-specific
Apple iOS:
Android:
Xcode
Android SDK
BlackBerry:
Windows Phone:
BB Eclipse plug-in
Visual Studio, Windows Phone Development Tools
Figure 2-7. Creating a native application
WU5061.1
Notes:
Native apps can interact with and take advantage of operating system features and other
software that is typically installed on that platform. A native app is built for a particular
device and its operating system, so it has the ability to use device-specific hardware and
software, such as a global positioning system (GPS) and camera. This can be viewed as
an advantage for native apps over Web apps. However, there are ways of accessing native
functionality from within an hybrid app. This technique is described later.

V8.1
Student Notebook
Uempty
Mobile web applications HTML5

While HTML4.2 was a page display language, HTML5 is closer to
being a complete environment for browser-based applications
Some new things available in HTML5:
Advanced UI components
Access to rich media types
Geolocation services
Offline availability
New audio capabilities
A mobile-optimized website can detect when the client is a Smartphone

and respond with an appropriate page
Figure 2-8. Mobile-web Applications - HTML5
WU5061.1
Notes:
HTML 5 improves on its predecessors in a number of ways. It can be written with different
markup syntaxes (HTML and XML), it introduces new, simpler markup for things that were
very complex in earlier versions (audio, for example), and it is being developed specifically
with a view to being used in mobile environments.
Modern mobile devices consist of powerful browsers that support many new HTML5
capabilities, Cascading Style Sheets 3 (CSS3) and advanced JavaScript. With recent
advancements on this front, HTML5 signals the transition of this technology from a
page-definition language into a powerful development standard for rich, browser-based
applications.
A few examples of the potential of HTML5 include advanced UI components, access to rich
media types, geolocation services and off line availability. Using these features and many
more that are under development, developers are able to create advanced applications,
using nothing but web technologies.

2-11
Student Notebook
Mobile web applications CSS3

Cascading Style Sheets were originally intended to separate
presentation elements from content elements
CSS3 divides the specification into modules. Four were published as
formal recommendations:
Media Queries
Used to tailor output to a device or range of devices
Namespaces
Selectors can be defined by namespace and local name
Selectors
Query the DOM by tag name, attributes, id
Color
Including transparency
Level 3 is still in the process of being defined
Figure 2-9. Mobile-web Applications - CSS3
WU5061.1
Notes:
This will of course change over time. The number four is correct as of June, 2012.

V8.1
Student Notebook
Uempty
Mobile web applications JavaScript

Client-side JavaScript adds behavior to web content
Typically works with the Document Object Model to interact with the
presentation of a page
Worklight Studio automatically creates a JavaScript file with the same
name as the application
A number of frameworks use JavaScript libraries and target mobile
applications:
jQuery
Sencha
Dojo Mobile
Figure 2-10. Mobile-web Applications - JavaScript
WU5061.1
Notes:

2-13
Student Notebook
Mobile web applications mobile websites

Feature
Mobile web app
Tools and
knowledge
Mobile website
HTML, CSS, JavaScript
Execution
Installed shortcut, started

like a native app.
URL
User experience
Interactive UI
Navigational UI between
pages that display static
data
Performance
UI logic is local. Responsive

and accessible offline
Code executed on server:

network-dependent
performance
Figure 2-11. Mobile web applications - mobile web sites
WU5061.1
Notes:
The point here is that the mobile device gets everything it needs, then works essentially
off-line. The standard web page is generated largely on the server side, then downloaded.

V8.1
Student Notebook
Uempty
Hybrid applications (1 of 2)
There are many things in a web design that are common to renderings
on any platform
For example, a background color or image, or a particular font
It is not good design practice to repeat the coding for each platform
Maintenance becomes an issue
The hybrid approach combines native development and web

technology
This approach requires a bridge between the native environment and
the web environment
Apache Cordova is one solution that is readily available developers
can use it instead of creating their own bridge
Figure 2-12. Hybrid applications (1 of 2)
WU5061.1
Notes:
The hybrid approach combines native development with web technology. Using this
approach, developers write significant portions of their application in cross-platform web
technologies, while maintaining direct access to native APIs when required.
The native portion of the application uses the operating system APIs to create an
embedded HTML rendering engine that serves as a bridge between the browser and the
device APIs. This bridge enables the hybrid app to take full advantage of all the features
that modern devices have to offer.
App developers can choose between coding their own bridge or taking advantage of
ready-made solutions such as PhoneGapopen-source library that provides a uniform
JavaScript interface to selected device capabilities that is consistent across operating
systems.
Apache Cordova was previously known as PhoneGap. The code was contributed to the
Apache Software Foundation.
Apache Cordova is discussed in detail later in this course.

2-15
Student Notebook

V8.1
Student Notebook
Uempty
Hybrid applications (2 of 2)
The web part of a hybrid application can be
A web page that is stored on a server and accessed like any traditional web
page
A package of files that are stored locally on a device
HTML, JavaScript, CSS, media files, text files, and so forth
Server storage allows the developer to modify the page code without
having to go through the process of submission that is required for an
App Store
However, offline availability is not an option if the page must be accessed from a
server
Local storage is more flexible and can offer better performance

However, remote update is not an option
Figure 2-13. Hybrid applications (2 of 2)
WU5061.1
Notes:
The native portion of the app can be developed independently, but some solutions in the
market provide this type of a native container as part of their product, thus empowering the
developer with the means to create an advanced application that utilizes all the device
features using nothing but web languages.
In some cases, a solution will allow the developer to use any native knowledge he or she
might have to customize the native container in accordance with the unique needs of the
organization.
The web portion of the app can be either a web page that resides on a server or a set of
HTML, JavaScript, CSS and media files, packaged into the application code and stored
locally on the device. Both approaches carry advantages and limitations. HTML code that
is hosted on a server enables developers to introduce minor updates to the app without
going through the process of submission and approval that some app stores require.
Unfortunately, this approach eliminates any off line availability,
as the content is not accessible when the device is not connected to the network. On the
other hand, packaging the web code into the application itself can enhance performance

2-17
Student Notebook
and accessibility, but does not accept remote updates. The best of both worlds can be
achieved by combining the two approaches. Such a system is
designed to host the HTML resources on a web server for f lexibility, yet cache them locally
on the mobile device for performance.

V8.1
Student Notebook
Uempty
2.2. Comparison of mobile application designs

2-19
Student Notebook
Comparison of mobile
application designs
Figure 2-14. Comparison of mobile application designs
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Native - advantages and disadvantages

Native code performs fast
Complete access mean that all device functions can be included in an
application
The critical disadvantage of pure native development is that the code is
not portable across platforms
Development effort might have to be repeated for each platform
Costly, time-consuming
Because each platform has a unique set of APIs, the developer must
be familiar with a wide range of languages
Or the company needs a wide range of specialized developers
Figure 2-15. Native - advantages and disadvantages
WU5061.1
Notes:
Scenarios for the native approach include:
Existing native skills
A single mobile OS
Native functionality
Rich UI requirements

2-21
Student Notebook
Web application advantages and disadvantages

Multi-platform support
Low cost of development
Runs in the browser, but has only limited access to the APIs of the
device through the browser
Scenaries for the web approach include:
Direct distribution
Pilot app
Visibility
Figure 2-16. Web application - advantages and disadvantages
WU5061.1
Notes:
The last point on the slide, the limited access to device APIs, may change in the future,
with advancements in HTML giving a better link between the web application and the
native APIs.
Scenaries for the web approach include:
Direct distribution
Pilot app
Visibility

V8.1
Student Notebook
Uempty
Hybrid applications
Multi-platform support
Medium cost of development
There might still be a need to code in a native device language
Not all device functionality is available

A bridge is needed to access native mobile device features and run
native code that uses JavaScript
Typically, Apache Cordova
Scenarios for the hybrid approach include:

Balancing the tradeoff
In-house skills
Future considerations
Figure 2-17. Hybrid applications
WU5061.1
Notes:
Scenarios for the hybrid approach include:
Balancing the tradeoff
In-house skills
Future considerations

2-23
Student Notebook
Comparison of features
Feature
Development
language
Native
Web
Hybrid
Native only
Web only
Native and web,

or web only
Code portability and

optimization
No
Access to devicespecific features
Yes
Take advantage of
web expertise
No
Yes
Advanced graphics
Yes
Some
Upgrade flexibility
Low (App Store)
Yes
Some, through
a bridge
Almost none
High
Medium (usually
App Store)
Figure 2-18. Comparison of features
WU5061.1
Notes:
This slide has to be viewed with a certain flexibility. Some shops may indeed have existing
expertise in a particular language (for example, Objective-C). The point is that in general, a
company will need to consider hiring or retraining in order to have the necessary expertise.
Likewise, the positioning of code portability, or advanced graphics, and so on, will change
with time.

V8.1
Student Notebook
Uempty
2.3. Choosing the right approach

2-25
Student Notebook
Choosing the right

approach
Figure 2-19. Choosing the right approach
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Scenario the native approach

An organization might have in-house expertise for a particular platform
For example, a company might issue an Android device to all
employees, and have developers who can code in Java for the Android
platform
The company would have a policy that the employee must use the issued
device. There is therefore no need to develop code for other platforms, or to
have common code
Some applications target a specific function that cannot be accessed in

any other way than natively
For example, Skype (VoIP)
For real-time responsiveness and complex user interface requirements,

the native approach is the only adequate solution
Games, for example
Figure 2-20. Scenario - the native approach
WU5061.1
Notes:
The next three slides give example scenarios for different approaches. Note that these
scenarios are not necessarily better, or more common, than others. As was stated
earlier in the presentation, factors such as budget, timeframe, target audience, or
required functionality will direct the decision as to what approach is best in a given
company.

2-27
Student Notebook
Scenario the web approach

An organization might want to control the distribution of its applications
internally, without having to submit them for approval through an App
Store
The application might begin as a pilot, just to prove a concept
A fully native application is more difficult to develop
Therefore, it takes longer and is more expensive
After the concept is finalized, the existiisng application can be either

adapted to native (rewritten) or can form the basis of a hybrid
application
This approach would build on the proven concept by adding native functionality
Figure 2-21. Scenario - the web approach
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Scenario the hybrid approach

An organization must create a mobile web presence rapidly
There is no particular need for fast response within the application
Native functionality is not required, or only slightly required
There will typically be in-house developers who are familiar with HTML,
CSS, and JavaScript
The development of a web application is therefore easy and efficient
Adding skills to bridge to native code is not difficult
The application can rapidly be distributed to all platforms, giving a good

return on investment
It can also be maintained easily
Figure 2-22. Scenario - the hybrid approach
WU5061.1
Notes:

2-29
Student Notebook
1. What are the three approaches for creating mobile web applications?
2. Which of these statements is not correct?
a)
b)
c)
A native application is specific to a platform

A web application is specific to a platform
A hybrid application might be specific to a platform
3. Name some of the new features of HTML5

4. True of false: A web page that is stored on a server can be part of a
mobile web application
5. True or false: A hybrid application combines HTML, JavaScript, and a
native language
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Unit summary
application designs
WU5061.1
Notes:

2-31
Student Notebook
Checkpoint answers
1. What are the three approaches for creating mobile web applications?
Native, web, hybrid
2. Which of these statements is not correct?

b)
A web application is specific to a platform
3. Name some of the new features of HTML5
Advanced UI components
Access to rich media types
Geolocation services
Offline availability
New audio capabilities
and others...
4. True of false: A web page that is stored on a server can be part of a

mobile web application
true
5. True or false: A hybrid application combines HTML, JavaScript, and a

native language
true
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Unit 3. Introduction to IBM Worklight v6.0

This unit introduces IBM Worklight V6.0 by describing its packaging
and component architecture.

Differentiate the IBM Worklight V6.0 product packages
Explain the IBM Worklight V6.0 component architecture

Checkpoint
References

3-1
Student Notebook
Unit objectives
WU5061.1
Notes:
3-2

V8.1
Student Notebook
Uempty
Topics
Component architecture
Code optimization
Client-side development
Server-side development
Secure authentication
Push notification
Direct update
Remote server application deployment
Device analytics reporting
Shell development
Application Center
Figure 3-2. Topics
WU5061.1
Notes:
Note: this module gives a general overview of these topics. They are discussed in depth in
further units.

3-3
Student Notebook
3-4

V8.1
Student Notebook
Uempty
3.1. IBM Worklight component architecture

3-5
Student Notebook
IBM Worklight
component
architecture
Figure 3-3. IBM Worklight component architecture
WU5061.1
Notes:
The first of the pages on component architecture sums up the five different parts of
Worklight and their relationship. Each part is discussed in more detail in the subsequent
pages.
You may want to bookmark the first slide, and refer back to it throughout the course as a
reminder of where the discussion is situated.
3-6

V8.1
Student Notebook
Uempty
Public/private App Stores
Backend and
Cloud services
Device
Runtime
Device
SDK
Application
Code
Worklight
Studio
Build Engine
Worklight components - overview
Worklight
Console
Worklight Server
App
Center
Backend
Version
Unified push
integration management notifications
Figure 3-4. Worklight components - overview
WU5061.1
Notes:
This slide shows the relationship between the five components of Worklight. Each of these
components is discussed briefly in this unit, and in depth in future units.

3-7
Student Notebook
Worklight Studio
HTML5, hybrid and native
coding
Optimization framework
Integrated device SDKs
3rd party library integration
Worklight
Studio
Build Engine
Plugin for Eclipse

Device
SDK
Public/private App Stores
Figure 3-5. Worklight Studio
WU5061.1
Notes:
With the file structure of IBM Worklight Studio, the optimization framework enables
developers to adjust applications to different mobile environments, while maximizing code
reuse. Common application code is shared among multiple environments;
environment-specific code that can overwrite or augment the commonly shared code is
then placed in separate folders. Application logic is consistent among the different
environments, while the user interface behaves natively.
Worklight Studio V6 plugin can be installed on Eclipse Juno, Eclipse IDE for Java EE
Developers, or on Eclipse Juno, Eclipse Classic 4.2.2.
3-8

V8.1
Student Notebook
Uempty
Worklight Studio plug-in

There are two ways to install the plug-in:
Download it as a compressed file and install it as an archive
Install it directly from the web through Eclipse
Figure 3-6. Worklight Studio plug-in
WU5061.1
Notes:
1. Select Install New Software
2. Click Add
3. Type a name and the URL of the download site.
The compressed file can be downloaded from
http://public.dhe.ibm.com/ibmdl/export/pub/software/mobile-solutions/wor
klight/.
To install through Eclipse, use the url
http://public.dhe.ibm.com/ibmdl/export/pub/software/mobile-solutions/wor
klight/wdeupdate/.

3-9
Student Notebook
Worklight Studio design perspective
2
3
Figure 3-7. Worklight Studio design perspective
WU5061.1
Notes:
1. An icon is added to the perspective for fast access to Worklight artifacts.
2. The Project is created with a framework of folders and files for the Worklight elements.
This framework is discussed in detail in the next slides.
3. The perspective includes a Rich Page Editor for creating and editing html pages, as
well as .

V8.1
Student Notebook
Uempty
Shell components and inner applications

Architecture:
The shell consists of native and web code
Inner applications consist of web code only
The shell provides access

to native device capabilities
The shell can restrict inner
applications from accessing
unsanctioned functions
Both native and JavaScript
functions
Figure 3-8. Shell components and inner applications
WU5061.1
Notes:
This course concentrates on hybrid development.
Inner applications can only be developed as a part of a shell component. The shell
component would be created first and provided to the developers of the inner application.
The intention is to create a common basis for all developers for things such as icons,
menus, placement, security requirements, and so on. The shell is populated with the things
that all developers must adhere to, and the inner application is added to the shell
component.
Shells and inner applications are discussed in a later unit.

3-11
Student Notebook
Distribution of mobile web

applications
Secure connection between
client and server
Backend and
Cloud services
Worklight server
Direct access to enterprise

backend data and transaction
capabilities
Worklight Server
Backend
Version
Unified push
integration management notifications
Enforcement of authentication
Control of the client:
Application version management
Remote disabling
Enforced application update
Unified push notification

Aggregation of statistics regarding the use of the application
Figure 3-9. Worklight server
WU5061.1
Notes:
The Worklight server is an application that runs on an Application server. As is discussed in
the unit on deploying applications, each project deployed to the application server has its
own Worklight server.
www.staplescopyprint.ca

V8.1
Student Notebook
Uempty
Server customization components

The server is bundled with
Worklight Studio
No need for a separate installation
The project in Worklight Studio has

a server folder which includes:
Server configuration files
authenticationConfig.xml and
worklight.properties
A basic login page
Folders for Java code and jar files
used for customizing the server
Java, lib
Figure 3-10. Server customization components
WU5061.1
Notes:
The server that is bundled with the IDE is intended as a part of the development
environment. For production, the server is installed as separate software.
This is the topic of a later unit.

3-13
Student Notebook
Contains configuration
information such as port
number, context root, and so
forth
Everything is commented out
Values are set automatically
Uncomment anything you
want to customize
Values for databases, bit.ly

credentials, WS-Security,
and so forth
Bit.ly is a way of referencing
long URLs by giving abbreviated
addresses and using a redirect
Figure 3-11. worklight.properties
WU5061.1
Notes:
This slide highlights the simplicity of Worklight development: a lot of the tasks, such as
setting a server address or a database address, default to predefined values. The
developer only needs to modify them if the predefinitions are not sufficient.
The defaults of course target the development environment, with a local server installed
with the Worklight Studio, and so forth.

V8.1
Student Notebook
Uempty
authenticationConfig.xml
Used to configure how widgets and web applications authenticate
users
Predefined security tests,
realms and login modules
are provided
You can use these
as a model for
customization
Figure 3-12. authenticationConfig.xml
WU5061.1
Notes:
As for the properties discussed on the previous slide, authentication information also
defaults to predefined values. An added advantage of this is that the format of a definition
is provided automatically. It is therefore easy to create a new, customized definition by
referring to the default.

3-15
Student Notebook
Deploying applications and adapters to the server
Figure 3-13. Deploying applications and adapters to the server
WU5061.1
Notes:
Adapters and applications are build and deployed in the same way. The slide shows the
context menu for both.
1. The Run As sub-menu for adapters has the option to deploy the adapter, or to invoke
a Worklight backend service or a procedure.
2. The Run As sub-menu for an application allows you to build and deploy the application
common resources and any environment you have created.
Not shown on the slide is the sub-menu for a specific environment, which offers the options
to build the environment only, or to build everything (as for the application).

V8.1
Student Notebook
Uempty
Device runtime
Troubleshooting
Analytics
Skins
Device
Runtime
Authentication
Application
Code
Device runtime includes these capabilities:
Local security
Version control
Each of these is discussed in future units.
Figure 3-14. Device runtime
WU5061.1
Notes:
Troubleshooting
Detection and correction of connectivity problems.
Analytics
Collection of information about application and device usage.
Skins
Optimization of look-and-feel, features, and functions of different types in a single
device family.
Authentication
Managing the authentication sequence for an application.
Local security
Encryption of data stored on a device.
Version control

3-17
Student Notebook
Apply new versions, or disable old versions in accordance with the information received
from the Worklight console.

V8.1
Student Notebook
Uempty
Application distribution and update

Native resources are deployed to the Application Store
Web resources are deployed to both the Application Store
and the server
The server has resources
for V1.0 and V1.0
After loading, the device
asks for updates
native
shell
Web
code
Application Stores
V1.0
Worklight Server
During development
recent web
cycles, testers automatically Maintain
resources for native
get recent web resources
applications V1.0 and V1.1
through internal distribution
mechanisms, not application stores
native
shell
Web
code
V1.1
Figure 3-15. Application distribution and update
WU5061.1
Notes:
Web resources are initially packaged with the application to ensure first offline availability.
They are transferred to cache storage in the application.
The application checks for updates:
On startup
On return to foreground
Newer versions of web resources are downloaded when necessary.

3-19
Student Notebook
Push notification
Messages are pushed from the server to the mobile device
Can be received even if the application is not running
It can be an alert, a badge, or a sound
Back end
Push service
mediator
5
1
Enterprise
data source
2
3
Worklight
adapter
event source
Figure 3-16. Push notification
WU5061.1
Notes:
A device obtains a token from a push service mediator (1), then send this token, together
with the request to be notified, to the Worklight server (2).
A backend data source sends a event notification to the Worklight server (3). The server
checks whether there are any subscriptions to this event, and sends the tokens to the push
service mediator (4). The mediator retrieves the device addresses associated with the
tokens and sends the notification (5).
Alert: A pop-up dialog that can be read and needs to be dismissed by clicking.
Badge: A small icon added to another icon to warn the user about some condition (this is
also very typical in Integrated Development Environments, for example when there is an
error in some code a red badge is added to the file icon).
Sound: Audio warning that, unlike an alert, does not need to be dismissed.

V8.1
Student Notebook
Uempty
Worklight console
The console is an
application running on
the Worklight server
If you are using the Worklight
Studio built-in server, Studio
needs to be running in order
to see the console
Two tabs:
Catalog
Shows a list of the
applications and the adapters
deployed to the server
Push notifications
Shows event sources, and
services and applications that
are subscribed to receive
notifications
Figure 3-17. Worklight console
WU5061.1
Notes:
The console opens as an internal view in Worklight Studio. Right-click on the project and
choose Open Worklight Console from the context menu.

3-21
Student Notebook
Worklight console - catalog tab

Applications may be deployed on the server in several versions
The latest version should be used. Earlier versions can be marked
as notifying or disabled
Notifying: give a message
that a version is deprecated
Disabled: the version
cannot be used. The
message may include
a URL where the user can
find a new version.
The display shows

description and display
name.
3
2
1
You can modify these in

application-descriptor.xml
Figure 3-18. Worklight console - catalog tab
WU5061.1
Notes:
1. The list of available applications and adapters. There may be different versions of an
application. You can set the state for an application to active (this is the default state),
active with notification (which can be used to warn the user, for example telling them
that there is a new version, or that the application is going to be disabled), and disabled
(the version can no longer be accessed).
2. The display name and the description are set by default to the name of the application
or adapter. They can be modified to something more informative by
changing:<application ><displayName>Engadget
Reader</displayName><description>This is v1 and v1.1 of the app.</description>
3. Building and deploying automatically is only an option in the development environment.
You can also upload a built application through the console.
An application can be uploaded to the server from the console as well as from Worklight
Studio.

V8.1
Student Notebook
Uempty
Worklight console - mobile browser simulator

The Mobile Browser
Simulator provides a
quick way to view what
an environment should
look like
Open it from the
catalog tab by clicking
the name or the icon of
an environment
Figure 3-19. Worklight console - mobile browser simulator
WU5061.1
Notes:
What the simulator is doing is placing the image of a mobile device around a rendering of
web code. It cannot render Xcode for an iPhone, nor can it render Java for an Android
device. Nevertheless, it is very useful as a quick way to visualize the rendering of web code
and the interaction with JavaScript.
A more accurate rendering can be got by using emulators. This course talks about the
Android emulator that is a part of the Worklight Studio setup, and the associated exercises
give supplemental instructions for rendering Xcode.

3-23
Student Notebook
Mobile browser simulator

3
2
1
Figure 3-20. Mobile browser simulator
WU5061.1
Notes:
1. Applications native to the displayed device can be simulated by clicking Simulate
Device API. The list is displayed on the left.
2. You can calibrate the device size to give a more accurate rendering on your monitor.
The calibration can be done by comparing the display to something the size of a credit
card.
3. You can compare the rendering on different devices by adding others. The drop down
list offers a choice of BlackBerry, Android and iOS.

V8.1
Student Notebook
Uempty
Application Center architecture

Application Server
Application Center
Application Catalog
Service
Application Center
Console
Application Install
Service
Application
Center
Installer App
Application Feedback
Service
Dojo 1.7.2 / HTML

/CSS/JavaScript
iOS / Android
Worklight 5
Dojo Mobile 1.7.2
HTML5 / CSS / JavaScript
iOS and Android native code
Rest Services
Database - Derby
Figure 3-21. Application Center architecture
WU5061.1
Notes:
The Application Center is composed of these main elements: a server-side component, a
repository, an administration console, and a mobile client application. The server-side
component is a Java Enterprise application that must be deployed in a web application
server such as IBM WebSphere or Apache Tomcat. The server-side component consists of
an administration console and a mobile application. This mobile application installs the
mobile applications available to the client-side component.
There is a repository, database that stores information such as which application is
installed on which devices, the feedback about applications, and the mobile application
binary files.
The administration console
A web console through which administrators can manage applications, user access rights
to install applications, user feedback about mobile applications, and details about
applications installed on devices. See The Application Center console.
Mobile client application

3-25
Student Notebook
You use the mobile client to install applications on a mobile device and to send feedback
about an application to the server.

V8.1
Student Notebook
Uempty
3.2. Code optimization

3-27
Student Notebook
Code optimization
Figure 3-22. Code optimization
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Code optimization
Worklight applications can execute in several different environments
Smartphones, tablets, web
Environments are distinguished by many aspects:

Screen size
Orientation
UI components
Physical interface
Functionality specific to an environment
Worklight provides an optimization framework for more efficient code

development
Figure 3-23. Code optimization
WU5061.1
Notes:
Code optimization makes the Worklight Studio development environment very efficient.
The intent is to make code as reusable as possible by placing it in a common environment
if it is used by different devices, and only putting code that is specific to an environment into
a more targeted folder structure. There are three layers to this optimization: common,
environment, and skin.
The following slides look in detail at how optimization works.

3-29
Student Notebook
The basis of optimization

A Worklight application is divided into environmental folders
iPhone, Android, and so forth
Each folder holds a number of sub-folders that hold code specific to

that environment.
There are sub-folders for
Cascading Style Sheets
Images
JavaScript
Native
Native resources
The application itself has a folder called common,

which holds resources that are shared by all
environments
The common folder also has a structure of sub-folders
including css, images and JavaScript
Figure 3-24. The basis of optimization
WU5061.1
Notes:
Note that the folder structure is mirrored between common and environment areas. There
is one more level, that is not shown on this page, called a skin, where the same folder
structure can be found. This structure is discussed in depth in the following pages.

V8.1
Student Notebook
Uempty
How does optimization work

The process of optimization combines resources
The fundamental resources (common folder) are the basis for all
environments
Any extra resources in the environment folders are combined with the
common resources
The process continues if there are skin folders
Common CSS, images, JavaScript
Environment
CSS
Environment
images
Environment
JavaScript
Skin
CSS
Skin
images
Skin
JavaScript
Figure 3-25. How does optimization work
WU5061.1
Notes:
This page gives the high-level view of optimization. As a general rule, you place into the
higher levels code that is general, and into the lower levels code that is specific. For
example, there may be an image that is provided for all devices (common to every device).
There may also be an Apple image for iOS devices. Since this image is not relevant to
other environments, it would be placed at a lower level. Skins follow the same logic, and
allow for fine-grained distinctions within one family of devices.

3-31
Student Notebook
Optimization CSS
Any CSS file in an environment folder is appended to the fundamental
common CSS file.
If any property name in the environment CSS is the same as in the
common CSS, the environment overrides
#content {
height: 460px;
margin: 0 auto;
width: 320px ;
}
body {
background-color: white;
}
div {
font: sans-serif;
}
common
#content {
height: 460px;
margin: 0 auto;
width: 320px ;
}
body {
background-color: white;
text-align: left;
}
div {
font: serif;
}
body {
text-align: left;
}
div {
font: serif;
}
environment
final CSS
Figure 3-26. Optimization - CSS
WU5061.1
Notes:
Here you see the specifics of optimization as it works for cascading style sheets. The basic
is the common folder (to the left on the image). The environment folder then combines in
two ways:
1. If the environment information does not exist in the common file, the two are
aggregated.
2. In the event of a name/value conflict, the lower level wins out (environment wins over
common).
Not shown on the slide is the skin structure. The same principle holds between skin and
environment as between environment and common: the information is either
aggregated or the skin information replaces the environment information.

V8.1
Student Notebook
Uempty
Optimization images
New images in the environment folder are appended to the collection
of images in the common folder.
In the event of a name collision, the environment images replace the
common images
bgd.png
icon.jpg
splash.jpg
common
bgd.jpg
bgd.png
icon.jpg // environment
splash.jpg
bgd.jpg
icon.jpg
environment
final images
Figure 3-27. Optimization - images
WU5061.1
Notes:
Images follow the same principle as cascading style sheets, except that here there is no
concept of information within the file: the comparison is at the level of the file name and
extension.
As you can see on the image, if the name is the same but the extension is different, then
the two files are different and both are added to the final list of images. In the one case
illustrated here where the file name and file extension are identical, it is the lower level
artifact (environment) that is used in the final collection of available images.
If there were the same conflict between environment and skin, it would be the image from
the skin that would win out and be added to the final collection of images.

3-33
Student Notebook
Optimization JavaScript
The main JavaScript file in an environment folder has a function,
wlEnvInit(), which invokes the function wlCommonInit() in the
common js folder
This helps ensure that common initialization happens before the more specific
environment initialization
Both the common and the environmental files have the same name:
applicationName.js.
Both files can hold any other functions that are required
If functions or variables in the environmental folder have the same
name as in the common folder, they are overridden
common
var a = "hello"; // env.

wlCommonInit(){}
wlEnvInit(){}
function_1(){} //env.
function_2(){}
var a = "hello;
wlEnvInit(){}
function_1(){}
function_2(){}
var a = 1;
wlCommonInit(){}
function_1(){}
environment
final JavaScript
Figure 3-28. Optimization - JavaScript
WU5061.1
Notes:
There is no conflict at the naming level between JavaScript files in the common folder
structure and the environment folder structure. On the contrary, be careful when you are
editing, because both are given a JavaScript file based on the name of the application! If
you have the two files open at the same time, it can be difficult to know which is which. For
the record, note that the common appName.js file has a function wlCommonInit(), while the
environment appName.js file has a function wlEnvInit() that calls wlCommonInit().
The resolution of potential conflicts in JavaScript follows the same process as the
cascading style sheets. The common file lays down the fundamental variables and
functions, then the environment file variables and functions are either aggregated or they
override.

V8.1
Student Notebook
Uempty
Optimization - HTML
By default, only the common folder of the application has an HTML file:
applicationName.html
An environmental folder can be given an HTML file, in which case it
simply replaces the common file
Note that this is not usual practice: typically you want a common feel
for an application between environments, and this is provided by using
a common HTML file
common
environment
Figure 3-29. Optimization - HTML
WU5061.1
Notes:
The HTML file is a special case. In the basic project with its one application, there is an
html file automatically added to the common folder, with the application name
(appName.html). When you create an environment, folders and files are automatically
created that mirror the common structure, but there is no html file. Usually, you want your
site to have a unified look and feel over all devices, and therefore overriding the html file is
not required. If for some reason you want to have a specific environment html file, if you
give it the name of the application, it simply replaces the common html file.

3-35
Student Notebook

V8.1
Student Notebook
Uempty
3.3. Client-side development:

the Worklight JavaScript SDK

3-37
Student Notebook
Client-side
development:
the Worklight
JavaScript SDK
Figure 3-30. Client-side development: the Worklight JavaScript SDK
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Overview of client-side development

Desired functionality
Example
Technology
Standard screens and graphics Lists, forms, images
JavaScript, HTML, CSS, 3rdparty JavaScript libraries
Use UI controls rendered as

native
Busy indicator, Dialog, Options

menu, Tab bar
Worklight JavaScript API
Optimize UI to specific device

type
Access device features
Utilize larger form-factor of iPad, Create a Worklight environment

adapt to OS UI standards
optimization, use JavaScript,
HTML CSS
Camera, GPS, accelerometer,
Use Apache Cordova
contacts, media player
JavaScript API
Incorporate 3rd-party native

Native encryption library
libraries
Combine native and web-based Bar code scanning, augmented
UI within the same application reality
Develop a full-native application Migrate existing native

using Worklight server
applications to the Worklight
platform
Write an Apache Cordova

plugin
Use Worklight native page API
to combine native and web
pages, with shared session
Use Worklight native SDK
(Objective-C, Java)
Figure 3-31. Overview of client-side development
WU5061.1
Notes:
It could be argued that most mobile development is client side, since it if for mobile devices!
It is true that the greatest variety of APIs in the Worklight Mobile environment is in the client
side coding, and server side code for Worklight mobile can essentially be summed up as
adapter.
This side gives an overview of the functionalities and corresponding technologies that are
the object of client side coding.

3-39
Student Notebook
Common controls
A common control is one that is available to all environments
Worklight automatically renders the controls natively for a particular
mobile platform
Typical examples are
WL.BusyIndicator
WL.SimpleDialog
WL.TabBar
WL.OptionsMenu
Figure 3-32. Common controls
WU5061.1
Notes:
These controls are discussed in more detail in a future unit.

V8.1
Student Notebook
Uempty
Skins
Skins give an alternative look to an environment.
They are packaged with an application, and are related to their
environment as environmentName.skinName
For example, Android.mySkin
Reasons for creating skins include

Accommodating different screen sizes
Allowing for different input methods
Creating different screen density
Figure 3-33. Skins
WU5061.1
Notes:
Skins have been mentioned briefly already. A device family (Android, for example) may
have many different types of device, with different screen shape and size, or different ways
of allowing user interaction. This can be accommodated by further specializing the
environment with skins. A skin has its own cascading style sheet, image folder, and
JavaScript file. These may have nothing more than the skeleton files generated by
Worklight, in which case using a skin does not change the look and feel of the environment.
However, the skin could provide smaller images for use on devices with less screen size, or
even modify the display of information radically (as is illustrated on this page).

3-41
Student Notebook
Apache Cordova
Allows developers to access native mobile device features and execute
native code using JavaScript
The framework is added by Worklight when you create an iOS or an
Android environment
It is then invoked using the JavaScript API
Example: a native alert
navigator.notification.alert(
"Native alert", null);
Figure 3-34. Apache Cordova
WU5061.1
Notes:
The complete call is navigator.notification.alert (message, alertCallback, [title],
[buttonName])
Where
Message is the Dialog message
alertCallback is the function to invoke when the alert dialog is dismissed.
Title is the dialog title (Optional; it defaults to "Alert")
buttonName is the name of the button (Optional; it defaults to "OK")

V8.1
Student Notebook
Uempty
Calls between native and web pages

The WL.NativePage API allows you to
call native pages from web pages
Share a single server session
Share data from one page to another
For example, to switch from a web page to a native page:

WL.NativePage.show(className, callback, data);
Figure 3-35. Calls between native and web pages
WU5061.1
Notes:
className: The name of the native class. For iOS this is just the name of the class. For
Android, the fully qualified package.Class is required.
Callback: A function that is called when the native page switches back to the web view.
This function is passed a single JSON object parameter when invoked.
data: A JSON object that is sent to the native class. For iOS, The data must be single string
or a flat record of strings.

3-43
Student Notebook
Offline access
Detection that an application has gone offline can be done in two ways:
Explicitly
Some Worklight server function may be invoked, and be unreachable
Implicitly
There may be an event listener
For example a foreground event may trigger a listener that checks whether
there is still a connection
Connection is checked at initialization

var wlInitOptions = {
connectOnStartup : true,
onConnectionFailure ; function (data) {
someFunction(data);
}
};
Figure 3-36. Offline access
WU5061.1
Notes:
With devices that are mobile, and can be travelling between base stations. Getting out of
range of a base station can happen in two ways: either you move too far away and the
signal is no longer strong enough to be detected, or you enter some structure that blocks
the signal: a tunnel, an elevator, and so on. It could also be that the signal provider stops
providing a signal
In all these scenarios, the mobile device may need to ascertain whether it has connectivity
or not. There are three times when it does this: when an application starts, when an
application is brought to the foreground, and when there is an explicit request from an
application. In the first two cases, there is an implicit check for connectivity through an
event listener. In the third case there is an explicit invocation that creates an error if there is
no connection available.
The importance of this for mobile devices is that you do not want your application to stop
working every time it loses the signal. You also do not want to lose information just because
you try to send it while there is no receiver available!

V8.1
Student Notebook
Uempty
Encrypted cache
Client side encryption implemented with HTML5 web storage using
key-value pairs
Two types of web storage: localStorage and sessionStorage
localStorage has no expiry date
sessionStorage is valid until the session ends
Encryption is done using a randomly generated token and a user key

Creating and opening encrypted cache uses the same mechanism:
WL.EncryptedCache.open(
credentials, createIfNone, onComplete, onError);
The cache must be explicitly closed. Once open, reading from

and writing to the cache is not challenged!
Figure 3-37. Encrypted cache
WU5061.1
Notes:
Encrypted cache is supported by iOS Safari, Android Browser, and Opera Mobile (from
V11).
The parameters are:
credentials: the user password
createIfNone: true=create the cache if none is found
onComplete: do this when the cache is ready for use
onError: do this if an error occurred, such as credentials mismatch, or local storage not
supported
Note that credentials are only required to open the cache. After that, reading and writing is
free to any user! You must be careful to explicitly close the cache.

3-45
Student Notebook
Globalizing strings
For globalization, anything that needs to be read by the user should be
translated into their preferred language
information strings, labels, messages, for example
Worklight provides messages.js in the common folder

The Message element holds the default list of name-value pairs, for
example:
Messages = { headerText: "Default header",
languageLabel: English",
sampleText: Sample Text }
Each message can be accessed

as a property, for example Messages.headerText
as an HTML element id, for example <div id=headerText>
Figure 3-38. Globalizing strings
WU5061.1
Notes:
In order to detect the locale of the device you can use WL.App.getDeviceLocale() and
WL.App.getDeviceLanguage().
Messages values can be overridden:
function setFrench() {
Messages.headerText = En-tte;
Messages.languageLabel = Franais;
Messages.sampleText = chantillon;
}
function setGerman() {
Messages.headerText = berschrift;
Messages.languageLabel = Deutsch;
Messages.sampleText = Beispiel;
}

V8.1
Student Notebook
Uempty
Element texts can then be updated:

setFrench();
$(sampleText).html(Messages.sampleText);

3-47
Student Notebook
UI frameworks
Using your own HTML, CSS, and JavaScript provides a highly
customizable framework for your application.
You can also use an existing framework
for example, Dojo Mobile, jQuery Mobile, or Sencha Touch
The Worklight client-side framework already

uses jQuery. The $ character is by default
assigned to jQuery calls in applicationName.js
window.$ = WLJQ
To use a framework, add the components

to the application and reference them in
the HTML page
Figure 3-39. UI frameworks
WU5061.1
Notes:
When you create a new application using the Worklight wizard, you have the option to
include three frameworks: jQuery, Dojo toolkit, and Sencha Touch. These frameworks ore
not exclusive, and you can select any combination of checkboxes to include them. The
required files are then automatically added to your application.
You can added them manually later, if you decide that you need them.

V8.1
Student Notebook
Uempty
3.4. Server-side development

3-49
Student Notebook
Server-side
development
Figure 3-40. Server-side development
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Integration adapters
Four adapter types can be developed with Worklight:
SQL
HTTP
Cast Iron
JMS
These are discussed in detail in a further module
Adapters are server side components that are used to connect to

backend systems
Adapters have
an XML file describing the connectivity options
a JavaScript file that holds the functions described
in the XML file
The adapter may transform the data it retrieves (optional XSL file), or
simply return it
In both cases, the adapter returns a JSON object
Figure 3-41. Integration adapters
WU5061.1
Notes:
After all those pages giving a high-level view of client side development, you may be
surprised that there is only one for server side development! This is not because it is
unimportant, or because there is little to do. It is simple because it can be summed up in
one word: adapters. The principle is simple: an XML file to configure the adapter, and a
JavaScript file to give it functionality. There may also be a transformation file (XSLT).
Adapters are discussed in depth in a future unit.

3-51
Student Notebook

V8.1
Student Notebook
Uempty
3.5. Secure authentication

3-53
Student Notebook
Secure authentication
Figure 3-42. Secure authentication
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Authentication
Worklight defines security in authentication realms
A realm describes how to authenticate uses
Realms are defined in authenticationConfig.xml
A realm consists of
an authenticator
Components used to collect credential information
a Login Module
Receives credential information from the authenticator and validates them
A securityTest then groups realms and defines the order in which the
tests should be applied
<customSecurityTest name="custom">
<test realm="realm_A" isInternalUserID="true" step="1"/>
<test realm="realm_B" isInternalDeviceID="true" step="2"/>
</customSecurityTest>
Figure 3-43. Authentication
WU5061.1
Notes:
Security is applied by configuring tests called securityTests. There are three different types
of securityTest. The one illustrated here shows the structure: the securityTest contains one
or more tests that reference a security realm, which in turn references a security
loginModule (you would need to look at the realm definition to see which loginModule was
referenced). Each test may be specified as referring to a user or a device. The tests can be
ordered by using the step attribute.

3-55
Student Notebook

V8.1
Student Notebook
Uempty
3.6. Application management and reporting capabilities

3-57
Student Notebook
Application
management and
reporting capabilities
Figure 3-44. Application management and reporting capabilities
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Push notification
Push refers to a server initiating communication with a device
Notifications are information that the device user must know, or may
need to know
for example, an application must be updated, a flight has been delayed, it may
rain, and so forth
The notification can be

a pop-up alert
a badge, or small icon added to the application icon
a sound
Figure 3-45. Push notification
WU5061.1
Notes:
A user must first register their interest for a notification. This is a two-step process; first, the
application gets a token from a Push Service Mediator (Apple Push Notification Service or
APN, Global System for Mobile Communications or GSM, and so on). This token is then
sent to the Worklight server. The server either itself waits for a notification to be pushed to
it, or it polls a backend server. When the notification is received, the server passes the
token back to the Push Service Mediator, which looks up the user information and passes
the notification on.

3-59
Student Notebook
Direct update
Hybrid iOS applications and Android applications can receive new
versions of their web resources without the user explicitly asking for
them
This has advantages in two directions:
The user can always have the latest version of an application
Server-side control over which versions of an application are being used.
The server can mark an application version as Active, Notifying

There would be a more recent version that the user can upload
The server can also disable a version

A URL can be provided where the user can download another version
Figure 3-46. Direct update
WU5061.1
Notes:
Note that this applies only to the applications web resources. Native updates are only
possible by going through the App Store.
An application can check for updates on start up, or when it is brought back to the
foreground.
The Worklight server can disable a native application, although it cannot update it.

V8.1
Student Notebook
Uempty
Remote server application deployment

In a development environment the resources are usually local
To prepare an application for deployment, you must modify some
definitions to point to the new environment
application-descriptor.xml has these definitions
For example, by default <worklightServerRootURL> points to
http://${local.IPAddress}:8080
You change this to the remote server address
In worklight.properties you change the Worklight server access

information
For example
publicWorkLightProtocol=http
publicWorkLightPort=8081
publicWorkLightContext=/theApp/
would create a URL of http://<server>:8081/theApp/

Figure 3-47. Remote server application deployment
WU5061.1
Notes:
These values are defaults in the development environment. They are provided in
worklight.properties as an indication of what the values are but they are commented out.

3-61
Student Notebook

V8.1
Student Notebook
Uempty
3.7. Mobile team development capabilities

3-63
Student Notebook
Mobile team
development
capabilities
Figure 3-48. Mobile team development capabilities
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Shell development
A shell is used as a code base wrapper by inner applications
It consists of native code and web resources that are intended for any
application in the shell
The shell is not itself executable it is a framework for inner
applications
An inner test application is added when you create a shell in order to verify the
correct functioning
The shell has a fragments folder which holds html that is added to the
web page of the inner application
Figure 3-49. Shell development
WU5061.1
Notes:
Shell development is intended to provide a common ground for teams engaged in
developing mobile applications. The shell is developed with the fundamental, common
code that every developer must adhere to. Inner applications then reference the shell, and
build on that basis.
This is not an absolute adhesion that is imposed! Inner applications can override anything
that is necessary.

3-65
Student Notebook
Application Center
The IBM Worklight Application Center for mobile applications is
focused on the needs of a development team
It is a private App Store
Scenario:
a developer shares a new version of an application with stakeholders, designers,
testers, and so forth
Everyone installs the new version on their device
They can send feedback to the developer from the Application Center Installer
app.
The developer can access the feedback from the Application Center Console
Figure 3-50. Application Center
WU5061.1
Notes:
Application Center is installed on the application server. IBMAppCenter is installed on the
mobile device. The web console is packaged as a war file (ibmapplicationcenter.war).
A Derby database is provided, together with the scripts.
Documentation includes an installation guide and a usage guide.

V8.1
Student Notebook
Uempty
Enhancements to Worklight in version 6.0

Automated functional testing for accelerated delivery cycles of native
and hybrid, cross-platform mobile applications
New advanced IT analytics for application usage insight, triggering of
actions based on analytics events, and location-based services such as
geo-fencing
Improved application development and testing abilities to record and
run tests of mobile applications on devices and emulators
Expanded mobile operating system support, including support for new
levels of iOS, Android, BlackBerry, Windows 8 and RT, and Windows
Phone 8 in addition to third-party software support updates for JQuery
Mobile and Dojo Mobile
Easier, more guided, hybrid application development, with tools and
building blocks such as improved Dojo Mobile setup and screen
templates
Improved application startup performance
Figure 3-51. Enhancements to Worklight in version 6.0
WU5061.1
Notes:
Some of these enhancements are indicated here simply for information (such as the
improved performance). Other enhancements are discussed in future units.

3-67
Student Notebook
Checkpoint
1. What are the five basic components in Worklight?
2. How does direct update work?
3. Which of these folders can be found in common resources and
environment resources:
a)
css
b)
c)
native
legal
d)
e)
js
native resources
4. true or false:
myApp.js in an Android folder overrides myApp.js in a common folder
5. What does it mean when a server marks an application version as
Active, Notifying ?
6. true or false:
a shell is an executable framework for inner applications
Figure 3-52. Checkpoint
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Unit summary
WU5061.1
Notes:

3-69
Student Notebook
Checkpoint answers
1. What are the five basic components in Worklight?
Worklight Studio, Server, and console; device runtime, Application Center
2. How does direct update work?

Download an application from an Application Store, then check Worklight Server
for updates. There is also a check when an application gets focus.
3. What is a push notification?

The server sends data to a device without first receiving a request
4. Which of these folders can be found in common resources and

environment resources:
a)
css, and d) js
5. true or false:
myApp.js in an Android folder overrides myApp.js in a common folder
false. Only functions with the same name override, otherwise they are merged
6. What does it mean when a server marks an application version as

Active, Notifying ? A more recent version of the application is available
7. true or false: a shell is an executable framework for inner applications
False. A shell is not executable in itself
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Unit 4. Overview of Worklight Studio

This unit shows you how to install Worklight Studio and how to set-up
an Android or iOS development environment. It also describes the
Worklight base development framework and provides an overview of
the Worklight Studio tools that facilitate mobile development.

Install IBM Worklight Studio using the Eclipse Update Site
Set-up an Android or iOS development environment
Explain the Worklight development framework
Describe the Worklight Studio mobile development tools
Describe the steps involved in creating, building and testing an
application in Worklight Studio

Checkpoint
Exercise
References

4-1
Student Notebook
Unit objectives
WU5061.1
Notes:
This unit shows how to install Worklight Studio and set-up an Android or iOS development
environment. It also describes the Worklight base development framework and provides
an overview of the Worklight Studio tools that facilitate mobile development.
4-2

V8.1
Student Notebook
Uempty
Topics
IBM Worklight Studio installation and configuration
Overview of mobile development steps
Creating a project and writing your code
Building your application
Previewing and testing your application
Publishing your application
Figure 4-2. Topics
WU5061.1
Notes:

4-3
Student Notebook
4-4

V8.1
Student Notebook
Uempty
4.1. IBM Worklight Studio installation and configuration

4-5
Student Notebook
IBM Worklight Studio

installation and
configuration
Installing the Worklight Studio plug-in

Setting up an Android development
environment
Setting up an iOS development environment
Figure 4-3. IBM Worklight Studio installation and configuration
WU5061.1
Notes:
4-6

V8.1
Student Notebook
Uempty
IBM Worklight Studio: Introduction

Worklight Studio is an Eclipse-base IDE that allows developers to
perform all the coding and integration tasks required to develop mobile
applications.
Contains an embedded version of Worklight Server and an embedded database
to facilitate the development process.
Worklight Studio allows you to easily:

Create and modify applications
Deploy applications to the embedded Worklight Server

Preview and manage applications by using the Worklight Console
Create custom server-side Java code that can be used by Worklight adapters
Create and modify Worklight adapters
Deploy Worklight adapters to the embedded Worklight Server

Test Worklight adapter procedures
Figure 4-4. IBM Worklight Studio: Introduction
WU5061.1
Notes:
IBM Worklight Studio v6 includes the following tools and components:
Embedded Worklight Server
Rich Page Editor
Development tools
Apache Cordova 1.6.1
IBM Dojo Mobile 1.7.2

4-7
Student Notebook
IBM Worklight Studio installation: Prerequisites (1 of 2)

Worklight Studio v6.0 is an Eclipse plug-in and can be installed in the
following Eclipse editions and versions:
Eclipse Classic or Eclipse for Java Enterprise Edition (Java EE) Developers
Version 4.2.2 (Juno)
Worklight Studio runs on operating systems where Eclipse is supported

(32 and 64-bit editions):
Microsoft Windows 7, Windows 8
Mac OS X 10.7 and above
Linux
Figure 4-5. IBM Worklight Studio installation: Prerequisites (1 of 2)
WU5061.1
Notes:
For a detailed list of system requirements, visit:
https://pic.dhe.ibm.com/infocenter/prodguid/v1r0/clarity-reports/report/html/softwareReqsF
orProductByComponent?deliverableId=1343665214557&duComponent=Desktop_CBE50
E800C6611E28BB5885E0925FE36#
4-8

V8.1
Student Notebook
Uempty
IBM Worklight Studio installation: Prerequisites (2 of 2)

Eclipse requires a JDK or JRE:
IBM Runtime Environment, Java Technology Edition 6.0, 7.0
Oracle Java SDK/JRE/JDK 7.0
Worklight Studio v6.0 supports the following mobile Software

Development Kits (SDKs) and tools:
iOS: Xcode version 4.5 and above
Android: Android Development Tools (ADT) latest version
Figure 4-6. IBM Worklight Studio installation: Prerequisites (2 of 2)
WU5061.1
Notes:
For more details, visit https://pic.dhe.ibm.com/infocenter/prodguid/v1r0/clarity-reports/report/html/softwareReqsF
orProductByComponent?deliverableId=1343665214557&duComponent=Desktop_CBE50
E800C6611E28BB5885E0925FE36#

4-9
Student Notebook
IBM Worklight Studio installation methods

Worklight Studio can be installed in one of two ways depending on the
target operating system and product packaging:
Eclipse Update Site
Supported on all operating systems
Supported on all IBM Worklight product editions
Uses an Eclipse P2 archive location for source of plug-in
> Accessed directly from the web or downloaded locally first
IBM Installation Manager

Supported on non-Mac operating systems only
Not applicable to IBM Worklight Developer Edition
Uses an IBM Installation Manager repository for source of plug-in
Figure 4-7. IBM Worklight Studio installation methods
WU5061.1
Notes:
IBM Installation Manager is a tool that allows you to install and maintain IBM software
packages. It includes wizards that guide you through the steps to install, modify, update,
roll back, or uninstall your IBM products.

V8.1
Student Notebook
Uempty
Installing IBM Worklight Studio using the Eclipse Update

Site (1 of 4)
In Eclipse:
Select Help > Install New Software.
Click Add to add a new location.
Figure 4-8. Installing IBM Worklight Studio using the Eclipse Update Site (1 of 4)
WU5061.1
Notes:

4-11
Student Notebook

Site (2 of 4)
Specify the location of the Worklight Studio plug-in source (Eclipse
Update web site or local archive)
WU5061.1
Notes:
You can download the Worklight Studio plug-in locally as a compressed file, and then install
it as an Eclipse archive, or you can install it directly from the Eclipse Update web site.

V8.1
Student Notebook
Uempty

Site (3 of 4)
Select the options to install:
IBM jQuery Mobile Tools
IBM Dojo Mobile Tools
Click Next
Install details page displays
You must accept terms of the license
You are prompted to restart Eclipse
WU5061.1
Notes:

4-13
Student Notebook

Site (4 of 4)
After Eclipse restarts:
The Create a Worklight Artifact icon is displayed on the tool bar.
WU5061.1
Notes:

V8.1
Student Notebook
Uempty

4-15
Student Notebook

installation and
configuration

environment
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Android development environment setup steps

The steps to set-up an Android development environment in Worklight
Studio are as follows:
1.Install the Android Software Development Kit (SDK)
a)
Install the Android SDK core tools
b)
Install the Android SDK platform and platform tools
2.Install the Android Development Tools (ADT) plug-in for Eclipse

3.Create an Android Virtual Device
Figure 4-13. Android development environment setup steps
WU5061.1
Notes:
The detailed instructions for installing the Android SDK are available online at:
http://developer.android.com/sdk/installing/index.html

4-17
Student Notebook
Installing the Android SDK: Core tools installation

The Android SDK core tools are required to download the rest of the SDK components.
Download the installer or zip file package from the Android SDK download site
Package varies by operating system platform
Figure 4-14. Installing the Android SDK: Core tools installation
WU5061.1
Notes:
The URL for the Android SDK download site is:
http://developer.android.com/sdk/index.html

V8.1
Student Notebook
Uempty
Installing the Android SDK: SDK platform and platform

tools installation
Once the core tools are installed, the
Android SDK Manager can be used to
install:
SDK platforms
SDK platform tools
Extras (for example, Google USB Driver)
Figure 4-15. Installing the Android SDK: SDK platform and platform tools installation
WU5061.1
Notes:
The Android SDK uses a modular structure that separates the major parts of the SDK Android platform versions, add-ons, tools, samples, and documentation -into a set of
separately installable packages. To develop an Android application, you need to download
at least one Android platform and the associated platform tools.

4-19
Student Notebook
Installing the ADT plug-in for Eclipse (1 of 3)

The ADT (Android Development Tools) plug-in for Eclipse is designed
to provide a powerful, integrated environment in which rich Android
applications can be built.
To install the ADT, select Help > Install New Software in Eclipse.
Launches the plug-in installation wizard.
Click Add and enter a name for the ADT plug-in repository and its
location.
The ADT plug-in repository is located at:
https://dl-ssl.google.com/android/eclipse/
17
Figure 4-16. Installing the ADT plug-in for Eclipse (1 of 3)
WU5061.1
Notes:
To develop an Android application or prepare a Worklight application to be run on the
Android platform, you need the Android Development Tools (ADT).
ADT is a plug-in for the Eclipse IDE that is designed to give developer an integrated
environment in which to build Android applications. It extends the capabilities of Eclipse to
let developers quickly set up new Android projects, create an application UI, add packages
based on the Android Framework API, debug your applications using the Android SDK
tools, and even export signed (or unsigned) .apk files in order to distribute your application.
Please follow the link at the bottom for more information on the ADT and its download
location.
For detailed instructions on installing the ADT plug-in, visit:
http://developer.android.com/sdk/eclipse-adt.html
The link at the bottom of the page provides the download location. You can use the HTTP
protocol as well. Make sure that you have an Internet connection and your firewall is not
blocking downloads.

V8.1
Student Notebook
Uempty

Select Developer Tools and click Next to proceed with the installation.
Proceed with the ADT installation sequence.
18
WU5061.1
Notes:
Select Developer Tools in the list of available software. Then follow the ADT installation
process to complete installing the plug-in.

4-21
Student Notebook

After the ADT plug-in installation
completes and Eclipse restarts, the
Window menu shows two new items:
Android SDK Manager
AVD Manager
If you dont see these items, make sure

that you are in the Java Perspective
19
WU5061.1
Notes:
After installing the ADT Eclipse plug-in, you can open the Android SDK Manager directly
from the workbench and use the Android Virtual Device manager to create virtual devices.

V8.1
Student Notebook
Uempty
Creating an Android Virtual Device (AVD)

To create a virtual device (emulator):
Select Window > AVD Manager.
Click New in the Android Virtual Device
Manager window.
Enter a name and select a target in the
Create new Android Virtual Device window.
Click Create AVD.
20
Figure 4-19. Creating an Android Virtual Device (AVD)
WU5061.1
Notes:
Once you have completed the Android SDK installation, you need to create and configure
an Android Virtual Device (AVD) on which to test your application.
An Android Virtual Device (AVD) is an emulator configuration that lets you model an actual
device by defining hardware and software options to be emulated by the Android Emulator.
An AVD consists of a hardware profile where you can define the hardware features of the
virtual device.
You can create as many AVDs as you need, based on the types of device you want to
model. To thoroughly test your application, you should create an AVD for each general
device configuration (for example, different screen sizes and platform versions) on which
your application is intended to run, and test your application on each one.

4-23
Student Notebook
Starting an Android Virtual Device

In the Android Virtual Device Manager window, select the virtual device
and click Start.

2013
Figure 4-20. Starting an Android Virtual Device
WU5061.1
Notes:
Starting an Android virtual device opens the Android emulator window.

V8.1
Student Notebook
Uempty

4-25
Student Notebook

installation and
configuration

environment
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
iOS development environment setup steps

Since Eclipse does not support iOS application development, Worklight
Studio requires the Apple Xcode IDE to compile an iOS application and
test it on an iOS simulator.
You can download and install Xcode as follows:
1. Register as an Apple developer.
2. Download and install the latest Xcode IDE from the Mac App Store.
Figure 4-22. iOS development environment setup steps
WU5061.1
Notes:
Note that you can still build and preview the portion of a hybrid iOS application built with
web technologies (HTML5, JavaScript and CSS) in Worklight Studio without having Xcode.
Any native code (Objective-C), however, will require the Xcode IDE.
To develop for iOS, register as an Apple developer and download Xcode, Apples IDE for
developing iOS or Mac applications.

4-27
Student Notebook
Developing for iOS: Register as an Apple developer

You first need to register as an Apple developer at the Apple Developer
Registration web site.
Requires an Apple ID
24
Figure 4-23. Developing for iOS: Register as an Apple developer
WU5061.1
Notes:
Use the following link to register as an Apple developer:
http://developer.apple.com/programs/start/register/create.php
During this step, you have the choice of creating a new Apple ID or use an existing one. An
Apple ID is used to access iTunes, the Apple Online Store or a MobileMe account. It is
required to register as an Apple developer. Follow the Apple registration wizard to complete
the process.

V8.1
Student Notebook
Uempty
Developing for iOS: Download and install Xcode

Download and install Xcode from the Mac App Store.
Xcode is a complete, full-featured IDE. It allows you to:
Develop, compile and build native iOS applications

Use an iPhone or iPad Simulator
Manage your testing devices
Install applications on an
iPhone or iPad device
25
Figure 4-24. Developing for iOS: Download and install Xcode
WU5061.1
Notes:
Xcode is an integrated development environment (IDE) containing a suite of software
development tools developed by Apple for developing software for OS X and iOS. First
released in 2003, Xcode is available via the Mac App Store free of charge for Mac OS X
Lion (and later) users. Xcode can only be installed on an Apple Mac machine. This means
that you do need a Mac machine to develop and test Worklight iOS applications.
For more information on how to get Xcode, visit:
https://developer.apple.com/technologies/tools/
Xcode integrates all the tools a developer needs to develop an iOS application. This
includes tools to write source code, compile and build. It also provides features such as
debugging and designing a user interface in a single window.
One of the handy tool provided by Xcode is the iOS simulator which you can use to test
most of application functions without a real device. The iOS Simulator presents the iPhone
or iPad user interface in a window on your Mac. It provides several ways to interact with it
by using the keyboard and mouse to simulate taps, device rotation, and other user actions.

4-29
Student Notebook
With the simulator, you can test your applications user interface and discover problems
early during testing.
Real device testing is also important for mobile application development. With Xcode, all
testing devices can be easily managed. You first need to provision a device before you can
deploy an application to it. Then you can install, update and uninstall the application. You
can also restore or install a new version of iOS on the device.

V8.1
Student Notebook
Uempty
Developing for iOS: Worklight Studio and Xcode

integration
Worklight Studio automatically generates an Xcode project for your
application and can open it directly in Xcode to compile and run on the
iOS simulator.
26
Figure 4-25. Developing for iOS: Worklight Studio and Xcode integration
WU5061.1
Notes:
With Xcode installed, you can start to develop your Worklight application to run on the iOS
platform. Worklight Studio automatically generates an Xcode project for the application. It
also provides an easy option to launch your application in Xcode where you can compile
and run it using the iOS simulator or deploy it to a real device for testing.

4-31
Student Notebook

V8.1
Student Notebook
Uempty
4.4. Overview of mobile development steps

4-33
Student Notebook
Overview of mobile
development steps
Figure 4-26. Overview of mobile development steps
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Worklight Studio mobile application development lifecycle
Figure 4-27. Worklight Studio mobile application development lifecycle
WU5061.1
Notes:
The Worklight Studio mobile application development steps consist of:
Creating a project for the application
Coding the applications user interface and business logic
Building the application and deploying it to the embedded Worklight Server
Previewing the application in the browser
If developing for iOS, building the application in Xcode
Testing the application on a simulator
Testing the application on a physical device
Publishing the application when development is complete
During the preview and test phase, you may cycle back to the construction phases to
correct any coding errors.
The next topic sections look at each of these steps in detail.

4-35
Student Notebook

V8.1
Student Notebook
Uempty
4.5. Creating a project

4-37
Student Notebook
Creating a project
Figure 4-28. Creating a project
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Worklight project creation wizard: Invocation

The Worklight Project wizard allows you to quickly create a project for
your application.
30
Figure 4-29. Worklight project creation wizard: Invocation
WU5061.1
Notes:
To start the Worklight Project wizard:
From the menu bar, select File > New Worklight Project. Alternatively, you can click the
Worklight icon from the tool bar, then select Worklight Project as shown in the screen
capture here.

4-39
Student Notebook
Worklight project creation wizard: Project name and type

Name your project.
Select a Project Template for it:
Hybrid Application
Combines web and native code
Inner Application
Web resources that will be run inside a
shell component
Native API
Shell Component
Wrapper component for a inner
application
31
Figure 4-30. Worklight project creation wizard: Project name and type
WU5061.1
Notes:
In the Worklight Project page, specify the project name and application or component type
that it will contain.
A Worklight project contains at least one hybrid application, inner application or shell
component. Once the project is created, you can add as many Worklight applications
and/or components to it as you want.
A hybrid application is a standard Worklight application type where both web and native
shell components are packaged into a single unit of deployment.
An inner application contains web resources (HTML, JavaScript, and CSS) that will be run
inside of a shell component.
A shell component is used by inner applications as a code base wrapper. Usually, it
consists of native classes and shell-specific web resources that are used in inner
applications. A shell component is implemented by shell developers and sent to inner
application developers to use.

V8.1
Student Notebook
Uempty
Inner applications and shell components are discussed in detail in the Team development
unit.

4-41
Student Notebook
Worklight project creation wizard: Hybrid application UI

framework selection
Name your application.
Optionally, select a JavaScript
mobile user interface framework to
use in.
In order to use jQuery Mobile or
Sencha Touch, you need to
manually download their library
files prior to adding them to the
application.
32
Figure 4-31. Worklight project creation wizard: Hybrid application UI framework selection
WU5061.1
Notes:
In the Hybrid Application page, specify the application name and optionally select a
JavaScript User Interface (UI) mobile framework to use.
You can package Dojo, jQuery Mobile or Sencha Touch libraries into your application. You
will learn more about this in the Working with UI frameworks unit.
A Hybrid application can contain HTML, JavaScript and CSS code along with native code,
allowing you to develop a mobile web, hybrid or pure native application.
When you click Finish, Worklight Studio generates a default project structure with an
application folder and initial skeleton code. You look at this structure next.

V8.1
Student Notebook
Uempty
Worklight project structure overview
References required for

application development
and deployment
Projects applications and

adapters
Server customization
components
Figure 4-32. Worklight project structure overview
WU5061.1
Notes:
The main components of the Worklight project structure created by the wizard include:
A set of artifacts and core libraries used by Worklight applications, including JRE and
JavaScript libraries. These are primarily used for application development and
deployment.
A folder named adapters that contains the projects adapters. Adapters are the
server-side code of applications deployed on and serviced by the Worklight Mobile
Application Platform. Adapters connect to enterprise applications (back-end systems),
deliver data to and from mobile applications, and perform any necessary server-side
logic on this data.
A folder named apps that contains Worklight applications belonging to this project.
A folder named Server that contains the configuration and third party libraries used by
the embedded Worklight test server.

4-43
Student Notebook
A bin folder that contains generated deliverables that will be deployed to the Worklight
server, once you build your application. The contents of this folder should not be modified
manually.

V8.1
Student Notebook
Uempty
Worklight project structure: Application folder

The default environment is called common and
contains all the resources that are shared between
environments:
HelloWorklight.html
The main HTML file
css
HelloWorklight.css - main applications CSS file
reset.css - bringing all rendering engines to one common
ground
images
Default Worklight images for the common environment
js
HelloWorklight.js
The main JavaScript file for the application
messages.js
JSON object holding all app messages. Can be used for
localization
auth.js
Applications custom authentication mechanism
implementation
legal folder should hold all legal related docs

application-descriptor.xml file contains applications
meta data
Figure 4-33. Worklight project structure: Application folder
WU5061.1
Notes:
All Worklight applications are organized under the apps folder.
After the project creation wizard finishes, several folders and files automatically created
under the apps/<applicationName> folder:
1. The most important one is the common folder as it contains the default environment for
a Worklight application. A Worklight application is built to run in multiple mobile, tablet
or even desktop runtime environments. Each runtime environment differs from the
other in many aspects such as screen size, orientation, specific UI guidelines and
components, physical user interface, unique environment functionality and more.
Worklight uses the environment concept to organize application artifacts into separate
units where runtime specific customization or optimization can be applied. For
example, you can create an iPhone environment vs. Android environment.
The common environment contains all the resources that are shared between
environments. Worklight generates a default HTML page and several subfolders to
contain your web application artifacts. Specifically:

4-45
Student Notebook
- A skeleton HTML file, named after your application is created. This HTML file is
often referred as the main HTML file. It loads all the web resources (scripts and style
sheets) necessary to define the general components of the application, and to hook
to required document events.
- A css folder is created to store application style sheets. Two skeleton css files are
generated in this folder. The one named after your application contains your main
application style sheets. A reset.css is also provided to bring all rendering engines
such as the mobile Webkit browser or the desktop browser to one common ground.
- Worklight also creates a js folder for JavaScript code that implements interactive
user interface components, business logic, backend query integration, and message
dictionary for localization purposes. Three default JavaScript files are created during
the application creation process. The one named after your application acts as the
main JavaScript file for your application. Worklight also creates a message.js file to
define JSON objects to hold all application messages. This is primarily used for
localization. Another generated JavaScript file is named auth.js and allows the
developer to add Worklight authentication logic when needed. All three JavaScript
files are loaded from the default main HTML page.
- Finally, an images folder is created to store application images.
1. The legal folder contains license documents for the application or third-party software
used in the application.
2. application-descriptor.xml file: The application descriptor is a mandatory XML file
containing application metadata, located in the apps root directory. This file is
auto-generated by the Worklight Studio application creation wizard and can then be
manually edited to add custom properties. Every application has an application
descriptor.

V8.1
Student Notebook
Uempty
Worklight project structure: Application folder additional

environments
You can add new environments for
different runtime platforms (for
example, Android or iOS).
The new environments resources will have
the following relationship with the common
resources:
images - override the common images in
case both share the same name
css extend and/or override the
common CSS files
js - extends the common application
instance JS object (The environment
class extends the common app class)
HTML - override the common HTML
code in case both share the same name
Figure 4-34. Worklight project structure: Application folder additional environments
WU5061.1
Notes:
You will learn more about the relationship between additional environments and the
common environment when discussing Code Optimization in a later unit.

4-47
Student Notebook
Worklight project structure: Server folder

The server folder contains files used for
server-side customization.
The conf folder contains:
worklight.properties: Contains server
configuration properties
authenticationConfig.xml: Defines
authentication realms
The Java folder is used to hold Java classes that
are compiled and deployed to a Worklight Server
once the application is built. You can put your
custom Java code here.
The lib folder is used for JARs that should be
deployed to the Worklight Server.
Figure 4-35. Worklight project structure: Server folder
WU5061.1
Notes:
Worklight Studio contains an embedded Worklight Server to use for development and
testing. Its configuration is controlled by the contents of the server folder. Specifically:
The conf folder contains the authenticationConfig.xml file which allows you to define
security and authentication information, and the worklight.properties file which specifies
server configuration information, such as the server hostname and port number.
The lib folder contains third party libraries used by your project. For example, you can
put JAX-RS jar files here if you are building RESTful services.
The Java folder houses custom Java code that you develop for components like a
Worklight adapter or a Worklight custom authenticator.

V8.1
Student Notebook
Uempty
Worklight project structure: bin folder

The bin folder contains project artifacts that should be deployed to a
Worklight Server
Evaluation version of Worklight Studio deploys the artifacts to the
embedded Worklight Server as a part of Build process
.wlapp files: application bundles
.adapter files: adapters
.jar and .war files: server
customization files containing
worklight.properties,
authenticationConfig.xml and
custom Java code
Figure 4-36. Worklight project structure: bin folder
WU5061.1
Notes:
The bin folder contains generated Worklight project artifacts such as the application
package file that is deployed to the Worklight Server (similar to a deployable EAR or WAR
file in Java EE).
Worklight applications and adapters are packaged as .wlapp and .adapter files that
essentially jar compatible zip files, respectively.
The bin folder is empty until you build the application for the first time.

4-49
Student Notebook
Worklight application descriptor

An application descriptor is an XML file that stores the metadata for a
Worklight application.
Based on the W3C widget packaging and configuration
Can be edited using the editors Design or Source tab
Figure 4-37. Worklight application descriptor
WU5061.1
Notes:
The Worklight application descriptor, named application-descriptor.xml, is a metadata file
that is used to define various aspects of the application.

V8.1
Student Notebook
Uempty
Worklight application descriptor: Basic information

Specifies the application name, description and author details to be displayed in the
Worklight Console
Figure 4-38. Worklight application descriptor: Basic information
WU5061.1
Notes:
In the <application> tag, id defines the unique identifier of the application. It must be an
alphanumeric string that starts with a letter.
The application descriptor allows you to specify the application name, its description and
the authors name and contact e-mail address. This information is displayed in the
Worklight Console.

4-51
Student Notebook
Worklight application descriptor: Environments

Environment specific information is inserted automatically as new
environments are added to projects.
iPhone
environment
Android
environment
Figure 4-39. Worklight application descriptor: Environments
WU5061.1
Notes:
As mentioned before, the environment concept is an important building block of a Worklight
application. Environment specific information is defined in the application descriptor.
Each environment on which the application can run must be declared with a dedicated XML
element. Each such element has one mandatory attribute, version. The value of this
version is a string of the form x.y, where x and y are numeric.
When you create an environment, a new entry is be automatically added to the application
descriptor for you to further customize.

V8.1
Student Notebook
Uempty
4.6. Writing your code

4-53
Student Notebook
Writing your code
Figure 4-40. Writing your code
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Constructing the UI: Main HTML document (1 of 3)

Default application HTML template complies with HTML5 standard
markup
Any other DOCTYPE can be specified.
During the runtime of an application, the main HTML document cannot

be replaced by another HTML document
Figure 4-41. Constructing the UI: Main HTML document (1 of 3)
WU5061.1
Notes:
The main HTML file is created to comply with HTML5 standard markup as indicated by the
DOCTYPE definition. You may change this, but the HTML5 standard is highly
recommended. During the runtime of an application, the main HTML document cannot be
replaced by another HTML document.
At top of the file, a meta tag named viewport controls the rendering layout of the page on a
mobile browser. For example, it defines the devices width and how HTML content should
scale on the device.

4-55
Student Notebook
Constructing the UI: Main HTML document (3 of 3)

Insert the HTML code for your user interface right after the opening
<body> tag.
The main HTML file also takes the responsibility of loading your
application logic JavaScript files, authentication logic and localization
implementation if any.
Figure 4-42. Constructing the UI: Main HTML document (3 of 3)
WU5061.1
Notes:
Add a <script> tag to the body section, to define and load any additional business logic
JavaScript files that your application uses.

V8.1
Student Notebook
Uempty
Constructing the UI: Rich Page Editor

The Rich Page Editor allows you to construct your application user interface in a
WYSIWYG fashion
Drag HTML5 components from Palette view and drop on to the editor
Customize HTML and CSS properties in Properties view
Split view shows both source and design view
Palette
Figure 4-43. Constructing the UI: Rich Page Editor
WU5061.1
Notes:
Worklight Studio 6.0 contains a new rich page editor for building UI of mobile apps. The
editor enables developers to create HTML files by dragging HTML5 components and Dojo
Mobile components from a built-in palette to the HTML canvas, and using property sheets
to control HTML and CSS properties of the components. At the same time, the editor
allows direct editing of HTML and CSS files, automatically updating the graphical canvas
so that developers can immediately see the result of their changes. The editor is integrated
with the Worklight optimization framework, allowing developers to view a specific
application environment or skin.
You will learn more about the Rich Page Editor in a subsequent unit.

4-57
Student Notebook
Coding the business logic: Main JavaScript document

The applications main JavaScript file, <appName>.js, contains its
JavaScript functions
It has a wlCommonInit() function that is automatically invoked once
when the Worklight framework initializes
You can add your applications initialization code here
This function is used in environment-specific JavaScript files to have a common
initialization starting point
You can also add business logic to the main JavaScript file or put it in
separate files that you can declare in the main HTML file
Figure 4-44. Coding the business logic: Main JavaScript document
WU5061.1
Notes:
The <appName>.js file is the applications main JavaScript file and contains the application
logic.
By default, an empty JavaScript function named wlCommonInit() is defined in it. This
function is invoked automatically once when the Worklight framework initializes. This is the
place where you can add your applications initialization logic, such as making any
necessary backend connections, checking device features, and so on.
Also, this function is used in environment-specific JavaScript files to have a common
initialization starting point. You will learn more about this feature when you discuss Code
Optimization in a subsequent unit.

V8.1
Student Notebook
Uempty
Adding a new environment (1 of 2)

A new environment definition allows you
to write code customized to a particular
mobile platform.
To add a new environment:
Select the application folder.
Select Worklight Environment
from the Worklight drop-down
menu.

2013
Figure 4-45. Adding a new environment (1 of 2)
WU5061.1
Notes:
Alternatively, you can right-click the application folder and select New > Worklight
Environment. This launches the Worklight environment creation wizard.

4-59
Student Notebook
Adding a new environment (2 of 2)

In the Worklight Environment
window, select the check boxes for
the platforms that you wish to add
and click Finish.
The wizard generates an environment
folder in your application folder for each
platform selected.
Figure 4-46. Adding a new environment (2 of 2)
WU5061.1
Notes:
The Worklight Environment window allows you to select the different platforms for which
you want to create an environment in your application.

V8.1
Student Notebook
Uempty
Android environment generated folders

Two folders are automatically added:
android folder inside the application folder
Android project folder named
<yourProjectNameYourAppName>Andro
id in your workspace
This folder does not contain a copy of the
code, but is mapped to the native folder
in the android folder of the application.
Maps to
Figure 4-47. Android environment generated folders
WU5061.1
Notes:
After adding an Android environment, two new folders are automatically created in your
application folder:
A folder name android at the same level as the common folder
An Android project folder named <yourProjectNameYourApplName>Android in your
workspace. This auto-generated folder does not contain a copy of the code, but is
mapped to the native folder in the android folder of the application.

4-61
Student Notebook
Android environment folder structure

The android folder contains the following subfolders, similarly found in the common folder:
css
Properties specified here override CSS files from the
common folder
images
Android specific images can be added here. If an image
with same file name exists in the common folder, it will
be overwritten by the one in the android folder
js
JavaScript functions defined here extend or override
similarly name functions in the common folder
The native folder contains automatically generated

android application code that is mapped to the
Android project created for the application.
Do not edit files in the assets folder directly, as they are regenerated each time the application is built
Figure 4-48. Android environment folder structure
WU5061.1
Notes:
Worklight studio automatically creates three folders for the newly created Android
environment:
The css folder contains style properties that you want to override from css files in the
common folder. So, if you want to design a different look and feel for your Android user
interface, you can add or modify css files in this folder.
In the images folder, you can add Android specific images. If an image with the same
file name exists in the common folder, it will be overwritten in the Android application.
The js folder is created to allow you to add JavaScript that can extend or override
JavaScript code in the common folder.
The native folder created in the android environment folder contains automatically
generated Android application code and artifacts. These consist of the Android native code
that you compile and run on the Android emulator or a real device, and configuration files.
In this folder, Worklight packages its own native shell, Apache Cordova framework libraries
and all of the applications web content required to run it on an Android device.
V8.1
Student Notebook
Uempty
The assets sub-folder contains the entire web application resources including HTML,
JavaScript, CSS and image files. These are generated artifacts with optimization applied
for the Android environment. Do not directly edit the files in this folder, as they are
re-generated each time the application is built.
The contents of the native folder are packaged and automatically imported into the Eclipse
workspace as an Android project named yourProjectNameYourApplNameAndroid.

4-63
Student Notebook
iPhone environment generated folders (1 of 2)

A new folder named iphone is automatically
added to the application folder.
The package sub-folder appears only after you build
and deploy the application
The iphone folder contains the following subfolders, similarly found in the common folder:
css
Properties specified here override CSS files

from the common folder.
iOS specific images can be added here. If

an image with same file name exists in the
common folder, it will be overwritten by the
one in the iphone folder.
JavaScript functions defined here extend or

override similarly name functions in the
common folder
images
js
Figure 4-49. iPhone environment generated folders (1 of 2)
WU5061.1
Notes:
After adding an iPhone environment, a folder named iPhone is automatically created in
your application folder at the same level as the common folder.
Worklight studio automatically creates three folders for the newly created iPhone
environment:
The css folder contains style properties that you want to override from css files in the
common folder. So, if you want to design a different look and feel for your Android user
interface, you can add or modify css files in this folder.
In the images folder, you can add iOS specific images. If an image with the same file
name exists in the common folder, it will be overwritten in the iOS application.
The js folder is created to allow you to add JavaScript that can extend or override
JavaScript code in the common folder.

V8.1
Student Notebook
Uempty
iphone environment folder structure (2 of 2)

The native folder contains automatically
generated iphone application code.
Do not edit files in the www sub-folder directly, as
they are re-generated each time the application is
built
The nativeResources folder contains

resources that is used by the native code.
The package folder contains a packaged
(zipped) application.
Figure 4-50. iphone environment folder structure (2 of 2)
WU5061.1
Notes:
The native folder contains automatically generated iPhone application code that you can
compile and run in the Apple Xcode IDE. In this folder, Worklight packages its own native
shell, Apache Cordova framework libraries and all of the applications web content required
to run it on an iOS device.
The www sub-folder under native contains the entire web application resources including
HTML, JavaScript, CSS and image files. These are generated artifacts with optimization
applied for the iOS environment. Do not directly edit the files in this folder, as they are
re-generated each time the application is built.
The nativeResources folder hosts resources that are used by the native code.
The package folder contains a packaged (zipped) application that is ready to be transferred
to an Xcode environment to compile and build. This is useful when you are developing
your Worklight application on a Windows machine, and later want to transfer the code to a
Mac machine to compile and build.

4-65
Student Notebook

V8.1
Student Notebook
Uempty
4.7. Building your application

4-67
Student Notebook
Building your
application
Figure 4-51. Building your application
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Building an application
Select an application folder to build and
right-click it
Click Run As > Build All and Deploy
After the build completes, the application
is available for preview in the Worklight
Console
Figure 4-52. Building an application
WU5061.1
Notes:
You can choose to build for all environments or a specific one.
The build process creates a set of .wlapp files the bin folder of your Worklight project:
If you build for all environments, a file named <app-name>.wlapp is created, containing
the code and resources of all environments supported by your application (For
example: HelloWorklight.wlapp).
If you build only for specific environments, a file named <app-name>-<env><version>.wlapp is created for each environment (For example:
HelloWorklight-android-1.0.wlapp).
When the build process is finished, it deploys the application to the embedded Worklight
Server. You can then for preview it in the Worklight console.

4-69
Student Notebook

V8.1
Student Notebook
Uempty
4.8. Previewing and testing your application

4-71
Student Notebook
Previewing and testing

your application
Figure 4-53. Previewing and testing your application
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Application preview and test tools

A variety of tools are available to preview and test your application.
Preview tools allow to quickly test your applications look and basic functions.
Test tools can either be a virtual device simulator or a physical device.
Allow you to test more completely, particularly native functions.
To preview your application, use the Worklight Consoles:

Preview as common resources feature
Good for verifying the look and feel of your application
Mobile Browser Simulator
Can emulate Cordova functionality and previewing using different device
skins.
To test your application, use a:

Virtual device simulator (for example: Android Virtual Device (AVD) or iPhone
Simulator)
Physical device
Mandatory step before publishing your application
2013
Figure 4-54. Application preview and test tools
WU5061.1
Notes:
Previewing is normally the first step in your application testing, followed by a more thorough
test using a device simulator, and finally a complete test on a physical device.

4-73
Student Notebook

V8.1
Student Notebook
Uempty
4.9. Previewing your application in the browser

4-75
Student Notebook
Previewing your
application in the
browser
Figure 4-55. Previewing your application in the browser
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Previewing as a common resource

Open the Worklight Console in
the browser at:
http://<host
name>:8080/console
On the Catalog tab, click

Preview as Common
Resources.
The application is loaded and
rendered in a separate tab or
page.

2013
Figure 4-56. Previewing as a common resource
WU5061.1
Notes:
The Worklight Console is a web-based administration tool used to manage the Worklight
Server, installed applications and adapters, and push notification services.
The consoles Catalog tab lists all deployed applications and allows you to preview them.

4-77
Student Notebook
Previewing in the Mobile Browser Simulator

Requires that you add an environment to your application
For each added environment, the Worklight Consoles Catalog view
shows a preview icon and active text link to preview the application in
the corresponding browser simulator.
Figure 4-57. Previewing in the Mobile Browser Simulator
WU5061.1
Notes:
Click the preview icon or active link text to open the application in the Mobile Browser
Simulator for the specific environment.

V8.1
Student Notebook
Uempty
Mobile Browser Simulator: Android device
59
Figure 4-58. Mobile Browser Simulator: Android device
WU5061.1
Notes:
The Mobile Browser Simulator mimics a real device from a general look and feel
perspective. It allows you to emulate a number of Apache Cordova functions and alter the
device skins to see how your application renders on different devices. It also allows you to
customize the User Agent header value which is often used to detect a device type such as
iOS or Android.
In addition, because the Mobile Browser Simulator runs your application in a browser, you
can leverage the browsers debugging and development tools to do advanced debugging.
For example, you can use Firefoxs firebug tool to analyze the HTML DOM elements or set
breakpoints and step through JavaScript execution.
You will learn more about the Mobile Browser Simulator in a subsequent unit.

4-79
Student Notebook
Mobile Browser Simulator: iPhone device
60
Figure 4-59. Mobile Browser Simulator: iPhone device
WU5061.1
Notes:
You will learn more about the Mobile Browser Simulator in a subsequent unit.

V8.1
Student Notebook
Uempty
4.10.Testing on a simulator

4-81
Student Notebook
Testing on a simulator
Figure 4-60. Testing on a simulator
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Testing on the Android emulator (1 of 2)

When you build a Worklight application
with an Android environment, Worklight
Studio generates a separate Android
project for it in the workspace.
You are then be able to run the application
on the Android simulator by right clicking
the Android project and selecting Run As
> Android Application.
Figure 4-61. Testing on the Android emulator (1 of 2)
WU5061.1
Notes:
Worklight Studio simplifies the development and test of application for the Android platform.
When you build a Worklight application using Worklight Studio, the build process generates
a separate Android project that will automatically appear in your workspace. There are no
extra processes required to convert your Worklight application into an Android application.
Worklight Studio also take cares of application updates for the generated Android project.
This build process does require that you have the Android ADT and SDK installed prior to
the build.
To test and run your Worklight application on the Android emulator, you simply right click
your application, and select Run As > Android Application from the context menu as shown
in the figure here. You need to have at least one Android AVD created before you can run
your application as an Android Application.

4-83
Student Notebook
Testing on the Android emulator (2 of 2)

The Android emulator window allows you to test your application on an
Android virtual device.
Figure 4-62. Testing on the Android emulator (2 of 2)
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Testing on the iPhone simulator: Pre-requisites (1 of 2)

Testing an application on the iPhone
simulator requires building and running it
in Xcode.
If you are running Worklight Studio in
Eclipse on a Mac OS machine, open your
application directly in Xcode from within the
workbench:
Right-click the
apps/HelloWorklight/iphone folder
Select Run As -> Xcode Project.
Figure 4-63. Testing on the iPhone simulator: Pre-requisites (1 of 2)
WU5061.1
Notes:
The Eclipse IDE, where Worklight studio runs, does not support iOS application
development, therefore your application needs to be opened in Apples native Xcode IDE
to compile and run.
For developers running Eclipse on a Mac, Worklight studio simplifies this process by
integrating the Xcode launch process right in Eclipse. You can right-click iPhone project
and select Run as > Xcode project. The Worklight plug-in automatically opens the
application in Xcode. Alternatively, you can open a Mac Finder window, locate the iPhone
environments native folder, and double-click the applications .xcodeproj file.

4-85
Student Notebook
Testing on the iPhone simulator: Pre-requisites (2 of 2)

Testing an application on the iPhone simulator requires building and
running it in Xcode.
If you are running Worklight Studio in Eclipse on a non-Mac OS machine:
Transfer the applications Xcode project zip file to the Mac OS machine.
Extract the zip file.
Open the applications Xcode project file in Xcode.
Figure 4-64. Testing on the iPhone simulator: Pre-requisites (2 of 2)
WU5061.1
Notes:
If you are running a Windows version of Eclipse, copy and unzip the applications iPhone
archive file generated in the package folder to a folder on your Mac. Then, double-click the
applications .xcodeproj file from this folder to open it in Xcode.

V8.1
Student Notebook
Uempty
Testing on the iPhone simulator: Building and running an

application (1 of 2)
Select a device simulator type and version to use (Scheme) .
Click Run to build and launch your application in the simulator.
Figure 4-65. Testing on the iPhone simulator: Building and running an application (1 of 2)
WU5061.1
Notes:
Once in xCode IDE, simply click the Build and Run button to preview your application in
iOS simulator. Depends on the environment you are testing, you need to select the correct
simulator, either iPhone or iPad simulator.

4-87
Student Notebook
Testing on the iPhone simulator: Building and running your

application (2 of 2)
The iPhone simulator allows you to test your application on a virtual
device.
Figure 4-66. Testing on the iPhone simulator: Building and running your application (2 of 2)
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Testing on a device
Figure 4-67. Testing on a device
WU5061.1
Notes:

4-89
Student Notebook
Testing on an Android device

When building a mobile application, it's important that you always test
your application on a real device before releasing it to end users.
Testing on an Android physical device requires:
Installing an USB driver on your computer to recognize your device if it is not
supported by the generic Google USB Driver provided in the SDK
Enabling USB debugging on the device
Connecting the device to your computer using an USB cable
Once the pre-requisites are met, you can select to run your application
on the device in the Android Device Chooser window.
For more information on how to set up your development environment
and Android-powered device for on-device testing and debugging, visit:
http://developer.android.com/guide/developing/device.html
Figure 4-68. Testing on an Android device
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Testing on an iOS device: Pre-requisites

Before you can deploy to an iOS device, you need to:
Enroll in the iOS Developer Program
Requires a paid subscription
Can register as an individual or a company
Provision the device for development. This process involves:
Obtaining a developer certificate that allows you to sign applications.
Obtaining a provisioning profile that identifies your developer certificate, your
device, and the applications you can run on the device.
Figure 4-69. Testing on an iOS device: Pre-requisites
WU5061.1
Notes:
As set by Apple, in order to deploy an application on a physical device or preparing it for
distribution, you need to enroll in the Apple iOS Developer Program. During this step, you
may invite other developers to the development group if you register as company. Then,
developers need to manage the devices to be used for testing the application (for example,
create and install a provisioning profile).

4-91
Student Notebook
Testing on an iOS device pre-requisite: Enroll in the iOS

Developer Program
Before you can deploy and test on a physical device, you must enroll in
the iOS Developer Program.
Figure 4-70. Testing on an iOS device pre-requisite: Enroll in the iOS Developer Program
WU5061.1
Notes:
Use the following link to enroll in the iOS Developer Program:
https://developer.apple.com/programs/start/standard/
With the iOS simulator, you can start developing iOS applications without using an real
device. However, you must always test your applications on an actual devices before
publishing them to ensure that they run as intended and to performance tune them.
Before you can test an application on a real iOS device or distribute it to the Apple App
store, you need to enroll in as paid subscriber in the iOS Developer Program. During this
process, you can choose to register as an individual or as a company.

V8.1
Student Notebook
Uempty
Testing on an iOS device pre-requisite: Provision your

device
Before you can deploy and test an application on a physical device,
you must first build and install a Provisioning Profile on it. This involves
the multi-step process depicted below.
Figure 4-71. Testing on an iOS device pre-requisite: Provision your device
WU5061.1
Notes:
The process of preparing an iOS device to use for application deployment and testing
involves:
Creating a public/private key pair using the Mac KeyChain program on the developers
machine.
Submitting a Certificate Signing Request using the generated key on the iPhone
Developer Program Portal.
Downloading and storing the created development certificate on the developers
machine.
Registering the iOS devices Unique Device Identifier (UDID) to the Developer Program
Portal. You can usually find out a devices UDID either from iTunes or Xcode Organizer.
Creating a unique ID for your application (App ID).
Creating a Provisioning Profile with the development certificate, device identifier and
App ID in the iPhone Developer Program Portal.

4-93
Student Notebook
Downloading the Provisioning Profile to the local development machine and installing it
on the device.

V8.1
Student Notebook
Uempty
Testing on an iOS device

Once you have met the pre-requisites, you can follow the instructions
below to test your application on the device.
Connect your device to your computer using an USB cable.
In Xcode, select an actual device in the Scheme drop-down menu.
Click Run. After your code compiles successfully, Xcode uploads and runs your
application on the device.
More info can be obtained at the Apple iOS Development Center:

http://developer.apple.com/devcenter/ios/index.action
Figure 4-72. Testing on an iOS device
WU5061.1
Notes:

4-95
Student Notebook
Publishing your
application
Figure 4-73. Publishing your application
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Publishing your application: Preparation

Prior to building a production version of your application, set the
worklightSettings property in of your application-descriptor.xml to
false.
This disables the ability of the user to change the address of the Worklight
Server with which the application communicates via the devices settings screen.
Figure 4-74. Publishing your application: Preparation
WU5061.1
Notes:
When you have successfully completed application development and on-device testing,
you can distribute your application for public access. Prior to doing so, prepare it as
indicated in this slide.

4-97
Student Notebook
Publishing your Android application in Google Play

To distribute your Android application for public access, use Google
Play.
Google Play (rebranded from Android Market in March 2012) is a
hosted service that:
Simplifies the download and installation process of applications to Androidpowered devices.
Makes it easy for developers to publish their applications for Android users.
Google Play requires that you create an account to use it.

To sign-up, visit: http://market.android.com/publish/signup
For more Information on Google Play, visit: https://play.google.com/

For a publishing checklist for Google Play, visit:
http://developer.android.com/distribute/googleplay/publish/preparing.html/
Figure 4-75. Publishing your Android application in Google Play
WU5061.1
Notes:
To distribute your Android application for public use, use Google Play.
Publishing on Google Play takes a few simple steps: register, configure, upload, and
publish.
During the registration process you will need to create a developer profile, pay a
registration fee, and agree to the Google Play Developer Distribution Agreement.
After you register you can access the Developer Console, where you can upload
applications, configure publishing options, and monitor publishing data.
When you have configured your application information and publishing options, you can
upload the Android application .apk file and publish it in Google Play for public access.

V8.1
Student Notebook
Uempty
Publishing your iPhone application in the App Store

iOS application deployment is done via the Apple App Store.
The deployment process is defined by Apple and involves:
Signing up for the iOS Developer Program if you havent already done so.
Submitting a certificate signing request.
Downloading the certificate and creating a distribution provisioning profile.
Submitting the application for App Store approval.
Normally takes about a week or so.
For detailed information on how to prepare an application for

submission and the App Store approval process, visit:
https://developer.apple.com/appstore/index.html
Figure 4-76. Publishing your iPhone application in the App Store
WU5061.1
Notes:
To distribute your iPhone application for public use, use the Apple App Store.

4-99
Student Notebook
Checkpoint
1. True or False: For iOS development, you need the Xcode IDE in
addition to Worklight Studio in order to compile an application and
2. What is default structure of a Worklight application?
a)
A single HTML file, and a number of CSS and JS files
b)
c)
A number of HTML and JS files, and a single CSS file

A number of HTML, JS, and CSS files
d)
A single HTML, single CSS, and a single JS file
3. The purpose of adding an environment to an application is to:

a)
b)
Import a specific platform SDK into Worklight Studio.

Allow you to write customized code for a specific platform on which you intend
to run the application.
c)
Define an additional Worklight Server where you can deploy the application.
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Checkpoint answers
1. True or False: For iOS development, you need the Xcode IDE in
addition to Worklight Studio in order to compile an application and
True
2. What is default structure of a Worklight application?

a)
A single HTML file, and a number of CSS and JS files
b)
c)
A number of HTML and JS files, and a single CSS file

A number of HTML, JS, and CSS files
d)
A single HTML, single CSS, and a single JS file

a) A single HTML file, and a number of CSS and JS files
3. The purpose of adding an environment to an application is to:

a)
b)
c)
Import a specific platform SDK into Worklight Studio.

Allow you to customize the application for a specific target platform.
Define an additional Worklight Server where you can deploy the application.
b) Allow you to customize the application for a specific target platform.
WU5061.1
Notes:

4-101
Student Notebook
Unit summary
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Exercise 1
Installing IBM Worklight Studio

and developing your first
application
Figure 4-80. Exercise 1
WU5061.1
Notes:

4-103
Student Notebook
Exercise objectives
After completing this exercise, you should be able to:
Install IBM Worklight Studio from an IBM Worklight V6.0 Developer
Edition package
Configure an Android development environment
Develop a simple Hello Worklight mobile application
Test the simple application in the browser and on an Android or iOS
virtual device
Figure 4-81. Exercise objectives
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Unit 5. Client-side core APIs

This unit provides a deep-dive look into key client-side mobile
development APIs provided by Worklight. These APIs include those
that enable cross-platform portability, device type customization, and
application globalization.

Identify essential Worklight client-side APIs including those that
enable cross-platform portability and localization
Explore the syntax of the JavaScript functions supporting the APIs

Checkpoint
Exercise
References

5-1
Student Notebook
Unit objectives
Identify essential Worklight client-side APIs including those that enable
cross-platform portability and localization
WU5061.1
Notes:
5-2

V8.1
Student Notebook
Uempty
Topics
Client-side basics
Building a multi-page application
Common controls
Skins
Offline access
String translation
Figure 5-2. Topics
WU5061.1
Notes:

5-3
Student Notebook
5-4

V8.1
Student Notebook
Uempty
5.1. Client-side basics

5-5
Student Notebook
Client-side basics

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
Figure 5-3. Client-side basics
8.0
WU5061.1
Notes:
5-6

V8.1
Student Notebook
Uempty
Application sources
Main HTML file:
For example, HelloWorklight.html
Main JavaScript file:

For example, HelloWorklight.js
messages.js: used for storing application

strings; primarily used for localization.
HelloWorklight.html
HelloWorklight.js
Messages.js
initOptions.js
wljq.js
wlclient.js
wlcommon.js
wlfragment.js
worklight.js
busy.js
Figure 5-4. Application sources
WU5061.1
Notes:
The main HTML file is the ultimate loader for all application and Worklight client API
JavaScripts. Worklight client runtime depends on this HTML file to define and actually load
the necessary APIs. Some of JavaScript loading only shows up on generated environment
specific main HTML file.
The main JavaScript file contains application logic including initialization, back-end data
access and loading of other application logic modules.
Messages.js is used for storing application strings, primarily used for localization.
Normally, the application developer works with the main HTML and JavaScript files.
The main HTML and main JavaScript files are available under the application common
folder when a new Worklight application is created. These are application specific
components that are developed and owned by your development team.
Another core library used by Worklight client API (not shown on slide) is the jQuery library.
Worklight comes bundled with an encapsulated jQuery, which can be added to developers
project with a single line of code. jQuery is discussed in a later unit.

5-7
Student Notebook
Worklight initialization
Defines application initialization options
HelloWorklight.html
HelloWorklight.js
Messages.js
initOptions.js
wljq.js
wlclient.js
wlcommon.js
wlfragment.js
worklight.js
busy.js
Figure 5-5. Worklight initialization
WU5061.1
Notes:
The initOptions.js file is included in the project template. It is used to initialize the Worklight
JavaScript framework. It contains a number of tailoring options, which you can use to
change the behavior of the JavaScript framework. These options are commented out in the
supplied file. To use them, uncomment and modify the appropriate lines.
The initOptions.js file calls WL.Client.init, passing an options object that includes any
values you have overridden.
5-8

V8.1
Student Notebook
Uempty
jQuery JavaScript framework

Worklight includes an encapsulated
jQuery, which can be added to the
developer project with a single line of
code:
window.$ = window.jQuery = WLJQ;
HelloWorklight.html
HelloWorklight.js
Messages.js
initOptions.js
wljq.js
wlclient.js
wlcommon.js
wlfragment.js
worklight.js
busy.js
Figure 5-6. jQuery JavaScript framework
WU5061.1
Notes:
In IBM Worklight V6, the jQuery library that is used as part of the product is upgraded to
version 1.9. If you are using other JavaScript libraries such as jQuery Mobile, you should
upgrade the version.
Note carefully the reference for the encapsulated jQuery in Worklight that is shown on this
page. It should be placed in the appName.js file. There is no error message, or problem
indicated if you do not include this line. But you may find that you get strange results (such
as an empty view) if you forget it!

5-9
Student Notebook
Worklight client JavaScript API

Worklight Client API uses WL namespace
Provides bridging to native mobile
platform APIs, dynamic HTML load, and
so on
HelloWorklight.html
HelloWorklight.js
Messages.js
initOptions.js
wljq.js
wlclient.js
wlcommon.js
wlfragment.js
worklight.js
busy.js
Figure 5-7. Worklight client JavaScript API
WU5061.1
Notes:
There are several reference to these APIs, as well as to the WL namespace, throughout
this course.

V8.1
Student Notebook
Uempty
The WL namespace
To use Worklight API, a WL namespace is used
WL.Client, WL.Utils, and so on
Exposes the API objects, methods, and constants (usually enums)

Automatically added to the application main HTML file
wlcommon.js
wlclient.js
worklight.js
WL Namespace is automatically available on application initialization
Figure 5-8. The WL namespace
WU5061.1
Notes:
The WL namespace is fundamental to the Worklight API (WL.Client, WL.Utils, and so on).
The application HTML page is initialized with WL.Client.init() in the body onload attribute.
The namespace is automatically available when the application is initialized.

5-11
Student Notebook
WL.Client
WL.Client.init (options) initializes the WL.Client object
onSuccess
onFailure
connectOnStartup
busyOptions
WL.Client.reloadApp() - reloads the application

WL.Client.login (realm, options) triggers login
WL.Client.logout (realm, options) triggers logout
General application information can be obtained by using:
WL.Client.getEnvironment ()
WL.Environment.ADOBE_AIR
WL.Client.invokeProcedure (invocationData, options) retrieves and

updates enterprise data
Figure 5-9. WL.Client
WU5061.1
Notes:
The onSuccess function is used to initialize the application.
If an onFailure function is not passed, a default onFailure function is called. If onFailure is
passed, it overrides any specific failure-handling function.
connectOnStartup: Whether to connect to the IBM Worklight Server. The default if no value
is specified is true. However, the value as set in the initOptions.js file is false. The value
false is appropriate if your application does not retrieve any corporate data on startup.
Note, though, that any server features such as Remote Disable or Direct Update are only
available after the application connects to the server.
The value true is appropriate if your application must receive data from the server when it
starts. However, the application might start more slowly.
WL.Client.reloadApp() - reloads the application. It can be used to recover an application
from errors. It is preferable to avoid using it and to use alternative error handling
mechanisms instead. The method is mainly available for compatibility with earlier versions.

V8.1
Student Notebook
Uempty
WL.Logger
A part of the WL.Client library
To enable the logger you must set the option on WL.Client.init(options)
WL.Client.init({showLogger:true})
A troubleshooting tool, it should only be used in the development

environment
Delete the code for production
Output can be directed to an environment console

Xcode console, Adobe AIR, Android Logcat, for example
WL.Logger.debug (msg, exc)
WL.Logger.error (msg, exc)
msg is the string to be displayed
exc is a JavaScript exception reference (optional)
Figure 5-10. WL.Logger
WU5061.1
Notes:
The WL.Logger.debug and WL.Logger.error methods output a specified debug or error
message to the environments log.
For iPhone and iPad, these methods print the message to the debugger console of Xcode,
the development environment for iPhone and iPad.
For Android, these methods print the message to the Android LogCat, accessible in the
Android development environment. Error messages are displayed in red; debug messages
are displayed in the default log line color.
For BlackBerry 6 and 7, these methods print the message to the BlackBerry event log. The
event log can be viewed on the device and in the BlackBerry Eclipse simulator and
debugger by pressing the key sequence Alt+LGLG.
To disable logging, include enableLogger: false in the object wlInitOptions in the
initOptions.js file.
var wlInitOptions = {enableLogger: false }

5-13
Student Notebook
WL.Logger - example
Use to troubleshoot environments without debugging tools
WL.Logger.debug(message)
WL.Logger.error(message)
The output is sent to the console
Figure 5-11. WL.Logger - example
WU5061.1
Notes:
The Logger API is intended as a development tool. If there is a need to inform the user
about a problem, there are other more appropriate ways to display the information (an alert,
for example). There is also WL.Client.logActivity (activityType). This stores custom log lines
for auditing and reporting purposes in special database tables, and is the API to use for
production-level auditing.

V8.1
Student Notebook
Uempty
5.2. Building a multi-page application

5-15
Student Notebook
Building a multi-page
application

Figure 5-12. Building a multi-page application
8.0
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Working with pages

Applications with multiple pages can be built in two ways
Single HTML file

containing all
application pages
Application.html
Application.html
<div
<div
<div
<div
<div
<div
<div
<div
<div
<div
<div
<div
id=loginPage>
id=loginPage>
id=Page1>
id=Page1>
id=Page2>
id=Page2>
id=Page3>
id=Page3>
id=Page4>
id=Page4>
id=Page5>
id=Page5>
.......
.......
Separate HTML file

for each application
page
loginPage.html
loginPage.html
Page1.html
Page1.html
Page2.html
Page2.html
Page3.html
Page3.html
Page4.html
Page4.html
Page5.html
Page5.html
Figure 5-13. Working with pages
WU5061.1
Notes:
Worklight multi-page applications can be built in two ways:
You can host your entire application content in a single HTML file. Different components of
an application or mobile pages can be grouped under a unique div block. The application
developer can control which div page to show and programmatically handle the transition
between pages. This is good for very simple application.
A single HTML file is the preferred model for a simpler applications. However, large
applications present a challenge:
- The developer has to take full responsibility of which <div> elements are shown and
which are hidden at any given moment.
- If you want to add some new content to a page, e.g. a table, you cannot load a
prepared template but must generate it manually.
- Single large HTML files with lots of divs take longer to load.
- It is easy to get lost in a single HTML file containing multiple pages. Separate files
are easier to manage.

5-17
Student Notebook
A Worklight hybrid application uses the single DOM model, which means that you must
never navigate between various HTML files by using hyperlinks or changing
window.location property
Instead, multi page interfaces must be implemented by loading external HTML file content,
using Ajax requests and injecting it into existing DOM. This is because the main application
HTML file loads the Worklight client side JavaScript framework files, and when the browser
navigates from one HTML file to another, the JavaScript context and loaded scripts are lost.
Most JavaScript UI frameworks (for example, jQuery Mobile, Sencha Touch, Dojo Mobile)
available today provide extensive APIs to achieve required multi-page navigation.
In this module, you learn how to build a multi-page Worklight application by using built-in
functionality only.
Important you must not use the built-in functionality that is described in this module if you
are using a JavaScript UI framework. You should use the framework APIs instead.

V8.1
Student Notebook
Uempty
Splitting code between HTML pages

To split code between pages, use the fragment implementation of
JavaScript frameworks such as jQuery Mobile, Sencha, and Dojo
Mobile
Fragments are files that contain html tags that can be appended to a
parent element. Fragments can include JavaScript files by adding a
<script> tag and style sheets by adding a <link> tag. For example:
<link
<link href="css/page1.css"
href="css/page1.css" />
/>
<script
src="js/page1.js"
type="text/javascript"></script>
<script src="js/page1.js" type="text/javascript"></script>
<div
<div id="page1div">
id="page1div">
This
This is
is page1
page1
</div>
</div>
Inline JavaScript and CSS are not supported in fragments.
Figure 5-14. Splitting code between HTML pages
WU5061.1
Notes:
For more information, see http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp, and
search for Splitting Your Code between HTML Pages (URL correct as of July 2013).

5-19
Student Notebook
Design considerations
Building a rich dynamic application with multiple pages can be easier
with dynamic pages loading
You can use built-in jQuery APIs to dynamically load, update and insert
DOM elements in your application
HTML pages with CSS and JavaScript can be inserted on the fly.
Possible to implement navigation history
JavaScript code can be executed when pages are loaded or unloaded
In the following slides you learn and implement a simple multi page
navigation interface
Figure 5-15. Design considerations
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Loading an external HTML file

An external HTML file is a segment of HTML code that can be injected
into any location in the existing DOM
May include JavaScript by using <script> tag
May include CSS files by using <link> tag
Injected into parent element, usually <div>, but not mandatory
Implemented using jQuery $().load() API
To load an HTML file, use the following syntax:
$(containerSelector).load(filePath,
$(containerSelector).load(filePath, callbackFunction);
callbackFunction);
Figure 5-16. Loading an external HTML file
WU5061.1
Notes:
Here is a definition of the elements of the code on the slide:
- containerSelector jQuery css selector of element to host the loaded content
- filePath Relative path to an HTML file. Always relative to main HTML file
- callbackFunction - a JavaScript function to execute when loading completes

5-21
Student Notebook
Loading an external HTML file example

This code loads MainPage.html file and inserts its content into the
pagePort <div> element
JavaScript and CSS from MainPage.html are loaded to DOM
When MainPage.html load completes alert(loaded!) is executed
Figure 5-17. Loading an external HTML file - example
WU5061.1
Notes:
MainPage.html does not replace MulitPageApp.html its contents is added to the div that
has the id pagePort. The load function takes two arguments: what to load, and what to do
after the load has completed. In the example on the image, an alert will be displayed once
the contents of MainPage.html is added to the pagePort div element.

V8.1
Student Notebook
Uempty
Implementing page navigation with history (1 of 4)

By using the technique described previously, you can implement a
navigation interface with history
You keep the navigation history as a stack in an array object
You also keep a reference to a currently loaded page functionality by
using a JavaScript object variable
Application
Application
HTML
HTML file
file
MainPage.html
MainPage.html
MainPage.js
MainPage.js
Page1.html
Page1.html
Page1.js
Page1.js
var
var == pagesHistory
pagesHistory == [];
[];
var
var == currentPage
currentPage == {};
{};
Figure 5-18. Implementing page navigation with history (1 of 4)
WU5061.1
Notes:
This page shows the general scenario that is discussed over the next three pages. The two
problems to address are: What do you want to see next, and where did you come from to
get to this view. Therefore, you need to add the correct page to the application html, and
keep navigation history so that you can return.

5-23
Student Notebook

Application
Application
HTML
HTML file
file
MainPage.html
MainPage.html
MainPage.js
MainPage.js
WU5061.1
Notes:
1. On application start MainPage.html is loaded from the application code and injected into
the #pagePort div
2. As a part of MainPage.html, MainPage.js is loaded
3. The currentPage object is declared
4. The currentPage.init function is declared
5. When the MainPage.html loading completes, currentPage.init method is called

V8.1
Student Notebook
Uempty

MainPage.html
MainPage.html
MainPage.js
MainPage.js
Page1.html
Page1.html
Page1.js
Page1.js
WU5061.1
Notes:
1. MainPage.html is pushed into pagesHistory stack
2. Page1.html is loaded and injected into #pagePort div
3. Page1.js is loaded as a part of Page1.html
4. currentPage object is declared (overriding the old one)
5. currentPage.init function is declared
6. When Page1.html loading completes, a new currentPage.init method is called

5-25
Student Notebook

MainPage.html
MainPage.html
MainPage.js
MainPage.js
Page1.html
Page1.html
Page1.js
Page1.js
WU5061.1
Notes:
1. Previous html file name is popped from the pagesHistory stack (MainPage.html).
2. It is loaded and injected into #pagePort <div>
3. MainPage.js is loaded as a part of MainPage.html
4. currentPage object is declared (overriding the old one)
5. currentPage.init function is declared
6. When MainPage.html loading completes, the currentPage.init method is called

V8.1
Student Notebook
Uempty
5.3. Common controls

5-27
Student Notebook
Common controls

Figure 5-22. Common controls
8.0
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
What is a common control?

Some controls are common to most environments, such as modal popup windows, loading screens, tab bars, and so on.
Worklight provides a JavaScript API to invoke these controls
regardless of the environment. It automatically renders them in a native
way for each mobile platform.
Busy indicator
Tab bar
Simple dialog
Figure 5-23. What is a common control?
WU5061.1
Notes:
Worklight common controls are sets of pre-built client side libraries or UI widgets for
frequently used UI functions such as modal popup, loading screens, tab bars, and so on.
These UI components are common to most device environments. Worklight provides a
JavaScript API to invoke these controls regardless of environment, and automatically
renders them in a native way for each platform.
Developers can therefore save a lot of time, since they so not have to build these UI
component controls. They customize them to render in a native fashion for each supported
device environment.
In this section, you explore 4 different types of common controls.

5-29
Student Notebook
WL.BusyIndicator (1 of 3)
WL.BusyIndicator implements a common API to display a modal
activity indicator
Uses native implementation on Android, iPhone and Windows Phone
platforms
Figure 5-24. WL.BusyIndicator (1 of 3)
WU5061.1
Notes:
The WL.BusyIndicator object can be used to display a modal, dynamic graphical image
when the application is temporarily busy, that is, not responsive to user input. This is
important from user experience perspective.
WL.BusyIndicator is implemented natively on iOS, Android, BlackBerry, and Windows
Phone as shown from the images on this page. In other environments it is implementing
using JavaScript with Busy.js.
One of the benefit of using this common control is that application developers dont need to
develop a native look and feel indicator for all the supported platforms, but rather accesses
a single unified Worklight API.

V8.1
Student Notebook
Uempty
Must be initialized before use
The parent element ID for WL.BusyIndicator is ignored in iOS,
Android, Windows Phone and BlackBerry environments
Available options are:
text: set the modal text
color: set the modal text
fullScreen: use if modal message should be displayed full screen (iOS only)
Parent element ID (web only)
Options
WU5061.1
Notes:
The application initializes the BusyIndicator by creating a new WL.BusyIndicator object.
The first parameter specifies the parent element ID where the WL.BusyIndicator is
placed. This parameter is ignored in iOS, Android, Windows Phone and BlackBerry
environments.
The second parameter specifies the look and feel and general behavior of the
BusyIndicator. For example, the text message to be displayed in the BusyIndicator and
color of the text etc. These options varies for different device platform. For example.
Android supports only text property. For detail information about additional options, refer to
the Developers Guide.

5-31
Student Notebook
WL.BusyIndicator provides the following API:
Initialization
void myBusyIndicator.show(): displays busy indicator
void myBusyIndicator.hide(): hides busy indicator
boolean myBusyIndicator.isVisible(): returns whether busy indicator is currently
visible
WU5061.1
Notes:
Once a BusyIndicator is created, you can issue show() and hide() method to either display
or hide the defined busy indicator.
To test whether the busy indicator is currently visible, you can use isVisible() method.

V8.1
Student Notebook
Uempty
WL.SimpleDialog (1 of 3)
WL.SimpleDialog implements a common API for showing a modal dialog window with
buttons
Uses native implementation on mobile platforms
Figure 5-27. WL.SimpleDialog (1 of 3)
WU5061.1
Notes:
WL.SimpleDialog implements a common API for showing a dialog with buttons for the
application. This technology is useful in constructing informational popups or getting users
attention.
The implementation of Worklight SimpleDialog depends on the environment. On iPhone,
Android, and BlackBerry as shown in the images in this slide, WL.SimpleDialog opens a
native dialog box; on other environments it opens an HTML dialog box. The goal is to
provide a native look and feel dialog box with a single unified API.
WL.SimpleDialog supports up to three buttons.

5-33
Student Notebook
Invocation syntax is:
Parameters: title, text, and buttons as an array of up to three button objects
The dialog is closed when any of the buttons is clicked
WU5061.1
Notes:
To display the SimpleDialog, call WL.SimpleDialog.show() function anywhere in your code.
With this common control, the dialog is displayed without blocking the JavaScript thread.
Worklight SimpleDialog takes four parameters:
The first parameter defines the title of the dialog box. It is mandatory.
The second parameter defines the text to show in the dialog box. It is also mandatory.
The third parameter represents the buttons to be placed in the dialog. You can add up
to three buttons.
The options parameter is ignored by iPhone and Android. It has the form { title: string,
text: string}.
The active Dialog is closed when any of the buttons is pressed.

V8.1
Student Notebook
Uempty
Each button object has two properties:
text: the text that is displayed on the button
handler: function to invoke if button is clicked
WU5061.1
Notes:
You can add up to 3 buttons to the simple Dialog. They are defined in an array of JSON
Objects, each array item represents a button on the dialog.
An button object can contain two properties: he text that is displayed on the button and
a callback handler function to invoke if button is pressed. This is where application logic
can respond to decisions from the Dialog actions.

5-35
Student Notebook
WL.TabBar (1 of 5)
Both Android and iOS environments support tabbed application
navigation with a tab bar component
Figure 5-30. WL.TabBar (1 of 5)
WU5061.1
Notes:
The Android and iPhone tab bars are graphical element which look and work very much
like tab bars of regular web or desktop applications. They provide an simple navigation
mechanism for users to easily browse through the application on a mobile device.
Worklight provides a client-side API for managing the tab bar. On iPhone, this API serves
as a proxy to the native iPhone tab bar object; on Android, it is implemented as an HTML
element.
The screens captures depict an iPhone tab bar (on the left) and an Android tab bar (on the
right).

V8.1
Student Notebook
Uempty
WL.TabBar (2 of 5)
iOS implementation takes
advantage of a native
component, while Android uses
an HTML generated tab-bar
The syntax is very similar,
although there are some minor
differences
Not here!
WL.TabBar must be initialized

before use
WL.TabBar.init();
Initialize WL.TabBar in a
designated JavaScript file
WU5061.1
Notes:
WL.TabBar implementation for iOS and Android are slightly different. Thus, the Worklight
JavaScript libraries for Tab bar component is not packaged under common folder, but
stored under iPhone and Android environment js folder respectively. Even with some minor
differences, the API syntax are very similar for both platforms.
Like most of Worklight common controls, you need to initialized the Tab bar before using it
on both platforms. The API you use is WL.TabBar.init(). It is recommended to initialize
WL.TabBar in a designated JavaScript file. Normally, the high level main JavaScript file of
your application.
The init function Initializes the tab bar by creating necessary JavaScript objects and
enabling it, but keeping it invisible.

5-37
Student Notebook
WL.TabBar (3 of 5)
Use the following syntax to add a tab bar item:
itemID: Internal reference for this tab
callback: JavaScript function to run when tab item is pressed
title: The text to display on tab bar item
options: Varies on iOS and Android platform, see next slide
WU5061.1
Notes:
Before displaying a tab bar on the device, application needs to add tab items. A tab item
represents a navigation entry for your application.
Note, you can only add tab bar items after Tab bar is initialized.
You use WL.TabBar.addItem to add a tab item. This API takes four parameter:
First is the item id that uniquely identifies this tab item.
The callback function that should be invoked when the user touches this tab item. For
example, load a new page or bring up a Dialog box when this tab item is touched.
The third parameter specifies title text for this tab item for display.
The fourth parameter is an option object that contains device specific information of
how to render the tab item.

V8.1
Student Notebook
Uempty
WL.TabBar (4 of 5)
iOS options
Android options
badge: string to display on items

badge
image: file name of an image to use
or native iOS button identifier:
image: file name of an image to use

for an unselected state
imageSelected: file name of an
image to use for a selected state
tabButton:More
tabButton:Favorites
tabButton:Featured
tabButton:TopRated
tabButton:Recents
tabButton:Contacts
tabButton:History
tabButton:Bookmarks
tabButton:Search
tabButton:Downloads
tabButton:MostRecent
tabButton:MostViewed
WU5061.1
Notes:
On iPhone, you can specify the badge and image options. iPhone Badge is a string to
display in the optional circular badge on the item. The image property defines the filename
or path with a PNG image for the tab or an internal identifier for standard tabs. Worklight
allows application place some default iPhone tab item images such as defined in the list
here.
If the supplied image name is one of the labels listed here, then a tab button is constructed
using the standard system buttons. Note that if you use one of the system images, the title
you supply is ignored.
Similar to iPhone, the image property for Android defines a filename or path with a PNG
image for the tab in unselected mode. The imageSelected property defines filename with
an image for the tab in selected mode.

5-39
Student Notebook
WL.TabBar (5 of 5)
iOS example:
Android example:
WU5061.1
Notes:
The example here illustrates how to add an tab item on iOS and Android devices using
Worklight addItem API. Review the code in order to become familiar with API used here.

V8.1
Student Notebook
Uempty
WL.OptionsMenu (1 of 4)
Android and Windows Phone environments have
the ability to display an options menu
Figure 5-35. WL.OptionsMenu (1 of 4)
WU5061.1
Notes:
Option menu is available on Android and Windows phones as shown in the images on this
slide.
On Android, The Options menu contains primary functionality that applies globally to the
current activity or starts a related activity. It is typically invoked by a user pressing a button,
often labeled Menu.
Worklight provides a client-side API for managing the menu and application bar.

5-41
Student Notebook
Initialize WL.OptionsMenu in the
appropriate JavaScript file
The syntax is very similar to that of the
tab bar with some minor changes
Not here!
WL.OptionsMenu.init();
Not here!
WU5061.1
Notes:
You need to initialize the Worklight OptionsMenu before you can use it. To do this, use
WL.OptionsMenu.init. It is recommended to initialize WL.TabBar in the main JavaScript file
of your application.
Worklight OptionsMenu syntax is very similar to that of the TabBar. WL.OptionsMenu is
packaged under the same Worklight library JavaScript CommonControl.js as TabBar.

V8.1
Student Notebook
Uempty
Use the following syntax to add an options menu:
itemID: Internal reference for this menu option
callback: JavaScript function to run when menu option is pressed
title: The text of the menu item
options: An options object with the following properties:
image: A path to a designated image, relative to resources root directory.
48x48px black and white .png file
enabled: Boolean stating if the item is enabled or disabled
WU5061.1
Notes:
To add an option menu, use the API WL.OptionsMenu.addItem . This API can be called
only after initializing the Options menu. Items are placed in the menu in the order in which
they were added. If you add an item with an existing ID, the new item replaces the existing
one.
It can take up to 4 parameters:
ItemID represents the unique identifier of a menu item
Second parameter defines callback function that should be invoked when the user
selects the item in the options menu.
You can specify the Menu title text via the third parameter.
The Options parameter allows the application to customize the menu item and set it to
enabled or disabled.

5-43
Student Notebook
WL.OptionsMenu.addTab example
WU5061.1
Notes:
The example here illustrate how to add a Worklight OptionMenu item. It adds a menu item
named as First item with callback function that shows an alert popup indicating that the
first item is selected.
This menu item displays an image file from images/tabicon.png. The code sets this menu
item to show as enabled when menu button is pressed, if this is on Android device.

V8.1
Student Notebook
Uempty
5.4. Skins

5-45
Student Notebook
Skins

Figure 5-39. Skins
8.0
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Skins
Provide support for multiple form factors in a single executable file for
devices of the same OS family
A sub-variant of an environment
Packaged together in one App
The decision on which skin to use is made automatically at runtime
Figure 5-40. Skins
WU5061.1
Notes:
Worklight Skins are provided to support multiple form factors in a single executable file for
devices of the same OS family. An application skin is a set of web resources that govern
the application look and feel, and behavior. Skins are used to adjust the application to
different devices of the same family.
They are sub-variants of an environment. For example, your application may require a
different look and feel for Android phones and Android tablets. In this case, you can create
a android.tablet skin to host all the code required for this unique device type.
All application skins are packaged together in one Worklight application along with the
associated environment. You can package multiple skins in your application and decide in
run time, upon application startup, which skin to apply to the application.

5-47
Student Notebook
Skin use cases

Different screen sizes (for example, iPhone versus iPad)
Different input methods (for example, touchpad versus keypad)
Different screen densities
Support for HTML5
Figure 5-41. Skin use cases
WU5061.1
Notes:
This slide looks at some of typical use case where you can apply Worklight Skins. First, you
may want to design applications for devices with different screen sizes under same OS
family; for example, develop Android phones application and android tablets application.
You can also use skins to specify the handling for different screen densities. Screen density
is the measurement of the resolution of particular devices. For example, create skins for
HTC vs. Samsung devices that have different screen densities.
Besides look and feel, you can also create different skins to handle different device input
methods. For example, touch vs. Keyboard based input method.

V8.1
Student Notebook
Uempty
Skin creation and packaging

Create skins by using the Worklight Skin Wizard
Skin directories are created next to environment directory
Directories contain HTML, CSS, JavaScript files
All skins for a specific environment are packaged within the app
Figure 5-42. Skin creation and packaging
WU5061.1
Notes:
Worklight Studio provides a wizard to create an application skin. You select the target
application, right click it to bring up the context menu, then select Worklight Application
Skin Wizard.
In the new skin wizard, the application developer needs to specify the skin name. The
wizard automatically prefixes your skin name with the OS family it associated with, for
example Android or iPhone.
Upon creating the new skin, Worklight generates a folder for the skin resources under the
name you specified in the wizard, for example android.phone. This folder is placed
adjacent to the environment directory.
The example screen capture on the left shows the wizard for a skin called android.phone.
The screen capture on the right shows the directories where the skin is packaged.

5-49
Student Notebook
Applying skins at run time

A developer-written JavaScript file is run at application startup
Determines which skin to load
The default skinLoader.js contains samples
Figure 5-43. Applying skins at run time
WU5061.1
Notes:
When a skin is added, a JavaScript file named skinLoader.js is created under the js folder
of the environment.
The application developer implements the function getSkinName() of the skinLoader.js file.
There, you define the rules and policy on how to load a particularly skin based on your use
case. For example, you can add logic to check device manufacture model, and then apply
associated skin to this runtime.

V8.1
Student Notebook
Uempty
Skin Registration
Skins are automatically registered in the application descriptor
Determines the hierarchy between the common folder, environment
and skin
Modify the application
descriptor manually
when a skin is deleted
Figure 5-44. Skin Registration
WU5061.1
Notes:
When adding a new application skin, Worklight studio adds a <skin> element in the
application descriptor. This element includes the name of the skin and a list of resource
folders. When the Studio builds the application, it applies the optimization rules on the
resource folders in the order they appear within the <skin> element.
The <skin> element includes the name of the skin and a list of resource folders. When the
Studio builds the application, it applies the optimization rules on the resource folders in the
order they appear within the <skin> element.
In the example here, two skins are packaged with the Android application: the default skin
and another two skins called android.phone and android.tablet.
To delete a skin, remove the element defining the skin from the apps descriptor. This is a
manual process.

5-51
Student Notebook

V8.1
Student Notebook
Uempty
5.5. Offline access

5-53
Student Notebook
Offline access

Figure 5-45. Offline access
8.0
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Working in Offline Mode

The Worklight Platform allows developers to detect application
connectivity failures and determine course of action
Applications going off- and on-line can be detected in two ways:
Explicitly, upon invoking server-based procedures
Implicitly, using JavaScript event listeners
Developers can define custom application behavior for off- and on-line
status
Figure 5-46. Working in Offline Mode
WU5061.1
Notes:
Unlike traditional desktop web applications, mobile device are likely to lose connectivity to
the internet or any backend connections, for example, when there is very weak or no
wireless signal, or when user is on an airplane or in a tunnel. So, enable application to
continue operating even without any connectivity becomes a frequent requirement when
constructing mobile application in order to provide best user experience. We generally
referring application working without connectivity as Working in offline mode.
There are three ingredients to enable application to work in offline mode:
1. The application code and supporting binary should be made available during offline
mode.
2. Application needs to be able to detect connectivity status in order to switch application
processing to either online or offline mode.
3. Application and supporting environment need to be able to persist key application data
to local device in offline mode.

5-55
Student Notebook
Worklight provides a framework to address all three requirement in order to build a true
offline-enabled application.
First, for mobile application built with web technologies, Worklight either package it as a
hybrid application so that all web artifacts such as HTML and CSS files are downloaded to
local device along with application download process. For pure mobile web app, Worklight
uses HTML5 App cache feature to allow web artifacts to be downloaded and stored locally
on mobile device.
The Worklight client frameworks provides a set of APIs that application can use to detect
network connectivity status to decide go offline or online.
In the Worklight environment, application going off and online can be detected in two ways
Explicitly or Implicitly.
Explicitly detects occurs when your application launches or tries to invoke Worklight server
based procedures.
Implicitly detection is basically an event driven programming model. Your application
registered to certain network connectivity events then react to it.
In both case, application developer can define custom application logic to handle off and
online status. For example, retrieve application data from local storage when application
goes offline, and save and update local storage when application comes back online.

V8.1
Student Notebook
Uempty
Explicit detection: using methods

There are two locations where connectivity loss can be detected:
Application initialization: WL.Client.init() method, usually called from initOptions.js
Adapter procedure invocation: WL.Client.invokeProcedure() method
To use connectivity failure detection add onConnectionFailure, and

specify a callback function to be invoked if connectivity fails
Figure 5-47. Explicit detection: using methods
WU5061.1
Notes:
There are two locations in your application code where connectivity loss can be detected:
The first place is during the application initialization phase. Worklight invokes a
WL.Client.init() method to initialize application. This method is normally invoked from the
main HTML body onload. The other place where you can detect connectivity is when
application invokes adapter procedure via API WL.Client.invokeProcedure.
Both API can take an option parameter that you can specify the connectivity detection
logic.
To add connectivity failure detection in either of them, add onConnectionFailure property
instead of onFailure and specify a callback function to be invoked in case connectivity fails.
Application developer often focus on implementing the callback function to react to offline
condition.

5-57
Student Notebook
Implicit Detection: offline/online events

Each time the Worklight framework attempts to access the Worklight
Server, it might detect that the application has switched from offline to
online status or vice versa
In each case, JavaScript events are fired
WL.Events.WORKLIGHT_IS_DISCONNECTED event is fired when connectivity
to the Worklight Server fails
WL.Events.WORKLIGHT_IS_CONNECTED event is fired when connectivity to
the Worklight Server is restored
Developers can add event listeners to these events and specify the
callback functions that handle them
Figure 5-48. Implicit Detection: offline/online events
WU5061.1
Notes:
Note that both WL.Events.WORKLIGHT_IS_DISCONNECTED and
WL.Events.WORKLIGHT_IS_CONNECTED are namespace constants, not strings.
Implicit detection helps to handle unexpected connectivity loss and allow application to
react to the offline mode.
Each time the Worklight framework attempts to access the Worklight Server, it might detect
that the application has switched from offline to online status or vice versa. This is handled
completely by Worklight framework such as heartbeat (discussed later).
In both cases, one of two JavaScript events can be fired
- WL.Events.WORKLIGHT_IS_DISCONNECTED event is fired in case connectivity
to the Worklight Server fails
- WL.Events.WORKLIGHT_IS_CONNECTED event is fired in case connectivity to
the Worklight Server is restored
As application developer, you need to add event listeners for these two events and
specify the callback functions so that your application can react accordingly.
V8.1
Student Notebook
Uempty
You add this event registration process using the JavaScript function
Document.addEventLister(), and pass the Worklight event constants and callback
function name to this registration function. The third parameter, capture, is a boolean
value that specifies whether the event needs to be captured or bubbled. A value of false
indicates that the event is bubbled (a discussion of capture, target, and bubble is
outside of the scope of this course. You can find detailed information on the web).

5-59
Student Notebook
isConnected() and connect()

Additional methods are provided by the Worklight framework to simplify
online/offline development:
WL.Client.isConnected (): Returns Boolean value for latest known
connectivity state; True for online; False for offline
WL.Client.connect (options): Attempts to connect to the Worklight
Server and return to online mode; options is an object containing the following
keys:
onSuccess: Callback function to invoke in case server connection is
established
onFailure: Callback function to invoke in case server connection fails
Timeout: Number of milliseconds to wait for the server response before
failing with request timeout
Figure 5-49. isConnected() and connect()
WU5061.1
Notes:
Another useful API Worklight provided is WL.Client.connect.
This call attempts to establish a connection to the Worklight Server and return to online
mode. It takes a Worklight options parameter which contains the following keys:
onSuccess is the Callback function to invoke in case server connection is
established
Likewise, onFailure defines Callback function to invoke in case server
connection fails
Timeout can be used to define Number of milliseconds to wait for the server
response before failing with request timeout
Often, this API is used when application goes back online or returns to device
foreground, where connectivity needs to restored.

V8.1
Student Notebook
Uempty
getNetworkInfo()
WL.Device.getNetworkInfo() method is available for iOS and
Android environments
A callback must be specified as a function parameter
Figure 5-50. getNetworkInfo()
WU5061.1
Notes:
For applications running on iOS and Android devices, you can use the
WL.Device.getNetworkInfo API to fetch network information from the device, and return it
to the specified callback function.
The callback function receives a JSON structure with these properties:
isAirplaneMode: true/false
carrierName: string (for example, AT&T, VERIZON, and so on)
telephonyNetworkType: string (for example, UMTS or GPRS)
isRoaming: true/false
networkConnectionType: mobile/WIFI
ipAddress: string
isNetworkConnected: true/false

5-61
Student Notebook

V8.1
Student Notebook
Uempty
Foreground event
When the Worklight Application returns to foreground, a foreground
JavaScript event is fired
Developers can add a listener to this event and specify the callback
functions to handle it
Figure 5-51. Foreground event
WU5061.1
Notes:
A mobile application may be frequently put into the background when user works on
another application, ortakes a phone call. When the mobile application comes back to the
foreground, the developer may want to want to add some initialization and sanity check
logic; for example, to ensure that connection is available.
To accomplish this, Worklight fires a foreground event when the application comes back
to foreground. It is easy for application developers to add a listener to this event and
specify the callback functions that can handle it.
This technique is particularly useful for cases in which the user has left the application to
restart connectivity on the device, expecting the application to connect when they return. In
this case, the developer can use the document.addEventListener API to registered the
foreground event as shown in the code snippet in this slide, then attempt to reconnect to
server if it detects that server connectivity is not available.

5-63
Student Notebook
Worklight heartbeat
Worklight heartbeat is designed to periodically ping the server to verify
connectivity
Use the heartbeat to verify that the application remains connected to
the server
You can set a heartbeat interval on application initialization, or at any
point during execution
Figure 5-52. Worklight heartbeat
WU5061.1
Notes:
The heartbeat interval is set by default to 420 seconds (7 minutes). You can specify the
heartbeat interval by using WL.Client.setHeartBeatInterval(intervalSeconds)
A value of -1 disables the heartbeat.

V8.1
Student Notebook
Uempty
5.6. String translation

5-65
Student Notebook
String translation

Figure 5-53. String translation
8.0
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Introduction to translation
You can use the Worklight framework to enable translation of
applications into other languages
You can set up translations for
Application strings
System messages
The Worklight Platform can automatically translate the application

strings according to a designated file
Multi-language translation can be implemented using JavaScript
Figure 5-54. Introduction to translation
WU5061.1
Notes:
Translation is part of the overall Globalization or localization process of computing
systems. Globalization normally refers to the process of designing and developing a mobile
application that functions in multiple cultures and locales. The globalization process
normally includes identifying the culture and locale that must be supported, Designing
features which support them, and writing code that functions equally well in any of the
supported cultures/locales.
Under IBM Worklights globalization system, the main focus is on translating the mobile
application to languages other than English. The specific items or software components
that can be translated are application Strings, and system messages.
Application strings are essentially static UI texts displayed or used in your mobile
application. Examples include the title of a page, menu labels, and so on. System
messages are messages your mobile application uses to communicate information, either
to the end user or among application components themselves. These tend to be low level
messages. Examples include error messages to warn user that network connection has
lost, and so on.

5-67
Student Notebook
Worklight platform simplifies the translation process by automatically matching and

translating the text Strings based on a designated file. This file is the message.js file that is
discussed later.
For other advanced mutli-language support, developers can also use JavaScript to extend
the function of the Worklight translation framework.

V8.1
Student Notebook
Uempty
Enabling translation
The messages.js file, which is designated for application strings,
is in the common/js folder
Application messages stored in messages.js can be referenced
in two ways:
As a JavaScript object property, for example, Messages.sampleText
As an ID of an HTML element
with class=translate
Figure 5-55. Enabling translation
WU5061.1
Notes:
Application String translation is often applied to the UI texts that are either defined in the
HTML file or dynamically generated using JavaScript.
Worklight translation is handled by a designated file under common/js folder named
message.js. It contains a dictionary object for localizing texts. If not specified, the default
object Messages (located in the same file) is used. Remember, you can also customize the
globalization by providing message.js file in your environment or skin folders.
The default message.js contains language a name:value pair dictionary for the default
locale or language.
There are two usage scenarios for applying globalized application strings. One is using
JavaScript to apply predefined messages using a JavaScript object property. For example,
under message.js you have a Messages dictionary defined in which you have a property
defined as header. In the JavaScript code, you can uses the JavaScript objective property
Messages.header to represent the text you want to use or display. Worklight replaces the
string with the message defined in message.js.

5-69
Student Notebook
You can also use message.js declaratively. This is used primarily for static HTML content.
You define an HTML element with class=translate and an element id that can be mapped
in message.js. Worklight uses the HTML element id field to find the matching string
definition in the Message.js file and replace the HTML element content with it. For example,
if you have a HTML div tag with id sampleText and a class attribute translate, the content is
replaced by Worklight if you have a sampleText property under the Messages object
defined in your message.js file. This is illustrated in the screen captures.

V8.1
Student Notebook
Uempty
Translating system messages

It is also possible to translate system messages that the application shows, for
example Internet connection is not available or Invalid user name or password
System messages are stored in WL.ClientMessages object
A full list of system messages can be found in wlclient/js/messages.js file inside
Worklight-generated projects (iOS, Android, and so on)
To enable translation for a system message, override it in your application
JavaScript
Figure 5-56. Translating system messages
WU5061.1
Notes:
You can also globalize system messages that the application shows, for example Internet
connection not available, or invalid user name or password. These tend to be messages
used by low level application logic often implemented in JavaScript component.
System messages are located under the environment folder, in wlclient/js, under the name
message.js.
To translate a system message, override it in your application JavaScript, normally in a
global level JavaScript component because some parts of the code are executed only after
successful application initialization.
For example, if you want to localize the message which warns users when a
requestTimeOut event occurs, you can overwrite the message
WL.ClientMessage.requestTimeout to a value you specify.

5-71
Student Notebook
Multi-language translation: set up the Strings

It is possible to implement multi-language translation for your
applications by using JavaScript
Set up default application strings in messages.js
Override specific strings when required
Figure 5-57. Multi-language translation: set up the Strings
WU5061.1
Notes:
To enable multi-language support, you can use JavaScript to override a specific string to
target the language you want to support.
For example, you start with defining a default language translation dictionary in
message.js. Then, override the string in a JavaScript function, as shown here.
You should implement this override in a global level JavaScript component so that it can be
used throughout your application.

V8.1
Student Notebook
Uempty
Multi-language translation: selecting the language

Bind a change in the value of the element id languages to the function
getLang()
Get the device locale and extract the locale String
Check the locale and call getLang()
The getLang() function is shown on the next slide
Figure 5-58. Multi-language translation: selecting the language
WU5061.1
Notes:
As a common practice, you might want to apply locale detection before applying translation
to your application.
Worklight allows you to do so easily using two APIs:
WL.App.getDeviceLocale() which returns the locale code according to user's device
settings, for example: en_US.
WL.App.getDeviceLanguage() which returns the language of the users device.

5-73
Student Notebook
Detecting device locale and language

Switch language Strings by calling on of the set<Language>() functions
If the chosen language flows from right to left, switch the direction
Figure 5-59. Detecting device locale and language
WU5061.1
Notes:
Example (refer to the previous page):
assume Messages = {header: Default header, actionsLabel: Default action}
The locale is detected as fr. getLang() is called with the String french (it may be simpler
to pass the detected locale identifier, but this is for the demonstration!).
The case that corresponds to the language calls the setFrench() function, which sets
Messages.header = Traduction. The message values are now:
{header: Traduction, actionsLabel: Default action}
Note that actionsLabel has not been changed. The function reset the header value, but any
String that is not reset has its original value.
The example shown on this page has been simplified for clarity. You would need
$("#AppBody").css({direction : ltr'}) as the first line of the function, since if you change to
Hebrew (right to left), then back to French, you would need to change the direction back
also! You also require a setEnglish() function. Although English is the default language in

V8.1
Student Notebook
Uempty
this example, you should provide the possibility of reverting to it if you change, for example,
to French.

5-75
Student Notebook
Checkpoint questions (1 of 2)
1. What is messages.js used for?
A. This file contains the texts of application prompts
B. This file contains the texts of error messages that the application can show
C. An internal framework file, it is used to store system messages for debugging
purposes
D. This file contains strings that can be used for application elements
2. Which API can be used across all environments to debug the

Worklight application?
A. console.log
B. console.debug
C. WL.Logger.debug
D. WL.Debugger.log
Figure 5-60. Checkpoint questions (1 of 2)
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Checkpoint questions (2 of 2)
1. A tab bar is an example of
A. A busy indicator
B. A simple dialog
C. An options menu
D. A common control
2. To display a modal activity indicator, you can use

A. WL.SimpleDialog
B. WL.BusyIndicator
C. WL.OptionsMenu
D. WL.TabBar
Figure 5-61. Checkpoint questions (2 of 2)
WU5061.1
Notes:

5-77
Student Notebook
Unit summary
Identify essential Worklight client-side APIs including those that enable
cross-platform portability and localization
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Checkpoint answers
1. D. This file contains strings that can be used for application elements
2. C. WL.Logger.debug
3. D. A common control
4. B. WL.BusyIndicator
WU5061.1
Notes:

5-79
Student Notebook
Exploring IBM Worklight

client-side APIs
Exercise 2

Figure 5-64. Exploring IBM Worklight client-side APIs
8.0
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Exercise objectives
Use Worklight client-side functions to access device environment
information, and use common controls and skins
WU5061.1
Notes:

5-81
Student Notebook

V8.1
Student Notebook
Uempty
Unit 6. Local storage APIs

This unit provides a detailed look into the encrypted cache and
JSONStore local storage APIs provided by Worklight.

Identify the Worklight client-side APIs that support storing data
locally on a device in an encrypted cache or a JSON data store.

Checkpoint
Exercise
References

6-1
Student Notebook
Unit objectives
Identify the Worklight client-side APIs that support storing data locally on a
device in an encrypted cache or a JSON data store.
WU5061.1
Notes:
6-2

V8.1
Student Notebook
Uempty
Topics
Encrypted cache
JSON data store
Figure 6-2. Topics
WU5061.1
Notes:

6-3
Student Notebook
6-4

V8.1
Student Notebook
Uempty
6.1. Encrypted cache

6-5
Student Notebook
Encrypted cache

Figure 6-3. Encrypted cache
8.0
WU5061.1
Notes:
6-6

V8.1
Student Notebook
Uempty
What is encrypted cache?

Encrypted cache is a mechanism for storing sensitive data on the client side
Implemented by using HTML5 local storage technology, which allows data to
be saved locally and retrieved on subsequent application use or re-launch
Data is encrypted with a combination of a user-provided key and serverretrieved randomly generated token, which makes it more secure
Data is stored using key-value pairs
Encrypted cache is just like a security deposit box - it remains open until you
close it, so it is important to close the cache once you are done working with it
Figure 6-4. What is encrypted cache?
WU5061.1
Notes:
Encrypted cache is a mechanism for storing sensitive data on the client side so that
application can continue operating even without server connection where normally
application data is retrieved from.
Under the cover, Worklight Encrypted cache is implemented using HTML5 local storage
technology which allows data to be saved locally as key-value pair.
Beyond the HTML5 Local Storage, Worklight encrypts the data persisted under the local
storage so that it makes your application more secure. Worklight uses a combination of
user-provided key and server-retrieved randomly generated token to encrypt the data.
Once application creates and opens an encrypted cache, it will remain open until
application closes it. So, one of best practices is to also clean and close your local cache
once you are done working with it.

6-7
Student Notebook
Supported Browsers and Devices
Show all
versions
iOS Safari
3 versions
back
3.2
2 versions
back
Opera Mini
Opera Mobile
Android
browser
4.0-4.1
10.0
2.1
Previous
version
4.2-4.3
11.0
2.2
Current
version
5.0
11.1
2.3-3.0
5.0-6.0
Near future
4.0
Supported=
Not supported=
Figure 6-5. Supported Browsers and Devices
WU5061.1
Notes:
Worklight encrypted cache support on browsers and mobile devices are driven by the
support for HTML5 Web storage technology.
Majority of the mobile devices are currently supporting HTML5 Web storage technology.
Please reference this chart for device supporting detail.
As a general development best practice, development may want to add web storage
feature detection logic in application JavaScript file before creating and using Encrypted
cache.
Additional information can be obtained at http://caniuse.com
6-8

V8.1
Student Notebook
Uempty
Creating or opening encrypted cache

To create or open a previously created encrypted cache, use the following API:
WL.EncryptedCache.Open(credentials, createIfNone,
onComplete);
credentials: string value representing user-provided password
createIfNone: Boolean value specifying whether new encrypted cache should
be created in case none is found
onComplete: a callback function to be invoked when cache opening/creating
is complete
onError: a callback function to be invoked when cache is not successfully
opened/created
Figure 6-6. Creating or opening encrypted cache
WU5061.1
Notes:
Note that the application must be able to connect to Worklight server in order to create a
new encrypted cache.
Worklight API WL.EncryptedCache.Open: opens an existing cache, or creates a new
cache, that will be encrypted using the provided credentials. This method runs
asynchronously because the key generation process is a lengthy process.
The process of creating a new cache involves obtaining a random number from the
Worklight Server. Hence, the action of creating a new cache requires that the app is
connected to the Worklight Server. Once a cache has been created, it can subsequently be
opened without a connection.
This API take three parameters when creating or opening a local cache:
Credentials, this first parameter is the string value representing user-provided password
The second parameter is a Boolean value specifying whether new encrypted cache should
be created in case none is found

6-9
Student Notebook
Lastly, you can provide call back function to be invoked when cache opening/creating is
complete
In your callback function, check the status of creating or opening an encrypted cache.
Application can get three possible status,
When an encrypted cache is successfully created or opened,
WL.EncryptedCache.OK status code will be returned to your call back function.
Normally, your application logic of storing or retrieving data should happen only when
successful status is detected.
WL.EncryptedCache.ERROR_CREDENTIALS_MISMATCH status will be returned
when an attempt was made to open existing encrypted cache using wrong credentials.
Finally, if the call is used to create a new local cache, worklight needs to contact
worklight server component to get the random security token. If worklight is
unable to generate random token due to Worklight Server unavailability, a
WL.EncryptedCache.ERROR_SECURE_RANDOM_GENERATOR_UNAVAILABLE
status will be returned.
Your application can catch WL.EncryptedCache.ERROR_NO_EOC exception to
handle the case where application could not open encrypted cache because it was not
previously created.
When a particularly device doesnt support HTML5 local storage, an Exception will be
thrown when you try to invoke Worklight open API. Use this in conjunction with the
HTML5 local storage feature detection logic we mentioned before can prevent
unexpected behavior when using Worklight Encrypted Cache.
Finally, if current application already issued to open or changeCredential call and still
waiting those procedure to complete, another attempt to open the same local cache will
results in an Exception being thrown by Worklight , this Exception is
WL.EncryptedCache.ERROR_KEY_CREATION_IN_PROGRESS

V8.1
Student Notebook
Uempty
Encrypted cache status

A callback function can receive one of the following statuses:
WL.EncryptedCache.OK Encrypted cache was successfully opened or
created
WL.EncryptedCache.ERROR_CREDENTIALS_MISMATCH an attempt was
made to open existing encrypted cache using wrong credentials
WL.EncryptedCache.ERROR_SECURE_RANDOM_GENERATOR_UNAVAIL
ABLE unable to generate random token due to Worklight Server unavailability
WL.EncryptedCache.ERROR_NO_EOC could not open encrypted cache
because it was not previously created
WL.EncryptedCache.ERROR_LOCAL_STORAGE_NOT_SUPPORTED device
does not support HTML5 local storage
WL.EncryptedCache.ERROR_KEY_CREATION_IN_PROGRESS an open()
or changeCredentials() request is already running
Figure 6-7. Encrypted cache status
WU5061.1
Notes:

6-11
Student Notebook
Opening encrypted cache example
Figure 6-8. Opening encrypted cache example
WU5061.1
Notes:
The sample code here shows how to evaluate the Cache open or create status.

V8.1
Student Notebook
Uempty
Reading and writing data with encrypted cache

When the encrypted cache is open, you can perform operations on it such as
reading, writing and removing data
To store data in encrypted cache use the following API:
WL.EncryptedCache.write(credentials, value, onSuccess, onFailure);
10
Figure 6-9. Reading and writing data with encrypted cache
WU5061.1
Notes:

6-13
Student Notebook
Reading and removing data from encrypted cache

To read data from the encrypted cache use the following API:
WL.EncryptedCache.read(credentials, onSuccess, onFailure);
To remove data from the encrypted cache use the following API:
WL.EncryptedCache.remove(key, onSuccess, onFailure);
11
Figure 6-10. Reading and removing data from encrypted cache
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Closing encrypted cache

To avoid possible undesired access to encrypted cache, close it
After encrypted cache is closed, access to its data is not possible without the
encryption key that was used to create it
Use the following API to close the encrypted cache
WL.EncryptedCache.close(onComplete, onFailure);
12
Figure 6-11. Closing encrypted cache
WU5061.1
Notes:

6-15
Student Notebook
Destroying encrypted cache

Encrypted cache can be wiped from the local storage
After encrypted cache is destroyed there is no way to return the data that was
stored in it
Destroy encrypted cache only if you are sure that data stored in it will never be
required again, or as a last measure if the encryption key is lost
To destroy an encrypted cache use the following API:
WL.EncryptedCache.destroy(onComplete, onError);
13
Figure 6-12. Destroying encrypted cache
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Changing the encryption key

While encrypted cache is in the open state, it is possible to change the
encryption key
To do so, use the following API:
WL.EncryptedCache.changeCredentials(credentials, onComplete, onError)
credentials new user password to be used.
onComplete a callback function to be invoked when complete.
onError a callback function to be invoked in case of an error.
Callback receives a status object with same structure as

WL.EncryptedCache.open()
14
Figure 6-13. Changing the encryption key
WU5061.1
Notes:

6-17
Student Notebook

V8.1
Student Notebook
Uempty
6.2. JSONStore

6-19
Student Notebook
JSONStore

Figure 6-14. JSONStore
8.0
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
What is JSONStore?
JSONStore is a JavaScript API for data storage and manipulation, based on
JavaScript Object Notation (JSON)
Similar to local storage or DOM storage, but with some advantages
It provides the following key features:
Storage of new and existing data that you can search, update, and delete without
network connectivity
Ability to pull and push data to your back-end system
Encryption for stored data
Tooling for you to get started
Figure 6-15. What is JSONStore?
WU5061.1
Notes:
You can write an application that maintains a local copy of its data and, on request, pushes
the local updates to a back-end service.
The local copy is a JSON data store. IBM Worklight supplies an API for working with a
JSON Store through the methods of the JavaScript class WL.JSONStore.
Using the JSONStore API, you can extend the existing adapter connectivity model to store
data locally and push changes from the client to a server. You can search the local data
store and update and delete data within it. You can secure the local data store by using
password-based encryption.

6-21
Student Notebook
Comparison of storage technologies
Figure 6-16. Comparison of storage technologies
WU5061.1
Notes:
(1): These features are further described in the module JSONStore Common
JSONStore usage.
(2): Reliable Storage means that your data is not deleted unless the application is removed
from the device or one of the
methods that removes data is called.
(3): Dev. Only means that it is designed only for development. There are no security
features and a ~5 MB storage space
limit.
If you are developing Worklight hybrid apps that target iOS and Android, consider working
with JSONStore instead of Encrypted. CacheThe key reason for this statement is Apples
position that HTML5 local storage is not guaranteed to be persistent on future iOS
versions. JSONStore uses the same encryption form and security mechanisms (PBKDF2
for key derivation from user password and AES 256) as current Encrypted Cache. For

V8.1
Student Notebook
Uempty
more information, search the IBM Worklight Information Center for the class
WL.JSONStore http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp

6-23
Student Notebook
JSONStore terminology: document

Document: JavaScript object with an auto-generated identifier (_id) and data in JSON format, similar to a
record or row in database terminology
Example:
var doc = {
_id: 1,
json: {
name: 'carlos',
age: 99
}
};
Figure 6-17. JSONStore terminology: document
WU5061.1
Notes:
JSONStore is not a relational database, but this unit uses relational database terminology
to explain some basic concepts. For example, the way data is structured through schemas
when using a relational database differs to the JSONStore approach, where you can store
any JSON content, and index what you need to search on.
Document: A JavaScript object that has an _id key that holds an integer and a json key that
holds a JavaScript object. Document is an internal structure we generate when you add or
store data, _id should not be modified. It is similar to a record or to a row in database
terminology.

V8.1
Student Notebook
Uempty
Example:
var doc = {
_id: 1,
json: {
name: 'carlos',
age: 99
}
};
You can also have an array of documents. Example:
var doc = [{_id : 0, json : {fn : 'carlos', age : 99, active : false}}];

6-25
Student Notebook
JSONStore terminology: collection

A collection is a named logical grouping of related documents, similar to a
table in the database terminology
Example -- Customer Collection
[
{ _id: 1, json: {name: 'carlos', age: 99} },
{ _id: 2, json: {name: 'tim', age: 100} },
]
Internal storage
Customer collection
Document:
{_id: 1, json:
{name: carlos,
age: 99}}
Document:
{_id: 2, json:
{name: 'tim',
age: 100}}
Figure 6-18. JSONStore terminology: collection
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
JSONStore terminology: search field

A search field is a JavaScript object with a key and a data type.
These keys are indexed for fast look-up times.
It is like column fields or attributes in the database terminology.
Additional search fields are keys that are indexed, but are not part of the
JSON data that is stored
These fields define the key whose values (in a given JSON collection) are
indexed, and therefore used to search faster
These fields can be of the following data types: string, boolean, number and
integer
These types determine how indexable fields are stored
For example: defining {age: 'number'} indexes 1 as 1.0, while defining{age:
'integer'} indexes 1 as 1.
Examples:
var searchField = {name: 'string', age: 'integer'};
var additionalSearchField = {key: 'string'};
Figure 6-19. JSONStore terminology: search field
WU5061.1
Notes:
searchFields: defines the keys in JavaScript objects that are indexed, thus determining
what you can query in a collection. The keys in the searchFields object must correspond to
paths in the stored JSON object. Search field keys will be applied to the JSON objects in a
style similar to object['keyPart1]['keyPart2']. When a searchField is located in the
JavaScript object, it will only be indexed if the value is a simple type (integer, number,
boolean, or string). The values for search fields are type hints and must be one of 'string',
'integer', 'number', or 'boolean'. The type declared in the searchField does not have to
match the type of the item matched at runtime, but the better the match the better the
optimization that can be done.
In the example below, the fields fn, age, gpa and active will only match keys found at the
top level of the JavaScript object: var myObj = { age: 42 }, and would not match var myObj2
= { person : {age : 18 } }, the search field would have to be person.age to match this case.
Example:
var searchfields = { fn : 'string',
age : 'integer',

6-27
Student Notebook
gpa : 'number', //floating point or int

active : 'boolean',
'address.state' : 'string' };
Query: a JavaScript object that does not contain nested objects or arrays. Keys must be
specified in the search fields or be the special _id identifier. Example:
var query = {_id : 0};
var query = {fn : 'carlos'};
var query = {age : 99};
var query = {active : false};
var query = {'address.state' : 'TX'};

V8.1
Student Notebook
Uempty
JSONStore terminology: query

query: JavaScript object that use search fields or additional search fields to
look for documents
Example: in the figure, the search field is the string name. When you query the
collection for name equals carlos, it identifies what document to return
Internal storage
Customer collection
Search field name (string)
carlos
Document:
{_id: 1, json:
{name: carlos}}
tina
Document:
{_id: 1, json:
{name: tina}}
Figure 6-20. JSONStore terminology: query
WU5061.1
Notes:
Queries are JavaScript objects that use search fields or additional
search fields to look for documents.
?? The following example presumes that name and age are search
fields, of types string and integer respectively.
?? Examples:
Find documents with name that matches carlos:
var query1 = {name: 'carlos'};
Find documents with name that matches carlos and age that
matches 99:
var query2 = {name: 'carlos', age: 99};

6-29
Student Notebook
Store internals
Example: the people table
When you search the people table with one or a combination of the
following queries, the retrieved document is {_id: 1, json: {name:
'carlos', age: 99} } :
{_id : 1}
{name: 'carlos'}
{age: 99}
{key: 'c'}
Figure 6-21. Store internals
WU5061.1
Notes:
In this example, the key elements are:
_id is the unique identifier (example: AUTO INCREMENT
PRIMARY KEY).
json contains an exact representation of the stored JSON object.
name and age are search fields.
key is an additional search field.
people is the collection name.

V8.1
Student Notebook
Uempty
Error object
The Error object is a JavaScript object that is returned when a JSONStore operation
(such as find or add) fails.
The Error object provides information about the cause of the failure.
Example:
var errorObject = {
src: 'find', //operation that failed
err: -50, //error code
msg: 'PERSISTENT_STORE_FAILURE', //error message
col: 'people', //collection name
usr: 'jsonstore', //username
doc: {_id: 1, {name: 'carlos', age: 99}}, //document that
the failure relates to
res: {...} //response from the server
}
Not all the key-value pairs are part of all Error objects
For example, the response from the server is available only when operations that use
the network fail, such as push
Figure 6-22. Error object
WU5061.1
Notes:

6-31
Student Notebook
JSONStore architecture
1. JSONStore requests data from a Worklight adapter
2. The adapter requests data from the enterprise service
3. The enterprise service returns data
4. The adapter returns data in JSON format
5. Data is stored on the device
Enterprise systems
Worklight
Web layer
2
Adapter
JSONStore
JavaScript API
5
REST, SOAP, SQL or
Cast Iron
Internal
storage
Native layer
Figure 6-23. JSONStore architecture
WU5061.1
Notes:
The JSONStore can be used to create a collection either from an adapter or otherwise.
When tied to an adapter, the API supports a convention of tying the various sync
operations (pushing to server) based on the action the user can perform on the local
collection in the JSONStore.

V8.1
Student Notebook
Uempty
Sending data back

1. JSONStore requests data from the internal storage
2. The internal storage returns JSON documents
3. JSONStore sends those documents to an adapter
4. The Worklight adapter sends data to the enterprise service
Enterprise systems
Worklight
Web layer
Adapter
JSONStore
JavaScript API
1
REST, SOAP, SQL or
Cast Iron
Internal
storage
Native layer
Figure 6-24. Sending data back
WU5061.1
Notes:

6-33
Student Notebook
JSONStore API
API is only in JavaScript, and mostly asynchronous
You can use it only when you develop Worklight hybrid applications, and you
must wait for callbacks to get results
options: an object that contains onSuccess and onFailure keys

These keys might have functions as values that execute after the operation
finishes
var
var
var
var
var
var
win
win == function
function (data)
(data) {{ };
};
fail
fail == function
function (data)
(data) {{ };
};
options
=
{onSuccess:
win,
options = {onSuccess: win, onFailure:
onFailure: fail};
fail};
Figure 6-25. JSONStore API
WU5061.1
Notes:
options: a JavaScript object that contains the failure and success callback functions.
Additional parameters may be accepted and will be documented in their respective
methods. These success and failure callbacks are specific to the function you're calling, for
example the onSuccess function passed to initCollection will only be called when
initCollection is successful.

V8.1
Student Notebook
Uempty
Initialization
Use init to start one or more JSONStore collections
Starting or provisioning a collection means creating the persistent storage that
contains collections and documents, if it does not exist
Example:
var
var collectionName
collectionName == 'people';
'people';
The sample app has a button
to initialize a collection.
//Object
//Object that
that defines
defines all
all the
the collections
collections
var
var collections
collections == {};
{};
//Object
//Object that
that defines
defines the
the 'people'
'people' collection
collection
collections[collectionName]
collections[collectionName] == {};
{};
//Object
//Object that
that defines
defines the
the Search
Search Fields
Fields for
for the
the 'people'
'people' collection
collection
collections[collectionName].searchFields
collections[collectionName].searchFields == {name:
{name: 'string',
'string', age:
age: 'integer'}
'integer'}
WL.JSONStore.init(collections)
.then(function
.then(function ()
() {{
//handle
//handle success
success
})
})
.fail(function
.fail(function (errorObject)
(errorObject) {{
//handle
//handle failure
failure
});
});
Figure 6-26. Initialization
WU5061.1
Notes:
Creates a new object to interact with a single collection. If local storage for the collection
does not exist, it is provisioned with the searchFields. Otherwise, the searchFields is
validated against the searchFields used to originally provision the collection.
Use init to start one or more JSONStore collections.
?? Starting or provisioning a collection means creating the persistent
storage that contains collections and documents, if it does not exist.
?? If the persistent storage is encrypted and a correct password is
passed, the necessary security procedures to make the data
accessible are run.
?? For optional features that you can enable at initialization time, see
Security, Multiple user support, and Worklight adapter
integration, in the second part of this module.

6-35
Student Notebook

V8.1
Student Notebook
Uempty
Get
Use get to create an accessor to the collection
You must call init before you call get, otherwise the result of get is undefined
Example:
var collectionName = 'people';
var people = WL.JSONStore.get(collectionName);
The variable people can now be used to perform operations on the people
collection such as:
add
find
replace
Figure 6-27. Get
WU5061.1
Notes:

6-37
Student Notebook
Handling data locally

When your local store is initialized, you can start handling the data by using the
JSONStore API
You can perform many functions on the local data, including:
Add
add (data, [options]) OnSuccess
Remove
remove (doc, {options]) OnSuccess
Count
([options]) OnSuccess
Replace
replace (doc, [options]) OnSuccess
Find
Find (query, [options]) OnSuccess
Store
(data, [options]) OnSuccess
Figure 6-28. Handling data locally
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Add
Use add to store data as documents inside a collection
Example:
var
var
var
var
var
var
data
data == {name:
{name: 'carlos',
'carlos', age:
age: 99};
99};
collectionName
'people';
options
options == {};
{}; //default
//default
WL.JSONStore.get(collectionName)
.add(data,
.add(data, options)
options)
.then(function
.then(function ()
() {{
//handle
//handle success
success

to add data to a collection.
})
})
.fail(function
(errorObject) {{
//handle
//handle failure
failure
});
});
Figure 6-29. Add
WU5061.1
Notes:

6-39
Student Notebook
Find
Use find to locate a document inside a collection by using a query.
Use findAll to retrieve all the documents inside the collection.
Use findById to search by the document unique identifier.
The default behavior for find is to do a fuzzy search
var
var query
query == {name:
{name: 'carlos'};
'carlos'};
var
var collectionName
'people';
var
options
=
{
var options = {
exact:
exact: false,
false, //default
//default
limit:
limit: 10
10 //returns
//returns aa maximum
maximum of
of 10
10 documents,
documents, default:
default: return
return every
every match
match
};
};
.find(query,
.find(query, options)
options)
.then(function
.then(function (arrayResults)
(arrayResults) {{
//arrayResults
//arrayResults == [{_id:
[{_id: 1,
1, json:
json: {name:
{name: 'carlos',
'carlos', age:
age: 99}}]
99}}]
})
})
.fail(function
(errorObject) {{
//handle
//handle failure
failure
});
});
Figure 6-30. Find
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Sample app Find buttons

The sample app has buttons to demonstrate each type of search
Figure 6-31. Sample app Find buttons
WU5061.1
Notes:

6-41
Student Notebook
Replace
Use replace to modify documents inside a collection.
The field that you use to perform the replacement is _id, the document unique
identifier.
var
var document
document == {_id:
{_id: 1,
1, json:
json: {name:
{name:
'carlitos',
'carlitos', age:
age: 99}};
99}};
var
var collectionName
'people';
var
var options
options == {};
{}; //default
//default
.replace(document,
.replace(document, options)
options)
to data in a collection.
.then(function
.then(function ()
() {{
//handle
//handle success
success
})
})
.fail(function
(errorObject) {{
//handle
//handle failure
failure
});
});
Figure 6-32. Replace
WU5061.1
Notes:
This example assumes that the document
{_id: 1, json: {name: 'carlos',
age: 99}} is in the collection, and shows
how to replace it with one where the name is
'carlitos'.

V8.1
Student Notebook
Uempty
Remove
Use remove to delete a document from a collection
Documents are not erased from the collection until you call push
var
var query
query == {_id:
{_id: 1};
1};
var
var collectionName
'people';
var
options
=
{exact:
var options = {exact: true};
true}; //default:
//default:
false
false
.remove(query,
.remove(query, options)
options)
.then(function
.then(function ()
() {{
//handle
//handle success
success
})
})
.fail(function
(errorObject) {{
//handle
failure
//handle failure
});
});

to remove a document.
Figure 6-33. Remove
WU5061.1
Notes:

6-43
Student Notebook
Remove collection
Use removeCollection to delete all the documents that are stored inside a
collection
This operation is similar to dropping a table in database terms
var
var collectionName
'people';
.removeCollection()
.removeCollection()
.then(function
.then(function ()
() {{
//handle
success
//handle success
})
})
.fail(function
(errorObject) {{
//handle
//handle failure
failure
});
});

to remove a collection.
Figure 6-34. Remove collection
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Destroy
Use destroy to remove all documents, collections, stores, and JSONStore
metadata and security artifacts
var
var collectionName
'people';
WL.JSONStore.destroy()
WL.JSONStore.destroy()
.then(function
.then(function ()
() {{
//handle
//handle success
success
})
})
.fail(function
(errorObject) {{
//handle
//handle failure
failure
});
});

to destroy everything.
Figure 6-35. Destroy
WU5061.1
Notes:

6-45
Student Notebook
Advanced features: Security (1 of 2)

You can secure all the collections in a store by passing a password to the init
function
If no password is passed, the documents of all the collections in the store are
not encrypted
Data encryption is only available on Android and iOS environments
Some security metadata are stored:
In the Keychain, on iOS
In Shared Preferences, on Android
The store is encrypted with a 256-bit Advanced Encryption Standard (AES) key
Use closeAll to lock access to all the collections until you call init again.
If you think of init as a login function, you can think of closeAll as the
corresponding logout function.
Use changePassword to change the password
Figure 6-36. Advanced features: Security (1 of 2)
WU5061.1
Notes:
All keys are strengthened with Password-Based Key Derivation Function 2 (PBKDF2).

V8.1
Student Notebook
Uempty
Advanced features: Security (2 of 2)

Example:
var
var collections
collections == {{
people:
people: {{
searchFields:
searchFields: {name:
{name: 'string'}
'string'}
}}
};
};
The sample app has buttons

for logging in, changing the
password and logging out.
var
var options
options == {{
password:
password: '123'
'123'
};
};
WL.JSONStore.init(collections,
WL.JSONStore.init(collections, options)
options)
.then(function
.then(function ()
() {{
//handle
//handle success
success
})
})
.fail(function
(errorObject) {{
//handle
//handle failure
failure
});
});
Figure 6-37. Advanced features: Security (2 of 2)
WU5061.1
Notes:

6-47
Student Notebook
Advanced features: multiple user support (1 of 2)

You can create multiple stores that contain different collections in a single
Worklight application
The init function can take an options object with a user name
If no user name is given, the default user name is jsonstore
Figure 6-38. Advanced features: multiple user support (1 of 2)
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Advanced features: multiple user support (2 of 2)

Example:
var
var collections
collections == {{
people:
people: {{
searchFields:
searchFields: {name:
{name: 'string'}
'string'}
}}
};
};
var
var options
options == {{
username:
username: 'carlos'
'carlos'
};
};
WL.JSONStore.init(collections,
WL.JSONStore.init(collections, options)
options)
The sample app has buttons

for logging in.
.then(function
.then(function ()
() {{
//handle
//handle success
success
})
})
.fail(function
(errorObject) {{
//handle
//handle failure
failure
});
});
Figure 6-39. Advanced features: multiple user support (2 of 2)
WU5061.1
Notes:

6-49
Student Notebook
Advance features: adapter integration (1 of 2)

Worklight adapter integration is optional, and provides ways to:
Send data from a collection to a Worklight adapter.
Get data from a Worklight adapter into a collection.
You can achieve these goals by using functions such as

WL.Client.invokeProcedure or jQuery.ajax if you need more flexibility.
In Worklight Studio, you can use a new wizard to create a template JavaScript
file.
This creation is based on search fields that are selected from the back-end
system that you used to communicate with the adapter.
Figure 6-40. Advance features: adapter integration (1 of 2)
WU5061.1
Notes:

V8.1
Student Notebook
Uempty

Example
function
function getPeople
getPeople ()
() {{
return
return {{ peopleList
peopleList :: [{name:
[{name: 'carlos',
'carlos',
age:
age: 100},
100},
{name:
{name: 'tim',
'tim', age:
age: 99}]
99}] };
};
}}
function
function addPerson
addPerson (data)
(data) {{
return
return WL.Logger.debug('Got
WL.Logger.debug('Got data
data
JSONStore
JSONStore to
to ADD:
ADD: '' ++ data);
data);
}}
function
function replacePerson
replacePerson (data)
(data) {{
return
return WL.Logger.debug('Got
WL.Logger.debug('Got data
data
JSONStore
JSONStore to
to REPLACE:
REPLACE: '' ++ data);
data);
}}
function
function removePerson
removePerson (data)
(data) {{
return
WL.Logger.debug('Got
return WL.Logger.debug('Got data
data
from
from
from
from
After creating the adapter in

Worklight Studio, you see it in
the project navigation.
from
from
JSONStore
JSONStore to
to REMOVE:
REMOVE: '' ++ data);
data);
}}
WU5061.1
Notes:
First, create a Worklight adapter, and define its procedures to get, add, replace, and
remove data (such as getPeople, addPerson, replacePerson, and removePerson).
Next, implement these procedures:
The following example only returns hard-coded data and logs for simplicity.
For more information about how to create a Worklight adapter, see the modules under
category 4, Worklight server-side development, in the IBM Worklight Information Center, at
http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/
topic/com.ibm.worklight.help.doc/start/c_gettingstarted.html.

6-51
Student Notebook

In the example, the key is peopleList because the goal is to store {name:
'carlos', age: 100} and {name: 'tim', age: 99} as two separate
documents
//
// (continued
(continued from
from the
the left
left column)
column)
var
var collections
collections == {{
people:
people: {{
searchFields:
searchFields: {{
name:
name: 'string',
'string',
age:
age: 'integer'},
'integer'},
//Initialize
//Initialize
//-//-- Start
Start adapter
adapter metadata
metadata
adapter
adapter :: {{
.then(function
.then(function ()
() {{
//handle
//handle success
success
name:
name: 'people',
'people',
add:
add: 'addPerson',
'addPerson',
})
})
remove:
remove: 'removePerson',
'removePerson',
replace:
replace: 'replacePerson',
'replacePerson',
load:
load: {{
.fail(function
(errorObject) {{
//handle
//handle failure
failure
});
});
procedure:
procedure: 'getPeople',
'getPeople',
params:
params: [],
[],
key:
key: 'peopleList'
'peopleList'
}}
}}
//-//-- End
End adapter
adapter metadata
metadata
}}
};
};
WU5061.1
Notes:
Start the people collection by calling init and passing adapter
metadata (adapter name, procedure names).
?? In the example, the key is peopleList because the goal is to
store {name: 'carlos', age: 100} and {name: 'tim',
age: 99} as two separate documents.

V8.1
Student Notebook
Uempty

When load is called, JSONStore uses some metadata about the adapter (such
as name and procedure), which you previously passed to init, to determine
what data to get from the adapter and eventually store it
WL.JSONStore.get('people').load()
WL.JSONStore.get('people').load()
.then(function
.then(function ()
() {{
//handle
//handle success
success
})
})
.fail(function
(errorObject) {{
//handle
//handle failure
failure
});
});
to load data from an adapter.
WU5061.1
Notes:

6-53
Student Notebook
Pushing and pulling changes

If your application is connected to an enterprise system by using an adapter,
then you can use the data push function that is included in JSONStore
With the API, you can:
Push all or selected documents to the back-end system
Load data from the back-end system into the local store initially, or refresh the
local copy from the server
Local collection data is pushed or loaded by using a Worklight adapter
Figure 6-44. Pushing and pulling changes
WU5061.1
Notes:
push: pushes the collection with an Adapter. For every document marked requiring push,
call the corresponding Adapter procedure linked to the collection. The Documents will be
processed on the client by order of their last modification date. To check the number of
records to push, see WL.JSONStore.getPushRequired.
Example
collection.push(options);
pushSelected: pushes only the selected Documents. See WL.JSONStore.push. The
document passed will not be sent to the Adapter (pushed) if it is not marked unpushed.
Example
var doc = {_id : 0, json: {fn : 'carlos', age : 99, active : false}}; collection.pushSelected(doc,
options); collection.pushSelected([doc], options);
load: gets data defined in load portion of the adapter.
Example
V8.1
Student Notebook
Uempty
customers.load(options)

6-55
Student Notebook
Example: getPushRequired
Calling getPushRequired returns an array of dirty documents, which are
documents that have local modifications that do not exist on the enterprise
system
These documents are sent to the Worklight adapter when push is called
To stop JSONStore from marking the documents as dirty, pass the option
{push:false} to add, replace, and remove
WL.JSONStore.get('people').getPushRequired
WL.JSONStore.get('people').getPushRequired
()
()
.then(function
.then(function ()
() {{
//handle
//handle success
success
})
})
.fail(function
(errorObject) {{
//handle
failure
//handle failure
});
});

to call getPushRequired.
Figure 6-45. Example: getPushRequired
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Example: push
push sends the document that changed to the correct Worklight adapter
procedure (for example, addPerson is called with a document that was added
locally)
This mechanism is based on the last operation that is associated with the
document that changed and the adapter metadata that is passed to init
WL.JSONStore.get('people').push()
WL.JSONStore.get('people').push()
.then(function
.then(function (res)
(res) {{
//handle
//handle success
success
//res
//res is
is an
an empty
empty array
array if
if all
all documents
documents
reached
reached the
the server
server
//res
//res is
is an
an array
array of
of error
error responses
responses if
if some
some
documents
documents failed
failed
to
to reach
reach the
the server
server
})
})
.fail(function
(errorObject) {{
//handle
//handle failure
failure
});
});

to push changes to the
adapter.
Figure 6-46. Example: push
WU5061.1
Notes:

6-57
Student Notebook
Example: enhance
Use enhance to extend the core API to fit your needs, by adding functions to a collection prototype
The example shows how use enhance to add the function getValue that works on the keyvalue
collection
It takes a key (string) as its only parameter and returns a single result
//Definition:
var collectionName = 'keyvalue';
WL.JSONStore.get(collectionName).enhance(
'getValue', function (key) {
var deferred = $.Deferred(),
collection = this;
//Do an exact search for the key
collection.find({key: key}, {exact:
true, limit: 1})
.then(deferred.resolve,
deferred.reject);
return deferred.promise();
//Usage:
var key = 'myKey';
WL.JSONStore.get(collectionName).getValue
(key)
.then(function (res) {
//res contains an array of documents
//with the results from the find
))
.fail(function () {
//handle failure
});

to add a key/value pair to a
collection.
Figure 6-47. Example: enhance
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Unit summary
Identify the Worklight client-side APIs that support storing data locally on a
device in an encrypted cache or a JSON data store.
WU5061.1
Notes:

6-59
Student Notebook
1. Which of the following sentences correctly describes the encrypted cache?
A. Encrypted cache is stored in the device native storage. Its size is limited by the
free space on a device, therefore large amounts of data can be stored.
B. HTML5 WebStorage is used for storing encrypted cache; therefore the amount of
data stored in it is limited to several megabytes
C. Encrypted cache is stored on Worklight server. Its size is limited by the free
space in the Worklight Server database, therefore large amounts of data can be
stored
D. Encrypted cache is stored in virtual memory. Its size is limited by the device
RAM and it is erased each time the user quits the application.
2. Which of the following APIs is synchronous and does not require callbacks to
be set up?
A. WL.EncryptedCache.open
B. WL.EncryptedCache.read
C. WL.EncryptedCache.destroy
D. All encrypted cache APIs are asynchronous and require setting up callbacks for
success and failure
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Checkpoint answers
1. B. HTML5 WebStorage is used for storing encrypted cache; therefore the
amount of data stored in it is limited to several megabytes
2. D. All encrypted cache APIs are asynchronous and require setting up
callbacks for success and failure
WU5061.1
Notes:

6-61
Student Notebook
1. Why would you consider using JSONStore instead of encrypted cache?
A. You need special encryption that is only available with JSONStore
B. If you are developing Worklight hybrid apps that target iOS and Android
C. You need to use HTML5 local storage
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Checkpoint answers
1. B. If you are developing Worklight hybrid apps that target iOS and Android
WU5061.1
Notes:

6-63
Student Notebook
Exercise 3
Exploring local storage APIs

8.0
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Exercise objectives
Use an encrypted cache and the JSON data store in a mobile application
WU5061.1
Notes:

6-65
Student Notebook

V8.1
Student Notebook
Uempty
Unit 7. Working with UI frameworks

This unit shows how to use the jQuery Mobile, Sencha Touch and Dojo
Mobile UI frameworks in a mobile application.

Include the jQuery Mobile, Sencha Touch or Dojo Mobile UI
frameworks in a Worklight mobile application

Checkpoint
References

7-1
Student Notebook
Unit objectives
WU5061.1
Notes:
7-2

V8.1
Student Notebook
Uempty
The need for an application toolkit

JavaScript provides APIs to manipulate the DOM on a web page, but
those APIs are not consistent across environments
CSS provides a means to separate page style from page content, but
CSS syntax and behavior varies across environments
Core JavaScript lacks efficient support for common web/mobile
application needs
Drag and drop, array handling, animation, and so on
HTML and JavaScript do not provide pre-built UI components and data
integration; each developer must build their own
Figure 7-2. The need for an application toolkit
WU5061.1
Notes:
HTML Document Object Model (DOM) Provides a standard, cross-platform manner
through which HTML documents can be accessed and traversed
Developers need frameworks and toolkits that provide value beyond core JavaScript APIs.
There are many reasons for this:
- JavaScript APIs, especially DOM-related APIs, behave differently across different
browsers. A unifying, consistent API improves application portability and developer
productivity
- Common activities like drag-and-drop and animation effects are not supported in the core
JS API. Thus, developers have to implement their own approach using the core JavaScript
API even though these problems have been solved many times. Toolkits like Dojo radically
simplify these common needs via APIs and configuration
- HTML and JavaScript do not provide a set of pre-built UI components with data
integration. Even though there are common needs for web and mobile applications, such

7-3
Student Notebook
as tabbed views, content panes, tree views, etc., HTML and JS do not do anything to make
constructing those UI views easier.
7-4

V8.1
Student Notebook
Uempty
Topics
Working with UI frameworks
Using jQuery Mobile
Using jQuery to build a multi-page application
Sencha Touch
Dojo Mobile
Figure 7-3. Topics
WU5061.1
Notes:
Designing and implementing the UI of your application is a vital part of the development
process. Writing your own CSS style for each component from scratch allows a very high
level of customization, but can use a large amount of resources. Sometimes it is better to
use existing JavaScript UI frameworks. This unit describes the development of Worklight
applications using different JavaScript UI frameworks: jQuery Mobile, Sencha Touch, and
Dojo Mobile.

7-5
Student Notebook
7-6

V8.1
Student Notebook
Uempty
7.1. Working with UI frameworks

7-7
Student Notebook
Working with UI
frameworks

Figure 7-4. Working with UI frameworks
8.0
WU5061.1
Notes:
7-8

V8.1
Student Notebook
Uempty
Working with UI frameworks

Designing and implementing the UI of your application is a vital part
of the development process
Writing your own CSS style for each component from scratch allows
you a very high level of customization, but requires a large amount of
resources
Sometimes it is better to use the existing JavaScript UI frameworks
This module describes the development of Worklight applications
using three JavaScript UI frameworks:
JQuery Mobile 1.1
jQuery 1.8
Sencha Touch 1.1 or 2
Dojo Mobile
Dojo Toolkit 1.8
Figure 7-5. Working with UI frameworks
WU5061.1
Notes:

7-9
Student Notebook

V8.1
Student Notebook
Uempty
7.2. Using jQuery Mobile

7-11
Student Notebook
Using jQuery Mobile

Figure 7-6. Using jQuery Mobile
8.0
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
jQuery Mobile
jQuery Mobile is a touch-optimized web framework for smart phones
and tablets
Simplifies HTML document traversing, event handling, animating, and
Ajax interactions for rapid web development
You can create mobile application screens in a few lines of code
For more information and documentation, see
http://jquerymobile.com/demos
Figure 7-7. jQuery Mobile
WU5061.1
Notes:
jQuery mobile is built on top of jQuery JavaScript framework. When using jQuery mobile,
you must include jQuery.js core library in your project.
Worklight client-side framework itself uses the jQuery 1.8 library for internal functions. By
default, the $ char is assigned to the internal jQuery in the application main JavaScript file.
This is reflected in the JavaScript file. For example, the application main JavaScript is
generated from the Worklight Studio application creation wizard.
This means that you do not have to separately include the jQuery.js library. If your
application does not require jQuery, you can remove or comment out this line.

7-13
Student Notebook
Working with jQuery Mobile

jQuery is a fast and concise JavaScript framework that simplifies HTML
document flow, event handling, animating, and Ajax interactions for
rapid web development
Worklight client side framework uses jQuery library for internal
functionality
By default, the $ char is assigned to the internal jQuery in the
application main HTML file
If your application does not require jQuery, or if you want to use a
different version of jQuery, you can remove this line
For more information about jQuery, see http://jquery.com/
Figure 7-8. Working with jQuery Mobile
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Adding jQuery to the Worklight application
Add the jQuery Mobile components to your application and reference them in the main
HTML file in order as follows:
1. Add jQuery Mobiles CSS file before any other CSS and JavaScript files
2. Add the jQuery Mobile framework
Figure 7-9. Adding jQuery to the Worklight application
WU5061.1
Notes:
You can download the jQuery mobile minified CSS file, and then copy the file
jquery.mobile.min.css into the application under the common/css folder.
In your application, in the main HTML file, define the jQuery mobile CSS file before any
other CSS and JavaScript file so that its style does not override or interfere with your
application styling.

7-15
Student Notebook
jQuery Mobile basic structure

The basic structure of a screen in a jQuery Mobile application is:
Header and footer elements are optional
The page is rendered by jQuery Mobile at runtime
All the required styles are automatically applied
You can create your own styles and themes using ThemeRoller tool at
http://jquerymobile.com/themeroller/
Figure 7-10. jQuery Mobile basic structure
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
jQuery Mobile widgets

WYSIWYG editor is provided for jQuery Mobile widgets
Figure 7-11. jQuery Mobile widgets
WU5061.1
Notes:

7-17
Student Notebook
jQuery Mobile application screen

By using jQuery Mobile, you can create mobile application screens
in a few lines of code
For more information and documentation, see

http://jquerymobile.com/demos/
Figure 7-12. jQuery Mobile application screen
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
7.3. Sencha Touch

7-19
Student Notebook
Sencha Touch

Figure 7-13. Sencha Touch
8.0
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Working with Sencha Touch

Sencha Touch allows developers to build mobile web apps that look
and feel native on iPhone, Android and BlackBerry touch devices
To download the Sencha Touch package, visit
http://www.sencha.com/products/touch/
Although the Sencha Touch package consists of many files, you only
need two of them to begin development - sencha-touch.js and
sencha-touch.css
Figure 7-14. Working with Sencha Touch
WU5061.1
Notes:

7-21
Student Notebook
Adding Sencha Touch components to an application

Add the Sencha Touch components to your application and add the
references to the <head> section of the main HTML
Figure 7-15. Adding Sencha Touch components to an application
WU5061.1
Notes:
Place the sench-touch.css file under your Worklight application common/css folder, and
place sencha-touch.js file under the application common/js folder.
In the application main HTML file, include both files, as shown in the picture.

V8.1
Student Notebook
Uempty
Working with Sencha Touch

When working with the Sencha Touch framework, build your
application UI using JavaScript
Visit Sencha Touch resources and learning center at
http://www.sencha.com/learn/touch/ to learn more
Figure 7-16. Working with Sencha Touch
WU5061.1
Notes:

7-23
Student Notebook

V8.1
Student Notebook
Uempty
7.4. Dojo Mobile

7-25
Student Notebook
Dojo Mobile

Figure 7-17. Dojo Mobile
8.0
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
What is Dojo?
You can use Dojo Mobile to rapidly develop mobile web applications on
iPhone, iPod Touch, iPad, Android, and BlackBerry touch devices, with
the appearance of the native device
Dojo Mobile is part of the Dojo Toolkit, which is developed and
maintained by the Dojo Foundation
For more information about the Dojo Toolkit, go to the Dojo Toolkit
website at http://dojotoolkit.org/documentation/
Worklight Studio includes a Dojo Toolkit package and tools that you
can use to develop your mobile web applications
Figure 7-18. What is Dojo?
WU5061.1
Notes:
Dojo is a toolkit used to create modern web and mobile applications.
Started back in 2004. Eight major releases since its inception and over 1 million downloads
of the toolkit.
IBM uses Dojo extensively internally, contributes to the toolkit and even co-leads some
areas (such as Dojo Mobile).
More information along with tutorials, API documentation, and reference material can be
found here: http://dojotoolkit.org/
Dojo Base and Dojo Core are the foundational elements of the toolkit. Dijit builds on a layer
of widgets and DojoX is a series of sub-projects built on Dojo Base/Core that are
considered experimental in nature. These sub-projects vary in their degree of maturity from
very new to mature and robust.

7-27
Student Notebook
Addind Dojo Toolkit package to a project

To add the Dojo Toolkit to your application place the Dojo Toolkit
package into your project root
This package contains compressed layers
Figure 7-19. Addind Dojo Toolkit package to a project
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Deployment configuration with Ant

IBM Worklight Studio automatically uses
the build-dojo.xml file to specify which
parts of the Dojo Toolkit package, such as
compressed layers and resources, must
be deployed with your application
Note: The build-dojo.xml file stores the
configuration that must be deployed to run
a basic Dojo Mobile application. You can
modify this build file to add other layers to
deploy with your application.
Figure 7-20. Deployment configuration with Ant
WU5061.1
Notes:

7-29
Student Notebook
Creating custom layers

To create custom layers, you can replace the provided Dojo Toolkit
package in your project with a Dojo Toolkit SDK.
To obtain a Dojo Toolkit SDK, go to the Dojo Toolkit website at
http://dojotoolkit.org/download/ and download the version that you want
to use
Update the build-dojo.properties file to indicate where to pick up the
Dojo Toolkit files from
Update the dojo.workspaceRoot property value to pick up the files from another
directory in your project, or from another project in your workspace
Use the dojo.root property instead if the directory is not in your workspace
Figure 7-21. Creating custom layers
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Using a Dojo Mobile HTML template

You can create mobile web
pages with a predefined Dojo
Mobile HTML template.
Using this template prepares the
web page to use Dojo Mobile
Figure 7-22. Using a Dojo Mobile HTML template
WU5061.1
Notes:

7-31
Student Notebook
Unit summary
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Checkpoint (objective only)

1. By default, what character is assigned to the internal jQuery in an
application's main JavaScript file?
A. $
B. !
C. @
D. #
2. To begin working with Sencha Touch, you need?

A. To write your own CSS style for each component from scratch
B. Only two files: sencha-touch.js and sencha-touch.css
C. All the files in the Sencha Touch package
D. Properly formatted header and footer elements
Figure 7-24. Checkpoint (objective only)
WU5061.1
Notes:

7-33
Student Notebook
Checkpoint answers
1. A. $
2. B. Only two files: sencha-touch.js and sencha-touch.css
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Unit 8. Apache Cordova

This unit explains the capabilities of the Apache Cordova framework
and describes the APIs that support them. It also shows you how to
create a Cordova plug-in, and it provides you with an example of a
WebViewOverlay plug-in that can be used to integrate server
generated pages in an application.

Use the Apache Cordova framework to access native device
functions
Develop an Apache Cordova plug-in
Develop a WebViewOverlay plug-in to integrate server generated
pages in an application

Checkpoint
Exercise
References

8-1
Student Notebook
Unit objectives
Use the Apache Cordova framework to access native device functions
WU5061.1
Notes:
This unit explains the capabilities of the Apache Cordova framework and describes the
APIs that support them. It also shows how to create a plug-in and how to use the
WebViewOverlay plug-in to integrate server generated pages in an application.
8-2

V8.1
Student Notebook
Uempty
Topics
Apache Cordova overview
Creating a plug-in
WebViewOverlay plug-in
Figure 8-2. Topics
WU5061.1
Notes:

8-3
Student Notebook
8-4

V8.1
Student Notebook
Uempty
8.1. Apache Cordova overview

8-5
Student Notebook
Apache Cordova
overview
Figure 8-3. Apache Cordova overview
WU5061.1
Notes:
8-6

V8.1
Student Notebook
Uempty
What is Apache Cordova?

An open source mobile development framework.
It provides a JavaScript API that allows developers to access native
mobile device features and even execute native code using JavaScript.
The framework is integrated into Worklight-generated iOS and Android
projects.
Figure 8-4. What is Apache Cordova?
WU5061.1
Notes:
Apache Cordova is developed by Nitobi Software. It was previously known as PhoneGap.
Cordova has been accepted into the Apache Software Foundation for incubation as
Apache Cordova, where it remains free and open source.
The Cordova framework is designed to bridge the gap between web based mobile
applications and pure native applications by allowing access device native features or
APIs, such as the camera and compass, in a platform independent way.
Using Apache Cordova, you can develop mobile applications using JavaScript, HTML5 and
CSS3, instead of using lower-level platform specific languages such as Objective-C to
access native features. This hybrid application approach renders the UI via a webview
instead of the native platforms specific UI framework, and enables access to part of the
devices APIs.
The Cordova framework is integrated into Worklight generated iOS and Android projects.

8-7
Student Notebook
Apache Cordova referenced in the HTML file

Worklight automatically references the Cordova JavaScript library in
the main HTML of the generated project file to allow applications to use
the API directly
Figure 8-5. Apache Cordova referenced in the HTML file
WU5061.1
Notes:
The Apache Cordova framework is tightly integrated into Worklight. When you build an
application, the main HTML file in its generated project automatically includes the
cordova.js framework. This allows you to invoke the Cordova APIs directly without having
to worry about loading the framework.
8-8

V8.1
Student Notebook
Uempty
Apache Cordova library files

The Cordova library files are automatically
added to iOS and Android projects
Figure 8-6. Apache Cordova library files
WU5061.1
Notes:
Apache Cordova is comprised of two components:
A Cordova JavaScript API which exposes native functionality to the JavaScript code
running in the browser
Platform-specific native code which is invoked by the Cordova JavaScript API
Worklight Studio automatically includes all of the Cordova framework library files in the
generated Android and iOS projects, including:
Cordova web components defined in the cordova.js file that provide JavaScript APIs
Environment specific native libraries
For Android, the libraries are provided in cordova.jar in the generated Android project,
while for iOS, they are included in the Cordova.framework sub-folder of the native folder.

8-9
Student Notebook
Apache Cordova API basics: Cordova objects

Various Cordova objects provide support for other device related
functions:
Device hardware and software information
device.<propertyName>
Lifecycle events
deviceready, pause, resume, online, offline, backbutton,
batterycritical, batterylow, batterystatus, menubutton,
searchbutton, startcallbutton, endcallbutton,
volumedownbutton, volumeupbutton
File related objects to read, write and navigate file system hierarchies
DirectoryEntry, DirectoryReader, File, FileEntry,
FileError, FileReader, FileSystem, FileTransfer,
FileTransferError, FileUploadOptions, FileUploadResult,
FileWriter, Flags, LocalFileSystem, Metadata
Media object to record and play back audio files
Media
Figure 8-7. Apache Cordova API basics: Cordova objects
WU5061.1
Notes:
Lifecycle events are fired when something happens to the application, such as being put in
the background or when a button is pressed. You attach an event listener for whichever
event you are interested in, for example:
document.addEventListener(pause", yourCallbackFunction, false);

V8.1
Student Notebook
Uempty
Apache Cordova usage example: Displaying a native alert

Calling a native alert notification from JavaScript on iOS and Android
devices:
navigator.notification.alert(I am a native alert!!!!, null);
Figure 8-8. Apache Cordova usage example: Displaying a native alert
WU5061.1
Notes:
This slide provides an example of the code used to display a native alert on an iOS and
Android device using the Cordova notification API.
The displayed alert is a native implementation, not a JavaScript web based alert. There are
four parameters:
message: The message that is displayed. String, required.
alertCallback: The callback function to invoke when the button is pressed. Function,
required, but can be null if there is no callback function.
title: The title shown at the top of the dialog. String, optional. If no title is given, it
defaults to "Alert, as in the slide.
buttonName: The value to display on the button. String, optional. If no value is given, it
defaults to "OK, as in the slide.

8-11
Student Notebook
Apache Cordova usage example: Retrieving information

Getting device hardware and software information:
This information is gathered using Cordova

JavaScript API
This information is gathered using Cordova

JavaScript API
Device Name: iPhone Simulator

Device Cordova: 2.2.0
Device Platform: iPhone Simulator
Device UUID: 1234567890
Device Version: 6.0
Device Name: SGH-1987

Device Cordova: 2.2.0
Device Platform: Android
Device UUID: 1234567890
Device Version: 2.2
10
Figure 8-9. Apache Cordova usage example: Retrieving information
WU5061.1
Notes:
Here is another example of using the Cordova API to get the devices hardware and
software information.
In this case, you use the device object to get the value of different device properties:
device.name: Returns the device's model name
device.cordova: Returns the version of Cordova running on the device
device.platform: Returns the device's operating system name
device.uuid: Returns the device's Universally Unique Identifier (UUID)
device.version: Returns the version number of the operating system

V8.1
Student Notebook
Uempty
8.2. Creating a plug-in

8-13
Student Notebook
Creating a plug-in
Apache Cordova plugin overview

Creating a native plugin class for Android
Creating a native plugin class for iOS
Creating a plugin JavaScript wrapper
Figure 8-10. Creating a plug-in
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Apache Cordova Plugin Overview

Developers may need to use a specific 3rd party native library or a
device function
Cordova allows developers to create custom native code blocks and
invoke them via JavaScript
This technique is called a Cordova Plugin
12
Figure 8-11. Apache Cordova Plugin Overview
WU5061.1
Notes:
Cordova's standard API makes the most commonly used device functions available to
JavaScript code. Occasionally, however, you might not find an available API that supports
a device function that you need to use. In such a case, you have to write native code to
implement it, and invoke this code via JavaScript. This is supported by the Cordova Plugin
technology.
In fact, since PhoneGap 1.0, all of the core Cordova APIs such as for the Camera and
Contacts functions are implemented as Cordova plugins. Plugins have become a
fundamental programming model in the Cordova framework.
Limitation:
Note that, as a best practice, tasks that involve complex business logic, intensive
background processing or heavyweight data processing should not be implemented in
JavaScript, as it may significantly slow down your application. These are not good
candidates for Cordova plugin implementation (for example: Communicating with a
Dropbox client, which requires continues background listening for possible file changes).

8-15
Student Notebook

V8.1
Student Notebook
Uempty
Apache Cordova plugin architecture

An Apache Cordova plug-in consists of two parts:
Native code which runs on the devices operating system
For Android: Java code
For iOS: Objective-C code
A JavaScript wrapper
The plugin calls the native code and returns a callback invocation
using cordova.exec()
cordova.exec();
or
callback
Native code
13
Figure 8-12. Apache Cordova plugin architecture
WU5061.1
Notes:
A Cordova plugin has two components: Native code and JavaScript wrapper.
The native code component is platform specific. For Android, it is written in Java, while for
iOS, it is written in Objective-C. The native code is developed to implement the desired
platform specific native function or provide a native library implementation for it.
The JavaScript wrapper wraps the native code so that it can be invoked in your application
as a JavaScript functions.
The next topics show how to create a Cordova plugin native class for Android and iOS, and
how to create a plugin JavaScript wrapper.

8-17
Student Notebook

V8.1
Student Notebook
Uempty
8.3. Creating a native plugin class for Android

8-19
Student Notebook
Creating a native
plugin class for
Android
Figure 8-13. Creating a native plugin class for Android
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Implementing a plugin: Java class

Create a Java class for the plugin
Extend org.apache.cordova.api.CordovaPlugin and add the

required imports:
public class HelloWorldPlugin extends CordovaPlugin {
Implement the execute() method
15
Figure 8-14. Implementing a plugin: Java class
WU5061.1
Notes:
To create an Apache Cordova plugin for Android:
1. Create a Java class that natively implements the plugins function. It should extend
org.apache.cordova.api.CordovaPlugin and implement its execute() method. Make sure
you organize imports in Worklight Studio to bring in all of the Cordova framework class
dependencies.
2. Define the plugin in the Cordova Android plugin definition file located in
res/xml/plugins.xml. Add an entry with the name of the plugin and the name of the class
that implements it.

8-21
Student Notebook
Plugin class execute() method

action input parameter indicates which plugin action to execute
Parameters for action are passed in a JSONArray
callbackContext specifies how to call back to JavaScript
public boolean execute(String action, JSONArray args,

CallbackContext callbackContext)
throws JSONException {
if (action.equals("sayHello")){
try {
String responseText = "Hello world, " + args.getString(0);
callbackContext.success(responseText);
} catch (JSONException e){
callbackContext.error("Failed to parse parameters");
}
return true;
}
return false;
}
16
Figure 8-15. Plugin class execute() method
WU5061.1
Notes:
Implement the execute() method of the plugin class. It is called by the Cordova plugin
framework on a new thread when a plugin action is invoked by the web caller.
This code is placed in android > native > src > package > plugin class.
The JavaScript wrapper calls the execute() method, passing it an action string and action
parameters.
In the code example above, if any other action but sayHello is invoked, the return is false,
which means that the action was not recognized. If the action is sayHello, the data is
retrieved from the input argument array and passed back to the JavaScript calling function.
If the data cannot be retrieved, and error message is passed back.

V8.1
Student Notebook
Uempty
8.4. Creating a native plugin class for iOS

8-23
Student Notebook
Creating a native
plugin class for iOS
Figure 8-16. Creating a native plugin class for iOS
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Implementing the plugin: Objective-C class creation

Create an Objective-C class for the plug-in
Import Cordova/CDV.h and inherit the CDVPlugin class

Add a property for the callbackId
Declare the method signature for the plugin
18
Figure 8-17. Implementing the plugin: Objective-C class creation
WU5061.1
Notes:
To implement the plugins native class, create an Objective-C class that extends
CDVPlugin. Make sure to import the header file, CDVPlugin.h, which contains all of the
Cordova plugin APIs.
Then, add a property for a callbackId and the actual method or functionality that you want
to expose to the web component (action method).

8-25
Student Notebook
Plugin class method: Input parameters

The sayHello method takes one argument, command
This contains references to all the parameters of the invocation
The result is returned to the callback function of the calling JavaScript
object
19
Figure 8-18. Plugin class method: Input parameters
WU5061.1
Notes:
The argument command is the equivalent of the Android JSONArray argument for the
execute() method. You can reference an element by position, or by name. The variable
called responseString is given the value of the command object at position 0.
The variable called pluginResult is then populated with a status value, indicating whether
the invocation succeeded, and the name of the function for the callback, taken from the
command argument.
Finally, pluginResult is returned to the calling JavaScript function.

V8.1
Student Notebook
Uempty
8.5. Creating a plugin JavaScript wrapper

8-27
Student Notebook
Creating a plugin
JavaScript wrapper
Figure 8-19. Creating a plugin JavaScript wrapper
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Implementing the plugin

The second step in implementing a plug-in is to create a JavaScript
wrapper for it and declare it in the DOM
Applies both to Android and iOS
21
Figure 8-20. Implementing the plugin
WU5061.1
Notes:
DOM = Document Object Model
After you have developed the native code for the plugin, you need to create a JavaScript
wrapper for it so that it can be exposed to a web caller and declare the plugin in the DOM
object.
In this example, the empty function serves as a wrapper for the plug-in.
A sayHello function is created in the HelloWorldPlugin prototype and is provided with the
names of the functions to call on success or on failure, together with any parameters that
need to be sent to the plug-in. The single line of code in the function is a call to the exec()
method on cordova. This call takes five arguments: the two callback function names, the
name of the plug-in, the name of the action on the plug-in, and an array that holds the
parameters.
The addConstructor() function is invoked to add the new plug-in to the plugins object of the
DOM. The condition checks whether there is a plugins object. If not, it creates one. It then
associates the name helloWorldPlugin with your new plugin object.

8-29
Student Notebook
You can now invoke the plug-in. The code is show on the next slide.

V8.1
Student Notebook
Uempty
Invoking the plugin from JavaScript

Invoke the plug-in by using:
window.plugins.<pluginFunctionName>.<pluginMethodName>(<parameters>)
22
Figure 8-21. Invoking the plugin from JavaScript
WU5061.1
Notes:
In the example above, the plugin client invokes the sayHello action of the
HelloWorldPlugin in the greetMe() function. It passes a sayHelloSuccess() and
sayHelloFailure() method as a success and failure callback method, respectively. It also
passes the string John Smith (hard-coded on the html page) as a parameter for the plugin
action.
The success callback and failure callback functions are shown. For the demonstration,
they simply pop up an alert.
The plugin name is the one declared in config.xml.
The arguments are passed as an array. In this case, there is only one argument, but there
can be as many as required. This is picked up as the second input argument for the plugin
execute() method.

8-31
Student Notebook
HelloWorldPlugin example screen shots
23
Figure 8-22. HelloWorldPlugin example screen shots
WU5061.1
Notes:
The screen shots above show the execution of the HelloWorldPlugin code example on an
Android emulator.
The string John Smith passed from the JavaScript code is passed to the native code, and
the native code simply passes back the string Hello World, John Smith which is displayed
in an alert by the success callback function.

V8.1
Student Notebook
Uempty
8.6. WebViewOverlay plugin

8-33
Student Notebook
WebViewOverlay
plugin
Motivation and overview

Java Implementation
JavaScript implementation
Examining the result
Figure 8-23. WebViewOverlay plugin
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
WebViewOverlay plugin: Motivation

Many enterprises today decide to develop their own customer or
employee facing mobile application.
Some of those companies already have mobile facing web-sites
(mobile web).
An important decision must be made by companies:
Should all of the mobile web features be implemented from scratch in the mobile
application, which is great from user experience perspective but very time and
money consuming?
Should the new mobile application contain only new features and the old
applications remain accessible by a mobile browser, which is easier to implement
but results in a poor user experience?
25
Figure 8-24. WebViewOverlay plugin: Motivation
WU5061.1
Notes:

8-35
Student Notebook
WebViewOverlay plugin: Overview

The WebView overlay approach allows reusing and integrating existing
mobile web sites within a new mobile application.
Navigation is smooth and seamless between the components that are
internal to the mobile application and the content that is on the external
mobile web site.
Web resources bundled
inside the application
External web content
This Page is implemented in

HTML and bundled with the
mobile application
26
Figure 8-25. WebViewOverlay plugin: Overview
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
WebViewOverlay case study: Description

The case study applications UI displays three tab bars:
Two tabs contain internal content.
The third tab shows an external IBM mobile web site
This Page is
implemented in HTML
and bundled with the
mobile application
First and second tabs

contain internal web
resources
Third tab looks

exactly like another
application page
But technically, it has

an additional WebView
component on top
27
Figure 8-26. WebViewOverlay case study: Description
WU5061.1
Notes:

8-37
Student Notebook
WebViewOverlay plugin: Implementation

WebViewOverlay is implemented using the Apache Cordova plugin
functionality
You can easily create your own protocol between internal web
components and the WebViewOverlay control
The next slides provide a case study example that shows how to create
a WebViewOverlay plugin
28
Figure 8-27. WebViewOverlay plugin: Implementation
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
WebViewOverlay Java implementation (1 of 4)

Declare a WebView object to display external content
29
Figure 8-28. WebViewOverlay Java implementation (1 of 4)
WU5061.1
Notes:
Use static references for the sake of simplicity.
The variable thisApp is created here as a reference to this WebViewOverlayApp object. It is
not used here though, but in the plugin. You see this further on.

8-39
Student Notebook

Instantiate the WebViewOverlay object, set its properties and add it as
a view to a root element
public void onWLInitCompleted(Bundle savedInstanceState){

...
webViewOverlay = new WebView(this);
webViewOverlay.setVisibility(View.INVISIBLE);
webViewOverlay.setWebViewClient(webViewClient);
RelativeLayout.LayoutParams webViewOverlayLayoutParams =
new RelativeLayout.LayoutParams(
RelativeLayout.LayoutParams.FILL_PARENT,
RelativeLayout.LayoutParams.FILL_PARENT);
webViewOverlay LayoutParams.setMargins(0, 65, 0, 0);
webViewOverlay.setLayoutParams(webViewOverlayLayoutParams);
webViewOverlay.getSettings().setJavaScriptEnabled(true);
30
WU5061.1
Notes:
The WebViewOverlay is initially invisible. It is set to visible at the moment an action is
invoked that requires the page to be seen. The code for this is shown further on in this unit.
The setMargins() method is used to control the positioning of the webViewOverlay
component. The method here includes a top margin of 65 pixels in order to leave the
buttons visible.

V8.1
Student Notebook
Uempty

Set up the content view for the webViewOverlay
The steps are:
Create a RelativeLayout object to function as a root layout
Remove the root instance from its original parent
Add root and webViewOverlay to rootRelativeLayout
Set the content view to rootRelativeLayout
public void onWLInitCompleted(Bundle savedInstanceState){

...
RelativeLayout rootRelativeLayout =
new RelativeLayout(this);
((FrameLayout)root.getParent()).removeAllViews();
rootRelativeLayout.addView(root);
rootRelativeLayout.addView(webViewOverlay);
setContentView(rootRelativeLayout);
}
WU5061.1
Notes:

8-41
Student Notebook
WebViewOverlay Cordova plugin (1 of 3)

Implement the Java code for the Cordova plugin
First, declare the actions that the plug-in supports
public class WebViewOverlayPlugin extends CordovaPlugin {

private final String ACTION_OPEN_URL = "open";
private final String ACTION_CLOSE_WEBVIEWOVERLAY = "close";
32
Figure 8-31. WebViewOverlay Cordova plugin (1 of 3)
WU5061.1
Notes:
This code is a part of the execute method in the WebViewOverlayPlugin class. Here, for
reference, is the complete class. This code is repeated on the next 4 slides for easy
reference.
Note that the previous version Plugin superclass is replaced by CordovaPlugin as of
Apache Cordova 2.2
package com.WebViewOverlayApp;
import org.apache.cordova.api.Plugin;
import org.apache.cordova.api.PluginResult;
import org.json.JSONArray;
import android.util.Log;
import android.view.View;
public class WebViewOverlayPlugin extends Plugin {

V8.1
Student Notebook
Uempty

private final String ACTION_GO_BACK = "goBack";
@Override
public PluginResult execute(String action, JSONArray args, String callbackId) {
PluginResult result;
if (action.equals(ACTION_OPEN_URL)) {
WebViewOverlayApp.thisapp.runOnUiThread(new Runnable() {
public void run() {
WebViewOverlayApp.clearWebViewOverlayHistory();
WebViewOverlayApp.loadWebViewOverlay("http://m.ibm.com/");
WebViewOverlayApp.setWebViewOverlayVisibility(View.VISIBLE);
WebViewOverlayApp.requestWebViewOverlayFocus();
}
});
result = new PluginResult(PluginResult.Status.OK, PuginResult :: opened");
} else if (action.equals(ACTION_CLOSE_WEBVIEWOVERLAY)) {
public void run() {
WebViewOverlayApp.loadWebViewOverlayContent("");
WebViewOverlayApp.setWebViewOverlayVisibility(View.INVISIBLE);
}
});
result = new PluginResult(PluginResult.Status.OK, "PluginResult :: closed");
} else if (action.equals(ACTION_GO_BACK)) {
result = new PluginResult(PluginResult.Status.OK, "PluginResult :: back");
} else
result = new PluginResult(PluginResult.Status.INVALID_ACTION);
return result;
}

8-43
Student Notebook

V8.1
Student Notebook
Uempty

If an open request is received from the web part of the application,
load the external content and make the webViewOverlay visible.
public boolean execute(String action, JSONArray args, CallbackContext callbackContext) {

public void run() {
}
});
return true;
33
WU5061.1
Notes:
Here is where you can see the use of the static variable thisApp that was declared but not
used in the previous class you saw.
reference:

8-45
Student Notebook

@Override
public void run() {
}
});
public void run() {
}
});
} else
return result;
}
V8.1
Student Notebook
Uempty

8-47
Student Notebook

If a close request is received from the web part of the application,
clean up the webViewOverlay and hide it
} else if (action.equals (ACTION_CLOSE_WEBVIEWOVERLAY)) {

WebViewOverlayApp.thisapp.runOnUiThread (new Runnable() {
public void run() {
WebViewOverlayApp.loadWebViewOverlayContent ("");
WebViewOverlayApp.setWebViewOverlayVisibility (View.INVISIBLE);
WebViewOverlayApp.clearWebViewOverlayHistory ();
}
});
34
WU5061.1
Notes:
Note that UI related actions should be performed on a dedicated UI thread.
reference:
V8.1
Student Notebook
Uempty

@Override
public void run() {
}
});
public void run() {
}
});
} else
return result;
}
}

8-49
Student Notebook

V8.1
Student Notebook
Uempty
WebViewOverlay JavaScript implementation (1 of 2)

In JavaScript, create a WebViewOverlayPlugin object and populate it
with the required methods
function WebViewOverlayPlugin() {};

WebViewOverlayPlugin.prototype.open = function() {
cordova.exec (null, null, 'WebViewOverlayPlugin', 'open', []);
};
WebViewOverlayPlugin.prototype.close = function() {
cordova.exec (null, null, 'WebViewOverlayPlugin', 'close', []);
};
window.webViewOverlay = new WebViewOverlayPlugin();
35
Figure 8-34. WebViewOverlay JavaScript implementation (1 of 2)
WU5061.1
Notes:
The three methods are open, close, and goBack (this last method was not shown in the
previous slides. You can of course add as many methods as you need). These are created
as a part of the prototype. The WebViewOverlayPlugin object is then created and added to
window.plugins.

8-51
Student Notebook
WebViewOverlay JavaScript implementation (2 of 2)

Determine which tab was clicked
function tabClicked(id){
$(".tab").addClass('hidden');
if (id=="3"){
openWebViewOverlay();
} else {
$("#tab" + id).removeClass('hidden');
closeWebViewOverlay();
}
}
function openWebViewOverlay(){
busyIndicator.show();
setTimeout(busyIndicator.hide, 5000);
window.plugins.webViewOverlay.open();
}
function closeWebViewOverlay(){
window.plugins.webViewOverlay.close();
}
36
Figure 8-35. WebViewOverlay JavaScript implementation (2 of 2)
WU5061.1
Notes:
Determine which UI tab was clicked and show or hide the webViewOverlay accordingly.
Loading external content can be time consuming, so it is a good idea to also add a
busyIndicator to improve the user experience.
This code is a part of the WebViewOverlayApp.js JavaScript file in the Android
environment.

V8.1
Student Notebook
Uempty
Modification to the code

In order to implement the WebViewOverlay technique on the Android
platform, the following changes are required to the Cordova code:
In the DroidGap.java file, the root element must be RelativeLayout and not
LinearLayout.
In the LinearLayoutSoftKeyboardDetect.java file, the class should extend

RelativeLayout instead of LinearLayout.
Make sure to use a Worklight certified Cordova version only when

applying these changes.
37
Figure 8-36. Modification to the code
WU5061.1
Notes:

8-53
Student Notebook
WebViewOverlay case study: Examining the result
38
Figure 8-37. WebViewOverlay case study: Examining the result
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Checkpoint
1. True or False: In order to use the Apache Cordova API in Worklight,
you must manually add the Cordova library files to your project folder.
2. True or False: All of the Apache Cordova standard APIs are
accessible through the navigator namespace.
3. Which step is required to develop an Apache Cordova plugin?
a)
b)
Define the plugin in a Cordova configuration or properties file.

Create a native class to implement the plugin functionality.
c)
d)
Create a JavaScript wrapper to access the native code.

All of the above
WU5061.1
Notes:

8-55
Student Notebook
Unit summary
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Checkpoint answers
1. True or False: In order to use the Apache Cordova API in Worklight,
you must manually add the Cordova library files to your project folder.
False. The Apache Cordova framework is integrated into Worklight and is
immediately available for use by Worklight applications.
2. True or False: All of the Apache Cordova standard APIs are

accessible through the navigator namespace.
False. Most of the standard APIs are accessible through the navigator
namespace, but a few a accessed through special Cordova objects. For
example, the device object is used to retrieved hardware and software
information.
3. Which step is required to develop an Apache Cordova plugin?

a)
b)
c)
d)
Define the plugin in a Cordova configuration or properties file.

Create a native class to implement the plugin functionality.
Create a JavaScript wrapper to access the native code.
All of the above
d) All of the above
WU5061.1
Notes:

8-57
Student Notebook
Exercise
Using Apache Cordova to

access native device functions
Figure 8-41. Exercise
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Exercise objectives
Use the Apache Cordova API to access the devices native Contacts
application and display native alerts
Use the Dojo Mobile toolkit to display various user interface elements
including views and buttons
Use to Rich Page Editor to visually construct an applications user
interface
WU5061.1
Notes:

8-59
Student Notebook
Apache Cordova additional resources

Apache Cordova website:
http://incubator.apache.org/cordova/
Apache Cordova API Reference:

http://docs.phonegap.com/en/1.6.1/index.html
Apache Cordova Wiki:

http://wiki.apache.org/cordova/
44
Figure 8-43. Apache Cordova additional resources
WU5061.1
Notes:
You can get more information about Apache Cordova by visiting the web sites listed here.

V8.1
Student Notebook
Uempty
Unit 9. Integration adapters

This unit describes the types of integration adapters that Worklight
supports and how to use them to access enterprise resources.

Describe the types of integration adapters that Worklight supports
Use integration adapters to access enterprise resources

Checkpoint
Exercise
References

9-1
Student Notebook
Unit objectives
WU5061.1
Notes:
9-2

V8.1
Student Notebook
Uempty
Topics
Adapters overview
SQL adapters
HTTP adapters
Using HTTP adapters with SOAP services
Cast Iron adapters
JMS adapters
Invoking Java code from an adapter
The InvocationData object
Invoking an adapter procedure from Java code
Server side scripting
Figure 9-2. Topics
WU5061.1
Notes:

9-3
Student Notebook
9-4

V8.1
Student Notebook
Uempty
9.1. Adapters overview

9-5
Student Notebook
Adapters overview
Figure 9-3. Adapters - overview
WU5061.1
Notes:
9-6

V8.1
Student Notebook
Uempty
Adapters: overview
An adapter is a transport layer used by the Worklight Platform to
connect to back-end systems
Adapters are used to:
Retrieve information
Perform actions
There are 4 adapter types:

SQL adapter
HTTP adapter (supports both REST and SOAP)
Cast Iron adapter
JMS adapter
Figure 9-4. Adapters: overview
WU5061.1
Notes:
Adapters are sever side artifacts (components) that are meant to interface with various
types of back-end systems like database, web-services, messaging systems etc. Client
applications, specifically Worklight mobile applications, connect to these adapters in a
uniform and simple manner. For example, with just a few lines of JavaScript code. The
purpose is to retrieve data from the back-end systems in a format that is adequately
lightweight for rendering on the mobile device. The adapters could also be used to save
user provided information within back-end systems. As indicated, some adapters, like
HTTP and SQL adapters, are available out-of-the-box such and these are discussed as
part of this module. Adapters must be deployed on the IBM Worklight Server.

9-7
Student Notebook
Benefits of using adapters

Support multiple integration technologies and back-end information
systems
Support read-only and transactional access modes to back-end
systems
Defined with simple XML syntax
Easily configured with JavaScript API
Flexible authentication facilities used to create connections with backend systems (provide control over the identity of the connected user)
Reduced number of transactions performed on back-end systems by
using cache to store retrieved back-end data
Transparency: data retrieved from back-end applications is exposed in
a uniform manner regardless of the adapter type
Figure 9-5. Benefits of using adapters
WU5061.1
Notes:
Here are some of the benefits of adapters in mobile solution-deployment:
Adapter deployments insulates the mobile application from having to deal with multiple
protocol and data formats associated with the back-end systems. The use of adapters
allows the mobile application to not only be able to read data from the back-end systems
but also initiate transactional data processing and just use the end results. Transactions
are performed by adapters and mobile applications do not have to deal with handling
transactional processing issues.
Worklight Adapter uses flexible authentication facilities provided by Worklight
authentication framework to create secure connections with back-end systems and it also
offers control over the identity of the connected server.
Use of adapters help scaling an application by reducing the number of transactions
performed on back-end systems by using cache to store retrieved back-end data
9-8

V8.1
Student Notebook
Uempty
IBM Worklight Adapter Framework
Worklight Server
Procedure
Procedure call
JSON/
HTTP
Application
Back-end
format
JavaScript
Response
JSON
XML
XSLT
(optional)
Back-end
Application
Auto-conversion
To JSON
(if necessary)
JSON
Auto-conversion
To XML
(if necessary)
Figure 9-6. IBM Worklight Adapter Framework
WU5061.1
Notes:
The adapter framework mediates between the mobile apps and the back-end services. A
typical flow is depicted in the diagram.
An adapter exposes a set of services, called procedures. Mobile apps invoke procedures
by issuing Ajax requests.
The procedure retrieves information from the back-end application.
The back-end application returns data in some format.
If this format is JSON, the Worklight Server keeps the data intact.
If this format is not JSON, the Worklight Server automatically converts it to JSON.
Alternatively, the developer can provide an XSL transformation to convert the data to
JSON. In such case, the Worklight Server first converts the data to XML (if it is not in
XML already) that serves as input for the XSL transformation.
The procedures JavaScript implementation receives the JSON data, performs any
additional processing, and returns it to the calling app.

9-9
Student Notebook
Worklight uses Rhino as the engine for running the JavaScript script used to implement
adapter procedures. Rhino is an open source JavaScript container developed by Mozilla. In
addition to being part of Java 6, Rhino has two other advantages:
? It compiles the JavaScript code into byte code, which runs faster than interpreted code.
? It provides access to Java code directly from JavaScript.

V8.1
Student Notebook
Uempty
Anatomy of a Worklight adapter

Each Worklight adapter consists of:
An XML file, describing the connectivity options and listing the procedures
exposed to the application or other adapters
A JavaScript file, containing the implementation of procedures declared in the
XML file
Zero or more XSL files, containing a transformation scheme for retrieved raw
XML data
Data retrieved by an adapter can be returned raw or preprocessed by

the adapter itself
The data is presented to the application as a JSON object
Figure 9-7. Anatomy of a Worklight adapter
WU5061.1
Notes:
Every adapter has a similar internal structure. There are three files that get created by the
Worklight Studio wizard for a new adapter. These are as indicated above. The XML file
describes the connectivity options and the lists all procedures that are available as part of
the adapter. Authentication related information for access to the adapter and the
procedures are also included in this file. The second file is the JavaScript file. This is where
the logic associated with the adapter is encoded in the form of JavaScript code. The code
could invoke Worklight server-side API to perform the overall functionality. The third is the
XSL file that is used to transform result obtained as XML from the back-end systems before
being sent to the mobile application running on a device. It is possible to specify more than
one XSL file for use in the transformation. By default, the Worklight server converts data
from the backed systems to a JSON object. Adapters could also be designed and
configured so as to have the back-end data returned without any transformation.

9-11
Student Notebook
Adapter procedures
Adapter functionality is available to the application by using procedures
Procedures call back-end services to retrieve data or to perform actions
Procedures are declared using XML
They are implemented using server-side JavaScript
A procedure can process the data before or after calling the service by
using server-side JavaScript
Additional filtering can be applied to retrieved data by using simple
XSLT
It is possible to use Java snippets in the adapter code
An adapter is a server side entity and can therefore integrate Java methods
Figure 9-8. Adapter procedures
WU5061.1
Notes:
Adapter functionality, exposed via procedures, is developed in the JavaScript files and is
available to be invoked by mobile applications. Typically procedure is implemented as a
JavaScript function. Mobile applications use client-side Worklight API to invoke the adapter
procedures. The code that makes up a procedure is essentially server-side JavaScript.
This runs within the RHINO container on the Worklight Server when deployed. A
procedure, can both process the data to the back-end server as well as process data from
the back-end service before sending a response to the mobile application. Post processing
could also include filtering of data received from the back-end by applying XSL transforms
on any XML information returned by the back-end systems.

V8.1
Student Notebook
Uempty
Creating an adapter (1 of 3)
In the Worklight project, right-click
Worklight Adapter
Select New Worklight Adapter
Figure 9-9. Creating an adapter (1 of 3)
WU5061.1
Notes:
An adapter is created using the Worklight wizard. The invocation of this wizard is shown in
the slide above. Select the New, Other option by from the pop-menu upon right-click on
the adapter folder of an already created Worklight project. Then select the Worklight
Adapter under the Worklight folder in the Select a Wizard dialog box that pops up.

9-13
Student Notebook
Select the project
Choose an adapter type
Enter a name for the adapter
Applications access the adapter using this name
Click Finish
WU5061.1
Notes:
In the Worklight Adapter dialog, select the Worklight Project under which this adapter is to
be created. Then choose the adapter type. There are two types of adapters that can be
created namely, the SQL adapter that is meant for interfacing with a Database or a HTTP
Adapter that is meant to interface with a back-end using HTTP.
Specify the name of the adapter. This is the name that the mobile application should use to
access the adapter. Once all of this information is provided, click Finish.

V8.1
Student Notebook
Uempty
Files are created and added to the project:
XML files to declare procedures and connection properties
JavaScript file to define procedures and adapter logic
WU5061.1
Notes:
At this point, the Worklight Adapter wizard creates a new folder with the adapter name
provided and creates the files mentioned earlier. The slide above shows the adapter
directory content when a SQL type adapter is created. Note the adapter XML file and the
adapter JavaScript file. The XSL transformation file is not applicable in the case of SQL
type adapters is so is not created.

9-15
Student Notebook
Adapter deployment (1 of 2)
Right-click the adapter to deploy
Select Run As > Deploy Worklight Adapter
Worklight Studio archives the adapter code and deploys it onto the
Worklight Server
Figure 9-12. Adapter deployment (1 of 2)
WU5061.1
Notes:
Adapter deployment in development environment is integrated in Worklight Studio
Right-click on the adapter to be deployed. Select the Run As and Deploy Worklight
Adapter from the respective context menus. This deploys the adapter to the embedded
Worklight test server. You can review the console message within the eclipse for the results
of the deployment.
In cases, where an adapter has to be deployed to a remote Worklight server, running on a
different system, the adapter can be exported from the local Worklight server, via its
console, for deployment on a remote system. Or using the generated adapter .wladapter
file to deploy to remote server. You learn remote server deployment in later training
module.

V8.1
Student Notebook
Uempty
Adapter deployment (2 of 2)
You can see the deployed adapter in the Worklight Console
Figure 9-13. Adapter deployment (2 of 2)
WU5061.1
Notes:
The deployed adapter can be seen in the Worklight server Console, under the catalog tab
as shown in the screenshot here.

9-17
Student Notebook
Testing adapter procedures (1 of 2)

To perform a procedure test, select Invoke Worklight Procedure
from the Run As menu
Figure 9-14. Testing adapter procedures (1 of 2)
WU5061.1
Notes:
This is the same context menu you saw a couple of slides ago. This time, it is the third
option that is chosen.

V8.1
Student Notebook
Uempty
Testing adapter procedures (2 of 2)

Select the procedure you want to test
The signature is displayed so that you know how many parameters to enter
Enter procedure parameters as a comma-separated list

Click Run
Figure 9-15. Testing adapter procedures (2 of 2)
WU5061.1
Notes:
In the resulting dialog that pops-up, select the procedure that is to be tested and provide
the input to the procedure as a comma separated list of values. These values is provided
as arguments to the procedure function running in the RHINO container in the Worklight
Server. Click the Run button to execute and exercise the adapter. The response (typically
in JSON) is displayed in the default (external) browser configured in eclipse IDE.

9-19
Student Notebook
Adapter structure: XML

wl:adapter name: mandatory attribute
displayName: the name to be displayed in the Worklight console
optional
description: additional information to be displayed in the Worklight

console
<wl:adapter
<wl:adapter name=>
name=>
optional
connectivity:
Defines the connection properties and
load constraints of the back-end system
When the back end requires user
authentication, this element defines how
user credentials are obtained
procedure: declares a service for

accessing a back-end application
One entry for each adapter procedure
<displayName
<displayName />
/>
<description
<description />
/>
<connectivity>
<connectivity>
<connectionPolicy>
<connectionPolicy>
<loadConstraints>
<loadConstraints>
</connectivity>
</connectivity>
<procedure
<procedure />
/>
<procedure
<procedure />
/>
</wl:adapter>
</wl:adapter>
Figure 9-16. Adapter structure: XML
WU5061.1
Notes:
The sample code in this slide shows the XML definition for an SQLAdapter. The root tag is
the <wl:adapter> tag. The name attribute of this tag is mandatory and is the name of the
adapter that was provided at the time the adapter was created.
Another attribute can be specified is the authenticationRealm that is to be used to
authenticate a user when this adapter is invoked via the mobile application. The
authenticationRealm attribute is optional.
displayName is a deprecated tag. Its purpose is to provide a readable name for the adapter
on the Worklight console. In its absence the <adapter> tag's name attribute is used for the
display in the Worklight Server console.
description is an optional tag and is meant to capture additional information that is to be
displayed in the Worklight Console.
The <connectivity> tag is a mandatory tag that is used to provide information regarding the
connection between the adapter running on the Worklight Server and the back-end system.

V8.1
Student Notebook
Uempty
There are two child-elements tags that can be specified for this tag. These are
<connectionPolicy> tag and the <loadConstraints> tag.
The <connectionPolicy> tag is a mandatory tag that is used to configure the connection
with the back-end system. This tag has sub-elements that are dependent on the nature of
the protocol that is used to connect to the back-end system. These sub-elements are
covered in later sections.
The <loadConstraints> tag is also a mandatory tag. It is used to control the load from the
adapter to the back-end system. Typically, it is used to define the number of concurrent
connections to the back-end system. The name of the attribute is
maxConcurrentConnectionsPerNode. If the number of connections that is established
with the back-end system is already at the specified number, the incoming requests from
the mobile applications are queued until a connection is available for forwarding the
request to the back-end. These queued requests are cleaned up upon timeout.
The <procedure> tag is used to declare a procedure. There can be any number of
<procedure> tags associated with an <adapter>. The <procedure> tag can have four
attributes, namely: name, connectAs, requestTimeoutInSeconds and audit.
name which is a mandatory attribute that indicates the name of the procedure.
connectAs, an optional attribute, indicates whether the connection to the back-end is to
be done as server, meaning Worklight server, or as endUser.
requestTimoutInSeconds, also an optional attribute, indicates the time in seconds to wait
for a response from the back-end system. The time specified here includes the time taken
to setup the connection.
audit, takes values of true or false. This is meant to indicate if the access to the
adapter from the mobile application instances should be logged in the Worklight server's
audit.log file. The audit attribute is an optional attribute.

9-21
Student Notebook
Adapter structure: JavaScript

Each procedure declared in the adapter XML file must have a
corresponding function in the .js file
Procedure logic is defined in JavaScript by using WL.Server
API
XML file
JavaScript file
18
Figure 9-17. Adapter structure: JavaScript
WU5061.1
Notes:
The JavaScript file that is also generated as part of the adapter creation via Worklight
Studio, this file is where your business or integration logic should be implemented.
As mentioned before, integration logic is handled as a procedure. In this implementation
file, a procedure is defined as a JavaScript function since adapter uses Server side
JavaScript as programming language.
The function name defined here has to match the procedure declaration in the XML file
under the procedure tag. Name attribute. For example, the procedure name procedure1
matches the function name procedure1.

V8.1
Student Notebook
Uempty
9.2. SQL adapters

9-23
Student Notebook
SQL adapters
Figure 9-18. SQL adapters
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Worklight SQL adapters

A Worklight SQL adapter is designed to communicate with any SQL
data source
Plain SQL queries or stored procedures can be used
Worklight supports the following databases:
MySQL
Oracle 11g
Derby
DB2
Download the JDBC connector driver for a specific database type and
add to the lib directory of Worklight project
Figure 9-19. Worklight SQL adapters
WU5061.1
Notes:
An SQL Adapter, that is available out-of-the-box, is capable of interfacing with a back-end
relational database with minimum configuration. The required configuration is reviewed in
the following slides. The adapter may either use an SQL Query or an SQL
Stored-procedure to perform database transactions on user data.
Worklight Version 6 supports MySQL, Derby, Oracle 11g and IBM DB2 databases.

9-25
Student Notebook
Creating a Worklight SQL adapter

Select SQL adapter type
A standard SQL adapter structure
consists of
an XML description file
a JavaScript implementation file
Place the JDBC connector file in the

project lib directory
Figure 9-20. Creating a Worklight SQL adapter
WU5061.1
Notes:
Creating the SQL Adapter only requires selecting the SQL Adapter as the adapter type
when creating an Adapter in Worklight Studio as shown the screen shots here. The
creation of an adapter in the Worklight studio was covered previously. You may recall that
in the case of SQL Adapters only two files are created for the adapter, namely, the XML file
that defines the adapter information such as authentication and procedures and the
JavaScript file that provides integration function or business logic via JavaScript code.
After SQLAdapter is created, you need to add the specific JDBC connector files to projects
server lib folder. For example, Db2 JCC JDBC driver jar file or mySQL connector jar file etc.
Worklight runtime relies on these library to establish connect with associated backend
database.

V8.1
Student Notebook
Uempty
XML file database connectivity settings

There are four parameters declared in the adapter XML file:
Driver Class
Database URL
User name
Password
Figure 9-21. XML file database connectivity settings
WU5061.1
Notes:
As discussed in adapter introduction module, every adapter has an XML file that is used to
store adapters setting and metadata. For SQLAdapters, this file is used to configure the
database connection information. You can open and Edit this XML file in Eclipse based
Worklight studio either in Design or Source mode.
Connect to backend database server is configured via the ConnectionPolicy element under
the connectivity tag.
There are four important information you need to provide to Worklight server runtime in
order to connect to backend database.
You need to specify the JDBC driver class as defined by the DriverClass element. For
different database, specify their JDBC driver class name with full package name. For
example, com.mysql.jdbc.Driver to connect to MySQL server.
The second configuration entry is the URL to the backend server. This might be different
depending on database you are connecting to. In a MySQL example, the connection URL
to the MySQL server would be jdbc:mysql://localhost:3306/worklight_training. You need to

9-27
Student Notebook
supply valid credential to access the database. They are specified via the user and
password elements. You can define the SQL connection attribution such as concurrent
connection numbers via the loadConstraints property.

V8.1
Student Notebook
Uempty
JavaScript file procedure

A procedure must be declared in the adapter XML file
The procedure logic is implemented in the adapter JavaScript file
Important:
The same name declared in
the XML file should be used
for the JavaScript function
There are two ways
to invoke SQL
statements:
SQL statement query
SQL Stored Procedure
Figure 9-22. JavaScript file procedure
WU5061.1
Notes:
An example of a procedure declaration is shown here.
The procedures for the SQL Adapter must be declared in the XML file. As mentioned
previously, SQL adapter's procedure is implemented as JavaScript function in adapter's js
file which well introduce later. As application developer, you need to ensure that The same
name declared in the XML file should be used for the procedures JavaScript function.
Depending on the database used and implementation requirement, the procedures could
use direct SQL Query to interact with the back-end database or could use a database
stored-procedure. Application developer need to work with data architect or database
developers to agree on the implementation type.

9-29
Student Notebook
JavaScript file SQL query
To execute an SQL query:

1. Prepare an SQL query using WL.Server.createSQLStatement
This API must always be called outside the function
2. Add parameters, if required
3. Use WL.Server.invokeSQLStatement to invoke prepared queries
Return results to the procedure invocator

Application, or another procedure
3
2
Figure 9-23. JavaScript file SQL query
WU5061.1
Notes:
The example query shown here highlights steps 1-3 from the procedure.
In the JavaScript implementation file, developer needs to implement the SQL adapter
procedures. As mentioned previous, you can use standard SQL query to interact with
backend data to retrieve, update or delete database records.
Define a JavaScript function as Adapter procedure.
To use Adapter SQL query, start with defining the SQL query using the
WL.Server.createSQLStatement API. Assign the this statement to a JavaScript variable.
Note, this variable definition and createSQLStatement should always be executed or
defined outside of the adapter procedure function thats going to use this SQL query. This is
shown as step 1 in the sample code provided in the slide.
Then, inside of your procedure JavaScript implementation function, use the
WL.Server.invokeSQLStatement API to execute the SQL Query created earlier as shown
as Step 4 in the sample code.

V8.1
Student Notebook
Uempty
Inside of the invokeSQLStatement, you can provide the parameters to replace variables
defined the SQL query, this is essentially the same programming model as Java Prepared
Statement for database query.
Finally, the call returns on invocation result object to the caller of the procedure, in this
case, the mobile client application. All query results are wrapped under this object.

9-31
Student Notebook
JavaScript file stored SQL procedure

To execute a stored SQL procedure
1. Use the WL.Server.invokeSQLStoredProcedure API to execute a stored
procedure.
2. Specify an SQL stored procedure name as an invocation parameter.
3. Add parameters if required.
Return invocation result to procedure invocator (application or another

procedure)
1
2
3
Figure 9-24. JavaScript file stored SQL procedure
WU5061.1
Notes:
This slides shows how to invoke a database stored procedure using Worklight SQL
adapter.
There is no need to define the SQL query since the logic is implemented in the database
stored procedures. To invoke the procedure, pass the database stored procedure as a
parameter to the Worklight API: WL.Server.invokeSQLStoredProcedure as shown in the
sample code step 1 in the slide.
Note, this API needs to be executed inside of the SQL adapter procedure or inside the
function block.
Again, you can pass optional parameters that required by the database stored procedure.
Similar as SQL query invocation, the stored procedure execution result is returned via the
invocation result object, and further returned to the caller of the adapter procedure, either
mobile client or another adapter procedure.

V8.1
Student Notebook
Uempty
WL adapters invocation result

Result retrieved as a JSON object
isSuccessful
Defines whether invocation was successful
resultSet
An array of returned records
Figure 9-25. WL adapters invocation result
WU5061.1
Notes:
This slide shows a typical result object of SQL adapter procedure invocation. The result is
always retuned in JSON format.
The JSON object that is returned by the adapter, consists of a isSuccessful flag that is
used to indicate whether the adapter invocation such as database query or stored
procedure execution was successful.
, the resultSet is an array of records retrieved from the database. In another words, these
are the records or information returned from the execution of SQL query or database stored
procedure. As you can see, Worklight SQL adapter automatically converted them to JSON
data for easy access by mobile or web clients.

9-33
Student Notebook

V8.1
Student Notebook
Uempty
9.3. HTTP adapters

9-35
Student Notebook
HTTP adapters
Figure 9-26. HTTP adapters
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Worklight HTTP adapter

Works with RESTful and SOAP-based services
Can read structured HTTP sources
For example, RSS feeds
Allows sending an HTTP request

GET or POST requests are supported
Retrieves data from the response headers and body

Customizable by server-side JavaScript
Optional server-side filtering
Retrieved data can be in the following formats:
XML
HTML
JSON
Plain text
Figure 9-27. Worklight HTTP adapter
WU5061.1
Notes:
A HTTP Adapter uses either HTTP GET or HTTP POST method to interact with the
back-end system REST or SOAP based services.
With HTTP adapter, developer can access structured HTTP resources such as RSS or
ATOM feeds easily with minimum coding.
Using Worklight HTTP Adapter and associated server side API, you can send HTTP
request via the standard GET or POST call, in the mean time, HTTP adapter can retrieve
data from the response HTTP headers and body in order to exchange data.
HTTP adapters can be extended and modified to implement server side functionality.
This can be done by using server-side JavaScript. As indicated in our overview section for
adapters, data retrieved from back-end system can be filtered / post-processed, as
required, and the resulting data can be sent back to the mobile application in any desired
format with the XML and JSON being the more convenient and popular choices.

9-37
Student Notebook
Create an HTTP adapter

Basic adapter structure:
The properties and procedures of the adapter are defined in XML
Procedures are created in JavaScript
Optionally, use XSL to filter received records and fields
Figure 9-28. Create an HTTP adapter
WU5061.1
Notes:
HTTP Adapters can be created, as explained before, by choosing the HTTP Adapter type
in the Worklight Adapter creation wizard as shown on the screen. This wizard can be
launched from the Menu bar New Others. Then select Worklight Adapter or by using the
context menu of adapters folder. Please refer to previous training module for details on
launching the Worklight Adapter wizard.
After an HTTP adapter is created, three files are generated in the adapter directory. They
are the adapter XML file containing adapter metadata, the JavaScript implementation file
and the XSL filter file.

V8.1
Student Notebook
Uempty
XML file connectivity settings

protocol
HTTP or HTTPS
domain
the domain part of the HTTP URL
port
TCP port
Figure 9-29. XML file connectivity settings
WU5061.1
Notes:
The protocol, domain, and port for the HTTP adapter must be set in the XML file.
Worklight Adapter uses an XML to define adapter configuration information and
procedures. Some of HTTP adapter unique connection configuration is defined in this XML
file.
You can open and Edit the adapter xml definition file in Eclipse editor using either source or
design view.
The important connection for an HTTP adapter is defined by the connectionPolicy element
under the connectivity tag.
The <connectionPolicy> element Defines the back-end endpoint information to establish a
connection between the Worklight server hosting the adapter and the back-end service
either RESTful or SOAP based service end point. The endpoint information includes:
<protocol> - which is typically HTTP or HTTPS,
<domain> - which is meant to specify the fully qualified domain name of the back-end
server that is hosting the HTTP service

9-39
Student Notebook
<port> - which is meant to specify the port to be used to establish the connection to the
back-end server
Optionally, the following could also be specified:
<authentication> - The authentication configuration for the HTTP adapter
<proxy> - The proxy system to be used to access the back-end system
These values are common and are used for all invocation of the back-end from each
procedure declared for the adapter.
The <connectionPolicy> tag itself can have a number of attributes to further specify the
nature of the connection to the back-end systems. These are:
xsi:type - this is mandatory and is to have a value of HTTPConnectionPolicyType
cookiePolicy - This attribute sets how the HTTP adapter handles cookies arriving from the
back-end application. This can take values such as: RFC_2966, IGNORE_COOKIES,
NETSCAPE. The default is RFC_2109
maxRedirects: - this is to indicate the number of HTTP redirects to be processed by the
adapter.
proxy: - which takes a value of true or false; indicates whether proxy information
specified in the worklight.properties files should be used to access back-end.

V8.1
Student Notebook
Uempty
JavaScript file procedure implementation overview

Service URL is used for procedure invocation
Some parts of the URL are constant
For example, protocol and host name
They are declared in the XML file
Other parts of the URL can be parameterized

values provided at runtime to the Worklight procedure
URL parts that can be parameterized are:

Path elements
Query string parameters
Query string
http://example.com/rest/customers?custid=12
Path elements
Figure 9-30. JavaScript file procedure implementation overview
WU5061.1
Notes:
See adapter documentation for advanced options such as cookies, headers, encoding.
HTTP adapter implementation relies on the service URL to access the backend system.
The connectionPolicy properties provided in the adapter XML files is used in Adapter
implementation file to fully construct the HTTP URL that is used to access the back-end
resource/service. These are the constant part of the URL.
The remaining parts of the URL are to be specified in the respective procedures depending
on the specific service or resource that is required to be accessed. These parts include the
path elements where the resource / service is exposed and any additional input parameters
to the retrieve the resource state or to the service itself.
Developer can specify these URL components as either path elements such as the
/rest/customers in the sample URL provide in the slide. You can also provide the query
string parameters as part of the HTTP end point URL such as custid=1 shown in the
example here.

9-41
Student Notebook
These URL parts are specified in the JSON object that forms the input to the Worklight
server-side API that is actually used to access the back-end service. This JSON object can
also be used to specify some of the optional inputs such as cookies, headers, encodings
etc.

V8.1
Student Notebook
Uempty
Procedure declarations in the XML file

Any adapter function that should be publicly visible must be declared in
the configuration file
The name of the procedure in the configuration file must match the
name of the function in the JavaScript file.
The JavaScript file can have other functions that are not declared in the
configuration file
They are not visible outside of the adapter
Figure 9-31. Procedure declarations in the XML file
WU5061.1
Notes:
The implementation file can have several more functions than are declared in the
configuration file. These are functions that should not be called externally, but only from
other functions. In the example on this slide, the configuration XML declares two
procedures, getFeeds and getFeedsFiltered. Therefore these two names must have
corresponding functions in the implementation file. The implementation file also has a
function called getPath() that is not mentioned in the configuration. It can therefore only be
called from one of the other functions, not directly as an adapter procedure.
Note that there is no error generated by having functions with no procedure declaration.
However, there is an error generated if you have a procedure declaration with no
implementation function!
Procedure and function are synonymous. The terminology is different between the two
files because the implication is different.

9-43
Student Notebook
JavaScript file procedures implementation

Required invocation parameters are:
method, returnedContentType and path
Procedure can be parameterized at runtime
Figure 9-32. JavaScript file procedures implementation
WU5061.1
Notes:
The example shows the JSON object that is constructed and used for input into the
Worklight server-side API call to invoke an HTTP based backend service. There are three
items included in the input JSON object. These indicate the HTTP Method to be used
either Get or POST, the format of the returned data and the service endpoint URL path
information described previously.
To invoke backend RESTful or HTTP service in HTTP adapter, you use the Worklight
server-side API WL.Server.invokeHTTP. This method can only be used in a HTTP
adapter type. This API transforms any resulting data returned from the associated
back-end service to JSON. In addition to the list of items shown in the input object
mentioned before, other items that could have been optionally provided include:
parameters a list of parameters to be sent to the HTTP end-point
headers a list of name-value pairs of HTTP header that are to be transmitted
cookies a list of cookies to be transmitted
body the request body. This is only used with the POST method.
V8.1
Student Notebook
Uempty
returnedContentEncoding defines the encoding of the returned content. The default is

utf-8
Transformation when defined, transforms the output from the adapter before it reaches
the mobile application based on the XSL specified here.
Refer to the development reference guide for more details on specifics associated with
each of the items listed above.

9-45
Student Notebook
XSL transformation filtering

XSL transformation can be applied to the received data
Specify the transformation options in the procedure invocation input
parameters
Figure 9-33. XSL transformation filtering
WU5061.1
Notes:
The output from the XML can be filtered by adding a criterion to the procedure invocation
input parameters.
You process the received HTTP service data by applying XSL transformation before
sending data back to the adapter procedure invocator (for example, a mobile client).
This slide shows how to specify the transformation as part of the input object to the
invokeHTTP method. Data received from the back-end resource or web-service is
transformed according to the specified XSL. The transformation is typically used to either
filter the data or to mash it with other data specified/computed within the adapter, or simply
convert to a data format can be easily consumed by the client application. The type such as
xslFile and the XSL file name needs to be specified in the transformation object as
highlighted in the slide.
Note: If the back-end returns HTML, the built-in transformation capability converts it to
XHTML before applying the XSL transform on it.

V8.1
Student Notebook
Uempty
9.4. Using HTTP adapters with SOAP services

9-47
Student Notebook
Using HTTP adapters

with SOAP services
Figure 9-34. Using HTTP adapters with SOAP services
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Creating a SOAP-based Service Request overview

SOAP envelope can be created and sent directly using the
WL.Server.invokeHttp method
To invoke a SOAP-based service in an HTTP adapter:
encode the SOAP XML envelope within the request body
Use E4X, which is officially part of JavaScript 1.6
This technology can be used to encode any type of XML document, not
necessarily SOAP envelopes
If you receive error messages concerning the SOAP envelope, disable the
JavaScript validator by going to Project > Properties >Builders and unchecking
the JavaScript Validator
Figure 9-35. Creating a SOAP-based Service Request overview
WU5061.1
Notes:
To invoke a SOAP based web-service, You can directly create and send the SOAP
envelope using the Worklight API WL.Server.invokeHTTP.
Unlike a standard HTTP like RESTful service invocation, you need to encode the SOAP
XML envelope within the HTTP request body in order to invoke SOAP based service using
Worklight HTTP Adapter. Worklight Adapter uses JavaScript E4X standard to handle the
SOAP XML encoding.
E4X is an official JavaScript standard that adds direct support for XML. With E4X, you can
declare an XML object variable the same way as you declare a Date or an Array object
variable:
In Eclipse editor, If you receive error messages for SOAP envelopes, disable the
JavaScript validator.
You can Select Project > Properties > Builders and clear JavaScript Validator

9-49
Student Notebook
Creating a SOAP-based Service Request (1 of 2)

Use JavaScript to create a SOAP Envelope
Figure 9-36. Creating a SOAP-based Service Request (1 of 2)
WU5061.1
Notes:
The soap:Envelope is the root element of the SOAP message.
Here is an example of the SOAP Envelope XML being assigned to a request JavaScript
variable. A request variable is defined that has the value of a SOAP envelope structure that
targets a SOAP based service called conversionRate.

V8.1
Student Notebook
Uempty
Creating a SOAP-based Service Request (2 of 2)

You can insert JavaScript code and variables into SOAP XML.
They are evaluated at runtime.
Figure 9-37. Creating a SOAP-based Service Request (2 of 2)
WU5061.1
Notes:
The messageHeader element contains application-specific information about the SOAP
message. If the header element is present, it must be the first child element of the
Envelope element.
With E4X support, you can insert JavaScript code into the SOAP Envelope XML. This
convenient method allows easy manipulation of the SOAP envelope. For example you can
dynamically specify the originating IP address of the SOAP messageHeader using a
Worklight configuration item by replacing the XML element with a Worklight JavaScript API
Wl.Server.configuration.

9-51
Student Notebook
Service request invocation

WL.Server.invokeHttp(options) method is used to invoke a
request for a SOAP service
Options object must include the following properties:
method
usually POST
returnedContentType
usually XML
path
a service path
body
content
SOAP XML as a string
contentType
Figure 9-38. Service request invocation
WU5061.1
Notes:
Like any other HTTP adapter usage, SOAP service invocation is handled via Worklight API
WL.Server.invokeHTTP().
The options object passed to the invokeHTTP method specifying important information for
the service invocation.
You can define the invocation HTTP method, normally, it is HTTP POST method.
You can specify the End port service path under the same rules as described in HTTP
adapter section.
IN body attribute, you specify the SOAP envelope that is assigned to the request variable
as described in previous slide using the content attribute. When sending it using
invokeHTTP method, you need convert the SOAP envelope to a string using the JavaScript
toString method to encode.
And you can specify the contentType for the invocation normally text/xml; charset=utf-8 for
SOAP based services.

V8.1
Student Notebook
Uempty
Full SOAP-based service invocation procedure example
SOAP
envelope
Options
Request
invocation
Figure 9-39. Full SOAP-based service invocation procedure example
WU5061.1
Notes:
This sample in the slide shows the complete code and steps to a SOAP based back-end
web-service.
Again, start by defining the SOAP envelope, then define the input options object that
specify the invocation detail such as service end point URL path and context type etc.
Finally, use the Worklight API WL.Server.invokeHttp with input object as parameter to
execute the invocation.
When SOAP service invocation returns, Worklight Server converts the response XML
payload into a JSON object use the element as is. This might not be that use for client
application to consume. So, its recommended to use XSL transformation post-processing
in your HTTP Adapter to convert to mobile/web friendly JSON before sending response
back to the mobile client.

9-53
Student Notebook

V8.1
Student Notebook
Uempty
9.5. Cast Iron adapters

9-55
Student Notebook
Cast Iron adapters
Figure 9-40. Cast Iron adapters
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Worklight Cast Iron adapter

A Worklight Cast Iron adapter initiates orchestrations in Cast
Iron to retrieve and return data to mobile clients
Worklight
Cloud apps
Cast
Iron
Invoke procedure
Enterprise
apps
42
Figure 9-41. Worklight Cast Iron adapter
WU5061.1
Notes:
To integrate a Worklight mobile solution with Cloud including SaaS (Software as a Service)
and Enterprise cloud, Worklight provides a Worklight Cast Iron adapter that developer can
create to simply integrate with Cast Iron platform.
Like other Worklight adapter types, Worklight Cast Iron Adapter sits in between the mobile
application and back end cloud or Enterprise applications. It provides Worklight server side
features such as session management.
A request from a mobile client can be processed by the Worklight Cast Iron adapter which
in turn invokes and iinitiates orchestrations in Cast Iron to retrieve and return data to mobile
clients. This is shown in the architecture diagram here.
For more information about Cast Iron, see
http://www.redbooks.ibm.com/redpapers/pdfs/redp4840.pdf
and
http://www.redbooks.ibm.com/abstracts/sg248004.html?Open

9-57
Student Notebook
Creating a Cast Iron adapter

Create a new Worklight Adapter
Select Cast Iron Adapter type
A standard HTTP adapter structure is created
Procedures are implemented in the adapter JavaScript file
43
Figure 9-42. Creating a Cast Iron adapter
WU5061.1
Notes:
Worklight Studio provides unified tools for creating Worklight Cast Iron Adapter.
In Worklight Adapter creation wizard, select the Adapter type as Cast Iron Adapter from the
drop down and click finish.
Worklight Studio creates the Cast Iron Adapter folder structure and skeleton files including
the Adapter definition xml file and implementation JavaScript placeholder.
The integration logic with Cast Iron is defined in the CastIronAdapter implementation
JavaScript file as shown in the slide.

V8.1
Student Notebook
Uempty
JavaScript file procedures implementation

To invoke a Cast Iron request, use the
WL.Server.invokeCastIron method
It expects an input object
You can specify:

HTTP method (get or post)
Application name
Request type
Service path
Returned content type
(XML, JSON, HTML, plain)
Transformation type
44
Figure 9-43. JavaScript file procedures implementation
WU5061.1
Notes:
For a full list of invocation options see the Developers Reference Guide.
Optionally, you can leverage XSL transformation to process returned data from Cast Iron
component; for example, converting backend XML data to JSON or another form of XML
file.
This approach can also be used to filter returned backend data; for example, retrieve only
data relevant to current logged in user.
To apply XSL transformation, define an optional property in Cast Iron invocation input
object. This attribute is defined as under transformation in the input object.
You need to specify the type of the transformation, for example xslFile, which indicates the
transformation should be handled by an XSL file.

9-59
Student Notebook

V8.1
Student Notebook
Uempty
9.6. JMS adapters

9-61
Student Notebook
JMS adapters
Figure 9-44. JMS adapters
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Java Message Service

Standard messaging API in Java
With JMS, you can read and write messages from any messaging
provider that supports the API
With the JMS adapter, you can read and write messages to any
messaging provider that supports JMS
Figure 9-45. Java Message Service
WU5061.1
Notes:
The Java Message Service (JMS) is the messaging standard defined by the Java
Enterprise Edition (JEE) APIs. It allows application components to send and receive
information asynchronously, without the other party being online, and without waiting for a
response. Communication between components of a distributed application can therefore
be loosely coupled.

9-63
Student Notebook
Worklight JMS adapter

Select JMS from the adapter wizard
This generates two files:
an xml descriptor, used to configure connection properties
a JavaScript implementation
Figure 9-46. Worklight JMS adapter
WU5061.1
Notes:
Creating a JMS adapter is the same process as for any other adapter. The generated files
are often very similar also. It is interesting to create different adapters and compare the
structure. The files are the same, but there are significant differences in the default code
that Workloight generates.

V8.1
Student Notebook
Uempty
Implementing procedures
Procedure names in the JavaScript file must be the same as in the
XML file
DESTINATION is the target for messages that are produced by the
client and the source for messages that are used by the client
Figure 9-47. Implementing procedures
WU5061.1
Notes:
This is minimal coding. In reality, you would want to verify that there was an id for the
JMSMessage, and either print out that the message was not sent correctly, or print a
confirmation message with the id to show that that it was sent correctly.

9-65
Student Notebook
Connection properties
Connection properties are configured in the adapter XML file
JMS Connection
connectionFactory: the classname for JMS Connection Factory that
contains JMS configuration properties
user, password: the credentials as set up by JNDI administrator
Figure 9-48. Connection properties
WU5061.1
Notes:
If you want to use an external JNDI repository you use a <namingConnection> property, as
follows:
<namingConnection url="MY_JNDI_URL"
initialContextFactory="providers_intial_context_factory_class_name"
user="JNDI_UserName"
password="JNDI_Password"/>

V8.1
Student Notebook
Uempty
JMS adapter methods: reading messages

readSingleJMSMessage
Gets the next message from
the destination
Waits for timeout in
milliseconds
Optional: a JMS message
selector
var result =
WL.Server.readSingleJMSMessage({
destination : "jms/MyQ",
timeout : 60,
filter : "NewsType = 'Opinion'"
});
readAllJMSMessages
var result =
Accepts the same parameters WL.Server.readAllJMSMessage({
destination : "jms/MyQ",
as the readSingleJMSMessage
method
timeout : 60
});
Returns a list of JMS
messages in the same format
as the readSingleJMSMessage
method
The result is contained in a
messages object
Figure 9-49. JMS adapter methods: reading messages
WU5061.1
Notes:
readAllJMSMessages returns a list of JMS messages in the same format as the
readSingleJMSMessage method. The result is contained in a messages object:
messages:[
{
body: Hello World,
properties : {
JMSCorrelationID: null,
}
},
{

9-67
Student Notebook
JMS adapter methods: writing messages

writeJMSMessage
writes a JMSText message
to the destination
User properties can be set
Returns the JMSMessageID of
the message that has been sent
var result =
WL.Server.writeJMSMessage({
destination : DESTINATION,
message: {
body: My text message,
properties: { }
}
});
requestResponseJMSMessage
Waits for a response on a dynamic destination
Designed for services that use the replyTo destination from the originating
message
Figure 9-50. JMS adapter methods: writing messages
WU5061.1
Notes:
The JMSMessageID is a JSON object with the form
{
JMSMessageID : ID:414d5,
isSuccessful: true
}
The requestResponseJMSMessage method takes the same parameter as the
writeJMSMessage method, a JSON object that contains the destination and a
message. Like the writeJMSMessage, it writes a JMSText message to the
destination. The JMS message that is returned is in the same format as
the readSingleJMSMessage method.

V8.1
Student Notebook
Uempty
9.7. Invoking Java code from an adapter

9-69
Student Notebook
Invoking Java code

from an adapter
Figure 9-51. Invoking Java code from an adapter
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Overview
An adapter is a server side entity, implemented using JavaScript
Complex functionality can be performed by an adapter, for example:
encrypting and decrypting data
generating and validating security tokens
and so on
In cases where JavaScript is not enough to implement this functionality

or a Java class that implements it already exists, it is possible to use
Java code in the adapter
Figure 9-52. Overview
WU5061.1
Notes:
There may be an existing Java application that has tried and proven functionality, and
those methods could be used for the Worklight adapter. It may also be that there is more
complexity in the business logic than can easily be handled by a JavaScript function. These
are the typical scenarios where it is useful to be able to call a Java method from a
JavaScript adapter.
It should be noted that Java is, in both cases, an extension to the functionality of the
adapter. It does not replace the adapter JavaScript file.

9-71
Student Notebook
Adding custom Java classes to a project

To use an existing Java library, add the JAR file to server\lib
directory of the Worklight project
After building and deploying the Worklight
Adapter, this JAR is automatically
deployed to the Worklight server
Figure 9-53. Adding custom Java classes to a project
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Adding custom Java classes to a project (1 of 2)

To add custom Java code to a project, right-click the server/java
directory of the Worklight project and add a Java class file.
In this example, it is named Calculator1.java
Be sure to put this file inside a package

In this example, the package is
com.worklight.customcode
Figure 9-54. Adding custom Java classes to a project (1 of 2)
WU5061.1
Notes:
Make sure that the package name starts with com. This way Worklight is able to find the
package. This is a requirement in Worklight version 6 that going forward will be modified to
allow any package name.

9-73
Student Notebook
Adding a custom Java class to your project (2 of 2)

Add two methods to the Java class:
In this example, one method is static, and therefore does require the creation of
a new instance of a class
This is just for the demonstration
If there are any other dependencies, put the required JAR files in the
server\lib directory of the Worklight project
Figure 9-55. Adding a custom Java class to your project (2 of 2)
WU5061.1
Notes:
There is no logical reason to make one method static in the code on this slide it is only
included to show the different calling structures, on the next slide.

V8.1
Student Notebook
Uempty
Invoking custom Java classes from adapter

After creating custom Java code or adding JAR files, you can create
references from the Worklight Adapter JavaScript just as if it was
written in Java
The static Java method is evoked by direct reference with the full class
name
Figure 9-56. Invoking custom Java classes from adapter
WU5061.1
Notes:
The code on the previous slide showed the method addTwoIntegers() declared as static.
The fully qualified package class method is therefore sufficient to invoke the method.
The method subtractTwoIntegers() was not declared static, therefore it is necessary to
create an instance of the class first (in this case, the variable calcInstance holds the
reference to this instance). The invocation and return of the calculated value is then
identical for subtractTwoIntegers() as for addTwoIntegers().

9-75
Student Notebook

V8.1
Student Notebook
Uempty
9.8. The InvocationData object

9-77
Student Notebook
The InvocationData
object
Figure 9-57. The InvocationData object
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
invocationData object
The invocationData object is used to provide invocation
configuration and procedure parameters
It consists of a JSON block of properties
Required parameters:
adapter
procedure
parameters
WL.Client.invokeProcedure (invocationData, options)
59
Figure 9-58. invocationData object
WU5061.1
Notes:
adapter (mandatory)
A string containing the name of the adapter as specified in the adapters <wl:adapter>
element.
procedure (mandatory)
Procedure name as defined in the XML file.
parameters (mandatory)
An array of parameters that are passed to the backend JavaScript procedure. Leave empty
if no parameters are required

9-79
Student Notebook
Options object
Success and failure behavior can be defined in an options
object
onSuccess: The function to be invoked on successful completion of
the asynchronous call.
onFailure: The function to be invoked on failure.
invocationContext: Optional parameter. An object that is returned to
the success and failure handlers.
The object is passed for all asynchronous calls to the server

var options = {
onSuccess : loadFeedsSuccess,
onFailure : loadFeedsFailure,
invocationContext : {}
};
60
Figure 9-59. Options object
WU5061.1
Notes:
onSuccess: The function to be invoked on successful completion of the asynchronous
call.
The response typically contains the following properties:
invocationContext: The invocationContext object that was originally passed in the
options object, or undefined if no invocationContext object was passed.
status: The HTTP response status.
invocationResult: An object containing the data returned by the invoked procedure,
and additional information about the procedure invocation.
onFailure: The function to be invoked on failure.
Includes both server-side errors, and client-side (such as server connection failure or timed
out calls). The response typically contains the following properties:
invocationContext

V8.1
Student Notebook
Uempty
errorCode: An error code string. All error codes that can be returned are defined as
constants in the WL.ErrorCode object in worklight.js.
errorMessage: This message is for the developer's use only, and should not be
displayed to the end-user. It is not translated to the user's language.
status: The HTTP response status
invocationContext: Optional parameter. An object that is returned to the success and
failure handlers.
The invocationContext object is used to preserve the context of the calling asynchronous
service upon returning from the service.

9-81
Student Notebook
Bringing it all together
1. Invocation data
2. Invoking the procedure

3. Setting the
success/failure handlers
4. Success handler
5. Failure handler
61
Figure 9-60. Bringing it all together
WU5061.1
Notes:
The onSuccess and onFailure functions are more complex than shown! Here is one
possible code sample:
The loadFeedsSuccess() function :
busyIndicator.hide();
if (result.invocationResult.Items.length>0)
displayFeeds(result.invocationResult.Items);
else
loadFeedsFailure();
And for loadFeedsFailure():
busyIndicator.hide();
WL.SimpleDialog.show("RSSFeedApp",
"Cannot retrieve feed. Check internet connectivity.",
V8.1
Student Notebook
Uempty
[{
text : 'Reload App',
handler : WL.Client.reloadApp
}]);
There is also a function to create the HTML code for the display.

9-83
Student Notebook
Invocation result (1 of 2)
A JSON object containing the data and additional information about

the procedure invocation is returned
Object is returned to a corresponding success/failure handler
62
Figure 9-61. Invocation result (1 of 2)
WU5061.1
Notes:
isSuccessful property:
- true if the procedure invocation succeeded (even if no data was retrieved)
- false otherwise
Records
An array of records retrieved from the backend. Each array entry is an object containing
the fields of the single record. If the procedure call returns no records, an empty array is
returned. If not specified otherwise in the XSL file, default property name is recordSet.
Error, Warn, Info Messages
An optional array of strings containing error messages. If no error messages are
provided, this object is NULL.

V8.1
Student Notebook
Uempty
Invocation result (2 of 2)
Function
Function loadFeedsSuccess
loadFeedsSuccess (result){
(result){
WL.Logger.debug
WL.Logger.debug ("Feed
("Feed retrieve
retrieve successful");
successful");
if
if (result.invocationResult.Items.length
(result.invocationResult.Items.length >> 0)
0)
this.displayFeeds
this.displayFeeds ((
result.invocationResult.Items);
result.invocationResult.Items);
}}
63
Figure 9-62. Invocation result (2 of 2)
WU5061.1
Notes:

9-85
Student Notebook

V8.1
Student Notebook
Uempty
9.9. Invoking adapter procedures from Java code

9-87
Student Notebook
Invoking adapter
procedures from Java
code
Figure 9-63. Invoking adapter procedures from Java code
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Invoking from Java

JavaScript functions in adapters can be called from Java methods
Create an instance of the DataAccessService
DataAccessService is in worklight-extension-api.jar
Create a parameter array and a ProcedureQName instance

ProcedureQName holds the names of the adapter to be invoked and the procedure
Invoke the function and process the result
65
Figure 9-64. Invoking from Java
WU5061.1
Notes:
DataAccessService is an interface that provides methods to invoke procedures, subscribe
and unsubscribe notifications, and update device tokens. All the methods return an
InvocationResult object. WorklightBundles has the method getDataAccessService() that
returns a DataAccessService instance.
Any required parameters are assembled in an array and a ProcedureQName object is
created with the references for the adapter and the function to be called.
The DataAccessService invokeProcedure() method is used to call the JavaScript function
with the adapter name, function name, and parameters. The result is converted into a
JSON object with the InvocationResult method toJSON().

9-89
Student Notebook

V8.1
Student Notebook
Uempty
9.10.Server side scripting

9-91
Student Notebook
Server side scripting
Figure 9-65. Server side scripting
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Server-side scripting
Enhances adapter capabilities
Pre and post processing logic
All processing can be done with only one call to the server and in one
transaction
Enables data mashups from different sources
PreProcessing
Invoke procedure
Procedure
Logic
PostProcessing
67
Figure 9-66. Server-side scripting
WU5061.1
Notes:
The point here is that the procedure logic is usually split over several functions, potentially
in different adapters (and even in Java). This, the logic is structured, easily maintained, and
reusable, while the user only needs to make one request to the server. There is nothing
new in such a process! Here, it allows for mashup of information.

9-93
Student Notebook
Server-side API
WL.Server.InvokeProcedure (invocationData)
Procedure invocation from current or other adapter
Same syntax as a client-side WL.Client.invokeProcedure()
WL.Logger.debug (msg)
Sends messages to the console
Used for debugging
WL.Server.configuration object
A map containing all the server properties defined in the worklight.properties
file
Syntax
WL.Server.configuration[property-name]
WL.Server.configuration.property-name
Example
Var addr = WL.Server.configuration[local.IPAddress];
68
Figure 9-67. Server-side API
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Mashups
A mashup is an aggregation of data or functionality from different sources
You can mash up different data sources and return the data stream to the
application as a single invocationResult object
Can be implemented in the same way for any number of data sources and
across different adapter types
Server-side
JavaScript
Yahoo Weather
(RSS)
City Weather
(MySQL)
SQL
CityWeather app
HTTP
69
Figure 9-68. Mashups
WU5061.1
Notes:
The example takes data from the following sources:
- SQL :
Extract a list of cities from the weather table. The result contains list of several
cities around the world, their Yahoo! Weather identifier and some description
- HTTP:
Connect to Yahoo! Weather Service
Extract updated weather forecast for each of the cities retrieved with SQL
The mashed-up data is returned to the application for display.

9-95
Student Notebook
Checkpoint
1. What are adapters most typically used for?
A. Authenticate users
B. Retrieve data or perform actions
C. Export and deploying applications
D. Convert from one protocol to another
2. What is a Worklight SQL adapter designed for?

A. Translating actions into plain SQL queries
B. Working with RESTful and SOAP-based services
C. Implementing JavaScript
D. Communicating with any SQL data source
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Checkpoint
You can invoke an adapter procedure with this call:
3.
Name one of the 3 name/value pairs for invocationData
4.
Name one of the 3 name/value pairs for options
5.
Which of the following may hold an array of messages about the

result of an invocation:
errors, isSuccessful, info, response, items, warnings
6.
What is a mashup?
WU5061.1
Notes:

9-97
Student Notebook
Unit summary
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Checkpoint answers
1. B. Retrieve data or perform actions
2. D. Communicating with any SQL data source
3. Name one of the 3 name/value pairs for invocationData
Adapter, procedure, parameters
4. Name one of the 3 name/value pairs for options
onSuccess, onFailure, invocationContext
5. Which of the following may hold an array of messages about the

result of an invocation:
errors, isSuccessful, info, response, items, warnings
6. What is a mashup?
An aggregation of data or functionality from different sources
WU5061.1
Notes:

9-99
Student Notebook
Exercise
Developing an integration adapter
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Exercise objectives
Develop an adapter
Invoke an adapter from a client application
WU5061.1
Notes:

9-101
Student Notebook

V8.1
Student Notebook
Uempty
Unit 10. Native and web page integration

This unit describes the Worklight APIs that support the combination of
both native and web pages inside a mobile application.

Combine native and web pages in a mobile application
Use transition effects to animate the navigation between a native
and web page

Checkpoint
Exercise
References

10-1
Student Notebook
Unit objectives
Use transition effects to animate the navigation between a native and
web page
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Topics
Overview of native and web page integration
Combining native and web pages on Android
Combining native and web pages on iOS
Figure 10-2. Topics
WU5061.1
Notes:

10-3
Student Notebook

V8.1
Student Notebook
Uempty
10.1.Overview of native and web page integration

10-5
Student Notebook
Overview of native and

web page integration
Figure 10-3. Overview of native and web page integration
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Limitations of web technologies

You can do a lot with web technologies only
Apache Cordova provides greater flexibility by allowing
JavaScript to access native device features
However, there are still cases where web technologies are not
enough
Augmented reality
Barcode scanner
Opening a native contacts page
Figure 10-4. Limitations of web technologies
WU5061.1
Notes:
This slides explains the need for combining web and native pages.
Web technologies like HTML5 and CSS3 are powerful and capable of delivering highly
interactive mobile applications. In addition, with the Apache Cordova framework, mobile
web applications can access native phone features that traditionally only native
applications could. This further closes down the gap between web and native applications
on a mobile device.
However, there are still cases where native applications do better than their web
counterpart. For example, accessing hardware sensors such as the gyroscope or
microphone is still a limitation for web applications. Or if you want to build a highly
interactive Map application using a native toolkit such as the iOS MapKit framework, you
have to write a native page.
Therefore, some portions of your mobile application need to be developed as native pages.
How then are you going to seamlessly integrate your web and native pages? Worklight
provides a solution which is described in the next slides.

10-7
Student Notebook
Combining native and web pages

Worklight provides a simple way to augment your web application with
native pages.
Using Worklights hybrid coding approach you can:
Navigate freely between web and native pages
Share data between pages
Share a single server session
Implement your own functions by creating Cordova plug-ins
Figure 10-5. Combining native and web pages
WU5061.1
Notes:
It may also be that a visible native page is not required, but the native functionality of the
device needs to be invoked. Examples of this are: retrieving certificates from the keystore,
native third party libraries, or complex computation that would be too slow in JavaScript.
Worklight allows you to include pages developed in the native operating system language
in your applications. The natively developed pages can be invoked from your web-based
pages and can then return control to the web view. You can pass data from the web page
to the native page, and return data in the opposite direction. You can also animate the
transition between the pages in both directions. Both web and native pages can share a
single server session maintained by Worklight Server.
Worklight provides a native API to communicate with the Worklight server from native
page. Information, including cookies, can be shared between the web environment and the
native environment.

V8.1
Student Notebook
Uempty
How does it work?

Developer writes one or more native pages and web pages
Worklight JavaScript API allows navigation to native pages and back
including the passing of data back and forth
WL.NativePage.show(className, callback, data);
The web page invokes the native class, className, with the parameters, data.
Upon return, the callback function is invoked.
Figure 10-6. How does it work?
WU5061.1
Notes:
To develop a combined native and web page mobile application:
Develop the web pages using the standard HTML5, CSS3 and JavaScript technologies
in Worklight Studio. When you need to invoke a native page from a web page, use the
Worklight web API, WL.NativePage.show(), to navigate to the native page and back,
passing any desired parameters. This method takes three parameters:
- The first parameter specifies the name of the native class. In example on the slide,
it is the Android Java class named com.demo.NativePage. Note, that the syntax for
iOS and Android is different, as for the former you only need to specify the class
name, while for the latter, you need to specify the package name and class name.
You can use Worklights environment optimization feature to easily handle both
situations.
- The second parameter defines a callback function that is called when the native
page switches back to the web view. This function is passed a single JSON object
parameter when invoked which can be used to pass back data from the native page.

10-9
Student Notebook
- The last parameter is a JSON object that is sent to the native class.
Develop the native pages using a platform specific language such as Objective-C for
iOS and Java for Android. For Android, you can develop native pages in Worklight
Studio, while for iOS, you develop them in Xcode. If desired, you can use Worklight
native API to communicate with backend Worklight server so that both web and native
pages can share the same server session and exchange information via cookies.
Package the web and native pages in the same Worklight project in Worklight Studio.
The web and native page communication is handled by Worklight client side web
containers which act as a shell program between the two layers.

V8.1
Student Notebook
Uempty
10.2.Combining native and web pages on Android

10-11
Student Notebook
Combining native and

web pages on Android
Figure 10-7. Combining native and web pages on Android
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Native on Android: Activity class and manifest definition

An Android page must be implemented as an Android activity
Either extend the base Activity class or an existing subclass
Like any other activity, you must declare it in the

AndroidManifest.xml file
Figure 10-8. Native on Android: Activity class and manifest definition
WU5061.1
Notes:
You can develop an Android native page in Worklight Studio if you have an Android
development environment set-up (Android SDK and Android Development Tools Eclipse
plug-in).
The page must be implemented as an Activity object must be declared the applications
Android manifest file.

10-13
Student Notebook
Native on Android: Receiving data from the web page

When the activity is invoked, arguments passed from the web view can
be retrieved using an Intent object
JavaScript code
Native code
Figure 10-9. Native on Android: Receiving data from the web page
WU5061.1
Notes:
In the activity, you can receive data passed from the web view using the activitys Intent
object. The Worklight client framework makes the data available to the activity in a Bundle.
Notice that the argument of the getStringExtra() method is the name of the JSON
parameter to retrieve (nameParam in the example shown).

V8.1
Student Notebook
Uempty
Native on Android: Returning control to the web page

When the native page needs to switch back to the web view, it call the
activitys finish() method.
You can pass data back to the web view by creating an Intent object.
Native code
JavaScript code
Figure 10-10. Native on Android: Returning control to the web page
WU5061.1
Notes:
The sample code shown here passes the phoneNumber string back to the web page.

10-15
Student Notebook
Native on Android: Animating transitions

You can animate page transitions with supported Android transition
effects in both direction
Use the overridePendingTransition() method
//// Transition
Transition animation
animation from
from the
the web
web view
view to
to the
the native
native page
page
@Override
@Override
public
public void
void onCreate(Bundle
onCreate(Bundle savedInstanceState)
savedInstanceState) {{
super.onCreate(savedInstanceState);
super.onCreate(savedInstanceState);
overridePendingTransition(android.R.anim.fade_in,
android.R.anim.fade_out);
}}
//// Transition
Transition animation
animation from
from the
the native
native page
page to
to the
the web
web view
view
@Override
@Override
protected
protected void
void onActivityResult(int
onActivityResult(int requestCode,
requestCode, int
int resultCode,
resultCode, Intent
Intent data)
data) {{
//your
//your code
code goes
goes here....
here....
finish();
finish();
}}
Figure 10-11. Native on Android: Animating transitions
WU5061.1
Notes:
You can implement any transition effect supported by Android when switching the display
from the web view to the native page and in the opposite direction:
To implement a transition animation when switching the display from the web view to
the native page, invoke the overridePendingTransition() method inside the onCreate()
method.
To implement a transition animation from the native page to the web view to, invoke the
overridePendingTransition() method inside the onActivityResult() method.
In the sample code above, the Android transition effect requested is a fade-in and fade-out.

V8.1
Student Notebook
Uempty
Web page on Android: Invoking the native page

Use the WL.NativePage.show() API to invoke the native page
First parameter is the name of the activity to be started
Second parameter is the name of the callback function to be invoked when the
native activity is finished
Third parameter contains data to be passed to the native code
Data passed back by the native page is received in the callback

functions single argument
Figure 10-12. Web page on Android: Invoking the native page
WU5061.1
Notes:
The class name parameter is the full package and class name of the activity implementing
the native page.
The data passed to the native page is a JSON object. The data passed back from the
native page is also a JSON object. In this sample code shown, the data parameter of the
backFromNativePage callback function contains the data sent from the native page.

10-17
Student Notebook

V8.1
Student Notebook
Uempty
10.3.Combining native and web pages on iOS

10-19
Student Notebook
Combining native and

web pages on iOS
Figure 10-13. Combining native and web pages on iOS
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Native on iOS: UIViewController subclass

Create the native page in Xcode:
Add it to your projects Classes folder
Subclass UIViewController
Figure 10-14. Native on iOS: UIViewController subclass
WU5061.1
Notes:
In Xcode, create your applications native pages in the same Worklight project that also
hosts the web artifacts.
In iOS, a native page must be implemented as an Objective-C class that extends the
UIViewController class in order to use the Worklight native navigation features. This class
must be able to initialize through the init method alone. The initWithNibName:bundle:
method is never called on the class instance.

10-21
Student Notebook
Native on iOS: Receiving data from the web page

Custom data parameters passed from the web view can be retrieved by
using setDataFromWebView:(NSDictionary *)data
JavaScript code
Native code
Figure 10-15. Native on iOS: Receiving data from the web page
WU5061.1
Notes:
You can access the data passed from the web page by implementing the
setDataFromWebView method. The web data is packaged in an Objective-C NSDictionary
object and passed to the method as a parameter.
Notice that the argument of the valueForKey method is the name of the JSON parameter to
retrieve (nameParam in the example shown).

V8.1
Student Notebook
Uempty
Native on iOS: Returning control to the web page

To switch back to the web view from the native page, call
NativePage showWebView
Make sure to import NativePage.h
Use a NSDictionary object to pass data back to the web view
Native code
JavaScript code
Figure 10-16. Native on iOS: Returning control to the web page
WU5061.1
Notes:
When the native page needs to switch back to the web view, it calls the NativePage
showWebView: method and passes it a NSDictionary object. This dictionary can be
structured in any hierarchy or can be an empty. The Worklight runtime framework encodes
it in a JSON format, and then sends it as the first argument of the JavaScript callback
function.
In order to access all of the Worklight native to web navigation features, you need to
include the NativePage.h header file in your class definition.
The sample code shown above passes the phoneNumber string back to the web page.

10-23
Student Notebook
Native on iOS: Animating web to native transitions

You can animate transitions from the web to the native page with
supported iOS transition effects.
Implement the animation in the onBeforeShow and onAfterShow methods.
Figure 10-17. Native on iOS: Animating web to native transitions
WU5061.1
Notes:
You can implement any transition effect supported by iOS when switching the display from
the web view to the native page. To do so, write the animation code in the onBeforeShow
and onAfterShow methods. These methods are called before the display switches from the
web view to the native page, and after the transition, respectively.
In the sample code above, the iOS transition effect implemented rotates the screen to the
right as the web page is replaced by the native page.
You can also implement any transition effect supported by iOS when switching the display
from the native page to the web view. To do so, write the animation code before you return
control to the web page, i.e., before calling NativePage showWebView.

V8.1
Student Notebook
Uempty
Web page on iOS: Invoking the native page

Use the WL.NativePage.show() API to invoke the native page
First parameter is the name of the UIViewController subclass that implements
the native page
Second parameter is the name of the callback function to be invoked when the
native page is finished
Third parameter contains data to be passed to the native code

functions single argument.
Figure 10-18. Web page on iOS: Invoking the native page
WU5061.1
Notes:
The first parameter of the WL.NativePage.show() function is the class name of the
Objective-C class that implements the native page.
The data passed to the native page is a JSON object.
Compare this code block with the code shown on slide 13, Web page on Android:

10-25
Student Notebook
Web page on IOS: Receiving data from the native page

functions single argument.
Figure 10-19. Web page on IOS: Receiving data from the native page
WU5061.1
Notes:
The data passed back from the native page is also a JSON object. Here, the data
parameter of the backFromNativePage callback function contains the data sent from the
native page, exactly as for the Android code.

V8.1
Student Notebook
Uempty
Checkpoint
1. The Worklight function used to invoke a native page from a web page
is:
a) WL.Client.connect
b) WL.Page.load
c) WL.NativePage.show
d) WL.Native.show
2. True or False:
On the Android platform, the native page must be implemented as a
subclass of UIViewController.
3. True or False:
Data passed from and received by the web page is in JSON format.
WU5061.1
Notes:

10-27
Student Notebook
Unit summary
Use transition effects to animate the navigation between a native and
web page
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Checkpoint answers
1. The Worklight function used to invoke a native page from a web page
is:
a) WL.Client.connect
b) WL.Page.load
d) WL.NativeShow
2. True or False: On the Android platform, the native page must be

implemented as a subclass of UIViewController.
False. On Android, the native page is implemented as an Activity
3. True or False: Data passed from and received by the web page is in
JSON format.
True
WU5061.1
Notes:

10-29
Student Notebook
Exercise
Combining web and native pages
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Exercise objectives
Combine a native and a web page in a mobile application
Exchange data between a native and web page
WU5061.1
Notes:

10-31
Student Notebook

V8.1
Student Notebook
Uempty
Unit 11. Using Worklight native APIs

This unit shows you how to use the application management features
of IBM Worklight. This unit describes the Worklight APIs that enable a
native Android or iOS client application to invoke an adapter procedure
running on Worklight Server.

Create a Worklight Native API application
Configure the native application
Invoke an adapter procedure
Manage a procedure response

Checkpoint
References

11-1
Student Notebook
Unit objectives
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Worklight native API

IBM Worklight provides the ability for native applications to
communicate with a Worklight server by using the Worklight native API
library
In order to serve a native application the Worklight server needs to be
aware of it
A Worklight native API is located under apps folder of your Worklight
project
A Worklight native API folder serves two purposes:
It contains a native API library and a configuration file that must be copied to
your native project
It contains an application-descriptor.xml file, which can be deployed to
a Worklight Server to serve as an entry point, similar to a Worklight application
Figure 11-2. Worklight native API
WU5061.1
Notes:
Typically, native applications do not have communication with the Worklight server. The
Worklight server is connected to the web part of an application, not to the native part. The
Worklight server is therefore not aware of the native application. However, there is now a
Worklight native API that can allow communication between the Worklight server and the
device native application. This unit looks at how this communication is achieved.

11-3
Student Notebook
Why use native API capabilities?

iOS and Android applications can communicate with the Worklight
server and benefit from features such as
Application Management
Native APIs for remote disable and Notify on Start up
Backend Integration
Native API to invoke adapter procedures
Authentication
Native APIs for custom client-side authentication
Analytics
Native API for Reporting
Figure 11-3. Why use native API capabilities?
WU5061.1
Notes:
There are a number of advantages to doing using native API capabilities. You have seen
already how the Worklight server can send notifications, or even disable an application.
With native API, this is possible even with native applications. You may want your native
code to communicate with server-side adapters, or use authentication on the client side.
You may also want to combine analytics with your native application.

V8.1
Student Notebook
Uempty
Creating a Worklight native API

1.
In Worklight Studio, create a Worklight project, and add a Worklight

Native API
2.
In the New Worklight Native API dialog, enter your application

name, and select Android or iOS for the Environment field
3.
Right-click the Worklight native API folder and select Build and
Deploy
Figure 11-4. Creating a Worklight native API
WU5061.1
Notes:
To create the Worklight native API you start with a standard Worklight project. Up to this
point, you have seen the creation of hybrid applications. This time, it is the native API that
is selected. For the next step, you need to specify an application, and to define which
environment you are using Android, iOS, or JavaME.

11-5
Student Notebook

V8.1
Student Notebook
Uempty
11.1.Android native API

11-7
Student Notebook
Android native API

Figure 11-5. Android native API
8.0
WU5061.1
Notes:
The following slides discuss the Android native API. If your interest is in iOS, move on to
the topic entitled iOS native API.

V8.1
Student Notebook
Uempty
Android native API

Defines application meta data and security
configuration
wlclient.properties
Contains connectivity settings to be used by
a native Android application.
This file must be copied to the native Android
project
This file is discussed in detail further on
worklight-android.jar
A Worklight API library that must be copied
to the native Android project
Figure 11-6. Android native API
WU5061.1
Notes:
This slide shows the structure of an application. The application is called
NativeAPIforAndroidApp. It includes an XML file called application descriptor, a properties
file called wlclient, and a jar file called worklight-android. The properties file and the jar file
are copied to the native Android project. The application descriptor XML file is copied to the
worklight server.

11-9
Student Notebook
Editing wlclient.properties (Android)

Edit wlclient.properties, which holds the server configuration
Figure 11-7. Editing wlclient.properties (Android)
WU5061.1
Notes:
wlServerProtocol
The communication protocol to the Worklight Server. Either http or https
wlServerHost
Hostname of the Worklight Server
wlServerPort
Port of the Worklight Server
wlServerContext
Context root path of the application on Worklight server
wlAppId
Application ID as defined in the application-descriptor.xml file
wlAppVersion
Application version
wlEnvironment
Target environment of the native application
V8.1
Student Notebook
Uempty

11-11
Student Notebook
Configure an Android native application

Create a native Android application
Copy two files from the Worklight native API folder to the new native
Android application:
worklight-android.jar goes to /libs
wlclient.properties goes to/assets
Add two permissions and an activity to AndroidManifest.xml :

Internet permission
<uses-permission
android:name="android.permission.INTERNET"/>
WIFI permission
< uses-permission
android:name="android.permission.ACCESS_WIFI_STATE"/>
Worklight UI activity
<activity
android:name="com.worklight.wlclient.ui.UIActivity"/>
Figure 11-8. Configure an Android native application
WU5061.1
Notes:
There are several steps that need to be accomplished in order to configure an Android
native application. This slide summarizes the steps. On the previous slides you saw that a
native Android application is created which contains files called worklight-android.jar and
wlclient.properties. These files are copied to the native application, as shown here. You
also need to open the AndroidManifest.XML file and add three tag elements. First, you
need to add a user-permission tag for the Internet, and another user-permission for WIFI.
Then you need to add an activity tag for a UIActivity.

V8.1
Student Notebook
Uempty
Initializing the WLClient Android

Create an instance of the WLClient
It requires a reference to the activity in which it is running
final WLClient client = WLClient.createInstance(this);
To connect to a Worklight Server, use the connect method by

specifying the MyConnectListener class instance as a parameter
Figure 11-9. Initializing the WLClient - Android
WU5061.1
Notes:
WLClient is a JavaScript client library that provides access to IBM Worklight capabilities
such as initializing an application, managing sessions, retrieving information, writing to a
logger window, and much more. You use this instance to create a connection using
MyConnectListener.
This class is discussed in more detail on the following slides.

11-13
Student Notebook
MyConnectListener Android
The WLClient instance connects to a Worklight server according to
properties of the wlclient.properties file
After the connection is established, it invokes one of the methods of the
MyConnectListener class
This class must implement the WLResponseListener interface
public class MyConnectionListener implements
WLResponseListener {}
This interface defines two methods:

public void onSuccess (WLResponse response)
public void onFailure (WLFailResponse response)
Figure 11-10. MyConnectListener - Android
WU5061.1
Notes:
WLClient finds information about where to try and establish a connection in the properties
file wlclient. MyConnectListener provides the necessary methods once the connection is
established. The class implements the interface WLResponseListener, which defines the
methods onSuccess and onFailure used to process connection success or connection
failure.

V8.1
Student Notebook
Uempty
Invoking a procedure Android

use the WLClient instance to invoke adapter procedures
Figure 11-11. Invoking a procedure - Android
WU5061.1
Notes:
1. Create a WLProcedureInvocationData object with the adapter and procedure names.
2. Add the required parameters as an object array and set request options (for example:
timeout).
3. Get existing the WLClient instance and use it to invoke adapter procedure. Specify the
MyInvokeListener class instance as a parameter.

11-15
Student Notebook
Processing a response: Android MyInvokeListener

The WLClient instance calls one of the methods of the
MyInvokeListener class
MyConnectListener class implements the WLResponseListener
interface
public class MyInvokeListener

implements WLResponseListener{
The onSuccess and onFailure methods are invoked by the
WLClient
Figure 11-12. Processing a response: Android - MyInvokeListener
WU5061.1
Notes:
The interface WLResponseListener defines only two methods, onFailure and onSuccess.
These methods are invoked in response to calls to WLClient.connect or
WLClient.invokeProcedure; in other words, user code does not call them directly, it just
defines when (and how) they should be called.

V8.1
Student Notebook
Uempty
Processing a response: Android MyConnectListener

If the procedure invocation is successful, the onSuccess method of
MyInvokeListener is invoked
Use it to get data that are retrieved from the adapter
The response object contains the response data

Use its methods and properties to retrieve the required information
Figure 11-13. Processing a response: Android - MyConnectListener
WU5061.1
Notes:
Assuming the response is a success response, the onSuccess method is invoked and the
response is passed in as argument. The response data can be extracted using the method
getResponseText, and the view can be updated accordingly. Likewise, in the event of
failure, the onFailure method is invoked and the response object is handed in as argument.
Again, the view would be updated accordingly.

11-17
Student Notebook

V8.1
Student Notebook
Uempty
11.2.iOS native API

11-19
Student Notebook
iOS native API

Figure 11-14. iOS native API
8.0
WU5061.1
Notes:
The next slides discuss the same topics as the previous, but this time from the point of view
of the iOS application.

V8.1
Student Notebook
Uempty
iOS native API

WorklightAPI
A Worklight API library that must be copied
to the native iOS project
Defines application meta data and security
configuration
Worklight.plist
Contains connectivity settings to be used
by a native iOS application.
This file must be copied to the native iOS
project
This file is discussed in detail further on
Figure 11-15. iOS native API
WU5061.1
Notes:
This slide shows the structure of the application that was generated earlier in this
presentation. It includes an XML file called application descriptor, a folder called
WorklightAPI that is copied to the iOS project, and the file called worklight.plist, which is
also copied to the native iOS project. This file is discussed on the next slide.

11-21
Student Notebook
Editing worklight.plist (iOS)

Edit the worklight.plist file that holds the server configuration
Figure 11-16. Editing worklight.plist (iOS)
WU5061.1
Notes:
- protocol
Communication protocol to the Worklight server. Either http or https
- host
Hostname of the Worklight server
- port
- Port of the Worklight server
- wlServerContext
Context root path of the application on the Worklight server
- application id
Application ID as defined in application-descriptor.xml
- application version
The application version

V8.1
Student Notebook
Uempty
- environment
Target environment of the native application

11-23
Student Notebook
Configure an iOS native application

Create a new Xcode project (or use an existing one)
Copy the WorklightAPI folder and the worklight.plist file from the eclipse
Worklight native API to the root of your native project
Link the following libraries in your native iOS application
CFNetwork
SystemConfiguration
MobileCoreServices
CoreData
Security
libz.dylib
Figure 11-17. Configure an iOS native application
WU5061.1
Notes:
To configure a native application for iOS you must first create a new Xcode project. There
are two objects that we have already seen in the Eclipse Worklight project that need to be
copied here the WorklightAPI folder and the worklight.plist file. You copy these to the root
of your iSO application. Then there are number of libraries that you must link. These are
shown on the slide.

V8.1
Student Notebook
Uempty
Initializing the WLClient iOS (1 of 3)

Create an instance of the WLClient to communicate with the Worklight
server by using the wlConnectWithDelegate
Make sure to import the WLClient.h and the WLDelegate.h in the

header file
Figure 11-18. Initializing the WLClient - iOS (1 of 3)
WU5061.1
Notes:
The next three slides show the initializing of WLClient.
First, you create an instance of WLClient. This communicates through
WLConnectWithDelegate with the worklight server. The slide

11-25
Student Notebook

Create a delegate called MyConnectListener for
wlConnectWithDelegate to receive the response from the server
The header file must specify that it implements the WLDelegate
protocol.
WLDelegate specifies that the class implements these methods:

onSuccess (WLResponse *)response
onFailure (WLFailResponse *)response
WU5061.1
Notes:
The next step in initializing the WLClient is to create a delegate that receives the response
passed back from the Worklight server. Here it is called MyConnectListener. It is through
WLDelegate that the onSuccess and onFailure methods are implemented.
These methods are discussed next.

V8.1
Student Notebook
Uempty

The onSuccess and onFailure methods are coded as follows:
WU5061.1
Notes:
After wlConnectWithDelegate finishes, the onSuccess method or the onFailure method of
the supplied MyConnectListener instance is invoked. In both cases, the response object is
sent as an argument. Use this object to work with data retrieved from the server.

11-27
Student Notebook
Invoking a procedure iOS

Create a WLProcedureInvocationData object and specify the
adapter name and the procedure name
Invoke the procedure using a shared instance of WLClient
The code requests the delegate to take care of the invocation result
Figure 11-21. Invoking a procedure - iOS
WU5061.1
Notes:
In order to invoke a procedure, you need to create an object with the name of the adapter,
and the name of the procedure that you want to invoke. These pieces of information are
wrapped in a WLProcedureInvocationData object. Finally, the procedure is invoked by
using a shared instance of the WLClient and passing in the WLProcedureInvocationData
object. The invokeListener object is passed in to handle the result.
This is discussed next.

V8.1
Student Notebook
Uempty
Processing a response: iOS MyInvokeListener

When the procedure invocation is completed, it sends a message to an
instance of the MyInvokeListener class
A delegate header must comply with a WLDelegate protocol
If the procedure invocation was successful, the onSuccess method

from MyInvokeListener is invoked
Figure 11-22. Processing a response: iOS - MyInvokeListener
WU5061.1
Notes:
In fact, you would probably want to check that there was something in the response before
trying to execute code in it! For example, you can add a simple test that the value of the
returned object is not nil:
if ( [response responseText] != nil) {}

11-29
Student Notebook
1. "Defines application meta data and security configuration
Which file is this defining?
2. In an Android application, you need to add an internet permission.
Which file do you edit?
1. AndroidManifest.xml
2. application_descriptor.xml
3. worklight.properties
4. android_config.xml
3. On iOS, you have created a WLProcedureInvocationData object and
specified the adapter name. What else must be specified?
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Unit summary
WU5061.1
Notes:

11-31
Student Notebook
Checkpoint answers
1. "Defines application meta data and security configuration
Which file is this defining?
application_descriptor.xml
2. In an Android application, you need to add an internet permission.

Which file do you edit?
2. application_descriptor.xml
3. worklight.properties
4. android_config.xml
3. On iOS, you have created a WLProcedureInvocationData object and

specified the adapter name. What else must be specified?
Procedure name
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Unit 12. Security

This unit describes the authentication techniques provided by
Worklight to secure a mobile application and the server-side APIs that
support them.

Describe the different authentication approaches supported by
Worklight
Use server-side APIs to secure a mobile application

Checkpoint
Exercise
References
Unit 12. Security

12-1
Student Notebook
Unit objectives
Worklight
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Topics
Authentication concepts and entities
Adapter-based authentication
Custom login modules
WebSphere LTPA-based authentication
Figure 12-2. Topics
WU5061.1
Notes:
Unit 12. Security

12-3
Student Notebook
Authentication
Worklight entities, such as applications and adapter procedures, can
be protected from unauthorized access
Entities are protected by authentication realms
Security rules are defined by a security test that contains one or
more authentication realms.
An authentication realm defines the process to be used to
authenticate users
Each authentication realm consists of:
A Challenge Handler component on the client slide
An Authenticator: client and server components which are used to collect
credentials (e.g. login form)
A Login module: server component that receives credentials from the
authenticator, validates them and builds the user identity object
The following slides look at these entities in detail
4
Figure 12-3. Authentication
WU5061.1
Notes:
The same authentication realm can be used to protect several resources.
Worklight runtime framework provides the ability to authenticate mobile application users
before access is granted to protected resources, namely: application itself or to the
information on back-end systems. Mobile applications are designed to use adapters to
access back-end systems. Mobile apps and adapters are referred as Worklight entities.
When required, an entity could be protected by defining and associating an authentication
realm with it. An authentication realm is a reference to the configuration that can be put in
place so that the Worklight runtime can enforce the checks required before access is
provided to a the mobile application entities. Once defined, an authentication realm can be
used to protect several entities.
An authentication realm definition references two other artifacts that are part of the
Worklight runtime framework, namely, authenticators and login-modules.
An authenticator can be a combination of both client and server side components. It is
essentially used to retrieve user credentials.
V8.1
Student Notebook
Uempty
A login-module is a server-side component and is used to validate the user credentials

received from the authenticator.
To integrate and use WebSphere Application Servers security service, you can use the
predefined realm IBMWebSphereLTPARealm.
Unit 12. Security

12-5
Student Notebook
Authentication sequence
Client
Unauthenticated
Unauthenticated user
user tries
tries to
to
access
access the
the resource
resource protected
protected
by
by an
an authentication
authentication realm
realm
Challenge
Challenge Handler
Handler :: detects
detects
the
the challenge,
challenge, collects
collects the
the
credentials,
and
sends
credentials, and sends them
them to
to
the
the Authenticator
Authenticator
Server
The
The server
server asks
asks the
the client
client to
to
provide
provide credentials
credentials (a
(a
challenge)
challenge)
Authenticator
Authenticator collects
collects the
the user
user
credentials
credentials
IfIf the
the supplied
supplied credentials
credentials pass
pass
validation,
Login
Module
validation, Login Module
creates
creates the
the User
User Identity
Identity
object
object and
and flags
flags session
session as
as
authenticated
in
a
given
realm
authenticated in a given realm
The
The client
client application
application autoautomatically
matically resends
resends the
the request
request
Authentication
Authentication success
success
message
returned
message returned to
to user
user
Figure 12-4. Authentication sequence
WU5061.1
Notes:
Here is the high level flow for end-user authentication process in Worklight: The Worklight
run-time determines if a request is being made t to the protected entity, it checks whether
the session is already authenticated. If not, Worklight invokes the authenticator associated
with the authentication realm the protected resource belongs to. The authenticator collects
the user credentials sends it to the Worklight Server. The server run-time passes these
credentials to the login-module associated with the realm, which then validates them
against the configured authentication service. Once the end-user is validated, the request
is handled.
In case the user is authenticated for a entity, all subsequent requests to that entity are
handled without request for end-user credentials as far as the session is still valid.
Worklight could be configured automatically grant access to all entities protected by a
specific authentication realm.

V8.1
Student Notebook
Uempty
Authentication entities: challenge handler

A client side entity that controls the authentication process
Used to detect and handle authentication challenges in the server responses
A separate challenge handler instance should be created for each

realm an application needs to authenticate in
It can be used to detect and handle Worklight-related and external
authentication challenges (authentication proxies, gateways)
Upon detecting an authentication challenge returned from the server, it
is responsible for collecting and returning the required credentials
After the authentication flow completes, the challenge handler can send
notification back to the Worklight framework about success or failure
Created with a predefined set of methods
used to submit credentials
to the built-in authentication
types of the Worklight Server
Figure 12-5. Authentication entities: challenge handler
WU5061.1
Notes:
The challenge comes from the server. The challenge handler therefore has functions that
are called when a server responds to a client request.
Unit 12. Security

12-7
Student Notebook
Authentication entities: authenticator

A server-side entity responsible for collecting credentials from the client
application
An authenticator can collect any type of information accessible from an HTTP
request object cookies, headers, body, or any other properties
The Worklight server includes a set of predefined authenticators:

Form-based authenticator. Returns a challenge in the form of an HTML login
form, making it useful for web environments as well as mobile applications
Adapter-based authenticator. Uses the Worklight adapter procedure to collect
and validate the credentials from the client application.
A header-based authenticator. Does not require interactive credentials collection,
but instead checks a specific HTTP header
Realm
Security test
Authenticator
Login module
Figure 12-6. Authentication entities: authenticator
WU5061.1
Notes:
In addition to predefined authenticators, you can create your own custom authenticator by
using the Java code.
An authenticator can be designed to be either inter-active or non-interactive. Typically,
non-interactive authenticators can be just server-side implementations.
Interactive authenticator could be realized either with just server-side implementation or
with both client and server implementation. The Worklight run-time provides the server
side jsp files in order to capture user credentials.
Implementation wise, developer needs to provide the client-side authentication logic such
as building UI to gather user credentials like userid and password.
An authenticator could be customized if required. This is covered later in the course.

V8.1
Student Notebook
Uempty
Authentication entities: login module

A server-side entity responsible for verifying user credentials, and for
creating a user identity object to hold user properties for the session.
Credential validation can be done in one of the following ways:
Using a web service
Looking up the user in a users table in a database
Using the WebSphere LTPA token
It is possible to add custom user properties according to the enterprise

needs
The user identity object is destroyed on session termination
It can be configured to automatically record login attempts for audit
purposes
In addition to predefined login modules, you can create your own
custom login module using Java code
Realm
Security test
Authenticator
Login module
Figure 12-7. Authentication entities: login module
WU5061.1
Notes:
A session may be terminated by the user logging out, or through a timeout.
Login-modules are always implemented on the server. The login-module validates user
credentials using one of several options, some of which includes accessing a web-service
or an LDAP based user registry. Once a user is authenticated, the login-module sets up a
user identity object which remains valid as long as the associated session is valid. The
contents of the user identity object are determined by the login module.
As part of the configuration that defines the login-module, it is possible to have the
Worklight runtime keep track of the number of attempts to login.
A login-module could be customized if required. This is covered later.
Unit 12. Security

12-9
Student Notebook
Authentication entities: authentication realms

A combination of one authenticator and one login module
Each authentication realm defines its authentication flow:
What should happen after the authentication process is triggered?

What is the form of challenge that should be sent to the client application?
Which credentials should be collected?
How and when should credentials be collected?
How should credentials be sent to server?
How should credentials be validated by server?
What is the result of the credentials validation?
What are the properties of the user identity object?
Worklight provides predefined authentication realms for security

features (remote application disable, application authenticity)
Realm
Security test
Authenticator
Login module
Figure 12-8. Authentication entities: authentication realms
WU5061.1
Notes:
Each authentication realm defined in the server authentication configuration should have a
corresponding challenge handler in the client application.

V8.1
Student Notebook
Uempty
Authentication entities: security tests

A security test is an ordered set of authentication realms that is used to
protect a resource such as an adapter procedure, an application, or a
static URL
A security test defines the realms that the user must authenticate
against in order to get access to the protected resource
A developer can define the order in which the authentication should be
performed
For example, execute request authentication in realm2 only if realm1
authentication has succeeded
Realm
Security test
Authenticator
Login module
10
Figure 12-9. Authentication entities: security tests
WU5061.1
Notes:
The IBM Worklight framework provides default security tests definitions for mobile and web
environments as well as the ability to create custom security tests. There is further
discussion of this in the following slides.
Unit 12. Security

12-11
Student Notebook

The same Authenticator type can be used for several realms.
Realm1
Authenticator 1
Security test 1
Login module 1
Realm 2
Authenticator 1
Security test 2
Login module 2
Realm 3
Authenticator 2
Security test 3
Login module 3
11
Figure 12-10. Authentication concepts and entities
WU5061.1
Notes:

V8.1
Student Notebook
Uempty

A realm has one authenticator and one login module
Realm1
Authenticator 1
Security test 1
Login module 1
Realm 2
Authenticator 1
Security test 2
Login module 2
Realm 3
Authenticator 2
Security test 3
Login module 3
12
WU5061.1
Notes:
Unit 12. Security

12-13
Student Notebook

A security test can use one or more realms
Realm1
Authenticator 1
Security test 1
Login module 1
Realm 2
Authenticator 1
Security test 2
Login module 2
Realm 3
Authenticator 2
Security test 3
Login module 3
13
WU5061.1
Notes:

V8.1
Student Notebook
Uempty

A realm can be used by one or more security tests
Realm1
Authenticator 1
Security test 1
Login module 1
Realm 2
Authenticator 1
Security test 2
Login module 2
Realm 3
Authenticator 2
Security test 3
Login module 3
14
WU5061.1
Notes:
Unit 12. Security

12-15
Student Notebook
Defining realms
Authentication settings are configured in the
server/conf/authenticationConfig.xml file of the project
Each realm has a name, a loginModule specification, a className of
an authenticator implementation and optional parameters
Figure 12-14. Defining realms
WU5061.1
Notes:
The key component that holds the configuration of authentication realms is the
authenticationConfig.xml file. This file is located in the server/conf directory located in the
Worklight server home in the Worklight installation directory or in your Studio project. A
sample snippet of the contents of the authenticationConfig.xml file is shown above. You
learn the details in the coming slides.

V8.1
Student Notebook
Uempty
Defining login modules

Each login module has a name attribute and a tag with the className
of the implementation
There may be an audit attribute
Some login modules have parameters
16
Figure 12-15. Defining login modules
WU5061.1
Notes:
The second stanza in the authenticationConfig.xml file is the login-module. The tag
<loginModules> defines the login-modules that are setup for use of end-user
authentication. Each login module defined under the <loginModules> tag is encapsulated
in the <loginModule> tag. This tag has one mandatory attribute, name, which is a unique
name to identify the login module. This is used in defining the login module associated with
a realm. The optional audit attribute defines whether the login module usage should be
logged in the Worklight server audit.log file.
The XML sub-elements that can be specified for <loginModule> are <className> which is
the Java class name of the module and <parameter> which is meant to specify initialization
parameter for the module. The list of parameters are implementation dependent.
Unit 12. Security

12-17
Student Notebook
Defining authenticators
Worklight provides several authenticators that are ready for
immediate use:
Form-based authenticator: presents a login form to the user containing
user name and password fields
Header authenticator: non-interactive, used with a Header login module
Adapter-based authenticator: fully customizable authenticator that is
implemented using the adapter. Can be used with any login module
Worklight allows writing custom login modules and authenticators

when the default ones are not sufficient
Worklight contains all necessary libraries to support WebSphere
Application Server security
For more information about Worklight authentication concepts, see
the Developer Reference Guide and Administration Guide
Figure 12-16. Defining authenticators
WU5061.1
Notes:
Worklight provides several authenticators out-of-the-box the slide provides a list of these.
Each authenticator requires a different parameter to be specified as part of the
configuration in the authenticatorConfig.xml file. This has been indicated against each
authenticator listed.
The basic authenticator implements basic HTTP authentication. The <basic-realm-name>
is a string that is sent to the client as a realm name, to be presented by the browser in the
login dialog.
The form-based authenticator presents a login form to the user. The <login-page>
parameter allows a login page URL to be specified. This URL must be relative to the web
application context. The <error-page> similarly allows an error page URL to be specified.
Typically the out-of-the-box jsp files are used for these two URL parameters. In case
custom pages are used, the login form must contain fields named j_username and
j_password, and the submit action should be j_security_check. If the login fails, the user is
redirected to an error page.

V8.1
Student Notebook
Uempty
The header authenticator is not interactive. The header authenticator must be used with
the Header login module.
The persistent cookie authenticator looks for a specific cookie in any request that is sent to
it. If the request doesnt contain the cookie, the authenticator creates a new cookie, and
sends it in the response. This authenticator is not interactive, that is, it doesnt ask the user
for credentials, and is mainly used in environment realms. The <cookie-name> parameter
allows the name of the persistent cookie to be specified. The default <cookie-name> is
WL_PERSISTENT_COOKIE.
The Adapter authenticator enables you developing custom authentication logic in
JavaScript within an adapter. This is mostly useful for multi-step login processes that
cannot be implemented by merely configuring the authenticators defined above. This
authenticator can be used with any login module. The parameters allow the login and
logout functions to be specified.
In case of interactive authenticators, the client side auth.js must be defined appropriately.
Unit 12. Security

12-19
Student Notebook
Defining security tests (1 of 2)

The IBM Worklight platform allows setting up multiple realms for a
security test
As a part of the security test setup, you must tell IBM Worklight which
of the realms are considered a user realm and a device realm
An identity that is taken from a realm that is defined as a user realm is
used by IBM Worklight as a user identity for features that require one,
such as the push notification or the application usage reports
An identity that is taken from a realm that is defined as a device realm
is used by IBM Worklight as a device identity for features that require
one, such as the device provisioning, the push notification, and the
SMS notification
18
Figure 12-17. Defining security tests (1 of 2)
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Defining security tests (2 of 2)

After you set up your authentication realms, you must define the
security tests used to protect your applications, adapter procedures,
and static resources
There are three types of security tests that can be defined in the
authenticationConfig.xml file:
The webSecurityTest a test that has default web security-related realms
enabled.
The mobileSecurityTest a test that has default mobile security-related realms
enabled.
The customSecurityTest a custom security test. Does not contain any default
realm.
Figure 12-18. Defining security tests (2 of 2)
WU5061.1
Notes:
Unit 12. Security

12-21
Student Notebook
webSecurityTest
The webSecurityTest is used to protect web applications
By default the webSecurityTest includes a protection against XSRF
attacks
See the IBM Worklight Info Center for details on this
Each webSecurityTest must contain one <testUser> element with a

realm definition
This realm is considered a user realm
Figure 12-19. webSecurityTest
WU5061.1
Notes:
Cross-site request forgery (XSRF) attacks occur when an unauthorized command seems
to be sent from a browser that the website trusts. For example, the browser is pointed to a
malicious site, which responds with an HTML page that silently retrieves banking
information from a cookie on the browser, then calls the bank using the genuine users
identity information.

V8.1
Student Notebook
Uempty
mobileSecurityTest
The mobileSecurityTest is used to protect mobile applications
By default the mobileSecurityTest includes:
A protection against XSRF attacks
An application authenticity test
For more information on both of these, see the IBM Worklight Info Center
The ability to remotely disable mobile application from the Worklight console
Each mobileSecurityTest must contain one <testUser> element with

realm definition
This realm is
considered a user
realm
Figure 12-20. mobileSecurityTest
WU5061.1
Notes:
Unit 12. Security

12-23
Student Notebook
customSecurityTest
The customSecurityTest defines custom security preferences
The developer defines realms
Any number of tests can be defined

User or device realms can be defines
Authentication order can be defined
Figure 12-21. customSecurityTest
WU5061.1
Notes:
The developer decides what security preferences are associated with the test. The order in
which tests are applied can be set by the test attribute step. If there is no property given,
all tests are executed as a single step. Two other attributes can be defined: isInternalUserId
and isInternalDeviceId. The isInternalUserID attribute indicates that the test realm is
applied for reporting and push subscriptions as a user identification. the isInternalDeviceID
attribute indicates that the realm is used for device identification in reporting, push
subscriptions, and device single sign on.

V8.1
Student Notebook
Uempty
Protecting adapters
Authentication is required when the adapter procedure is invoked
A separate securityTest can be defined for each adapter procedure in
the adapter XML file
Figure 12-22. Protecting adapters
WU5061.1
Notes:
The authentication realm that is to be used to protect an adapter procedures needs to be
specified in the adapter's declaration XML file as a attribute to the <adapter> tag. The n
attribute is securityTest. See the slide for an example of an adapter XML file with the
attribute specified.
Unit 12. Security

12-25
Student Notebook
Protecting applications
Authentication is required immediately when an application connects
to the Worklight server
A separate securityTest can be defined for each application
environment
Figure 12-23. Protecting applications
WU5061.1
Notes:
Mobile applications can be configured in three ways with respect to protection from user
access:
- In case the application uses data that is publicly available and this data is modified
just for a specific user without impacting others, then such mobile applications can
be configured with no protection at all.
- In case the application displays user sensitive information and allows actions that
permanently impact user data, then such mobile applications can be configured to
be protected upon startup.
- In case the mobile application can start with needing protection but at some point,
based on usage, results in an attempt to access or modify user sensitive
information, then such mobile applications can be configured to be protected on
demand. In such cases, the user is required to provide credentials only when
required by the application.

V8.1
Student Notebook
Uempty
If no securityTest is defined for a specific environment, only a minimal set of default

platform tests is performed.
Unit 12. Security

12-27
Student Notebook
Protecting static resources

A static resource is a URL loaded from a Worklight server:
For example: the Worklight console or mobile web application.
Protecting a static resource means that the Worklight server

requires authentication when an attempt to browse to the
specified URL is made.
The static resources and their protection can be defined in the
authenticationConfig.xml file.
Figure 12-24. Protecting static resources
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
12.1.Adapter-based authentication
Unit 12. Security

12-29
Student Notebook
Adapter-based
authentication
Figure 12-25. Adapter-based authentication
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Adapter-based authentication
Adapter-based authentication is the most flexible type to implement
With adapter-based authentication, the entire authentication logic,
including the credentials validation, can be implemented in
JavaScript in an adapter
Any login module can be used in the adapter-based authentication as
an additional authentication layer
In this unit, a simple username/password adapter-based authentication
mechanism is described
Figure 12-26. Adapter-based authentication
WU5061.1
Notes:
Among various choices Worklight authentication framework provides, Adapter based
authentication is probably the easiest one to implement, but it contains all the features and
benefits of the Worklight server authentication framework.
Adapter based authentication provides a flexible framework to authenticate users. Its entire
logic, including gathering user credentials and validate against user repository for the
credential, can be implemented in an adapter, using using plain JavaScript without writing
custom login modules in Java. This simplifies the implementation and speeds up the
development.
Still, if you have complex or custom login logic, you can easily integrate with Adapter based
authentication framework by providing it a custom login module as an additional
authentication layer.
The remaining discussion for adapter based authentication illustrates implementing a
simple username and password adapter based authentication.
Unit 12. Security

12-31
Student Notebook
Adapter-based authentication process
Application tries to access a

protected resource
YES
Worklight platform checks whether

user is already authenticated
Protected resource access is

granted. Application receives the
requested data.
NO
Authentication process is started. Application

receives the authentication required payload
as defined by the developer.
Authentication process
YES
Success
NO
Figure 12-27. Adapter-based authentication process
WU5061.1
Notes:
Before diving into the implementation, it is important to understand how Worklight handles
the authentication process for adapter based authentication.
The process starts with a request made to a protected resource, such as invoking a
protected adapter procedure from a mobile client. Worklight server checks whether user is
already authenticated using techniques such as persistent cookie. If user is already
authenticated, allow user to access protected resource, business logic is executed.
If not, authentication process is started. The calling application such as mobile client
receives a response that contains authentication required. Then, the client and side
component engages in authentication process such as providing user credential and
validate username and password until the process success. Then, Worklight grant the
access to invoked Worklight resource, business logic is executed.

V8.1
Student Notebook
Uempty
Configuring a realm on authenticationConfig.xml

Add a new authentication realm to authenticationConfig.xml
This realm uses SingleStepAuthLoginModule login module, defined later
Figure 12-28. Configuring a realm on authenticationConfig.xml
WU5061.1
Notes:
Under the new SingleStepAuthRealm definition, specify a Worklight built-in authenticator
used for adapter based authentication for Worklight server. This component is defined by a
className element with value com.worklight.integration.auth.AdapterAuthenticator. This
component is a Java class that provides adapter based authenticator.
Define two parameters for SingleStepAuthRealm. There parameters specify the adapter
which provides the authentication implementation and also defines the mapping of login
and logout function to the adapter procedures. The SingleStepAuthRealm uses an adapter
named SimpleAuthAdapter to implement the login and logout function, through its
procedures onAuthRequired and onLogout.
When the Worklight authentication framework detects an attempt to access a protected
resource, an adapter function that is defined in a login-function parameter is invoked
automatically. When logout is detected (explicit or session timeout), a logout function is
invoked automatically. In both cases, the parameter value syntax is
adapterName.functionName.
Unit 12. Security

12-33
Student Notebook
Configuring a login module on authenticationConfig.xml

NonValidatingLoginModule means that no additional validation is
performed by the Worklight Platform, and the developer takes
responsibility for credential validation within the adapter
Figure 12-29. Configuring a login module on authenticationConfig.xml
WU5061.1
Notes:
Now you have the realm and authenticator defined, need to add the definition loginModule
used by SimpleAuthRealm.
Worklight login module is defined with a LoginModule element under loginModules section
in authenticationConfig.xml file.
The className element specifies how the login is handled, this component normally is a
JavaClass either provided by Worklight out-of-the-box or a custom built one.
The built in loginModule com.worklight.core.auth.ext.NonValidatingLoginModule is used in
the example on the slide.
Because all authentication-related actions are done in the adapter code, using
NonValidatingLoginModule is a mandatory requirement for adapter-based
authentication.

V8.1
Student Notebook
Uempty
Configuring authenticationConfig.xml
Add a security test to the <securityTests> section of the
authenticationConfig.xml file
This security test is used to protect the adapter procedure, therefore it
is a <customSecurityTest>
Remember the security test name: you see it in the following slides

2013
Figure 12-30. Configuring authenticationConfig.xml
WU5061.1
Notes:
Unit 12. Security

12-35
Student Notebook
Server-side authentication: components overview

The flow to be implemented:
getSecretData
Application
Authentication is required
Worklight
Server
submitAuthentication
You are authenticated now
getSecretData
Here is your secret data
Figure 12-31. Server-side authentication: components overview
WU5061.1
Notes:
What happens for the sample app is illustrated in the diagram here, following the
authentication process discussed earlier.
The mobile application invokes the protected getSecretData procedure for the first time.
Worklight detects that the user is not authenticated, it send an authentication required
message back to the client. A client side component such a custom login form asks the
user to input username and password, then the client code invokes adapter procedure
submitAuthentication and pass in username and password.
Once Adapter receives valid username password and validate them successfully, it marks
user authenticated and creates a user object in session. This returns back to the client
code, it can completes the invocation for the getSecretData procedure and gets the data
needed from backend adapter.

V8.1
Student Notebook
Uempty
Server-side authentication components (1 of 3)

SimpleAuthAdapter defines two procedures that are publicly visible
submitAuthentication: No security constraint
requestForData: Requires the user to be logged in
Figure 12-32. Server-side authentication components (1 of 3)
WU5061.1
Notes:
Functions are made publicly visible in an adapter by defining a procedure tag in the
configuration. There are two forms of the tag: either the function can be directly accessed
(only its name is listed), or it requires the user to be logged in (its name is listed together
with a securityTest). An unauthenticated user who sends a request to the requestForData
function is redirected to an authentication mechanism. An authenticated user is able to
access both of the functions.
Unit 12. Security

12-37
Student Notebook

Whenever the Worklight framework detects an unauthenticated
attempt at access to a protected resource, the onAuthRequired
function is invoked (as previously set up in the
authenticationConfig.xml file)
This function receives response headers and an optional
errorMessage parameter. The object returned by this function is
sent to the client application.
Note the authRequired: true property. The client application uses
this property to detect the request for authentication
WU5061.1
Notes:
The returned JSON information is a custom Authentication is required object.
Here is a break down of the flow into implementation detail.
In the first step the Worklight framework detects an unauthenticated attempt at access to a
protected resource. The framework therefore invokes the adapter onAuthRequired function
(as previously set up in authenticationConfig.xml).
This function receives response headers and an optional errorMessage parameter. The
object returned by this function is sent to the client application.
In the return message, the property authRequired:true is critical because client
authentication code uses this attribute to launch the login procedure.

V8.1
Student Notebook
Uempty

submitAuthentication is invoked by a client
WU5061.1
Notes:
The second implementation in the adapter is the actual procedure that receives the
username and password supplied by the user, and validates them against a user registry to
complete the authentication process. This procedure is invoked by the client side
authentication logic.
Note that for simplicity the conditional logic is hardcoded in the example on the slide. In a
real-world implementation, you need to provide a validation implementation, such as
validating against database or invoking a web service to validate the login credentials.
If validation is successful, the WL.Server.setActiveUser API is called to create an
authenticated session for the realm with user data stored in a userIdentity object. Note that
you can add your own custom properties to the user identity attributes. An object is
returned to the application stating that the authentication screen is no longer required
(authRequired:false).
If validation fails, onAuthRequired is invoked to create an object that is returned to the
application with an error message.
Unit 12. Security

12-39
Student Notebook

V8.1
Student Notebook
Uempty
Invoking the protected function

getSecretData function returns a hardcoded value in this example
The onLogout function is defined in the authenticationConfig.xml file to be
invoked automatically on logout
To perform a cleanup, for example
Figure 12-35. Invoking the protected function
WU5061.1
Notes:
Finally, when authentication process completes successfully, the client application can
invoke the protected adapter procedure getSecretData just as any other procedure.
In the same adapter, you can implement the logout function via the onLogout procedure.
For example, destroying a user object or writing a log message.
Unit 12. Security

12-41
Student Notebook
Client-side authentication : HTML AppDiv

The common HTML consists of two main <div> elements
<div id=AppDiv> element is used to display the application content
<div id=AuthDiv> element is used for authentication form purposes
Figure 12-36. Client-side authentication : HTML AppDiv
WU5061.1
Notes:
For this simple application, a custom login form is built that captures user name and
password. This is wrapped in an AuthDiv HTML element.
The AppDiv represents the application user interface. When authentication is required, the
application hides the AppDiv and shows the AuthDiv. When authentication is complete, it
does the opposite. Buttons are used to invoke the getSecretData procedure and log out.
<div id=ResponseDiv> is used to display the getSecretData response.

V8.1
Student Notebook
Uempty
Client-side authentication : HTML AuthDiv

AuthDiv contains the following elements
AuthInfo to display error messages

AuthUsername and AuthPassword input elements
AuthSubmitButton button
AuthDiv is styled as display:none, because it must not be displayed

before authentication is requested by the server
Figure 12-37. Client-side authentication : HTML AuthDiv
WU5061.1
Notes:
The AuthDiv provides text fields for the user to enter the values required by the
authentication mechanism in this case, a simple id and password combination. Typically,
when the Submit button is clicked, there would be client-side JavaScript to verify that there
is some information in the fields, and that it is of the correct format (for example, it only
includes the characters that make up a decimal number, in a field used to enter a money
value).
Unit 12. Security

12-43
Student Notebook
Client-side authentication : challengeHandler

Create a challenge handler
Use WL.Client.createChallengeHandler() to create a challenge
handler object
A realm name must be supplied as a parameter
Figure 12-38. Client-side authentication : challengeHandler
WU5061.1
Notes:
The isCustomResponse function of the challenge handler is called each time a response is
received from the server. It is used to detect whether the response contains data that is
related to this challenge handler. It returns true or false.
If isCustomResponse returns true, the framework calls the handleChallenge() function.
This function is used to perform required actions, for example, hide the application screen
and show the login screen.

V8.1
Student Notebook
Uempty
More challengeHandler functions

myChallengeHandler.submitAdapterAuthentication()
Used to send credentials to a specific adapter procedure. It has the same
signature as the WL.Client.invokeProcedure() API
myChallengeHandler.submitSuccess()
Notifies the Worklight framework that the authentication finished successfully
The Worklight framework then automatically issues the original request that
triggered the authentication
myChallengeHandler.submitFailure()
Notifies the Worklight framework that the authentication completed with failure
The Worklight framework then destroys the original request that triggered the
authentication
Figure 12-39. More challengeHandler functions
WU5061.1
Notes:
You see these functions used for the implementation of the challenge handler further on.
Unit 12. Security

12-45
Student Notebook
Creating client-side authentication components (8 of 11)

The isCustomResponse function detects whether the server
response contains the challenge object previously defined
Adapter code
The challenge object was defined

in the adapter
Figure 12-40. Creating client-side authentication components (8 of 11)
WU5061.1
Notes:
The authRequired property was defined in the adapter JavaScript implementation. It is
used here
to determine whether authentication is required or not. The function returns true if the
authRequired
property is found, otherwise it returns false.
The function also checks whether the response is in a format that can be understood by the
condition that looks at the value of authRequired. If not, it is assumed that authentication is
not required.
From this, you can see that if authentication is required the adapter must return a clear
authRequired statement to the application.

V8.1
Student Notebook
Uempty
Create the Handler function

Handler prepares the authentication view
Figure 12-41. Create the Handler function
WU5061.1
Notes:
The view is switched according to whether authentication is required or not. If
authRequired is true, it shows the login screen, empties the password field and AuthInfo,
and shows an errorMessage (if present).
If the authRequired is false, it hides AuthDiv and shows AppDiv, and it notifies the Worklight
framework that the authentication completed successfully.
Unit 12. Security

12-47
Student Notebook
Binding the AuthSubmitButton to a function

Clicking a login button triggers a function that collects the user name
and password from the HTML input fields, and submits them to the
adapter
The challenge handler submitAdapterAuthentication method is
used to bind the click to the function
Figure 12-42. Binding the AuthSubmitButton to a function
WU5061.1
Notes:
There is no need to specify the callbacks because the response is checked by the
Worklight framework.

V8.1
Student Notebook
Uempty
12.2.Custom login modules
Unit 12. Security

12-49
Student Notebook
Custom login modules
Figure 12-43. Custom login modules
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Session scope and additional modules

Authenticator, Login Module and User Identity instances are stored in a
session scope. They exist as long as the session exists
You can write custom login modules and authenticators when the
default ones do not suffice
The previous topic described how to implemented an adapter-based
authentication without using additional login modules
You used a non-validating login module and performed credentials validation
manually using an adapter
In some cases, when credential validation cannot be performed on the

adapter level and requires more complex code, an additional login
module can be implemented, for example:
Enterprise custom credentials validation is required
Additional information must be retrieved from each client request, such as
cookie, header, user-agent, and so forth
Figure 12-44. Session scope and additional modules
WU5061.1
Notes:
Unit 12. Security

12-51
Student Notebook
Custom authenticator overview

Implement a custom authenticator that collects user name and
password by using a request to a predefined URL.
Implement a custom login module that checks credentials received
from the authenticator.
Define a realm that uses your custom authenticator and login module.
Write a simple application that is protected by this realm. It runs the
authenticator and is used to authorize users with the custom login
module
Figure 12-45. Custom authenticator overview
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Configuring authenticationConfig.xml (1 of 2)
Add authentication information to the authenticationConfig.xml
Define a new realm called CustomAuthenticatorRealm.
Define its login module as CustomLoginModule
Specify MyCustomAuthenticator as className

<realm
<realm name="CustomAuthenticatorRealm"
name="CustomAuthenticatorRealm"
loginModule="CustomLoginModule">
loginModule="CustomLoginModule">
<className>com.mypackage.MyCustomAuthenticator</className>
<className>com.mypackage.MyCustomAuthenticator</className>
</realm>
</realm>
In the loginModules section add a new loginModule called

CustomLoginModule with class MyCustomLoginModule
<loginModule
<loginModule name
name ="CustomLoginModule"
="CustomLoginModule" canBeResourceLogin="true
canBeResourceLogin="true
isIdentityAssociationKey="false">
isIdentityAssociationKey="false">
<className>com.mypackage.MyCustomLoginModule</className>
<className>com.mypackage.MyCustomLoginModule</className>
</loginModule>
</loginModule>
Figure 12-46. Configuring authenticationConfig.xml (1 of 2)
WU5061.1
Notes:
Again, all authentication is defined under server/conf/authenticationConfig.xml file.
In here, you create a new authentication realm CustomAuthenticationRealm and make
sure that this realm uses CustomLoginModule.
Unlike the adapter based authentication, this realm uses a custom Java implementation as
authenticator, this is defined under the className section of the realm.
Then in the loginModule definition, again, specify the custom implementation Java class
name in the className section as shown in the slide.
Unit 12. Security

12-53
Student Notebook
Configuring authenticationConfig.xml (2 of 2)
Add a new security test in authenticationConfig.xml
This security test is used to protect the adapter procedure, therefore it
is defined as <customSecurityTest>
Figure 12-47. Configuring authenticationConfig.xml (2 of 2)
WU5061.1
Notes:
The LoginModule is referenced in the realm definition, then the realm definition serves to
built a securityTest definition.
Note the security test name. It is used in the following slides.

V8.1
Student Notebook
Uempty
Authenticator API (1 of 2)
Here is a summary of the Authenticator API:
void init(Map<String, String> options)
AuthenticationResult processRequest(HttpServletRequest request,
HttpServletResponse response, boolean isAccessToProtectedResource)
AuthenticationResult processAuthenticationFailure(HttpServletRequest
request, HttpServletResponse response, String errorMessage)
AuthenticationResult processRequestAlreadyAuthenticated
(HttpServletRequest request, HttpServletResponse response)
Figure 12-48. Authenticator API (1 of 2)
WU5061.1
Notes:
The init() method is invoked when an Authenticator instance is created. It is passed the
options map specified in realm definition in the authenticationConfig.xml.
processRequest () is invoked for each request from an unauthenticated session.
processAuthenticationFailure() is invoked when the login module returns a credentials
validation failure.
processRequestAlreadyAuthenticated() is invoked for each request from a session that
has already been authenticated.
Unit 12. Security

12-55
Student Notebook
Authenticator API (2 of 2)
Map<String, Object> getAuthenticationData()
HttpServletRequest getRequestToProceed(HttpServletRequest request,
HttpServletResponse response, UserIdentity userIdentity, LoginExtension...
loginExtension)
Boolean changeResponseOnSuccess (HttpServletRequest request,

HttpServletResponse response)
WorklightAuthenticator clone()
Figure 12-49. Authenticator API (2 of 2)
WU5061.1
Notes:
getAuthenticationData() is used by a login module to get credentials collected by an
Authenticator.
getRequestToProceed() is invoked after a login module successfully validates credentials
collected by an Authenticator.
The changeResponseOnSuccess() method is called after authentication success. It is used
to add data to the response after the authentication is successful.
clone() creates a deep copy of class members.

V8.1
Student Notebook
Uempty
Creating a custom Java authenticator

Create a new class in server\java folder. Call it
MyCustomAuthenticator
Make sure it implements the WorklightAuthenticator interface
public
public class
class MyCustomAuthenticator
MyCustomAuthenticator implements
implements WorklightAuthenticator
WorklightAuthenticator {{
Add the authenticationData object to your Authenticator to hold

the credentials information. This object is retrieved by a login module
private
private Map<String,
Map<String, Object>
Object> authenticationData
authenticationData == null
null ;;
Figure 12-50. Creating a custom Java authenticator
WU5061.1
Notes:
The authenticator Java class you write must implement the interface
com.worklight.server.auth.api.WorklightAuthenticator. This interface defines the signatures
for the methods you have seen: getRequestToProceed, processRequest, and so on. It
extends java.lang.Cloneable, and therefore you can create deep copies of authentication
objects.
Unit 12. Security

12-57
Student Notebook
Server library dependency

Add a Server runtime library dependency in order to use server related
classes, e.g. HttpServletRequest. The steps are:
Right-click the Worklight project and select Properties
Select Java Build Path Libraries and click Add Library
Select Server Runtime and click Next
You see a list of Server Runtimes installed in your Eclipse
Select the required library
Figure 12-51. Server library dependency
WU5061.1
Notes:
Unless you have other servers on your system, you only see one option for the server
runtime: Worklight Development Server, the Worklight Server that is installed as a part of
your Worklight plug-in.

V8.1
Student Notebook
Uempty
Custom Java Authenticator: init() and clone()

The init(..) method is invoked when Authenticator instance is created. It
receives options map specified in a realm definition in the
public
public void
void init(Map<String,
init(Map<String, String>
String> options)
options)
throws
MissingConfigurationOptionException
throws MissingConfigurationOptionException {{
logger.info(init);
logger.info(init);
}}
clone() creates a deep copy on the members of the object

@Override
@Override
public
public WorklightAuthenticator
WorklightAuthenticator clone()
clone() throws
throws CloneNotSupportedException
CloneNotSupportedException {{
MyCustomAuthenticator
MyCustomAuthenticator otherAuthenticator
otherAuthenticator ==
(MyCustomAuthenticator
(MyCustomAuthenticator )) super.clone();
super.clone();
otherAuthenticator.authenticationData
=
otherAuthenticator.authenticationData =
new
new HashMap<String,
HashMap<String, Object>(authenticationData);
Object>(authenticationData);
return
otherAuthenticator;
return otherAuthenticator;
}}
Figure 12-52. Custom Java Authenticator: init() and clone()
WU5061.1
Notes:
There are several key methods your custom authenticator needs to implement. Here is a
look at some of the core APIs.
The first is the init() method of Authenticator that is invoked when Authenticator instance is
created. It receives options map specified in realm definition in the
Clone is a routine Java method to create a deep copy of the members of a class.
Unit 12. Security

12-59
Student Notebook
Creating a custom Java Authenticator: overview

Here is the
code that is
discussed
over the
following
slides
Figure 12-53. Creating a custom Java Authenticator: overview
WU5061.1
Notes:
This slide is intended to give an overview of the code. The following slides show this same
code, broken into smaller pieces, and discussed in detail.

V8.1
Student Notebook
Uempty
Custom Java Authenticator: processRequest

Invoked for each unauthenticated request. Used to collect credentials
This function receives request, response and
isProtectedResource arguments.
It may retrieve data from a request and write data to a response
It must return a specific AuthenticationResult status
Figure 12-54. Custom Java Authenticator: processRequest
WU5061.1
Notes:
The processRequest() method is invoked for each request from an unauthenticated
session. This method is called by Worklight server side authentication framework.
This is where you can add logic to gather credential and decide whether to invoke the
custom login module.
The Authenticator collects the credentials for a login module; it does not validate them.
Unit 12. Security

12-61
Student Notebook
processRequest: verify URL and credentials

The application sends an authentication request to a specific URL. This
contains my_custom_auth_request_url, which the Authenticator
uses to make sure that this is an authentication request.
The Authenticator retrieves username and password credentials which
are passed as request parameters
if (request.getRequestURI().contains(
"my_custom_auth_request_url")) {
String username = request.getParameter("username");
String password = request.getParameter("password");
Figure 12-55. processRequest: verify URL and credentials
WU5061.1
Notes:
The String is not in itself any particular URL; it does not even have to be a URL. Its use is
simply to verify that the request did come from a given client.
It is recommended to have a different URL component in every Authenticator.

V8.1
Student Notebook
Uempty
processRequest: authenticationData object

The authenticator checks credentials for basic validity, creates an
authenticationData object and returns SUCCESS
if (null!=username && null!=password && username.length()>0

&& password.length() > 0) {
authenticationData = new
HashMap<String, Object>();
authenticationData.put ("username", username);

authenticationData.put ("password", password);
return AuthenticationResult.createFrom(
AuthenticationStatus.SUCCESS);
Figure 12-56. processRequest: authenticationData object
WU5061.1
Notes:
Basic validity is here a simple check that the arguments exist and have some content. You
can expand this to verify whether the format of the argument is correct, or whether it falls
within a certain range, and so on, but this would be better done on the client side, before
the call is made to the server. Assuming some client side JavaScript has determined that
the arguments are correctly formatted, the Authenticator need only do basic checking in
order to avoid potential Java problems with nulls.
SUCCESS is a static final field defined in the AuthenticationStatus class. It indicates that
all the login data was received correctly. If this were not the case then FAILURE would be
returned, indicating that the client did not provide correct login data.
Note that in previous versions this was returned directly as return
AuthenticationResult.STATUS. From Worklight version 5.0.6 this was changed to an
indirect call, and the STATUS values were placed in a separate class.
Unit 12. Security

12-63
Student Notebook
The code on the slide shows how the argument values are gathered into a HashMap.
Remember that this is only a successful collection of credentials; the login module is
invoked to validate them.

V8.1
Student Notebook
Uempty
processRequest: problem response

If there was a problem with the credentials, errorMessage is added to
the response and CLIENT_INTERACTION_REQUIRED is returned
} else {
response.setContentType("application/json; charset=UTF-8");
response.setHeader(
"Cache-Control", "no-cache, must-revalidate");
response.getWriter().print(
"{\"authRequired\":true, \"errorMessage\":"
+ "\"Please enter username and password\"}");
return AuthenticationResult.createFrom(
AuthenticationStatus.CLIENT_INTERACTION_REQUIRED);
}
Figure 12-57. processRequest: problem response
WU5061.1
Notes:
The comments on the previous slide about the AuthenticationStatus class apply here also.
CLIENT_INTERACTION_REQUIRED indicates that the request cannot be fulfilled until the
client has provided credentials for authentication.
Unit 12. Security

12-65
Student Notebook
processRequest: authentication not needed

The isAccessToProtectedResource argument specifies whether
an access attempt was made to a protected resource
If not, the method returns REQUEST_NOT_RECOGNIZED
if (!isAccessToProtectedResource)
return AuthenticationResult.REQUEST_NOT_RECOGNIZED;
Figure 12-58. processRequest: authentication not needed
WU5061.1
Notes:
See the comments on the previous two slides about AuthenticationResult.
The value of isAccessToProtectedResource was passed in as the third argument to the
method. A value of false indicates that the resource does not have security protection
and therefore Authenticator treatment is not required. Worklight can process the
request without user credentials.

V8.1
Student Notebook
Uempty
processRequest: credentials required

If the request is made to a protected resource but it does not contain authentication
data, the authenticator adds an authRequired:true property to the
response
response.setContentType("application/json; charset=UTF-8");
response.setHeader(
"Cache-Control", "no-cache, must-revalidate");
response.getWriter().print(
"{\"authRequired\":true, \"errorMessage\":"
+ "\"Please enter username and password\"}");
return AuthenticationResult.CLIENT_INTERACTION_REQUIRED;
}
Figure 12-59. processRequest: credentials required
WU5061.1
Notes:
This situation is similar to what you saw two slides ago. On that previous slide, the check
on the URL returned true and the credentials were formatted correctly, but then something
was incorrect and therefore the request was returned to the client. This slide shows that the
same situation arises if the check on the URL returned false, but the request is for a
protected resource.
Unit 12. Security

12-67
Student Notebook
The login module API

void init(Map<String, String> options)
boolean login(Map<String, Object> authenticationData)
UserIdentity createIdentity(String loginModule)
void logout()
void abort()
WorklightLoginModule clone()
Figure 12-60. The login module API
WU5061.1
Notes:
The init() method is invoked when Login Module instance is created. It receives the
options map specified in login module definition of the authenticationConfig.xml.
The login() method is used to validate credentials collected by the Authenticator.
The createIdentity () method is used to create a userIdentity object once credential
validation succeeds.
The logout() and abort() methods are used to clean up cached data once logout or
authentication abort occur.
The clone() method is used to create a deep copy of class members.

V8.1
Student Notebook
Uempty
Creating a custom Java login module

Create a new class called MyCustomLoginModule in the server\java
folder
Make sure it implements WorklightAuthLoginModule interface
Add two private class members USERNAME and PASSWORD

They hold user credentials
public class MyCustomLoginModule implements WorklightAuthLoginModule {

private String USERNAME;
private String PASSWORD;
Figure 12-61. Creating a custom Java login module
WU5061.1
Notes:
In previous versions of Worklight the interface implemented by the login module was
WorklightLoginModule.
Unit 12. Security

12-69
Student Notebook
Login module: init and clone methods

The init(..) method is invoked when the Login Module instance is
created. It receives the options map specified in a login module
definition in authenticationConfig.xml
The clone() method of the Login Module creates a deep copy of the
objects members
public void init(Map<String, String> options) throws

MissingConfigurationOptionException {
//initialize the login module
}
public CustomLoginModule clone() throws CloneNotSupportedException {
return (CustomLoginModule) super.clone();
}
Figure 12-62. Login module: init and clone methods
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Login module: login method

The login() method is invoked when the Authenticator has returned
SUCCESS status
the login() method gets an authenticationData object from
Authenticator
public boolean login (Map<String, Object> authenticationData)
{
logger.info ("MyCustomLoginModule :: login");
USERNAME = (String) authenticationData.get ("username");
PASSWORD = (String) authenticationData.get ("password");
if (USERNAME.equals("wluser") && PASSWORD.equals("12345"))
return true;
else
throw new RuntimeException ("Invalid credentials"));
}
Figure 12-63. Login module: login method
WU5061.1
Notes:
The authenticationData HashMap that was created in the Authenticator is passed to this
method (see the previous slide processRequest: authenticationData object).
The coding is reduced to a minimum here for the demonstration. You need to provide
try/catch blocks in case there is a problem extracting the values from the map, and of
course the validation of the values would be much more complex! You can implement your
own validation rules. The method returns true if the credentials are valid.
In the case of credential validation failure, the login() method throws a RuntimeException
with text that is returned to Authenticator as an errorMessage parameter.
Unit 12. Security

12-71
Student Notebook
Login module: createIdentity method

Once the login() method returns true, the createIdentity() method
is invoked
It is used to create a UserIdentity object
public UserIdentity createIdentity(String loginModule) {

logger.info ("MyCustomLoginModule :: createIdentity");
HashMap<String, Object> customAttributes =
new HashMap<String, Object>();
customAttributes.put ("AuthenticationDate", new Date());
UserIdentity identity = new UserIdentity(loginModule,
USERNAME, null, null, customAttributes, PASSWORD);
return identity;
}
Figure 12-64. Login module: createIdentity method
WU5061.1
Notes:
You can store you own custom attributes in the Useridentity to use later in Java or adapter
code.
The UserIdentity object constructor is passed six pieces of information:
1. loginModule (the String passed in to the method) indicates the name to set the user for
2. USERNAME is a unique identifier for the user
3. The third value is a display name, which may not be the same as the username
4. The fourth value is a String Set of Java security roles associated with the user
5. customAttributes has been created and populated in this method
6. The last argument is self-evident!

V8.1
Student Notebook
Uempty
Login module: logout and abort methods

The logout() and abort() methods are used to clean up class members
once user logs out or aborts the authentication flow
public void logout()

{
USERNAME = null;
PASSWORD = null;
}
@Override
public void abort()
{
USERNAME = null;
PASSWORD = null;
}
Figure 12-65. Login module: logout and abort methods
WU5061.1
Notes:
Unit 12. Security

12-73
Student Notebook
Examining the Result

Upon application start, an authentication form is displayed as required
Enter wluser and 12345 as user credentials
If the specified credentials are correct, authentication is saved for the
users session and the application screen is displayed
Click GetLoginName and verify that the correct login name is displayed
Figure 12-66. Examining the Result
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
12.3.WebSphere LTPA-based authentication
Unit 12. Security

12-75
Student Notebook
WebSphere LTPAbased authentication
Figure 12-67. WebSphere LTPA-based authentication
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
WebSphere LTPA-based authentication introduction

WebSphere Application Server uses a secure token in a Lightweight
Third Party Authentication cookie to authenticate
This mechanism is used to trust users across a secure WebSphere
Application server domain, thereby providing single sign-on across
various resources protected on these servers
When running IBM Worklight on the WebSphere Application server,
you can use the WebSphereFormBasedAuthenticator and the
WebSphereLoginModule to authenticate to the Worklight application
using an LTPA token
There is a default option for configuring this authentication and an
alternate option to accomplish support of WebSphere LTPA based
authentication for the Worklight applications
Figure 12-68. WebSphere LTPA-based authentication introduction
WU5061.1
Notes:
Both of these options are discussed in the following slides.
Unit 12. Security

12-77
Student Notebook
Understanding server-side authentication options

The WebSphere LTPA-based authentication process:
Application
Application tries
tries to
to access
access aa protected
protected resource
resource
YES
Worklight
checks user authentication:
LTPA token?
Protected
Protected resource
resource access
access is
is
granted.
granted. Application
Application receives
receives
the
the requested
requested data
data
NO
Authentication
process starts.
starts.
Application
Application receives
receives the
the
authentication
required
message
authentication required message
Authentication
process
Set
Set LTPA
LTPA
token
token as
as
HTTP
HTTP
Cookie
Cookie
YES
Success?
NO
Figure 12-69. Understanding server-side authentication options
WU5061.1
Notes:
You can recognize this flow chart from earlier in the unit during the discussion of the
Adapter-based authentication process. The main difference here is that once the
authentication process has completed successfully an LTPA token is set as a cookie.

V8.1
Student Notebook
Uempty
Server-side authentication options: option 1

Worklight security configuration handles user authentication at the
Worklight platform level
It uses the security configuration of the underlying application server
The Worklight project deployed as WAR file on the WebSphere

Application Server is not secured
The web.xml of this WAR file does not reference any security constraints
protecting the web resources
The authenticator and login module defined as part of this configuration

authenticate the user (based on the provided credential) using the
underlying WAS Security API
If the user provides username/password upon initial login, then this is
used to authenticate against the underlying registry of the WebSphere
Application Server configuration
Figure 12-70. Server-side authentication options: option 1
WU5061.1
Notes:
If the application server security mechanism validates the provided credentials, it creates
an LTPA token as was shown on the previous slide. Upon subsequent access, this LTPA
token is used, thus avoiding a challenge on each request.
Unit 12. Security

12-79
Student Notebook
Server-side authentication options: option 2

The application server security configuration handles authentication
The Worklight project deployed as a WAR file on the Application Server is not
secured. The web.xml references all security constraints protecting the
resources
Web resources are secured in the Worklight project WAR file by

specifying the resource and the user role
The authenticator and loginmodule that are defined as part of this
configuration authenticate the user by using the underlying application
server security API
Authentication based on the provided credentials
The user provides user name and password on initial login, then this
data is used to authenticate the user against the underlying registry
that the application server is configured against
Figure 12-71. Server-side authentication options: option 2
WU5061.1
Notes:
If the enterprise policy requires WAR files to be protected on secured application servers,
then this option can be used to handle the situation.
The pros and cons of these two options are discussed in the following slides.

V8.1
Student Notebook
Uempty
Understanding server-side authentication options

Worklight Server enforces the
authentication relying on application
server configuration
Authentication is enforced by
WebSphere Application server
WebSphere
Application
Server
User
Registry
WebSphere
Application
Server
User
Registry
Figure 12-72. Understanding server-side authentication options
WU5061.1
Notes:
Unit 12. Security

12-81
Student Notebook
Worklight invokes WAS security
Worklight
Server
getSecretData
Authentication required by Worklight server
Application
Authentication successful, LTPA set
getSecretData (passing in LTPA)
Secret data returned to application
Figure 12-73. Worklight invokes WAS security
WU5061.1
Notes:
Worklight invokes WebSphere Application Server security by using the loginmodule to
authenticate the user against the User Registry of WebSphere Application Server. This was
the first option discussed previously.

V8.1
Student Notebook
Uempty
Authentication through WebSphere Application Server
Worklight
Server
getSecretData
Authentication required by app.server
Application
Authentication successful, LTPA set
WebSphere
Application
Server
getSecretData (passing in LTPA)

Secret data returned to application
Figure 12-74. Authentication through WebSphere Application Server
WU5061.1
Notes:
WebSphere Application Server authenticates the user against the User Registry. Based on
successful authentication, Worklight loginmodule sets the Worklight user and provides an
LTPA token. On the subsequent request to get the secret data, this token is passed back to
the server, which recognizes that the user is authenticated and responds with the
requested information.
This was the second option discussed previously.
Unit 12. Security

12-83
Student Notebook
Server-side authentication options: summary

The default option and the alternate option both present benefits and has different usages:
Worklight invokes WAS
Application server
Benefits
Uses traditional WAS authentication and trust

model without the impact of modifying the
Worklight project WAR. The container enforces
all security and can use existing investments in
securing the JEE container using third-party
SSO products. The layered authentication of
device, application, application instance and user
function as intended. Flexibility in configuring
Worklight runtime security settings without being
hindered by the underlying container security.
Uses traditional WAS

authentication and
trust model. Container
enforces all security
and can use existing
investments in
securing the JEE
container using thirdparty SSO products
Usage
Suitable for scenarios where the devices or the

applications on the device cannot be trusted.
The multi-step authenticity checking built into the
IBM Worklight platform ensure denial of service
to jail-broken devices, rogue applications and
unauthorized users.
Suitable for scenarios

where the devices can
be trusted and rogue
access is restricted.
Figure 12-75. Server-side authentication options: summary
WU5061.1
Notes:
The multi-step authenticity checking that is built into IBM Worklight platform ensures denial
of services to jail-broken devices, rogue applications, and unauthorized users.
In general, it is preferable to use Worklight to enforce the security, unless there is a
business policy that requires the application server to be responsible for security.

V8.1
Student Notebook
Uempty
Checkpoint
1.
The server component that receives credentials from the authenticator, validates
them and builds the user identity object is
A. The authentication realm
B. A basic web form
C. The LTPA token
D. The login module
2.
Authentication settings are configured in which file?

A. authenticationConfig.xml
B. sas.client.props
C. application-descriptor.xml
D. plugin-cfg.xml
3.
True or False:
Any login module can be used in the adapter-based authentication as an
additional authentication layer
WU5061.1
Notes:
Unit 12. Security

12-85
Student Notebook
Unit summary
Worklight
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Checkpoint answers
1. D. The login module
2. A. authenticationConfig.xml
3. True

2013
WU5061.1
Notes:
Unit 12. Security

12-87
Student Notebook

V8.1
Student Notebook
Uempty
Unit 13. Push notification

This unit shows how to use the push notification mechanism to send
notifications to a mobile device.

Describe push notification architecture and API
Create an application that uses push notifications

Checkpoint
Exercise
References

13-1
Student Notebook
Unit objectives
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
What are push notifications?

Push notification is the ability of a mobile
device to receive messages that are
pushed from a server
Notifications are received regardless of
whether the application is currently running
Notification can take several forms:
Alert: a pop-up text message
Badge: a small badge mark appearing next
to the application icon
Banner or Toast: a disappearing pop-up
text message at the top of the device display
Sound alert
Figure 13-2. What are push notifications?
WU5061.1
Notes:
Push notification allows to push the message directly to the device from a server. It is a
short message sent by an application that is installed in the device. The information could
be a message, an impending calendar event, or new data on a remote server. Often the
size and number of such messages varies by Platform (iOS, Android, BlackBerry,
Windows Phone)
Until such Push notifications are turned off, the applications continue to receive them
irrespective of the state of the application whether it is running in foreground ,background
or even when it is not running.
Push notifications can be sent in any form. A pop-up Alert, a small badge that appears
next to the application icon, a sound alert are some of the forms that are widely used.
Some of the leading mobile platforms such as Android and iPhone provide centralized
management interface for Push Notification where device users can manage the
subscriptions, turn on and off notification for apps, configure how to be notified and other
notification configurations.

13-3
Student Notebook
All the Push Notifications messaged are delivered to this central place and furthered
handled from here.
this component is normally referred to as Notification center. The screen shots show the
notification configuration on both Android and iPhone.

V8.1
Student Notebook
Uempty
Device support
Worklight supports push notifications for mobile platforms:
Android 2.2 or later
iOS
Windows Phone 8
Android devices must be logged into a Google account

For information about push notifications for BlackBerry, contact IBM
Worklight customer support
Figure 13-3. Device support
WU5061.1
Notes:
Currently Worklight supports push notifications for iOS and Android version 2.2 or later
mobile platforms.
Android device users must have a valid Google account set up in order to subscribe to the
push notification requests with GCM service.

13-5
Student Notebook
Notification architecture terminology

Event source
A push notification channel to which mobile applications can register. An event source is defined
within a Worklight adapter.
Device token
A unique identifier, obtained from the push mediator (Google or Apple), which identifies the
request of a specific mobile device to receive notifications from the Worklight server.
User ID
A unique identifier for a Worklight user. Obtained through authentication or other unique identifier
such as a persistent cookie.
Application ID
Worklight application ID that dentifies a specific Worklight application on the mobile market.
Figure 13-4. Notification architecture terminology
WU5061.1
Notes:
There are 4 important terms needed in order to understand Worklight push notification
implementation.
First, Event Source It is a push notification channel that the applications can register to.
For developers know traditional messaging put/sub programming model, Worklight event
source is similar as Topic in sub/pub. Event source is normally defined within a Worklight
Adapter.
Device Token It is a unique identifier supplied by the push mediators (such as APN or
GCM) which uniquely identifies a device. Worklight server maintains the device token with
associated user information so that device token can be provided to the push mediators to
send message to the target device.
Userid is a unique identifier for a Worklight user. Often, userid is obtained via Worklight
authentication such as creating user object or via other techniques like persistent cookie.
Finally, application ID Identifies a specific Worklight application on the mobile market such
as Apple App store or Google Play.
V8.1
Student Notebook
Uempty
Notification architecture: subscription (1 of 3)

In order to start receiving push notifications, an application must first
subscribe to a push notification event source
An event source is declared in the Worklight adapter that is used by
the application for push notification services
The user must approve the push notification subscription
When the user approves, the device registers with an Apple, Google, or
Microsoft push server to obtain a token, which is used to identify the
device
For example, Allow notifications for application X on device Y - sends a
subscription request to the Worklight Server
Performed automatically by the Worklight framework
Figure 13-5. Notification architecture: subscription (1 of 3)
WU5061.1
Notes:
Push notification starts with device subscribes to an event source. This process also know
as Subscription.
Event Source is declared in the Worklight Adapter and maintained by Worklight server to
allow application to subscribe to this event source. Worklight provides API to create an
event source. You will learn about APIs in coming slides.
Before server or service provider can send any notification to a user. It must first obtain
users approval whether allows push notification for this application or not.
After the user approves push notification, the device registers with Apple/Google push
server to obtains a token, which is used to identify the device and sends a subscription
request to the Worklight Server all this is performed automatically by the Worklight
framework via the client side unified API in JavaScript.
Worklight Server, in turn, stores the device token information in database along with user
information.

13-7
Student Notebook

When the subscribe API is called, a
device registers with a push services
mediator and obtains a device token (done
automatically by Worklight)
Push services
mediators
Worklight
adapter
event source
WU5061.1
Notes:
The diagram here further explains the push notification subscription process.
When a user initiates the subscription using Worklight Client side push notification API, the
device registers itself with the Push Service Mediators (APN, GSM) and a device token is
obtained.

V8.1
Student Notebook
Uempty

When the token is obtained, the
application subscribes to an event source
Both actions are done automatically using
a single API call as described later
Push services
mediators
Worklight
adapter
event source
WU5061.1
Notes:
Once a device token is obtained, Worklight client side API then automatically forwards the
device token to backend Worklight server to register to an event source thats defined in an
Adapter. This process also saves the device token to the Worklight repository.
Again, this process and previous step are all done via the Worklight unified API.

13-9
Student Notebook
Sending notifications: overview (1 of 2)

Worklight provides a unified push notifications API
Adapter API allows:
Managing subscriptions
Pushing and polling notifications from backend
Sending push notifications to devices
Application API allows:

Subscribing to and unsubscribing from push notifications event sources
Handling arriving notifications
Figure 13-8. Sending notifications: overview (1 of 2)
WU5061.1
Notes:
Now, lets review the process of sending a push notification in Worklight.
Again, You will use the Worklight supplied push APIs to send a notification irrespective of
the mobile platforms that the target devices belong to. The APIs for sending notification
consists of client and server side.
On the server side, Worklight push API allows developer to managing subscriptions such
as getting subscription detail including user name and device token. The API allows your
application to use either Pushing or polling mechanism to get the message or initiate the
push notification from back-end enterprise system.
On the client side, besides subscribing and unsubscribing push notification as we
discussed previously, developer can define how to handling the arriving notification and
retrieve notification data using the client side push API.

V8.1
Student Notebook
Uempty
Sending notifications: overview ( of 2)

In order to send a notification, it must first be retrieved from the back
end
An event source can either poll notifications from the back end or wait
for the back end to explicitly push a new notification
When a notification is retrieved by the adapter, it is processed and sent
via the corresponding push services mediator (Apple or Google)
Additional custom logic can be added in the adapter to pre-process
notifications
The push services mediator receives the notification and sends it to a
device
Figure 13-9. Sending notifications: overview ( of 2)
WU5061.1
Notes:
Message or attempt to send a message to mobile users have to be retrieved or initiated
from backend-enterprise system. For example, a transaction complete statement or system
admin wants to send a message some users via an admin program.
Worklight Event Sources defined within the Adapter can either pull the messages or wait
for the back end systems to push the messages.
On receiving the messages, Worklight push notification APIs will send it to the platform
specific push service mediators such as APN or GCM using the supported transmission
protocols.
Additionally, you can add any pre-processing logic in the Adapter before sending the
notification such as write an audit entry about the notification, process the notification
message payload etc..

13-11
Student Notebook
Sending notifications (1 of 4)
1. Notifications are retrieved by the
Worklight adapter event source either by
poll or push from the back end
Back end
Push services
mediators
Enterprise
data source
Worklight
adapter
event source
Figure 13-10. Sending notifications (1 of 4)
WU5061.1
Notes:
In step Notifications are retrieved by the Worklight adapters event source by either poll or
push from the back end Enterprise Data source.

V8.1
Student Notebook
Uempty
2. A Worklight adapter processes the
notification and sends it to a push
services mediator
Back end
Push services
mediators
Enterprise
data source
Worklight
adapter
event source
WU5061.1
Notes:
Step 2, Adapter processes that information and sends it to push service mediators using
Worklight unified push API. In this case, server side push API.

13-13
Student Notebook
3. The push service mediator sends a push
notification to the device
Back end
Push services
mediators
2
3*
Enterprise
data source
Worklight
adapter
event source
*User must subscribe to push notification with the push service

mediators before steps 3 and 4 can happen.
WU5061.1
Notes:
Step 3, Push service mediators such as Apple APN or Google GCM sends the notification
to the device. At the point, the process is actually taking place at those cloud service
provider end. Worklight has little control the message delivery.

V8.1
Student Notebook
Uempty
4*
4. The device processes the received
notification
Back end
Push services
mediators
2
3
Enterprise
data source
Worklight
adapter
event source
*User must subscribe to push notification with the push service

mediators before steps 3 and 4 can happen.
WU5061.1
Notes:
Last step, step 4, notification is delivered to the device. Any client side notification handler
registered during subscription time will be fired at this time, by the Worklight unified push
API, client side API.
This completes a notification delivery using Worklight push notification framework.

13-15
Student Notebook
Subscription management: user subscription

User subscription
An entity containing user ID, device ID and event source ID. It represents the intent of the user to
receive notification from a specific event source.
Creation
The user subscription for an event source is created when the user subscribes to that event
source for the first time from any device
Deletion
A user subscription is deleted when the user unsubscribes from that event source from all of his
or her devices
Notification
As long as the user subscription exists, the Worklight server can produce push notifications for
the subscribed user. These notifications can be delivered by the adapters code to all or some of
the devices the user has subscribed from
Figure 13-14. Subscription management: user subscription
WU5061.1
Notes:
Worklight push notification allows applications to easily manage notification subscription
using a set of built-in API both on client and server side.
In Worklight, subscription is represented as a User Subscription object that contains
user ID, device ID and event source ID. It represents the intent of the user to receive
notification from a specific event source.
Worklight allows application to manage the lifecycle of a subscription. A subscription is
created when the user subscribes to that event source for the first time from any device.
User or application can delete or unsubscribe from an event source using Worklight API.
As far as the user subscription existing, the Worklight server can produce push notifications
for the subscribed user. These notifications can be delivered by the adapters code to all or
some of the devices the user has subscribed from.

V8.1
Student Notebook
Uempty
Subscription management: device subscription

A device subscription belongs to a user subscription, and exists in the scope of a specific
user and event source. A user subscription can have several device subscriptions.
The device subscription is created when the application on a device calls the
WL.Client.Push.subscribe() function
The device subscription is deleted either by an application calling
WL.Client.Push.unsubscribe() or when the push mediator informs the Worklight server
that the device is permanently not accessible
User subscription
Device
subscription
Device
subscription
Event source
Figure 13-15. Subscription management: device subscription
WU5061.1
Notes:

13-17
Student Notebook
Notification API: server side (1 of 10)

Start by creating an event source
Declare a notification event source in the adapter JavaScript code on a global level
name: a name that the Event Source is referenced by
onDeviceSubscribe: an adapter function that is invoked when user subscription request is
received
onDeviceUnsubscribe: an adapter function that is invoked when user unsubscribe request is
received
securityTest a security test from authenticationConfig.xml file used to protect the event source
Notifications are pushed

by the backend
Notifications are polled

from the backend
Figure 13-16. Notification API: server side (1 of 10)
WU5061.1
Notes:
If you recall, Worklight push notification starts with creation of an event source. You can
easily create an event source in Adapters JavaScript code on a global level using API:
WL.Server.createEventSource .
This API takes three parameters:
name name of the event source that the device user will subscribe to.
OnDeviceSubscribe An adapter function that will be invoked when a subscription
request from mobile device is received.
OnDeviceUnsubscribe An adapter function that will be invoked when a unsubscribe
request is received.

V8.1
Student Notebook
Uempty

Start by creating an event source
Declare a notification event source in the adapter JavaScript code at a global level (outside any
JavaScript function)
Poll: a method used for notification retrieval. The following parameters are
required:
Interval: polling interval in seconds
onPoll: polling implementation an adapter function to be invoked at specified intervals
Notifications are pushed
Notifications are polled
WU5061.1
Notes:
To implement the polling notification, or poll the request to send a notification from backend
enterprise system,
You need to specify a poll property as an optional parameter when creating event source.
It has two additional parameters, interval and onPoll.
interval Mandatory. The interval in seconds between the polls
onPoll Mandatory. The name of JavaScript function which is called on each poll

13-19
Student Notebook

Sending a notification
In this example, a
submitNotifications()
adapter function is invoked
by a back end service as an
external API to send
notifications
WU5061.1
Notes:
As discussed before, notifications can either be polled from the back end or pushed by the
back end. In this example, a submitNotifications() adapter function is invoked by a back
end service as an external API to send notifications.

V8.1
Student Notebook
Uempty

Obtain notification data
The submitNotification()
function receives a userId
to send notification to, and
the notificationText.
WU5061.1
Notes:
The submitNotification() function receives a userId to send notification to, and the
notificationText. These arguments are provided by a back end service, which invokes this
function.
Before sending notification to push mediator such as APN or GCM, its developers
responsibility to obtain the notification data such as message text.
You can get the necessary data from the backend system either by using Push
mechanism or Pull mechanism.

13-21
Student Notebook

Retrieve the active user and use it to get user subscription data
A user subscription object contains

the information about all of the
users subscriptions. Each
user subscription can have several
device subscriptions.
The object structure is as follows:
WU5061.1
Notes:
Notification has to be sent to a specific user subscription which contains the important
information device token that the push mediator uses to locate the physical device. So, you
need to get that information before sending notification.
Worklight provide a simple API to do that. You call
WL.Server.getUserNotificationSubscription by passing the event source and userId.
This call returns a subscription object for the user with the specified ID subscribed to event
source passed as parameter.

V8.1
Student Notebook
Uempty

Retrieve the user subscription data
If the user has no subscriptions

for the specified event source,
a null object is returned.
WU5061.1
Notes:
If the user has no subscriptions, the API will return a null object. You can use this
information to decide whether you need to send notification to a user.

13-23
Student Notebook

Retrieve the user subscription data
Separate subscription data
for each of the users devices
can be obtained by using the
getDeviceSubscriptions API.
The result is an array of objects
with the following structure:
WU5061.1
Notes:
There are cases that a user may have multiple devices. For example, one user owns both
iPhone and iPad. In case you want to know about these devices or send notification to only
some of the devices, Worklight allows to call userSubscription.getDeviceSubscriptions()
The method returns an array of the device subscriptions. The device subscriptions contain
the device token, the application ID, the platform, and the options passed by the client in
the subscribe call.

V8.1
Student Notebook
Uempty

Send notification to the users devices
WL.Server.createDefaultNotification
API creates and returns a default
notification JSON block for the supplied
values.
Payload
Badge number
Text to be pushed to the device
WU5061.1
Notes:
Finally, the core of Worklight push notification is sending the notification.
WL.Server.createDefaultNotification API creates and returns a default notification JSON
block for the supplied values.
notificationText: the text to be pushed to the device.
Badge number that will be displayed on the application icon or tile (in environments that
support it.
Payload is a JSON object that is transferred to the application and that can contain custom
properties.

13-25
Student Notebook
WL.Server.notifyAllDevices
API sends notification to all
the devices that are
subscribed to the user.
WU5061.1
Notes:

V8.1
Student Notebook
Uempty

Several APIs exist for notification sending:
WL.Server.notifyAllDevices(userSubscription, options): used to send
notification to all a users devices (see previous slide).
WL.Server.notifyDevice(userSubscription, device, options): used to send
notification to a specific device belonging to a specific userSubscription.
WL.Server.notifyDeviceSubscription(deviceSubscription, options): used to
send the notification to a specific device.
WU5061.1
Notes:
Depending on usage scenarios, you can use different Worklight APIs to send notifications.
WL.Server.notifyAllDevices is used to submit a notification to all the device subscriptions of
the given user.
WL.Server.notifyDevice is used to submit a notification to the specified user with the
specified device ID.
WL.Server.notifyDeviceSubscription is used to submit notification to the specified device
of a subscribed user

13-27
Student Notebook
Notification API: client side (1 of 4)

Event Source registration
First, register an event source within the application

Worklight provides the customizable onReadyToSubscribe function to register an event source
Always set up your onReadyToSubscribe function on a global JavaScript level
onReadyToSubscribe is invoked when the authentication finishes
API is WL.Client.Push.registerEventSourceCallback(alias, adapterName,
eventSourceName, callbackFunction)
Figure 13-26. Notification API: client side (1 of 4)
WU5061.1
Notes:
Now let us discuss about the Client Side Push notification APIs.
An application has to register itself to an event source to start subscribing for notifications.
Registering to an event source is handled by a client side API
WL.Client.Push.registerEventSourceCallback which specifies the event source, adapter
implementation and a register callback function.
The registration process can be managed by Worklight internal object
WL.Client.Push.onReadyToSubscribe. You need to define this function at a global
JavaScript level.

V8.1
Student Notebook
Uempty

Event Source subscribing and unsubscribing
A user must be authenticated in order to subscribe
Use the following API to subscribe to the event source
WL.Client.Push.subscribe() receives the following parameters:
An alias declared in WL.Client.Push.registerEventSourceCallback
(Optional) onSuccess callback
(Optional) onFailure callback
Callbacks receive a response object if one is required
WU5061.1
Notes:
The registration process can be managed by Worklight internal object
WL.Client.Push.onReadyToSubscribe. You need to define this function at a global
JavaScript level.

13-29
Student Notebook

Event Source subscribing and unsubscribing
Use the following API to unsubscribe from the event source
WL.Client.Push.unsubscribe() receives the following parameters:
An alias declared in WL.Client.Push.registerEventSourceCallback
Optional onSuccess callback
Optional onFailure callback
Callbacks receive a response object if one is required
WU5061.1
Notes:
An user must be authenticated in order to use Worklight push notification since Worklight
serve ties the subscription information to a particularly identified user.
After user is authenticated and event source registration completed, application can now
allow users to subscribe or unsubscribe to the event source.
You do this using the API WL.Client.Push.Subscribe. It takes two parameters.
:
First, the alias is mandatory field representing The event source, as defined in the API
WL.Client.Push.registerEventSourceCallback.
onFailure - A JavaScript function is called when a registration fails. The default value is a
function that prints to the log the failure reason.
onSuccess - A JavaScript function is called when a registration succeeds. Default value is
an empty function

V8.1
Student Notebook
Uempty

Additional client side APIs:
WL.Client.Push.isPushSupported() returns true if push notifications are
supported by the platform, and false otherwise
WL.Client.Push.isSubscribed(alias) returns whether the currently logged-in
user is subscribed to a specified event source alias
When push notification is received by a device, the callback function

defined in WL.Client.Push.registerEventSourceCallback is invoked.
It receives the following arguments:
If the application was in background mode (or inactive) when the push
notification arrived, this callback is invoked upon the applications
return to foreground.
WU5061.1
Notes:
WL.Client.Push.unsubscribe is used to unsubscribe to receive push notification.
Similar as Subscribe call, this API passes the alias as a mandatory parameter. This is the
event source defined in WL.Client.Push.registerEventSourceCallback API we
discussed earlier.
Then, you define the unsubscribe success and failure handling callback functions.
Besides subscribe and unsubscribe, there are couple of other useful APIs that you can
leverage to manage and get status of the application subscription.
WL.Client.Push.isPushSupported returns true if the Worklight JavaScript API supports
push notifications in the current environment and false otherwise. You can use this API to
check the device and environment support for push notification.
WL.Client.Push.isSubscribed returns whether the currently logged in user is subscribed
to the specified event source.

13-31
Student Notebook
WL.Client.Push.registerEventSourceCallback registers a callback method whenever a

notification arrives from the specified event source. If the notification arrives while the
application is not running, the mobile OS will start the application at the specified callback.

V8.1
Student Notebook
Uempty
Setup: Android
To send push notifications to Android devices, you must use Android
Google Cloud Messaging (GCM)
You need a valid Gmail account to register to Googles GCM. To get a
GCM key and senderId, refer to:
http://developer.android.com/guide/google/gcm/gs.html
Android OS 2.2.x/2.3.x devices must be synchronized with a Gmail

account.
Android OS 4.x does not impose Gmail account synchronization.
The following servers must be accessible from the Worklight Server:
https://www.google.com
https://android.apis.google.com
Figure 13-30. Setup: Android
WU5061.1
Notes:
Android push notification is sent and managed via Google Could-to-Device messaging
GCM.
You need to use a valid Gmail account to register to the Google Cloud Messaging system.
This is used by Worklight server to communicate with GCM provider. It is recommended to
use your organization or company Gmail account instead of a personal Gmail account.
On iOS side, The push notification service for iOS is provided via Apple Push Notification
Service. To send the notification, you need to be to a registered Apple iOS developer and
request a APNS certificate.
From Worklight server configuration perspective, loginExtension parameter must be added
to an authentication realm protecting the application that uses push notifications.

13-33
Student Notebook
Setup: iOS
To send push notifications to iOS devices, you must use Apple Push Notifications
Service (APNS).
You must be a registered Apple iOS Developer in order to obtain an Apple APNS
certificate for your application. An APNS certificate must have a non-blank
password.
Rename you certificate file to apns-certificate-sandbox.p12 and put it in the application root
folder.
When you are in development, rename your certificate file to apnscertificatesandbox.p12 and place it in the application root folder.
When you move to production, rename your certificate file to apnscertificateproduction.p12 and place it in the application root folder.
The following servers must be accessible from the Worklight Server:
Sandbox servers:
gateway.sandbox.push.apple.com:2195
feedback.sandbox.push.apple.com:2196
Production servers:
gateway.push.apple.com:2195
Feedback.push.apple.com:2196
Figure 13-31. Setup: iOS
WU5061.1
Notes:
Eventually, message are sent to push mediator such as APN or GCM.
So, you need to make sure that your Worklight server has access to the follower servers to
send the notifications:
For iOS development Sandbox servers: they are
gateway.sandbox.push.apple.com:2195
feedback.sandbox.push.apple.com:2196
For Production servers: you use
gateway.push.apple.com:2195
Feedback.push.apple.com:2196
For Android: the servers locations are:
https://www.google.com
https://android.apis.google.com
V8.1
Student Notebook
Uempty
Setup: Windows Phone 8

To send push notifications to Windows Phone 8 devices, you must use
the Microsoft Push Notifications Service (MPNS).
Non-authenticated push notification does not require any setup from
the developer.
Authenticated push notification requires a Windows Phone Dev Center
account.
To use authenticated push, you must use a certificate that is issued by
a Microsoft-trusted root certificate authority.
For production, consider using authenticated push notification to
ensure that your information is not comprised.
Consider using non-authenticated push only for development-time.
No specific ports needs to be open in your server configuration MPNS
uses regular http or https requests.
Figure 13-32. Setup: Windows Phone 8
WU5061.1
Notes:

13-35
Student Notebook
Edit application-descriptor.xml (1 of 2)
To set up push notifications in an app, add the following lines to the
application-descriptor.xml file
The Apple APNS certificate file must be placed in the root of the
applications folder
Replace pushSender settings values with your credentials
Android
iOS
Figure 13-33. Edit application-descriptor.xml (1 of 2)
WU5061.1
Notes:
Lastly, you need to specify Apple APNS certificate and Android push sender Gmail account
to your Worklight application-descriptor file.
For iOS, The certificate issued by APNS should be placed in the applications root folder.

V8.1
Student Notebook
Uempty
Edit application-descriptor.xml (2 of 2)
Windows Phone 8:
To set up non-authenticated push:
To set up authenticated push:
For more information about how to use the certificate file in the
Worklight project, follow the instructions that are provided in the IBM
Worklight Information Center under the Windows Phone 8 push
notifications topic.
Figure 13-34. Edit application-descriptor.xml (2 of 2)
WU5061.1
Notes:

13-37
Student Notebook
PushBackendEmulator
The sample for this training module comes with a backend emulator
that you can use to simulate push notification submissions by a backend system.
To run the backend emulator, open the PushBackendEmulator folder
of the sample project in a command prompt, and then run the supplied
JAR file by using the following syntax:
java jar PushBackendEmulator.jar <userId>
<notificationText> <context_root> <serverPort>
userId is the user name you used to login to the sample application.
contextRoot is the context root of your Worklight project
For example:
java jar PushBackendEmulator.jar JohnDoe My first
push notification myContextRoot 10080
Figure 13-35. PushBackendEmulator
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Unit summary
WU5061.1
Notes:

13-39
Student Notebook
1. Which of the following connections are mandatory for push
notifications to work?
A. Client application must be able to connect to an APNS/GCM server
B. Client application must be able to connect to a Worklight server
C. Worklight server must be able to connect to an APNS/GCM server
D. All of the above
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Checkpoint answers
1. D. All of above
WU5061.1
Notes:

13-41
Student Notebook
Checkpoint (objective only)

1. (True/False) Push notifications are received only if the application is
currently running.
2. (True/False) For push notifications to work, Android devices must be
logged into a Google account.
3. To start receiving push notifications, what must an application first
do?
A. Start up.
B. Subscribe to a push notification event source.
C. Log in to Gmail.
D. Obtain an authentication ID.
Figure 13-39. Checkpoint (objective only)
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Checkpoint answers
1. False
2. True
3. B. Subscribe to a push notification event source
WU5061.1
Notes:

13-43
Student Notebook
Exercise 8
Exploring the push notification

API
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Exercise objectives
Use the Push Notification API to:
Test if a device supports push notification

Test if the currently logged-in user is subscribed to a specified event
source alias
Subscribe a user to an event source

Un-subscribe a user from an event source
Send a notification to a device
WU5061.1
Notes:

13-45
Student Notebook

V8.1
Student Notebook
Uempty
Unit 14. Device analytics reporting

This unit shows you how to set-up, produce, and view reports that
reflect the device activity in your environment.

Set up the Worklight Server and Eclipse environment to enable
reporting
Produce and view device analytics reports

Checkpoint
References

14-1
Student Notebook
Unit objectives
reporting
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Topics
Device Analytics introduction
Setup before viewing reports
Configuring BIRT
Viewing Reports
Figure 14-2. Topics
WU5061.1
Notes:

14-3
Student Notebook
Device analytics
introduction

Figure 14-3. Device analytics introduction
8.0
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Introducing reports and analytics

IBM Worklight provides analytics capabilities
to help understand device usage across the
Worklight servers
Basic set of reports viewable by using
the BIRT Eclipse plug-ins
BIRT: Business Intelligence
Reporting Tool
Flexible architecture to support access
to the data for consumption from other
reporting tools
Worklight
DB
Worklight
server
Raw
data
BIRT
reports
Aggregated
data
Other
reporting
tools
Figure 14-4. Introducing reports and analytics
WU5061.1
Notes:
BIRT: Business Intelligence Reporting Tool
You can find sample reports at
https://www.ibm.com/developerworks/mobile/worklight/getting-started/

14-5
Student Notebook
Enabling raw data reports

Create a separate database for reports as the raw data table is rapidly
populated
Edit worklight.properties file
Figure 14-5. Enabling raw data reports
WU5061.1
Notes:
Uncomment reports.exportRawData property in worklight.properties and set it's value to
true (by default, it is false).
Uncomment the wl.reports.db properties and add values for your database settings.
Make sure that the wl.reports.db.url property contains URL of the database you're
planning to use for Raw Data reports!
For these settings to take effect, you must stop the application server and restart it.

V8.1
Student Notebook
Uempty
Device analytics: raw data

IBM Worklight emits raw data that enables an OLAP system to extract
the required information and present it through corporate reporting
mechanisms
With the Raw Data reports feature collections of analytics information
can be created about your applications and adapters usage
For example: activity type, device info, app version
Figure 14-6. Device analytics: raw data
WU5061.1
Notes:
OLAP: online analytical processing, an approach to the analysis of business data that
allows the analyst to view information rapidly from several different points of view. It is often
referred to as a cube, although that implies three dimensions and OLAP is more accurately
described as multi-dimensional. As an example, for a cube, one dimension could be
software components completed, another dimension geography of the teams writing the
software, and another dimension date. Other dimensions can be added. Data can be
consolidated (software can be viewed as individual components, or rolled up into groups or
types), you can drill down into the data (for example, analyze software components as
connectivity, authentication, and so on), slice the data (take a specific sub-set) and dice it
(view the sub-set in different ways).
Worklight analytics is based on this OLAP approach to data analysis.

14-7
Student Notebook
APP_ACTIVITY_REPORT table
The raw reports table includes the following information:
Column
Description
ACTIVITY
Activity type. See next slide
ACTIVITY_TIMESTAMP
Time of entry (UTC)
ENVIRONMENT
Application environment (iPhone, android,)
ADAPTER
The Worklight adapter name
PROC
The procedure name in the adapter
IP_ADDRESS
IP address of the client
DEVICE_MODEL
Manufacturer model (for example, iPhone 6)
GADGET_NAME
Application name
Figure 14-7. APP_ACTIVITY_REPORT table
WU5061.1
Notes:
Other report elements include information about the Worklight application version number
(GADGET_VERSION), the user agent (from the HTTP header of the client device), a
unique device id, and the device operating system.

V8.1
Student Notebook
Uempty
APP_ACTIVITY_REPORT ACTIVITY column
Activity
Description
Init
Application initialization
Login
Successful authentication using the application
Query
Procedure call to an adapter
Logout
User logout
Figure 14-8. APP_ACTIVITY_REPORT ACTIVITY column
WU5061.1
Notes:
Other report elements include information about the Worklight application and its version
number (GADGET_NAME, GADGET_VERSION), the user agent (from the HTTP header
of the client device), a unique device id, and the device operating system.

14-9
Student Notebook
Device usage reports

Device Usage reports are default
aggregations that are based on the Raw
Data and are provided for the benefit of
organizations that do not have OLAP
systems or choose not to integrate IBM
Worklight with an OLAP system
The Worklight server runs an analytics
data processor task with a default
24-hour interval
This allows simple and fast access to the
reports data
This task retrieves the raw entries for

the specified time interval from
app_activity_report table, processes
them, and fills the fact_activities table
Figure 14-9. Device usage reports
WU5061.1
Notes:
The fact_activities table contains a total activity count (number of logged actions) per
application, application version, device, and environment.

V8.1
Student Notebook
Uempty
activities_cube table
The fact_activities data is also processed and put into a table called
activities_cube
This table has the same structure as the fact_activities table, but
contains records for the last 30 days only
Figure 14-10. activities_cube table
WU5061.1
Notes:
The raw data of the fact_activities table is also processed and stored in the activities_cube
table.
This table is so named because of the online analytical processing concept of
multi-dimensional data analysis. As was mentioned earlier in this unit, cube does not imply
three dimensions here.
Since the table is intended for consolidation, drill-down, slicing, and dicing (analysis of
current data) it only contains records for the last 30 days.
It has the same structure as the fact_activities table.

14-11
Student Notebook
Notification_report table
The raw data reports engine also
populates the notification_report
table
This table contains information about
notifications sent from all event
sources
SMS, GCM, APNS
Figure 14-11. Notification_report table
WU5061.1
Notes:
The notification_report table data is also processed to populate the notification_activities
table with consolidated data. In other words, the two tables have the same relationship as
the app_activity_report and fact_activities tables. The difference is that these tables hold
reports about SMS text messages, Google Cloud Messaging (GCM), and Apple Push
Notification Service (APNS).
Every time the notification_report table data is processed, an entry is added to the
notification_proc_report table, which is similar to the proc_report table.

V8.1
Student Notebook
Uempty
proc_report table
Each time data processing is performed for fact_activities a timestamp
is added to a proc_report table with the processing result
timestamp, number of processed entries
In addition, notification_report table data is also processed, filling the

notification_activities table with consolidated data. This is done
similar to filling fact_activities table. Every time notification_report table
data is processed an entry is added to notification_proc_report table,
similar to proc_report
Figure 14-12. proc_report table
WU5061.1
Notes:
The process report table is one of the simplest. It is in a sense a report on the reports! Each
time the data processing is done, a new time stamp is added to a proc_report table with
information about the number of entries that were processed.

14-13
Student Notebook
Summary: relationship of the tables

24-hour interval
APP_ACTIVITY_REPORT
APP_ACTIVITY_REPORT
FACT_ACTIVITY
FACT_ACTIVITY
PROC_REPORT
PROC_REPORT
ACTIVITIES_CUBE
ACTIVITIES_CUBE
NOTIFICATION_REPORT
NOTIFICATION_REPORT
NOTIFICATION_PROC_REPORT
NOTIFICATION_PROC_REPORT
NOTIFICATION_ACTIVITIES
NOTIFICATION_ACTIVITIES
Figure 14-13. Summary: relationship of the tables
WU5061.1
Notes:
The 24-hour interval is a default. The next page shows how to modify this.

V8.1
Student Notebook
Uempty
Processing interval
Processing this quantity of information can be intensive
The default interval is 1 day
You may not require one report every day

It may be that once a week is sufficient
It may be that a report is needed every hour
The processing interval can be modified by changing the value of the

factProcessingInterval property in worklight.properties
Figure 14-14. Processing interval
WU5061.1
Notes:
The property is set in seconds. It is a default and is therefore commented out. You can find
it, not as you may expect in the Raw Reports properties, but at the bottom of the DB
settings properties.

14-15
Student Notebook
BIRT reports

Figure 14-15. BIRT reports
8.0
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
BIRT reports
The Business Intelligence Reporting Tool is used to generate and
render report content.
The tool can be installed
as an eclipse plug-in
as an application on the server
The IBM Worklight installation contains a number predefined BIRT

Reports
Configurable XML files designed to retrieve and present data from
Worklight reports database tables
These files have the extension .rptdesign
Figure 14-16. BIRT reports
WU5061.1
Notes:
There is comprehensive information about how to set up BIRT reports viewer on an
application server on the IBM Worklight V6 Information Center at
http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp?topic=%2Fcom.ibm.help.doc%
2Fwl_home.html (URL verified July 2013).

14-17
Student Notebook
Installing BIRT
You can install Eclipse with BIRT as an all-in-one package
You can install it from http://www.eclipse.org/downloads/packages/
eclipse-ide-java-and-report-developers/indigosr2
If you already have Worklight Studio or Eclipse version 4.2 or later

installed, you can install the BIRT plug-in as follows:
Click Help > Install New Software > Juno http://download.eclipse.org/releases/juno
Expand Business Intelligence, Reporting, and Charting in the list.
Select BIRT Framework from the list
Figure 14-17. Installing BIRT
WU5061.1
Notes:
This slide describes how to install the BIRT environment in Eclipse. For production, you
need to follow these steps:
1. From your Worklight administrator or operator, get:
The WLREPORT database type and location
The library for the specific database type
- Typically a JAR file, for example mysql-connector-java-5.1.20-bin.jar
The credentials for connecting to the WLREPORT database from BIRT
2. Open the Report Design perspective
3. In the Data Sources tab, select the wl_analytics data source
4. Configure the JDBC driver

V8.1
Student Notebook
Uempty
Exploring BIRT in Eclipse

The BirtSample database is added to Eclipse
Open the Database Development perspective
You can examine the table contents in the SQL Results view
Figure 14-18. Exploring BIRT in Eclipse
WU5061.1
Notes:
If you install documentation, examples, and source features (source code for BIRT) you
can explore the Eclipse BIRT environment without installing an external database. The
image shows the database that is created when you install the BIRT environment.

14-19
Student Notebook
Viewing reports

Figure 14-19. Viewing reports
8.0
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Report types: environment access

Environments accessing the application version in the last 30 days
environment_usage.rptdesign
Figure 14-20. Report types: environment access
WU5061.1
Notes:

14-21
Student Notebook
Report types : daily visits

Daily visits seen for a specific application version in the last 30 days
daily_visits.rptdesign
Figure 14-21. Report types : daily visits
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Report types : unique devices

Unique devices seen in the last 90 days by the platform
LICENSE_total_device_count.rptdesign
Figure 14-22. Report types : unique devices
WU5061.1
Notes:

14-23
Student Notebook
1. What is BIRT?
2. What kind of information are reports based on?
3. One of the types of information that the app_activity_reports
table provides is ACTIVITY_TIMESTAMP. Name another.
4. Name one of the report types discussed in the module
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Unit summary
reporting
WU5061.1
Notes:

14-25
Student Notebook
Checkpoint answers
1.
What is BIRT?
Business Intelligence Reporting Tool
2.
What kind of information are reports based on?

Raw data
3.
One of the types of information that the app_activity_reports

table provides is ACTIVITY_TIMESTAMP. Name another.
ENVIRONMENT, ADAPTER, PROC, IP_ADDRESS, DEVICE_MODEL,
ACTIVITY
4.
Name one of the report types discussed in the module

Environments accessing the application version in the last 30 days
Daily visits seen for a specific application version in the last 30 days
Unique devices seen in the last 90 days by the platform
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Unit 15. Direct update

This unit shows you how to use the application management features
of IBM Worklight.

Define what direct update is
Use the Direct Update feature to automatically update deployed
applications with new versions

Checkpoint
References

15-1
Student Notebook
Unit objectives
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
What is direct update?

With Direct Update, hybrid iOS and Android apps can automatically be
updated with new versions of their web resources, without the active
involvement of the user
Hybrid applications are written in HTML and can access native device
features
The web resources of an application can be downloaded to the users
device, like mobile web apps
Figure 15-2. What is direct update?
WU5061.1
Notes:
You have seen how applications are deployed from the development environment to the
production environment. But what about the user? If they have downloaded an application
which is subsequently updated, who do they find out that there is a newer version, or that
their current version may soon be deprecated? This is the philosophy behind direct
updates.

15-3
Student Notebook
The advantages of direct update

Organizations can ensure that users always use the latest version of an
application web resources
This provides better control of application versions
Users are notified of pending updates, or access to obsolete versions is blocked
The time for the application store review process is cut down
This is not a new application, just a new version of something which has already
been sanctioned
Figure 15-3. The advantages of direct update
WU5061.1
Notes:
Note that the first bullet says always use. The mobile device can display an alert stating
that it is about to update the application not asking whether the user wants to update it!

V8.1
Student Notebook
Uempty
The restrictions of direct update

Direct update of application web resources
Support for iOS and Android only
Update is only for the web resources of the application
Native resources require uploading a new version to the application stores
iOS-specific restrictions:
B2C: Per company's terms of service
Usually at least bug fixes are allowed
B2E: Through the enterprise developer program
Figure 15-4. The restrictions of direct update
WU5061.1
Notes:
Android does not have the restrictions shown in the second bullet. Direct updates for iOS
have some restrictions due to Apple policy.

15-5
Student Notebook
Version detection
Detection upon startup and when an application is brought into the
foreground
Dialog for easy user selection
Application download progress bar
The web part of the application is automatically reloaded after update

Figure 15-5. Version detection
WU5061.1
Notes:
As you saw on the previous slides, direct update refers to the Worklight application
environment. There is no dialog for the update of the web artefacts: it happens silently after
an update.

V8.1
Student Notebook
Uempty
Direct update: distribution

native
shell
Application Stores
Web
code
V1.0
Worklight Studio
Develop
Native applications
Web resources
Worklight Server
Maintain recent web
resources for native
applications V1.0 and V1.1
native
shell
Native resources are

deployed to the Application Store
Web
code
Web resources are deployed to both the

Application Store and the server
V1.1
The server has resources for V1.0 and V1.1

After loading, the device asks for updates
Figure 15-6. Direct update: distribution
WU5061.1
Notes:
An application is downloaded from an App Store and becomes a part of the cached
resources on the device. A request to check for updates is sent to the server when the
application starts up or when the application is brought to the foreground. If there is a
newer version available on the server it can be downloaded, and the device informs the
user of the newer version, or warns the user that the current version is deprecated and
should no longer be used.
Note that direct update only refers to the web contents. While the server can inform the
user about new native contents, it cannot provide it to the user. It can however block the
native application so that the user must go to an app store and obtain the new version.

15-7
Student Notebook
Disabling old app versions

Use the Worklight Console to disable obsolete versions
Notify users about the state of the application
You can indicate that a version is soon going to be disabled
active, notifying
You can disable a version

Provide information that is sent to the device
Indicate where the new version can be obtained
Figure 15-7. Disabling old app versions
WU5061.1
Notes:
The server cannot provide a complete new version of a hybrid application. Any updates to
the native part of an application must go through the app store distribution process again.
The server can however provide direct updates to web parts of the application, which do
not require approval from the app store.
The server can disable a native application on a device. When an application is started (or
brought to the foreground), it can communicate with the server automatically (this is
configurable). In the example on this page, when an Android device calls this server, and
the server detects that the device is running Version 1.0 of the application, it can respond
with the message that the version is disabled, and provide notification so that the user is
aware of what is happening. This notification usually includes a URL so that the user can
go the app store and obtain the new version (for example, 1.1). When this has been
installed on the device, the application automatically calls the server, which detects that the
application version is 1.1 and notes that it is the active version. No action is taken.

V8.1
Student Notebook
Uempty
1. Where are native resources deployed?
2. Where are web resources deployed?
3. On the Worklight console, versions can be marked as active,
disabled, or?
WU5061.1
Notes:

15-9
Student Notebook
Unit summary
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Checkpoint answers
1. Where are native resources deployed?
Application store
2. Where are web resources deployed?

Application store and Worklight server
3. On the Worklight console, versions can be marked as active,

disabled, or?
Active, notifying
WU5061.1
Notes:

15-11
Student Notebook

V8.1
Student Notebook
Uempty
Unit 16. Migrating an application from

development to production
This unit shows you how to use the application migration features of
IBM Worklight.

Prepare an application for deployment
Deploy an application to a remote server
Use the Ant utility with Worklight
Install IBM Worklight Server in a WebSphere Application Server
and DB2 environment.
Migrate applications from a development to a production
environment

Checkpoint
References
Unit 16. Migrating an application from development to production

16-1
Student Notebook
Unit objectives
Install IBM Worklight Server in a WebSphere Application Server and
DB2 environment.
Migrate applications from a development to a production environment
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
16.1.Overview of application management

16-3
Student Notebook
Overview of application
management
Figure 16-2. Overview of application management
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Overview
A Worklight project contains various components, such as applications,
adapters, configuration files, custom Java code and libraries
In development stages these components are deployed to a local
server which resides on the developers computer
The deployment is automated by Worklight Studio
Each environment (production, pre-production, QA, Development) has

its own unique settings
Locations of backend services, public URL, database connectivity parameters,
logging, and so forth
These settings and components eventually need to be transferred to

the remote server
WU5061.1
Notes:
The deployment environment may be configured in several different ways: There may be
one or several environments (Android, iOS, and so forth), there may be adapters (Cast
Iron, http, and so forth) and there may be purely web artifacts in a .war file.

16-5
Student Notebook
Steps in the process of remote deployment

Prepare the application for deployment
Adjust application properties in application-descriptor.xml
Adjust server and database properties in worklight.properties
Build the application
Rename the generated .war file
Deploy the application

Deploy the .war file to the remote server
Deploy applications and adapters using the Worklight Console
The next slides look in detail at this process
Figure 16-4. Steps in the process of remote deployment
WU5061.1
Notes:
The application descriptor file is under the application folder and includes information such
as the display name of the application, author information, authentication requirements,
and server root information.
The worklight properties file is in the conf folder under server and initially includes a large
number of properties that are all commented out; for example, database-related values,
raw report values, and bit.ly credentials.
Some of these properties are highlighted in the following slides.

V8.1
Student Notebook
Uempty
Architecture of deployment (1 of 6)
A Java web application server is required to run Worklight
WebSphere, Tomcat or Liberty
Copy the supplied worklight-jee-library.jar file to the lib folder of the

application server
worklight-jee-library.jar
Application server
project-name.war
Worklight applications and adapters
Database
Figure 16-5. Architecture of deployment (1 of 6)
WU5061.1
Notes:
worklight-jee-library.jar is a part of the Worklight Server package. When you install the
server (for example, using IBM Installation Manager), the file can be found in the Worklight
> WorklightServer folder. You copy it over to the application server.

16-7
Student Notebook
A Worklight project contains various server related settings under
\server\conf folder
For example, worklight.properties and AuthenticationConfig.xml
It is possible to add custom Java code and libraries to the java and lib
folders under server
These files are compiled to the project-name.war file under the bin folder
Application server
project-name.war
Database
WU5061.1
Notes:
Everything required for the administration of the project by the application server is
deployed in the .war file, including a Worklight console instance that will be used to
manage the web potions of the application or applications associated with the project. This
is covered in detail further on.

V8.1
Student Notebook
Uempty
Database connection properties are defined in the
worklight.properties file
You can use either application server level JNDI or Worklight server level JDBC
connections.
Application server
project-name.war
Database
WU5061.1
Notes:
As you have already seen, there are several options commented out in the
worklight.properties file pertaining to database connectivity. For development, you do not
need to uncomment anything, because the connectivity is automatic, and the developer
does not have to install or configure anything. For remote deployment, you must
uncomment the relevant properties and give the required values.

16-9
Student Notebook
Build and deploy project-name.war to the application server
Worklight Console is bundled within this .war file
In Worklight terms this .war file is called a Server customization bundle.
There is only one .war file for a project, deployed per application server
Application server
project-name.war
project-name.war
Database
WU5061.1
Notes:
Although the built project file is called a war, it is more sccurate to refer to it as a server
customization bundle. The information that is bundled and sent to the server is not simply
an application or an adapter. It is a server configuration file that gives access to the
configuration of the applications and adapters through the Worklight console. This is
discussed in a few slides.

V8.1
Student Notebook
Uempty
When the .war file has been deployed to the server you can open
Worklight Console at http://server:port/context/console
The .war file functionality is using worklight-jee-library.jar
This was previously copied to the lib folder of the application server
Application server
project-name.war
Database
WU5061.1
Notes:
The worklight-jee-library.jar file was provided with the Worklight server installation. It has to
be copied over to the application server.
Note the URL that is used to call the console. By default, the name of the project becomes
the context root, and the console for a particular project is bundled with the project in the
server customization bundle.

16-11
Student Notebook
The Worklight Console is now accessible, so you can deploy
applications and adapters
There is no limit to the number of applications/adapters deployed
However, they all share same Server customization bundle
Application server
project-name.war
Database
WU5061.1
Notes:
The point made on this page is an important one: it is the Worklight console that is
accessible after deployment, and it is through the console that you manage the
applications and adapters. This is in fact identical to the system you have been using
throughout the exercises: when you right click on a project and select Run on Worklight
Console, you are given a browser view of the console, and from there you manage your
applications and adapters.

V8.1
Student Notebook
Uempty
16.2.Worklight Apache Ant utility

16-13
Student Notebook
Worklight Apache Ant

utility
Figure 16-11. Worklight Apache Ant utility
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Worklight Apache Ant utility

Apache Ant is a project developed and maintained by the Apache
Software Foundation
It provides command line tools that can be used for tasks such as
building applications and copying files
Worklight provides an Apache Ant utility
It can be used to automate build and deploy processes of Worklight artifacts
Figure 16-12. Worklight Apache Ant utility
WU5061.1
Notes:
Apache Ant can be downloaded at http://ant.apache.org/
More documentation about Apache Ant can be found at
http://ant.apache.org/manual/index.html

16-15
Student Notebook
Apache Ant basics

Apache Ant is run by invoking the following syntax from a command
line
ant buildfile build-script-name.xml
build-script-name.xml has the following structure template
<project base=. default=target-name>
<target name=target-name>
<echo message=messageText/>
<taskdef>...</taskdef>
</target>
</project
<target> is a set of tasks which are performed one by one
<echo> can be used to output messages for debugging or for
information on the task
<taskdef> is discussed on the next slide
Figure 16-13. Apache Ant basics
WU5061.1
Notes:
Install Apache Ant and make sure that its binaries are in the path variable of your operating
system

V8.1
Student Notebook
Uempty
Adding a reference to Worklight Ant jar file

A <taskdef> adds a task or a data type definition
A Task is any class that extends org.apache.tools.ant.Task
Two attributes are required:
the name that identifies this data type uniquely
The name of the class that implements this type
Including its package name
<taskdef resource=com/worklight/ant/defaults.properties>
<classpath>
<pathelement location=
C:\IBM\Worklight\WorklightServer\worklight-ant.jar/>
</classpath>
</taskdef>
Figure 16-14. Adding a reference to Worklight Ant jar file
WU5061.1
Notes:
The first sub-element added in the <target> element is a <taskdef> reference to the IBM
Worklight Ant utility. This addition ensures that Ant recognizes the IBM Worklight tasks and
has a default configuration for performing them.
The <taskdef> resource reference states what it is that is required in the Worklight ANT jar
file: defaults.properties. This properties file holds references for configuring a database or
an application server, building applications and adapters, or deploying them.
<classpath> gives the location of the worklight ANT jar file that holds the properties file.
This is the default location that was set up when the Worklight server was installed.

16-17
Student Notebook
Ant task: application builder

To build an application add <app-builder> with the following syntax:
<app-builder
applicationFolder = "C:\TestProject\TestApp"
environments = "common"
nativeProjectPrefix = "com.mycompany.TestApp"
outputFolder = "C:\TestProject\bin"
/>
applicationFolder: the root folder of the application
environments: comma separated list of environments to build
Optional parameter; omitting it means build all environments found
in application-descriptor.xml
nativeProjectPrefix: mandatory parameter when building iOS
applications
outputFolder the folder for the generated .wlapp files
Figure 16-15. Ant task: application builder
WU5061.1
Notes:
app-builder is one of the tasks in worklight-ant.jar. It references the class
ApplicationBuilderTask, which has methods to create an apps backup folder, static final
strings for BUILD_SUCCEED and BUILD_FAILED, and so on.
To invoke the ANT build, you need to state where everything is, what you want to build, and
where you want the result to be placed.

V8.1
Student Notebook
Uempty
Ant task: application deployer

To deploy an application add <app-deployer> with the following
syntax:
<app-deployer
worklightServerHost = http://localhost:8080/"
deployable=C:\TestProject\bin\TestApp-common.wlapp"
/>
worklightServerHost: full URL of your Worklight server.
Deploy fails if the Worklight console is protected by a password
deployable: the .wlapp file to deploy

To deploy several .wlapp files add <app-deployer> entries
Figure 16-16. Ant task: application deployer
WU5061.1
Notes:
Deploying an application with ANT is an app-deployer task, and it really underlines the
simplicity of using an ANT process. You say where you want the Worklight application
deployed to, and where the task should look for the .wlapp file to deploy.
Note a small but important point: there is no provision here for a console password. If your
Worklight console is protected by a password, the ANT task will not be able to respond to
the challenge.

16-19
Student Notebook

V8.1
Student Notebook
Uempty
16.3.IBM Worklight Server installation and configuration

overview

16-21
Student Notebook
IBM Worklight Server

installation and
configuration overview
Figure 16-17. IBM Worklight Server installation and configuration overview
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Worklight Server overview

IBM Worklight Server provides the runtime and administrative services
required by a Worklight mobile application to support:
Push notification
Security
Back-end integration
Version management
Worklight Server is packaged as a Java EE web application (WAR file) that

is deployed to an application server.
WAR file is application-specific:
It contains properties, libraries, security settings and other server-side resources that
are specific to a mobile application.
Each mobile application created using IBM Worklight Studio connects at runtime to its
own customized instance of Worklight server.
WAR file is environment-specific:
A different Worklight server WAR file is typically required for each higher-level
deployment environment (for example, QA and production) to specify environmentspecific properties such as the public access URL and the database user ID and
password.
WAR file contains an instance of the Worklight Console.
Figure 16-18. Worklight Server overview
WU5061.1
Notes:
IBM Worklight Servers capabilities include:
Adapter technology to allow a mobile application to connect to a variety of back-end
resources using SQL or protocols such as HTTP/SOAP and HTTP/REST.
Data mashup capabilities to efficiently integrate several data streams into one and
serve it to the mobile application.
Security functions that integrate with the corporate authentication infrastructure to help
secure application and data access.
Application deployment and version control features that are managed and accessed
through the IBM Worklight Console.
Collection of a mobile applications user adoption and usage data for auditing and
reporting purposes.

16-23
Student Notebook
Worklight Server runtime architecture
Figure 16-19. Worklight Server runtime architecture
WU5061.1
Notes:
This diagram illustrates the following key points:
Worklight Server is a Java EE web application that is deployed to an application server.
It uses two databases, WRKLGHT, the core database and WLREPORT, the reporting
database.
A separate customized instance of Worklight Server is deployed for each application,
and each application communicates with its own customized instance of Worklight
Server at runtime.
Each instance of Worklight Server has its own Worklight Console used to deploy the
corresponding applications .wlapp and .adapter files.

V8.1
Student Notebook
Uempty
IBM Worklight Server installation: Prerequisites

Worklight Server v6 can be installed on the following application
servers:
Apache Tomcat 7.0
WebSphere Application Server version 7.0, 8.0, 8.5 and 8.5.5
WebSphere Application Server Network Deployment version 7.0, 8.0, 8.5 and
8.5.5
Worklight Server v6 can use the following database systems to store its
internal database:
Apache Derby 10.8 or later
DB2 Enterprise Server Edition version 9.7, 10.1 or later
MySQL 5.5 or 5.6
Oracle Database 11g Standard/Enterprise Editions release 1 or later
Figure 16-20. IBM Worklight Server installation: Prerequisites
WU5061.1
Notes:
For a detailed list of system requirements for Worklight Server v6, visit:
http://www-01.ibm.com/support/docview.wss?uid=swg27024838

16-25
Student Notebook
Configuring Worklight Server resources in WebSphere

Application Server
Define the database resources and configure the runtime components
used by Worklight Server using the WebSphere Integrated Solutions
Console. This includes:
Creating a data source for the Worklight core database and for the reports
database
Defining worklight-jee-library.jar as a shared library
Installing the Worklight sample customization WAR file to use for testing the
installation
Figure 16-21. Configuring Worklight Server resources in WebSphere Application Server
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
16.4.Application migration: Overview

16-27
Student Notebook
Application migration:
Overview
Figure 16-22. Application migration: Overview
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Application migration overview

The Worklight project contains various components such as
applications, adapters, configuration files, custom Java code and
libraries.
In the early development stages, all of these components are deployed
to a local server which resides on the developers computer.
Deploying those components to a local development server is automated by
Worklight studio.
Each environment (production, pre-production, QA, Dev) has its own

unique Worklight-specific settings, for example: locations of back-end
services, public URLs, database connectivity parameters, and logging
settings
Eventually a need to transfer these settings and components to the
remote server arises.
Figure 16-23. Application migration overview
WU5061.1
Notes:
While the deployment of Worklight applications in Studios embedded server is almost
transparent and very convenient for development and unit testing, for integration testing
(and other similar higher levels of testing) as well as for production environments,
deployment to a remote and dedicated Worklight server is essential.
The full Worklight application package consists of various components, such as
applications, adapters, authentication modules, custom modules, and third party libraries.
During the development phase, all of these components are on the developers workstation
in a Worklight Studio workspace under a Worklight project.
When its time for integration and QA testing, as well as production release, these
application artifacts need to be transferred and deployed to the remote test or production
Worklight server.
Because each environment (production, pre-production, QA, Dev) has its own unique
Worklight-specific settings, for example, database connectivity parameters, an application
must be prepared or configured prior to deployment to a specific remote environment.

16-29
Student Notebook
The next slides describe how to prepare and package an application in order to deploy it to
a remote server.

V8.1
Student Notebook
Uempty
Application migration process

The process consists of two main steps:
Prepare the application for deployment:
Adjust application properties in application-descriptor.xml
Adjust server and database properties in worklight.properties
Build the application
Deploy the application:
Deploy the .war file to the remote server.
Deploy the applications .wlapp and .adapter files using the Worklight
Console
25
Figure 16-24. Application migration process
WU5061.1
Notes:
In general, deploying a Worklight application entails two steps:
First, the developer or build master configures the Worklight application for deployment.
This includes adjusting the application properties in application-descriptor.xml, for
example, to specify the remote servers URL and define the appropriate Push
Notification subscription ID.
Another configuration file that needs to be prepared is the worklight.properties file in the
server/conf location of the Worklight project where you need to supply the target
environment server and database properties.
After the two files are configured, re-build the application in Worklight Studio.
The second step deals with transferring and deploying the application artifacts to the
target remote server. The System Administrator gets the Worklight project files from
the developer and deploys it to the remote server runtime such as WebSphere
Application Server as a Java EE artifact. This installs the Worklight server for the
application.

16-31
Student Notebook
Once the project-specific Worklight sever is installed and configured, the System
Administrator deploys the projects applications and adapters using the Worklight
Console.

V8.1
Student Notebook
Uempty
16.5.Application migration: Preparing your application

16-33
Student Notebook
Preparing your
application
Figure 16-25. Application migration: Preparing your application
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Adjusting the worklight.properties file: Database settings

For a remote server, set
elements to describe the
connection to a database
the Worklight Server uses
Select the database type
used by the target
Worklight server,
for example, DB2, Oracle
or MySQL
Enter the JDBC connection
or data source information
Enter the database
user name and password
Figure 16-26. Adjusting the worklight.properties file: Database settings
WU5061.1
Notes:
In addition to the application configuration, the developer or build master also needs to
prepare the Worklight Server configuration defined in the worklight.properties file in the
projects server/conf directory.
There are two important settings you need to define prior to deployment: Database
configuration and server access settings (the latter is discussed in the next slide).
Worklight server uses the database configuration properties to connect to the products
database. In Worklight Studios development environment, the embedded test server uses
a file based lightweight database. In a higher level environment, such as QA or production,
Worklight server is configured to use a full-fledged database system, such as DB2 or
Oracle. Therefore, you need to change the database properties contained in
worklight.properties to match the database used on the target server.
Note that the default worklight.properties file provides template configuration lines which
you can easily modify with real database value.

16-35
Student Notebook
Adjusting the worklight.properties file: Server access

settings
Adjust the properties describing the public Worklight Server access:
Protocol
Port
Context root
The project-specific Worklight server is available at

http://remoteServerURL:8181/MyContext/
Figure 16-27. Adjusting the worklight.properties file: Server access settings
WU5061.1
Notes:
Another important configuration information defined in the worklight.properties file is the
Worklight server access settings which specify how the Worklight server can be accessed
by a client. This is controlled by three properties:
publicWorklightProtocol: Defines the communication protocol used to access Worklight
server. Normally, it is HTTP.
publicWorklightPort: Defines the port number on which Worklight server can be
reached.
publicWorklightContext: Defines the context root of the Worklight server Java EE web
application.

V8.1
Student Notebook
Uempty
Adjusting configuration files: Best practice

As a best practice, when adjusting properties in the configuration files:
Create a copy of the configuration file with different names for each environment.
When ready to build the application, copy the contents of the desired version to
the main configuration file.
Figure 16-28. Adjusting configuration files: Best practice
WU5061.1
Notes:
By creating a different configuration file for each target environment, you can quickly copy
and set the main configuration file with the desired version prior to re-building the
application.

16-37
Student Notebook
Building the project

When you have made all the required modifications to the configuration
of your Worklight project, build your application, adapter, or both.
This creates a projectName.war file in the \bin folder which
contains the console application used to deploy the projects
application and adapter files to the remote server.
This .war file also contains classes built from Java code in the server\java
folder.
Figure 16-29. Building the project
WU5061.1
Notes:
Once you have made all the required modifications to your Worklight projects configuration
as described in the previous slides, build your application and adapter(s) to generate the
deployable Worklight war file and application artifacts.

V8.1
Student Notebook
Uempty
16.6.Application migration: Deploying your application

16-39
Student Notebook
Deploying your
application
Figure 16-30. Application migration: Deploying your application
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Deploying the applications Worklight server WAR file

Deploy the generated .war file to the remote server.
For WebSphere Application Server, use the WebSphere Integrated Solutions
Console.
Figure 16-31. Deploying the applications Worklight server WAR file
WU5061.1
Notes:
Deploy the generated Worklight server .war file to the target runtime following the standard
procedure for deploying a Java EE Web Archive file in the target application server:
For WebSphere Application Server, use the WebSphere Integrated Solutions Console
to deploy the WAR file.
For Tomcat server, copy the WAR file to the webapps directory and restart the server.
For detailed information on deploying the Worklight server .war file to the supported
environments, refer to the IBM Worklight V6.0 Administration Guide.

16-41
Student Notebook
Checkpoint
1. True or false:
Each Worklight application has its own Worklight server WAR file
2. Which of the following types of component can be deployed using the
Worklight console?
a) .adapter files
b) .war files
c) .wlapp files
d) .jar files
3. Which project configuration file contains the Worklight server root

URL definition?
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Unit summary
Install IBM Worklight Server in a WebSphere Application Server and
DB2 environment.
Migrate applications from a development to a production environment
WU5061.1
Notes:

16-43
Student Notebook
Checkpoint answers
1. True or false:
Each Worklight application has its own Worklight server WAR file.
True
2. Which of the following types of files can be deployed using the

Worklight console?
a) .adapter files
b) .war files
c) .wlapp files
d) .jar files
a) and c)
3. Which project configuration file contains the Worklight server root

URL definition?
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Unit 17. Shell development

In this unit, you learn how to use the Shell component feature of IBM
Worklight to improve the development process and facilitate sharing
application components during development.

Develop a Shell component

Checkpoint
References

17-1
Student Notebook
Unit objectives
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Topics
shell component concepts
Creating and using a shell component
Android shell development
iOS shell development
Figure 17-2. Topics
WU5061.1
Notes:

17-3
Student Notebook

V8.1
Student Notebook
Uempty
17.1.shell component concepts

17-5
Student Notebook
shell component concepts

Figure 17-3. shell component concepts
8.0
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Overview
The main idea of the shell component methodology is to create two
levels of development inside the organization:
Developers skilled in native development: implement native and web code
base that can be used as a starting point for applications. For example,
Native functionality to be invoked from JavaScript (Cordova plug-ins)
Authentication framework
Security configuration
Web resources shared between applications: logotypes, themes, and so on
Developers who are more focused on web development: receive ready to
use shell component and use it as a wrapper to create the organization
applications. For example,
Business logic
UI development
Data integration
5
WU5061.1
Notes:
The Worklight applications you have studied and built were primarily Hybrid application
types that contain both web and native code in a single application package or unit. It is a
standard Worklight application type that can be tested and deployed to mobile devices
directly with everything packaged in a single artefact.
Sometimes, certain organizations or development teams might want to create two levels of
development for the mobile application. Developers skilled in native development such as
Objective-C and Java programming can focus on implement native and web code base
that can be used as a starting point in single or several mobile applications. The type of
work might fall under native development include developing Apache Cordova plug-in code
that exposes native functionality to Web JavaScript component, developing and configuring
Security configuration such as Custom Java authenticator and Login modules, and
potentially also developing the web resources that are shared between applications like
logotypes and themes. In another words, these are the foundational enterprise core
libraries that built to be shared by maybe multiple mobile apps. In Worklight terminology,
the code or application typed developed by native development team is called a shell
Component.

17-7
Student Notebook
The second level of development is targeted to developers who are less skilled in native
development, but have more web expertise: HTML, JavaScript and CSS programming.
The Web developers can focus on developing the mobile application to meet the business
requirement such as business logic, user interface development and data integration
between mobile client and backend. They can use the shell component developed by the
native development team as a wrapper for their mobile application. In Worklight, this web
resource or web application developed by web team is called an inner application.
Development skills and asset reuse are two main driving factors behind the Worklight shell
component concept. Obviously, there are some other benefits as well such as easier
source control management, and so on.

V8.1
Student Notebook
Uempty
Architecture of a shell-based application (1 of 2)

A shell component is a building
block that is used to create inner
applications
Used by inner applications as a code
base wrapper
Usually consists of native classes and
shell-specific web resources that are
used in inner applications
Implemented by shell developers and
sent to inner application developers to
use
Customizable native
shell code
Mobile browser
inner
application
Web code
Customizable
web shell code
Device APIs
Figure 17-5. Architecture of a shell-based application (1 of 2)
WU5061.1
Notes:
The chart here illustrates the architecture of the Worklight shell component and the
relationship among the various building blocks of the shell based application model.
The outer contains or code base is the Customizable Native shell code or shell component
developed by the native development team. It can be either an iOS or an Android shell
created in Worklight Studio. This components uses Worklight client side runtime and may
interact with device native APIs directly to provide native services to the inner application.
This includes exposing native functionality though the Apache Cordova plug-in, and native
mobile pages built with a native programming language such as Java or Objective-C. One
of the important function carried by the shell component is to launch a mobile device
browser instance such as a WebKit instance on iOS or Android platform, and load the Web
resources packaged as an inner application. From the development perspective, shell
components consist of code auto generated by Worklight studio together with custom
developed native artifacts.

17-9
Student Notebook
From a packaging perspective, the shell component development team sends or source
control the shell component to the inner Web application development team to wrap their
code under the shell component. You see how this work in the coming slides.

V8.1
Student Notebook
Uempty
Architecture of a shell-based application (2 of 2)

inner application: web
resources (HTML, JavaScript,
CSS) that run inside the shell
component
Test application: shell
component is not executable by
itself. Once it is created, an inner
application is automatically added
to the project by Worklight Studio.
This application is used by the
shell developer to test shell
component functionality.
Customizable native
shell code
Mobile browser
inner
application
Web code
Customizable
web shell code
Device APIs
Figure 17-6. Architecture of a shell-based application (2 of 2)
WU5061.1
Notes:
The inner component of the overall architecture is the Web code that developed by Web
team. This is the standard Web code, and consists of HTML, JavaScript and CSS files that
run under a device mobile browser instance launched by the shell component.
In order to create an inner application, a web development team first needs the shell
component from the native team or from a source control system.
Unlike a standard Worklight hybrid application, the shell component itself is not deployable.
In order to test the shell component and any libraries built, Worklight introduces a test
application concept. When a shell component is created, an inner application is
automatically added to the project by Worklight Studio. The application is used by the shell
developer to launch the application either in a device or a device simulator to test the shell
component. The test application is only for unit testing.

17-11
Student Notebook
Creating a shell component

Create a Worklight project of type shell Component
Create the shell component
8
Figure 17-7. Creating a shell component
WU5061.1
Notes:
Regardless of whether the type is hybrid, shell or inner application, they are all managed
under a Worklight project that is the development unit in Worklight Studio.
Create a Worklight shell component using Worklight Studio. You can right click the
components folder and select New -> Worklight shell Component. This launches new shell
component creation wizard as shown on this page.
Specify the Worklight project to add the shell component to and name the shell component,
for example Myshell.
In this wizard, you can also add the UI frameworks to be packaged with the shell
component so that later the inner applications can use that framework.

V8.1
Student Notebook
Uempty
shell component file structure (1 of 2)

A shell component is a building
block that is used to create
inner applications
The MyshellTest application is
automatically created
This is a test application as
described in the Overview
section
You can use it to test and debug
the shell component
9
Figure 17-8. shell component file structure (1 of 2)
WU5061.1
Notes:
After clicking finish Worklight studio creates two components under the project. The first
one is created under the project components folder as shown in the lower part of the
screen shot. The folder name Myshell matches the component name. This folder is the
central place for native development team to work on the shell component.
A MyshellTest application is automatically created under the project applications folder as
shown on the upper portion of the screen shot. This is a test application, as described in
the terminology section. It is used to test/debug shell components.

17-13
Student Notebook
shell component file structure (2 of 2)

The common folder of the
shell component includes the
following subfolders:
css, images, js: contain web

resources that are added
automatically to inner applications
in build time
fragments: contains HTML

fragments that are added to various
parts of the inner application main
HTML file in predefined locations
preview: can be used to implement

native functionality stubs for
simulation in the Worklight Console
preview instead of receiving
exceptions
10
Figure 17-9. shell component file structure (2 of 2)
WU5061.1
Notes:
Like hybrid or standard Worklight applications, there is a common folder created for the
shell component. This is used to host all the artefacts shared by different device platforms
such as iOS and Android.
Under the common folder, folders for CSS, images and JS are used to host web resources
that are added automatically to inner applications at build time. If you are developing
reusable web widgets, or mobile client-side data binding component to be reused by inner
applications, this is where the code is managed.
The fragments folder contains html fragments that are added to the inner applications main
HTML file in predefined locations.
A shell component is primarily dealing with native code, thus it is often tested in a native
device or simulator environment. If you want to pre-view the web portion of the shell
component using desktop-based browser application preview feature, you can stub out
some of the native functions using this preview folder. Replace a native function or data
with stub UI or data defined under the preview folder.

V8.1
Student Notebook
Uempty

17-15
Student Notebook
shell-descriptor.xml
The shell-descriptor.xml file contains shell component information
and application-specific properties
Application-specific properties set in the shell descriptor are used in
all inner applications
Can be edited in
Design or Source
mode
11
Figure 17-10. shell-descriptor.xml
WU5061.1
Notes:
Like the applicationDescriptor.xml file for a standard hybrid application, the shell
component uses a file named shell-descriptor.xml to define shell component information
and application specific properties. For example, a native shell environment such as
Android shell or iPhone shell are defined under this file.
Application-specific properties set in the shell descriptor are used in all inner applications
that wrapped under this shell component.

V8.1
Student Notebook
Uempty
17.2.Creating and using a shell component

17-17
Student Notebook
Creating and using a shell

component

Figure 17-11. Creating and using a shell component
8.0
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Using the shell component in a test application (1 of 3)

Using the Myshell example, create a myshell.js file under
Myshell\common\js folder
Add the following function to it:
Modify body-top.wlfragment and add the following:
13
Figure 17-12. Using the shell component in a test application (1 of 3)
WU5061.1
Notes:
A test application is created for shell component developers for unit testing tasks. It is
automatically created by Worklight Studio. You can add testing logic to the test application
to validate your shell component. In this section, you see some simple examples to
illustrate how to use a test application to test your shell component.
Under the shell component, create a dummy shell function to say hello in a JavaScript
alert. You create a new myshell.js file under the Myshell\common\js folder.
In this file, create a simple JavaScript method sayHelloFromshell as shown in the screen
capture.
Expanding the shell/fragments folder, you see the file named body-top.wlfragment file. Edit
it and add the code shown in the side. The shell fragment loads the JavaScript myshell.js
just created. Save the file.

17-19
Student Notebook
Using the shell component in a test application (2 of 3)

Modify MyshellTest.js in apps/MyshellTest/common/js
Invoke the function added in the shell component:
Build and deploy

MyshellTest
Once deployed, the it is
listed in the Console as a
regular hybrid application
14
Figure 17-13. Using the shell component in a test application (2 of 3)
WU5061.1
Notes:
The sayHelloFromshell() function is not a part of the inner application, but a part of the shell
component. Edit the generated test application to test the code added on the previous
page.
Modify the MyshellTest.js file under apps/MyshellTest/common/js folder. In the application
initialization function wlCommonInit, add the statement to invoke the sayHelloFromshell
function.
Note that sayHelloFromshell is not defined in the Test application. The Worklight shell
component handles the code injection.
Build and deploy the MyshellTest application. Open the Worklight console and you find
your application listed as a regular hybrid application.
Preview the MyshellTest as Common Resource, which renders the test application in a new
browser tab or window.

V8.1
Student Notebook
Uempty
Using the shell component in a test application(3 of 3)

Preview of the test application
The browser includes web resources from both the shell component
and the inner application
15
Figure 17-14. Using the shell component in a test application(3 of 3)
WU5061.1
Notes:
Under application preview window, you can see the HTML text added to the shell fragment
and shell JavaScript function executed. Also, the inner test applications own HTML is also
rendered.
This simple test case illustrates how the Worklight shell component works, and how you
can test the shell component in Worklight studio.

17-21
Student Notebook
Creating and using a shell bundle (1 of 3)

When a shell developer builds a shell component, a .wlshell file
is created under the project bin folder
This file is called a shell bundle
It can be sent to inner application developers to use.
shell developers are not required to explicitly create a shell bundle;

the test application references the shell component source code
directly as specified in the application-descriptor.xml
If a shell developer wants to send a shell component to an inner
application developer, a shell bundle must be created
16
Figure 17-15. Creating and using a shell bundle (1 of 3)
WU5061.1
Notes:
Most of the bundle creation process is handled by Worklight studio. You start with a build
shell component. This can be started using the context menu by right-clicking the shell
component, for example myshell that was created here. Once the shell developer builds
the shell component a .wlshell file is created under projects bin\ folder. This file is called a
shell bundle and can be sent to inner application developers.
While the shell developers are working with the Test application they are not required to
explicitly create a shell bundle because the test application references the shell
components source code directly, as specified in the application-descriptor. However, once
a shell developer wants to send the shell component to the inner application developer,
they need to create a shell bundle.

V8.1
Student Notebook
Uempty
Creating and using a shell bundle (2 of 3)

To create a shell bundle, right-click a shell component folder and
select Run > Build shell Component
The .wlshell file is created under the project bin folder
17
Figure 17-16. Creating and using a shell bundle (2 of 3)
WU5061.1
Notes:
The shell bundle creation process is easy and is handled by Worklight studio. To create a
shell bundle right click on a shell components folder (in this case myshell) and select Run
? Build shell Component. The.wlshell file is created under bin\ folder of your project. In the
sample test component, it is Myshell-1.0.wlshell file.

17-23
Student Notebook
Creating and using a shell Bundle (3 of 3)

The inner application
developer must:
Copy the shell bundle file to a
Worklight project
Specify the location
If necessary, replace the existing
shell bundle file
shell
Component
shell Bundle
(.wlshell file)
Rebuild the application

inner
Application
APK or IPA file

containing
resources from
both shell and
inner components
18
Figure 17-17. Creating and using a shell Bundle (3 of 3)
WU5061.1
Notes:
Here is a review of how the inner application developer can bundle the web code under the
shell bundle.
The inner application developers must first copy the shell bundle file to a Worklight Project
they are working on. This can be copied into the project bin folder as well. Once inner
application developer creates a new inner application they must specify the location of a
shell bundle file. When the shell bundle file is received from shell component developers,
the inner application developer need to replace the existing shell bundle file and rebuild the
application. When building the inner application, Worklight Studio packages the shell
component and inner application to generate the final deployable mobile application as an
APK for Android application or an IPA file for iOS app. The process is highlighted in the
diagram on the right.

V8.1
Student Notebook
Uempty
17.3.Android shell development

17-25
Student Notebook
Android shell development

Figure 17-18. Android shell development
8.0
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Adding an Android environment to the shell component

Start by adding an Android environment to the shell component
20
Figure 17-19. Adding an Android environment to the shell component
WU5061.1
Notes:
Just like regular application environment optimization, preparing a shell component for an
Android environment starts with adding a new Android environment to a shell component.
The process is exactly the same as adding an Android environment for a regular hybrid
From either the shell component folder context menu or Eclipse toolbar Worklight short cut,
select New Worklight Environment to bring up the wizard. Specify the Worklight project and
the shell Component you want to add environment to. Then, under Create Folders, check
Android phones and tables.
The difference from the regular application new environment wizard is that the shell
component can only have three types of Environment: iPhone, iPad and Android phones
and tablets.

17-27
Student Notebook
Android shell component file structure

The following folder
structure is created:
css, images, fragments
and js: contain resources
that override/extend
resources from the shell
components common
folder
native: contains an
application template to be
used when creating an
Android project from an
inner application
nativeEmptyApp:
contains an application
built from the shell
component and an empty
inner application
21
Figure 17-20. Android shell component file structure
WU5061.1
Notes:
Once an Android environment is added to the shell component, a set of folders and files
are automatically generated. Similar to regular applications, a new folder named android is
created under the Myshell shell component application, as the same level as the common
folder.
The relationship between the environment specific artefacts and the ones under common
folders are similar to the rules used in regular Worklight application.
Android environment specific web code goes in the css, images, fragments, and js folders.
The native folder contains the native application template that is used when creating an
Android project from an inner application. This is where native developers work most of the
time such as adding new Apache Cordova plugins, or developing native Android pages
using Java.
The nativeEmptyApp folder contains an application built from the shell component and
an empty inner application. It is created for testing purposes.

V8.1
Student Notebook
Uempty
Adding an Android environment to shell component

The files that reside under the
native folder are templates used
to create the inner application
Android project
Some of the folder and file names
contain placeholder elements,
which are populated during build
For example:
${packageDirectory}
placeholder is populated with a
package name used in the
application
${appName} placeholder is
populated with the application name;
creates the main application activity
Files that end with .wluser are

user-editable templates, which can
be modified by a shell developer
22
Figure 17-21. Adding an Android environment to shell component
WU5061.1
Notes:
The files that reside under the native folder are templates that are used to create the inner
applications Android project.
You can define a Java native Android page implementation template under the native/src
folder. You can add Android User interface artefacts such as a UI definition and native
images under the res folder.
To be easily customized by the inner applications, two of the folder and file names under
the native folder contain placeholder elements which are populated during build time.
The ${packageDirectory} placeholder is populated with a real Java package name used
in the application. The ${appName} placeholder is populated with the applications
name, thus creating the main applications activity. All these placeholders allows a
single shell component be shared by multiple inner apps that may have different
configuration and attributes.
These placeholders are normally populated or generated by the Worklight studio build
process.

17-29
Student Notebook
Files that end with .wluser are user editable templates, which can be modified by a shell
developer. These files contain the business specific implementation such as a custom
built Android native page implemented in Java.

V8.1
Student Notebook
Uempty
Adding custom Java code to shell component (1 of 5)

Since the android\native
folder of a shell component is
not an Android project, Eclipse
does not provide advanced
features such as auto-complete
when working on it directly
Use an Android environment to
create, modify and debug Java
code
1. Add an Android environment to
the test application
2. Build and deploy the test
application
3. The generated Android project
is then added to Workspace
23
Figure 17-22. Adding custom Java code to shell component (1 of 5)
WU5061.1
Notes:
The Android/native folder is simply a placeholder used by Worklight shell component
framework, it is not a real Android project as the one under a regular Worklight application
is. So, Eclipse does not provide advanced features such as auto-complete when working
on it directly.
To continue getting support from these Eclipse feature, one of the solutions is adding an
Android environment to Test application added during the shell component creation time,
and using the Test Application Android environment to create, modify and debug Java
code.
To illustrate the concept, the following slides look at the process of building a simple
Android component called customToaster using Java.
You start by adding an Android environment for the Test Application. For the Myshell
sample, it is MyshellTest application. Once the new Android Environment is added, you can
work on the generated Android project.

17-31
Student Notebook
Add the package com.mycustomcode to the generated Android project
Add MyCustomToaster.java class under this package
Add a static method
Open the main

application class
Invoke MyCustomToast.showToastAlert()
24
WU5061.1
Notes:
From here, normal Android native development can be carried on, and all Eclipse support
feature like code assistant can be used.
A new package com.mycustomcode is created under the generated Android project, under
the src folder. A new Java class, MyCustomToaster.java, is added under this package.
Define a static Java method to invoke the Android Toast API to show a custom message.
In the application main activity, the Java class MyshellTest, the custom Toaster message is
invoked using MyCustomToast.showToastAlert().

V8.1
Student Notebook
Uempty

Run the application to see the implemented functionality
25
WU5061.1
Notes:
To test the shell component, run the Build and Deploy and then run the MyshellTest
Android project in an Android emulator or a real Android device.
The JavaScript alert (not discussed on the previous slides) is implemented in ShellProject.
The alert at the bottom of the screen capture is the custom toaster message implemented
in native Java code in ShellProjectMyShellTestAndroid.

17-33
Student Notebook

Copy the Java code from the Android project to the shell component
26
WU5061.1
Notes:
Copying the Java code is done in two steps:
Custom code is copied as-is, including the packages. The class
com.mycustomcode.MyCustomToaster is copied to the shell component source folder as
com/mycustomcode/MyCustomToaster.
For modifications made to artifacts that are predefined, or generated files created by
Worklight studio, the code content has to be copied manually to the corresponding
template files. In this specific case the code add to MyshellTest.java
(MyCustomToaster.showAlert(this, txt);) must be copied to the file
${appName}.java.wltemplate.wluser.

V8.1
Student Notebook
Uempty

The native folder of the test application is not rebuilt from the shell
component each time you build the Android application
This is done to prevent overwriting of the test application native code
with the one residing in the shell component on each build, thus
allowing the shell developer to debug code conveniently
27
WU5061.1
Notes:
In order to take in the changes made in the shell component native artifact, delete the
native folder in the Test application and perform a Build and Deploy to recreate it
automatically.

17-35
Student Notebook
Using the NativeEmptyApp Project

nativeEmptyApp is a native application project that uses the
shell component, but has an empty inner application. This project
can be built as an APK or IPA by a shell developer and sent to
inner application developers to use for debugging applications
Once nativeEmptyApp is installed on a device, the developer
can specify the URL of the Worklight Server from which to load
the inner application. This helps developers test their code without
needing native SDKs installed
or example, develop and test iPhone
applications without a Mac
To use nativeEmptyApp import its folder

as a Generic Project in Eclipse
28
Figure 17-27. Using the NativeEmptyApp Project
WU5061.1
Notes:
NativeEmptyApp is used primarily for inner application developers to test native functions.
It is not intended to deliver a final deployable native or hybrid application.
The NativeEmptyApp project can be deployed to an Android device or Device emulator.
Once NativeEmptyApp is installed on the device, inner application developer can specify
the URL of Worklight Server to load the inner application from. This helps inner application
developers to test their code without a need to have native SDKs installed, e.g. develop
and test iPhone application without a Mac.
To use NativeEmptyApp in the development environment, developers import the entire
nativeEmptyApp folder as a generic project in Eclipse. It has all the necessary folder
structure and configuration to be treated as an Android application.

V8.1
Student Notebook
Uempty
Using the NativeEmptyApp Project

The native empty application is automatically recognized as an
Android project
When built and deployed to an Android device, the application allows
you to change the URL from which the inner application content is
loaded by clicking Menu and going to Settings
29
Figure 17-28. Using the NativeEmptyApp Project
WU5061.1
Notes:
When deployed to an Android device or Android emulator, developers and testers can load
the inner application they want to test by performing some simple actions.
The NativeEmptyApp provides the instruction on the default page, as shown in the left
screen capture.
You need to Press the Android menu button, send select the setting. This brings up the
application setting screen as shown on the right screen capture.
In here, you change the URL that the inner application content is loaded from. The empty
shell then loads the inner application remote artifact to the device and render it as regular
Worklight hybrid application.

17-37
Student Notebook

V8.1
Student Notebook
Uempty
17.4.iOS shell development

17-39
Student Notebook
iOS shell development

Figure 17-29. iOS shell development
8.0
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Adding an iOS environment to shell component

Start by adding a new iPhone or iPad environment to the shell
component
31
Figure 17-30. Adding an iOS environment to shell component
WU5061.1
Notes:
Just like regular application environment optimization, preparing a shell component for iOS
development starts with adding a new iPhone or iPad environment to a shell component.
The process is exactly the same as adding an iOS environment for a regular hybrid
From either the shell component folder context menu or Eclipse toolbar Worklight short cut,
select New Worklight Environment to bring up the wizard. Specify the Worklight project and
the shell Component you want to add environment to. Then, under Create Folders, check
iPhone or iPad.
The difference from the regular application new environment wizard is that the shell
component can only have three types of Environment: iPhone, iPad and Android phones
and tablets. If there is already an environment created, it is greyed out here.

17-41
Student Notebook

The following folder structure is
created
css, images, fragments and js:
contain resources that override
or extend resources from the
shell component common folder
native: contains an application
template to be used when
creating an iOS project from an
inner application
nativeEmptyApp: contains
application built from shell
component and an empty inner
application
32
WU5061.1
Notes:
Once an iOS environment is added to the shell component, a set of folders and files are
automatically generated. Similar to regular applications, a new folder named iPhone or
iPad is created under the Myshell shell component application, as the same level as the
common folder.
The relationship between the environment specific artefacts and the ones under common
folders are similar to the rules used in regular Worklight application.
The native folder contains the native application template that is used when creating an
iOS project from an inner application. This is where native developers work most of the
time such as adding new Apache Cordova plugins, or developing native iOS pages.
The nativeEmptyApp folder contains an application built from the shell component and
an empty inner application. It is created for testing purposes.

V8.1
Student Notebook
Uempty

The files under the native folder
are templates used to create the
inner application
Some of the names contain
placeholder elements, which are
populated during build:
${XcodeProjectName}.
Xcodeproj.wluser is populated
with a package name used in the
application
${XcodeProjectName}.
info.plist.wltemplate.
wluser is populated with the
application name; creates the main
application activity
Files that end with .wluser are

user-editable templates, which can
be modified by a shell developer
33
WU5061.1
Notes:
The files that reside under the native folder are templates that are used to create the inner
applications iOS project.
example, you can add iPhone User interface artefact such as UI definition and native
images under the Resources folder.
To be easily customized by the inner applications, some of the folder and file names under
the native folder contain placeholder elements which are populated at build time:
${XcodeProjectName}.Xcodeproj.wluser and
${XcodeProjectName}-Info.plist.wltemplate.wluser.
All these placeholders allows a single shell component be shared by multiple inner
apps that may have different configuration and attributes.
These placeholders are populated or generated by Worklight studio build process.
Files that end with .wluser are user editable templates, which can be modified by a
shell developer. These files tend to contain the business specific implementation such
as a custom built iPhone native page implemented in Objective-C.

17-43
Student Notebook

V8.1
Student Notebook
Uempty
Adding Objective-C code to shell component (1 of 5)

The iphone\native folder of a
shell component is not an iOS
project, so features such as
auto-complete are not provided
when working on it directly
The solution is to add an iPhone
environment to the application
and use it to create, modify and
debug Objective-C code
34
Figure 17-33. Adding Objective-C code to shell component (1 of 5)
WU5061.1
Notes:
The iPhone/native folder is simply a placeholder used by Worklight shell component
framework, it is not a real iPhone project as the one under a regular Worklight application
is. So, Eclipse does not provide advanced features such as auto-complete when working
on it directly.
To continue getting support from these Eclipse feature, one of the solutions is adding an
iPhone environment to Test application added during the shell component creation time,
and using the Test Application iPhone environment to create, modify and debug
Objective-C code.
To illustrate the concept, the following slides look at the process of building a custom alert
iPhone component using Objective-C.
You start by adding a iPhone environment for the Test Application. For the Myshell sample,
it is MyshellTest application. Once new iPhone Environment is added, you can work on the
generated iPhone project.

17-45
Student Notebook
Open the generated iOS project in Xcode

Add a new Objective-C class called MyshellTest under Classes folder
Add a static method to this class
Invoke this method from viewDidLoad of the application ViewController
35
WU5061.1
Notes:
Create a new Objective-C class called MyshellTest under the Classes folder. This is your
custom iPhone component.
Add a static method to the newly create class. The method raises an alert using the
Objective-C UIAlertView API.
Modify the Worklight studio generated iPhone main class of your application ViewController
and invoke the custom Alert class you created earlier.
This completes the native development work, all done in the iPhone environment of the test
application MyshellTest.

V8.1
Student Notebook
Uempty

Run your application to see the implemented functionality
36
WU5061.1
Notes:
To test the shell component, you need to run the Build and Deploy.
Build and Deploy all or iPhone environment for the MyshellTest Test application. Then, run
MyshellTest iPhone project in iPhone simulator or a real iPhone device from Xcode.
You see the custom alert message MyCustomClasss alert you have implemented in native
Objective-C code in previous slides.
This completes your testing, youve validated that the custom Objective-C alert
implementation is working properly. Now, its time to get the native code back into the shell
component.

17-47
Student Notebook

Copy the Objective-C code from the iPhone project to the shell
component
2
37
WU5061.1
Notes:
1. The custom Objective-C classes added to the iPhone project can be copied as-is,
keeping the folder structure intact. These files are under the Classes folder, as shown in
the screen capture here.
2. Xcode keeps its project structure stored in project.pbxproj. Therefore the content of
this file should also be copied from Test application to shell component.

V8.1
Student Notebook
Uempty

The native folder of the Test
application is not being rebuilt
from the shell component each
time you build the iOS
application
This is done in order not to
overwrite the Test applications
native code with the shell
component on each build
This allows the shell Developer to
debug code conveniently
To fully recreated the native

code from a shell component
erase it in the Test application
and perform a Build and
Deploy
38
WU5061.1
Notes:
When you make changes to the shell component, you need to synchronize the code with
the generated Test Application iPhone project.

17-49
Student Notebook
Using the nativeEmptyApp Project

nativeEmptyApp is a native
application project that uses the shell
component, but has an empty inner
application.
When nativeEmptyApp is installed on
the device, the inner application
developer can specify the URL of the
Worklight Server from which to load the
inner application.
To use nativeEmptyApp, open it as an
Xcode project
39
Figure 17-38. Using the nativeEmptyApp Project
WU5061.1
Notes:
The nativeEmptyApp project can be built as an APK or IPA by the shell developer and sent
to inner application developers to use for debugging applications.
The ability to specify the URL of the Worklight Server from which to load the inner
application helps inner application developers to test their code without a need to have
native SDKs installed, (for example develop and test iPhone application without a Mac).
Important: nativeEmptyApp cannot load a remote inner application that has the device
provisioning enabled. NativeEmptyApp can only be used in the development environment.
Its used primarily for inner application developer to test the native function rather than
delivering a final deployable native or hybrid application.
You can deploy the NativeEmptyApp project to an iOS device or Device emulator. Once
nativeEmptyApp is installed on the device, inner application developer can specify the URL
of Worklight Server to load the inner application from. This helps inner application
developers to test their code without a need to have native SDKs installed, e.g. develop
and test iPhone application without a Mac.
V8.1
Student Notebook
Uempty
To use the NativeEmptyApp in development environment, developers can open it as an

Xcode project. To open it in Xcode, it follows the same process as a regular application
iphone environment. Right click the NativeEmptyApp and select Run As Xcode project.

17-51
Student Notebook
1. When a shell developer completes developing the shell components,
what is the correct way to distribute it to inner application
developers?
A. Compressing the Worklight project and emailing it to inner application
developers
B. Committing the Worklight project to a source control management system and
telling inner application developers to use source code from it
C. The shell developer should not distribute the shell component to inner
application developers. They should send their inner applications to the shell
developer in order to build them
D. Sending the .wlshell shell bundle file to inner application developers
2. Which of the following should not be a part of the shell component?

A. Authentication module
B. Native functionality JavaScript wrapper
C. Application UI components
D. Company logotype that should be shared between several applications
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Unit summary
WU5061.1
Notes:

17-53
Student Notebook
Checkpoint answers
1. D. Sending the .wlshell shell bundle file to inner application
developers
2. C. Application UI components
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Unit 18. IBM Application Center

In this unit, you learn about the IBM Application Center, which is like a
private "app store" that you can use to manage and share mobile
applications within your organization.

Configure Application Center users
Use the Application Center to manage and share mobile
applications within a development team.

Exercise
References
Enabling Mobile Apps with IBM Worklight Application Center (An IBM
Redpaper publication)
http://www.redbooks.ibm.com/abstracts/redp5005.htm
l

18-1
Student Notebook
Unit objectives
Use the Application Center to manage and share mobile applications
within a development team.
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
What is IBM Worklight Application Center?

The Application Center can be used as an Enterprise application store
and is a means of sharing information among different team members
within a company.
The concept of the Application Center is similar to the concept of the
Apple public App Store or the Android Market, except that it targets
only private usage within a company.
By using the Application Center, users from the same company or
organization download applications to mobile phones or tablets from a
single place that serves as a repository of mobile applications.
Works with IBM Worklight hybrid applications, but not restricted to
Worklight apps
Supports any iOS or Android application
Figure 18-2. What is IBM Worklight Application Center?
WU5061.1
Notes:
repository, an administration console, and a client mobile application.

18-3
Student Notebook
Typical scenario
As part of the development process of an application, a development
team creates a new version of an Android or iOS application
A developer uploads the new version of the application to the
Application Center
The developer enters a description that mentions elements that the team
added or fixed from the previous version
The new version of the application is available to other members of the team
for testing and review
A beta tester can launch the Application Center installer application,

the mobile client, locate the new version of the application and install
it on their mobile device
After testing, the beta tester can rate the application and submit
feedback on the Application Center console
Figure 18-3. Typical scenario
WU5061.1
Notes:
You can use the Application center as part of the development process of an application. A
typical scenario of the Application Center is a team building a mobile application; the
development team creates a new version of an Android or iOS application. The
development team wants this new version to be reviewed and tested by the extended
team. A developer goes to the Application Center console and uploads the new version of
the application to the Application Center. As part of this process, the developer can enter a
description of the application version. For example, the description could mention the
elements that the development team added or fixed from the previous version. The new
version of the application is then available to the other members of the team.
Another person, for example, a beta tester, can launch the Application Center installer
application, the mobile client, to locate this new version of a mobile application in the list of
available applications and install it on his mobile device. After testing the new version, the
beta tester can rate the application and submit feedback. The feedback is visible to the
developer from the Application Center console.

V8.1
Student Notebook
Uempty
Application Center architecture (1 of 2)

Application Server
Application Center
Application Catalog
Service
Application Center
Console
Application Install
Service
Application
Center
Installer App
Application Feedback
Service
iOs / Android
Rest Services
Database - Derby
Figure 18-4. Application Center architecture (1 of 2)
WU5061.1
Notes:
repository, an administration console, and a mobile client application.
Server-side component
The server-side component is a Java Enterprise application that must be deployed in a web
application server such as IBM WebSphere or Apache Tomcat.
The server-side component consists of an administration console and a mobile application.
This mobile application installs the mobile applications available to the client-side
component.
The web console and the installer application communicate through REST services with
the server component.
Several services compose the Application Center server-side component; for example, a
service that lists available applications, a service that delivers the application binary files to
the mobile device, or a service that registers feedback and ratings.
Repository

18-5
Student Notebook
A database that stores information such as which application is installed on which devices,
the feedback about applications, and the mobile application binary files. The Application
Center application is associated with the database when you configure the Application
Center for a particular web application server and a supported database.
Administration console
A web console through which administrators can manage applications, user access rights
to install applications, user feedback about mobile applications, and details about
applications installed on devices. See The Application Center console.
Mobile client application
You use the mobile client to install applications on a mobile device and to send feedback
about an application to the server.

V8.1
Student Notebook
Uempty
Application Center architecture (2 of 2)

The Application Center is installed as part of the Worklight Server
installation
As of IBM Worklight V5.0.6, the App Center is divided into two WAR
files: one for the console and one for services
The pre-built EAR file is available in
{worklight_install_folder}/ApplicationCenter/console.
The paths of the WAR files in this EAR file are as follows:
Console: /applicationconsole
Services: /applicationcenter
Figure 18-5. Application Center architecture (2 of 2)
WU5061.1
Notes:

18-7
Student Notebook
Application Center configuration

The Application Center has two JEE security roles defined:
The appcenteruser role that represents an ordinary user of the Application
Center who can install mobile applications from the catalog to a mobile device
belonging to that user
The appcenteradmin role that represents a user who can perform administrative
tasks through the Application Center console
You must map the roles to the corresponding sets of users in your
organization
Figure 18-6. Application Center configuration
WU5061.1
Notes:
If you choose to use an authentication method through a user repository such as LDAP,
you can configure the Application Center so that you can use users and groups with the
user repository to define the Access Control List (ACL) of the Application Center. This
procedure is conditioned by the type and version of the web application server that you
use.
After you configure authentication of the users of the Application Center, which includes
configuring LDAP if you plan to use it, you can, if necessary, define the endpoint of the
application resources. You must then build the Application Center mobile client. The mobile
client is used to install applications on mobile devices.

V8.1
Student Notebook
Uempty
Application Center user configuration

You configure Application Center users in the WebSphere Application
Server console.
Access the Application Center by the following URL:
http://server:port/appcenterconsole
Where server is the address and port of the server where the
Application Center is installed
Only users with the administrator role can log in to the Application
Center console
Figure 18-7. Application Center user configuration
WU5061.1
Notes:

18-9
Student Notebook
Applications view
1.
To add an application to the

console, click Add Application
2.
Select an application (APK or IPA

file) to upload
Figure 18-8. Applications view
WU5061.1
Notes:
In the Applications view you can add applications to the Application Center. Initially the list
of applications is empty and you must upload an application file.

V8.1
Student Notebook
Uempty
Application details view
Figure 18-9. Application details view
WU5061.1
Notes:
Application details:
Description: used to describe the application to the mobile user.
Recommended: select to indicate that you recommend users to install this
application. Recommended applications appear in a special list of applications in
the mobile client.
Installer: Administrator only; indicates that the application is used to install other
applications on the mobile device.
Active: indicates that an application can be installed on a mobile device. If you
do not select this property, the application is inactive and grayed on the list of
applications in Application Management.
For Android applications:
Package: the package name of the application; package attribute of the
manifest element in the manifest file of the application.

18-11
Student Notebook
Internal Version: the internal version identification of the application;

android:versionCode attribute of the manifest element in the manifest file of
the application.
Commercial Version: the published version of the application.
Label: the label of the application; android:label attribute of the application
element in the manifest file of the application. See the Android SDK
documentation for more information.
For iOS applications:
Package is the company identifier and the product name;
CFBundleIdentifier key.
Internal Version is the build number of the application; CFBundleVersion
key of the application.
Commercial Version is the published version of the application.
Label is the label of the application; CFBundleDisplayName key of the
application. See the iOS SDK documentation for more information.

V8.1
Student Notebook
Uempty
Available applications view
Version number
Access control setting
Rating
Figure 18-10. Available applications view
WU5061.1
Notes:
To edit application properties, click the version number of the application > Application
details.
To view feedback details, click the version number of the application.
To set access control, click the unrestricted or restricted links of the application.

18-13
Student Notebook
Feedback and rating
Stakeholders and
testers submit
feedback directly from
the Application Center
mobile client
Developers can review

feedback in the context of
specific device and user by
using the Application
Center console
Figure 18-11. Feedback and rating
WU5061.1
Notes:
Users of mobile applications can rate an application and send feedback through the
Application Center mobile client. The feedback is available in the Application Center
console. Individual feedback is always associated with a particular version of an
application.
The rating is an average of all recorded feedback. It consists of one to five stars, where one
star represents the lowest level of appreciation and five stars represents the highest level
of appreciation. If no stars are selected, no feedback is recorded.

V8.1
Student Notebook
Uempty
Setting access control
1.
2.
3.
Select Applications > Available

Applications
Click unrestricted or restricted state of an
application.
To add a user, enter a user ID and click Add
User.
You can also add users

from another application.
Click Add users from
application, select the
application from the list,
and click OK.
Figure 18-12. Setting access control
WU5061.1
Notes:
Select Applications > Available Applications.
Click unrestricted or restricted state of an application.
To add a user, enter a user ID and click Add User.
There are different ACLs for installation (for example, testers) and administration (fellow
developers).

18-15
Student Notebook
Registered devices view
Figure 18-13. Registered devices view
WU5061.1
Notes:
The devices that are connected to the Application Center are listed under Device
Management > Registered Devices.
You can edit the Name of a device. Click OK or Apply to save the changes.

V8.1
Student Notebook
Uempty
Application Center client

A mobile application to manage
applications on the device
List all applications from the
catalog (for which you have
access rights)
List applications you have installed
on the device
Install an application or upgrade to
a new version
Provide feedback and rating for an
application (1-5 stars)
Set up the installer from the

Application Center console
Figure 18-14. Application Center client
WU5061.1
Notes:

18-17
Student Notebook
Installing an application from the mobile client (1 of 2)
Nothing is installed
Figure 18-15. Installing an application from the mobile client (1 of 2)
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Installing an application from the mobile client (2 of 2)
Standard iOS controls

Figure 18-16. Installing an application from the mobile client (2 of 2)
WU5061.1
Notes:

18-19
Student Notebook
Unit summary
Use the Application Center to manage and share mobile applications
within a development team.
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Exercise 9
Exploring the Application Center

8.0
WU5061.1
Notes:

18-21
Student Notebook
Exercise objectives
Configure the Application Center
Manage applications in the Application Center
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Unit 19. Course summary

This unit summarizes the course, explains the class evaluation
process, and provides information for future study.

Explain how the course met its learning objectives
Submit an evaluation of the class
Identify other WebSphere Education courses that are related to
this topic
Access the WebSphere Education website
Locate appropriate resources for further study

19-1
Student Notebook
Unit objectives
Identify other WebSphere Education courses that are related to this
topic

WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Course learning objectives

Identify a mobile application design type suitable for your application
Develop a mobile application to run on an Android or iOS platform
using the IBM Worklight hybrid coding approach
Use IBM Worklight client-side APIs for cross-platform portability
Use IBM Worklight server-side APIs for back-end integration
Include the Dojo Mobile, jQuery Mobile or Sencha Touch UI framework
in an application
Secure a mobile application using different IBM Worklight
authentication techniques
Manage application updates and versions

Figure 19-2. Course learning objectives
WU5061.1
Notes:

19-3
Student Notebook
References
http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp?topic=%2Fcom.ibm.
help.doc%2Fwl_home.html

Figure 19-3. References
WU5061.1
Notes:

V8.1
Student Notebook
Uempty
Unit summary
Identify other WebSphere Education courses that are related to this
topic

WU5061.1
Notes:

19-5
Student Notebook

V8.1
Student Notebook
AP
Appendix 20.List of abbreviations

IBM
International Business Machines Corporation
Appendix 20. List of abbreviations

20-1
Student Notebook

V8.1
backpg
Back page

Work Light

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Work Light

Uploaded by

Copyright:

Available Formats

V8.

WebSphere Education Solutions Team offering - Early release material

WebSphere Education Solutions Team offering - Early release material

June 2013 edition

Copyright International Business Machines Corporation 2013.

WebSphere Education Solutions Team offering - Early release material

Copyright IBM Corp. 2013

WebSphere Education Solutions Team offering - Early release material

Mobile Application Development with IBM Worklight V6

Copyright IBM Corp. 2013

WebSphere Education Solutions Team offering - Early release material

Worklight console - mobile browser simulator . . . . . . . . . . . . . . . . . . . . . . . . . . .

Unit 4. Overview of Worklight Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

WebSphere Education Solutions Team offering - Early release material

IBM Worklight Studio installation and configuration . . . . . . . . . . . . . . . . . . . . . . . . .4-6

Copyright IBM Corp. 2013

WebSphere Education Solutions Team offering - Early release material

Adding a new environment (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-60

WebSphere Education Solutions Team offering - Early release material

jQuery JavaScript framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-9

Copyright IBM Corp. 2013

WebSphere Education Solutions Team offering - Early release material

Unit 6. Local storage APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

WebSphere Education Solutions Team offering - Early release material

Handling data locally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-38

Mobile Application Development with IBM Worklight V6

Copyright IBM Corp. 2013

WebSphere Education Solutions Team offering - Early release material

7.4. Dojo Mobile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Unit 8. Apache Cordova . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

WebSphere Education Solutions Team offering - Early release material

WebViewOverlay Cordova plugin (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-42

Mobile Application Development with IBM Worklight V6

Copyright IBM Corp. 2013

WebSphere Education Solutions Team offering - Early release material

Procedure declarations in the XML file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

WebSphere Education Solutions Team offering - Early release material

Checkpoint answers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-99

Mobile Application Development with IBM Worklight V6

Copyright IBM Corp. 2013

WebSphere Education Solutions Team offering - Early release material

11.2. iOS native API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Unit 12. Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1

WebSphere Education Solutions Team offering - Early release material

Server-side authentication components (2 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . .12-38

Mobile Application Development with IBM Worklight V6

Copyright IBM Corp. 2013

WebSphere Education Solutions Team offering - Early release material

Unit 13. Push notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-1

WebSphere Education Solutions Team offering - Early release material

Introducing reports and analytics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-5

Copyright IBM Corp. 2013

WebSphere Education Solutions Team offering - Early release material

Worklight Apache Ant utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Unit 17. Shell development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1

WebSphere Education Solutions Team offering - Early release material

Creating and using a shell Bundle (3 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17-24

Mobile Application Development with IBM Worklight V6

Copyright IBM Corp. 2013

WebSphere Education Solutions Team offering - Early release material

Unit 19. Course summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Appendix 20. List of abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-1

Copyright IBM Corp. 2013