Walkthrough: Deploy a JavaScript JMS App as a Hybrid Android App

In this walkthrough, you will learn how to deploy an existing JavaScript JMS web app built with the Kaazing WebSocket Gateway JavaScript JMS libraries as a hybrid app for Android. This topic walks you through the following subjects:

What You Will Accomplish
Before You Begin
Install the Tutorial, Gateway (optional), Android SDK, and Cordova 6.0
Build the Hybrid Android App Using Cordova
Configure and Run the Gateway and Apache ActiveMQ (optional)
Test the Hybrid Android App
Summary

Notes:

A hybrid Android app is a hybrid of a browser-based application and a native Android app. A native Android app is built using the Android SDK. A hybrid Android app is built using HTML, CSS, and JavaScript like a typical browser-based application, and then packaged in a framework that allows it to be converted into an app that runs on Android devices much like a native app. Hybrid Android apps enable web developers to leverage their web experience to create apps for Android. For information on native Android development, see Android Develop.
A hybrid Android app is also different from a browser-based application that is intended for viewing in a browser on Android, but not downloaded through the Android app store. If you have an existing Kaazing WebSocket Gateway JavaScript JMS browser-based application, you can use it to create a hybrid Android app or you can modify its web content to make it compatible with browsers on Android.

What You Will Accomplish

At the end of this walkthrough, a JavaScript JMS demo app created using the Kaazing JavaScript JMS SDK libraries runs as a hybrid Android app on Android, connects to the local or publicly available Apache ActiveMQ broker via the Gateway, and sends and receives JMS messages using a native or emulated WebSocket connection. Users can run the hybrid Android app on any Android device and connect via the Gateway to the Apache ActiveMQ broker.

This walkthrough uses the JavaScript JMS tutorial app that is available online at https://github.com/kaazing/javascript.client.tutorials, but the steps outlined in this walkthrough are the same for other JavaScript JMS client applications built with the Kaazing JavaScript JMS SDK.

Note: For this walkthrough, you can use any JMS-compliant message broker. By default, the Gateway is configured to connect to the server on tcp://localhost:61613. You can configure the connect URL in the file GATEWAY_HOME/conf/gateway-config.xml. See About Integrating Kaazing WebSocket Gateway and JMS-Compliant Message Brokers for more information.

Before You Begin

Before starting this walkthrough you need the following:

Kaazing JavaScript JMS Tutorial App - https://github.com/kaazing/javascript.client.tutorials.
Kaazing WebSocket Gateway (optional). See Setting Up Kaazing WebSocket Gateway. You can also use the publicly available Kaazing WebSocket Gateway and Apache ActiveMQ broker at the URL wss://demos.kaazing.com/jms.
Android Studio and SDK.
Apache Cordova 6.0 and its Command-Line Interface (CLI).

Learn about supported browsers, operating systems, and platform versions in Release Notes.

Note: Steps for installing and configuring Android Studio, Android SDK, and Cordova 6.0 are included in this walkthrough.

Install the Tutorial, Gateway, Android Studio, Android SDK, and Cordova 6.0

The following steps take you through the installation of the software required for deploying a hybrid Android app. If you have already have this software installed, you can simply note the locations of the installed software for later use.

Download or clone the Kaazing JavaScript JMS Tutorial, available on Github at https://github.com/kaazing/javascript.client.tutorials. Build the project using the instructions here https://github.com/kaazing/javascript.client.tutorials/blob/develop/README.md.
Install the Gateway as described in Setting Up Kaazing WebSocket Gateway (optional). There is also a publicly available Kaazing WebSocket Gateway and Apache ActiveMQ message broker available at the URL wss://demos.kaazing.com/jms. You can use either option.
Download and install Android Studio from http://developer.android.com/sdk/installing/index.html?pkg=studio.
Launch Android Studio.
In Welcome to Android Studio, click Configure, and then click SDK Manager.
Select the Android 2.2 and the Android 4.1 packages and then click Install packages.
Download and install Cordova 6.0 as described in Installing the Cordova CLI from Cordova.

Build the Hybrid Android App Using Cordova

The following steps will create the project directory for the hybrid Android app, and populate the directory with the web app files and JavaScript JMS library files required to communicate with the Gateway.

Note: The general steps for creating an Android app using Cordova are documented in the Apache Cordova Documentation, Create the App.

Note the location of the Kaazing JavaScript JMS Tutorial you downloaded and built, for example /Users/johndoe/Desktop/github/javascript.client.tutorials/jms. When you create your Cordova project you will reference the jms folder in order for Cordova to build the hybrid Android app using the tutorial files.
Open a Terminal at the folder where you want to save the app.
To create the app and populate it with the JavaScript demo, enter the following:

cordova create myAndroidApp com.example.myapp myAndroidApp --template /Users/johndoe/Desktop/github/javascript.client.tutorials/jms

The /Users/johndoe/Desktop/github/javascript.client.tutorials/jms points to the JavaScript demo files you downloaded and built.

Note: This walkthrough uses the JavaScript JMS tutorial app as an example web app, but when you create your own JavaScript JMS app, you can create it in your favorite IDE and then copy it to this www directory. You must name the HTML file for your app index.html and you must ensure that links in index.html point to the JavaScript WebSocket library and the JavaScript JMS library (see Setting Up the Gateway and Clients), for example:
```
      <script src="WebSocket.js" type="text/javascript" language="javascript"></script>
      <script src="JmsClient.js" type="text/javascript" language="javascript"></script>
      
```
In Terminal, navigate to the folder for your new app (cd myAndroidApp).
To specify the target platform as Android, enter the following command: cordova platform add android. Note: To see a list of the current platforms available, enter: cordova platforms ls.
To build the project, enter the following command: cordova build android. The build process might take some time. When it is finsihed, Cordova generates the platform-specific project within the project's platforms subdirectory that you can open with Android Studio (for example, myAndroidApp/platforms/android).

On Mac or Linux, if you receive the error Error: Android SDK not found then open your .bash_profile file and enter the following (replace JohnSmith with your user name):

export ANDROID_HOME=/Users/JohnSmith/Library/Android/sdk export PATH=$ANDROID_HOME/platform-tools:$PATH export PATH=$ANDROID_HOME/tools:$PATH

For more info, https://cordova.apache.org/docs/en/dev/guide/platforms/android/.

Configure and Run the Gateway and Apache ActiveMQ (optional)

If you are going to use a local copy of Kaazing WebSocket Gateway, the following steps start the Apache ActiveMQ service that is included with the Gateway, configure the cross-site constraint for the jms service on the Gateway, and then run the Gateway.

Start Apache ActiveMQ. For steps on starting Apache ActiveMQ, see the setup information for Apache ActiveMQ or Setting Up the Gateway and Clients.
Open the GATEWAY_HOME/conf/gateway-config.xml file in a text editor. You need to modify this file to use the Android Emulator loopback IP address (10.0.2.2) and you need to change the cross site constraint to allow any origin in order to run the app locally. 10.0.2.2 is the special alias to your host loopback interface (127.0.0.1 on your development machine). For more information about Android Emulator networking, see Emulator Networking from Android.

Modify the jms service to use the Android loopback IP address and the cross site constraint to allow any origin:

  <service>
    <name>JMS Service</name>
    <description>JMS Service</description>
    <accept>ws://10.0.2.2:8888/jms</accept>

    <type>jms</type>

    <properties>
      <connection.factory.name>ConnectionFactory</connection.factory.name>
      <context.lookup.topic.format>dynamicTopics/%s</context.lookup.topic.format>
      <context.lookup.queue.format>dynamicQueues/%s</context.lookup.queue.format>
      <env.java.naming.factory.initial>org.apache.activemq.jndi.ActiveMQInitialContextFactory</env.java.naming.factory.initial>
      <env.java.naming.provider.url>tcp://localhost:61616</env.java.naming.provider.url>
    </properties>

      <accept-options>
        <ws.bind>localhost:8888</ws.bind>
      </accept-options>

    <realm-name>demo</realm-name>

    <cross-site-constraint>
      <allow-origin>*</allow-origin>
    </cross-site-constraint>
  </service>

Save the gateway-config.xml file.
Start the Gateway as described in Setting Up the Gateway and Clients.

The output from the command will display that the Gateway is listening on:

ws://10.0.2.2:8888/jms @ localhost:8888

Test the Hybrid Android App

The following steps use the Android Emulator to test the hybrid Android app that you created.

Notes:

If you are using a local Gateway and Apache ActiveMQ broker, then both the Gateway and Apache ActiveMQ must be running before testing the hybrid Android app.
When testing on Android devices: In order to connect the hybrid Android app on the Android device to the Gateway and Apache ActiveMQ, the Android device must be able to resolve the host name of computer running the Gateway on the network. This is the host name that you will use in the Location field of the hybrid Android app. For example, ws://host_name:8001/jms. You can also configure the Android device to use the IP Address of the computer running the Gateway (for example, ws://192.168.4.86:8001/jms). Using the IP Address is often the easiest method during testing.

In Terminal, ensure that you are in the root of the project directory (for example, myAndroidApp), and enter the following to see a list of all available Simulator targets: cordova run android --list. For this walkthrough, we will use Nexus_5_API_22_x86.
To run the app in the Android Simulator, enter the following: cordova run android --target="Nexus_5_API_22_x86". The Android Simulator opens and displays the hybrid Android app. It might take several minutes for the Android Simulator to launch and display the app. The app icon might appear on the Android Simulator screen for a while before displaying the GUI of the app. You might need to relaunch the app within the Android Simulator.
In the hybrid app in the Android Simulator, click in the Location field. If you are using a local Gateway, enter the jms service URI ws://10.0.2.2:8888/jms. If you are using the publicly available Gateway and Apache ActiveMQ broker, enter wss://demos.kaazing.com/jms. Click Connect.

The Log messages field reports a successful connection. If the app does not connect, ensure that you have the Gateway and Apache ActiveMQ running.
Play with hybrid app to see the full functionality.
For information on testing your hybrid Android app on an Android device, see Setting up a Device for Development and OEM USB Drivers in the Android developer documentation (http://developer.android.com).

Summary

In this walkthrough, you learned how to turn one of the Kaazing JavaScript JMS tutorial app into a hybrid Android app. To learn how to build your own Kaazing WebSocket Gateway JMS apps, refer to the documentation.

Notes

Clients built using Kaazing WebSocket Gateway 3.x libraries will work against Kaazing WebSocket Gateway 4.x. If you wish to upgrade your 3.x client to the 4.x libraries, please note that the 3.x clients used a single JMS library and 4.x clients include and use separate WebSocket and JMS libraries. Update your client library file and code references to include both the WebSocket and JMS libraries, as described in the 4.x documentation. For more migration information, see Migrate JavaScript Applications to Kaazing WebSocket Gateway 4.x.