App Developer Guide 2.4 M3

8/9/2019 App Developer Guide 2.4 M3

1/47

OpenMobster - MobileBackend as a Service Platform

App Developer Guide

openmobster at gmail.com


2/47

OpenMobster - Mobile Backend as a Service Platform: App DeveloperGuideopenmobster at gmail.com

2.4


3/47

iii

Table of Contents

1. Introduction to OpenMobster - Mobile Backend as a Service Platform ... ... ... ... ... ... ... ... ... ... ... ... .. 1

Enterprise Data Sync ................................................................................................... 1

Real-Time Push Notifications ..... ..... ...... ..... ...... ..... ...... ...... ..... ...... ..... ...... ...... ..... ...... .... 1

Mobile RPC (Remote Procedure Call) ............................................................................ 1

Management Console ............................................................... ................................... 12. Programming Concepts ...................................................... .............................................. 2

Cloud Server ............................................................... .............................................. 2

Channel ................................................... ...................................................... ... 2

MobileServiceBean ............................................................................................ . 2

Mobile App Frameworks ...................................................... ....................................... 2

Mobile Data Framework ...................................................... ................................ 2

3. Architecture ... ... ... .. ............... ....................................................... .................................. 4

OpenMobster Architecture ................................................... ........................................ 4

Device SDK Stack ...................................................................................................... 5

Sync ...... ................................. .......................................................................... 5

Push ...... ........................................................................................................... 5

OfflineApp ................ ...................................................... .................................. 5

Mobile RPC ....................................................................................... ............... 6

Network ............................................................................................................ 6

Local Storage ............................................... ..................................................... 6

Cloud Server Stack .................................................... ................................................. 7

4. Get Started: CRUD App in Action ..................................................................................... 9

...................................................... ........................................................ ................. 9

System Requirements ......................................................... ................................. 9

Installation ................................ ........................................................ ........................ 9

Download OpenMobster ... ... ... ....................................................... ...................... 9

Install Cloud Server ........................................................... ................................. 9

Install CRUD App on 2 devices ...... ...... ..... ...... ................................................... 10

App Activation .. ... ... .. ............................ ................................................................... 10

CRUD App Features .................................... ..................................................... ........ 10CRUD App Help ................................................................ ...................................... 10

5. Show me the Code ......... .............................. ........................................................ ......... 12

.............................................................................................................................. 12

Tutorial ....................................................... ................................................... ......... 12

Cloud-Side: Channel Development ................................................................... .... 12

App/Device-Side Programming ...................................................... ..................... 18

6. AppCreator ............................... ...................................................... ............................. 24

Start writing your own App ........................................................................................ 24

app-android .............................. ................................................................................ 24

cloud ................................................................................... ................................... 24

JBoss AS Deployment ...................................................... ......................................... 25

7. MobileBean ..................................... ............................................................................. 26

MobileBean ........................................... .................................................. ................ 26Cloud-Side .................... ........................................................................................... 26

Specification ....................................... .................................................... ......... 26

Device-Side ......................................... .................................................... ................ 26

Accessing a Simple Property ............................................................... ............... 26

Accessing a Nested Property ......................................................................... ...... 26

Accessing an Indexed Property (One-Dimensional Array or a java.util.List) .. .. .. .. .. .. .. .. . 27

Iterating through an Indexed Property (One-Dimensional Array or a java.util.List) .. .. .. .. . 27

8. Push Programming ............................... ................................................. ........................ 28


4/47

OpenMobster - Mobile

Backend as a Service Platform

iv

Sending a Push Notification ........................................................................................ 28

Push Setup on an Android App ...... ..... ...... ...... ..... ...... ..... ...... ...... ..... ...... ..... ...... ...... .... 28

Push Setup on an iOS App ......................................................................................... 29

Apple Provisioning ................................................. .......................................... 29

OpenMobster Provisioning ...... ..... ...... ...... ..... ...... ..... ...... ...... ..... ...... ..... ...... ...... .. 29

9. iOS + OpenMobster integration ...... ..... ...... ..... ...... ...... ..... ...... ..... ...... ...... ..... ...... ..... ...... ... 32

Introduction ........................................................ ..................................................... 32Prepare the mobilecloudlib static library ........ ..... ..... ...... ..... ...... ..... ...... ...... ..... ...... ..... ... 32

Start a View-based App ..... ...... ...... ..... ...... ..... ...... ...... ..... ...... ..... ...... ...... ..... ...... ..... .... 32

Create a Group called OpenMobster ............................................................................. 32

Add the libraries and Frameworks ..... ..... ...... ..... ...... ..... ...... ...... ..... ...... ..... ...... ...... ..... .. 32

Add OpenMobster bootstrap code .......... ..... ...... ..... ...... ...... ..... ...... ..... ...... ...... ..... ...... ... 33

The bootstrapping functions ................................................................................ 33

Integrating the bootstrapping function with the App Delegate ..... ... ... ... ... ... ... ... ... ... ... . 34

Integrating the CloudManager ..... ...... ...... ..... ...... ..... ...... ...... ..... ...... ..... ...... ...... ..... ...... . 36

Integrate the CloudManager button on the View ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... .. 36

Implement the action behind the button .......... ..... ..... ...... ..... ...... ..... ...... ...... ..... ..... 37

Sample App ............................................................................................................. 37

10. iOS + OpenMobster Sample App ......................................................... .......................... 38

Introduction .......................................................................... ................................... 38Prepare the mobilecloudlib static library ....................................................... ................ 38

Run the Cloud Server ................................................................................................ 38

Run the SampleApp ...................................................... ............................................ 38

11. Mobile RPC (Remote Procedure Call) Development ................................................ .......... 39

Cloud-Side: MobileServiceBean implementation .......... ................................................... 39

Cloud-Side: Configuration ..................................................................... ..................... 40

Cloud-Side: Pack aging and Deployment ........................................................................ 40

Putting it altogether ......................... .......................................................................... 40

App/Device-Side: Invoking the MobileServiceBean ........................ ................................ 40

12. Clustering .................................................. ................................................................. 41

Clustering the Cloud Server ........................................................................................ 41

High Availability ................................................. ............................................. 41

Load Balancing ........................................................................... ..................... 41Setup ...................................................................... ................................................ 41

Configuration ...................................................................................... ............. 41

Starting the Cluster ..................................................... ...................................... 42

13. Management Console ................................................ ................................................... 43

........................ ............................ .......................................................................... 43

GUI Functionality ............................................................................... ...................... 43

Create Account ............ .................................... ................................................. 43

Devices ..................... ................................................... ................................... 43

Administrators .................................................................................................. 43

Push Setup ................. ................................................. .................................... 43


5/47

1

Chapter 1. Introduction toOpenMobster - Mobile Backend as a

Service Platformopenmobster at gmail.com

OpenMobster is an Open Source Mobile Backend Platform for mobilizing/integrating Enterprise services

with Mobile Apps

It provides the following features:

Enterprise Data Sync

Cloud data is made available to an App's local storage. It is available via a simple API. This allows the App

to function seamlessly in both online as well as offline modes. The data is automatically synchronized withthe Cloud service based on local state changes. These state changes are auto detected and synchronized

with the Cloud. It does not require any special device-side sync-related programming on the part of the

developer.

Real-Time Push Notifications

Changes on the Cloud are automatically pushed to the Apps in real time. The Push mechanism uses pure

network/socket based approach instead of clunky methodologies like sending sms alerts or email alerts.

The Push notifications happen inside the App's execution environment. Push notifications are sent via a

simple API. It does not require the developer to learn any low-level platform specific services.

Mobile RPC (Remote Procedure Call)Provides a simple way of exposing your server-side coarse grained business services. These services are

invoked via a simple RPC mechanism without any low-level programming like http-client code, client

side REST library, etc on the part of the App developer. There is a simple RPC API that is used for making

these calls.

Management Console

A Management Console is provided to administrate the Cloud Server. It provides security, and account

provisioning features. Over time the console will carry device management features like remote wipe,

remote tracking, remote lock-down, etc.


6/47

2

Chapter 2. Programming Conceptsopenmobster at gmail.com

Cloud ServerA Cloud Server is the server-side component of the infrastructure that is located in the 'Cloud'. The

system provides mobile-oriented features like data synchronization, real-time push, and mobile rpc. From

an architecture standpoint it sits between the mobile device and the actual cloud data services being

mobilized. The Cloud Server provides a Java based Developer API to expose your data services. Here are

its programming concepts:

Channel

A Channel serves as a gateway for integrating on-device model/data objects with the server-side backend

storage systems such as relational databases, content repositories, or Enterprise systems like CRMs, ERPs

etc. It provides a simple CRUD (Create, Read, Update, and Delete) interface to expose the backend data.The Channel is specifically designed such that the Developer does not have to worry about any low-level

state management, synchronization, or other mobile-oriented issues. The idea is to keep a Channel a purely

data-oriented component .

MobileServiceBean

A MobileServiceBean exposes some coarse grained business process to the on-device Mobile App.

It provides a very simple request/response based synchronous invocation mechanism. It frees up the

developer from all low-level (Remote Procedure Call) concerns like making network connections, security,

marshalling/unmarshalling payloads etc.

Note: This component is quite simple at the time of the milestone M1 release. Eventually it will providemore robust REST-based functionality. In any case, the Developer will still be shielded from the low-level

programming details regardless of what higher-level services will be supported.

Mobile App Frameworks

Mobile Data Framework

The Mobile Data Framework provides Cloud data-oriented services like data synchronization, real-time

push notifications, and simple RPC (Remote Procedure Call) mechanism.

MobileBean

MobileBean is a managed Mobile Component which carries the state of the domain object that it represents

on the Cloud. It is propagated from the Cloud Server to the mobile device via its corresponding "Channel"

on the server. The Mobile Data Framework shields the App developer from state management issues like,

offline access, receiving push notifications related to state changes on the server, synchronizing locally

modified beans back with the server, sync concepts like two-way sync, one-way sync etc. The native

runtime smartly tracks the changes to the local state of the MobileBean and decides which type of sync

is needed.


7/47


8/47

4

Chapter 3. Architectureopenmobster at gmail.com

OpenMobster Architecture


9/47

Architecture

5

Device SDK Stack

This is a software stack that is installed on the mobile device. It provides the following services to Mobile

Apps: Sync, Push, OfflineApp, Mobile RPC , Network , Local Storage.

Sync

Sync service auto-synchronizes all state changes to App/Moblet Data back with the Cloud Server. It

supports various synchronization modes such as two way sync, one way server sync, one way device sync,

slow sync, and boot sync.

Push

Push service manages state updates being sent as notifications from the Cloud Server. This improves the

mobile user's experience as they do not have to pro-actively check for new information. When relevant

information becomes available on the server, the user is automatically notified via system notifications like

a beep, vibration, etc. Clarification: The Push service is a real time comet based service. The notificationsare received within the context of the App and not as SMS alerts or some other non-intuitive experience.

The experience is just like the Blackberry email experience. The Cloud Server does not require any special

infrastructure like the Blackberry Enterprise Server to make this happen.

OfflineApp

OfflineApp service provided is designed to be an App Developer's best friend. Its carries the management

capabilities to create smart coordination between low-level services like Sync and Push. Because of the


10/47

Architecture

6

OfflineApp service, the programmer never has to write any code to actually perform any synchronization.

Synchronization is something that is managed by the OfflineApp service and it decides which mode of

synchronization is the best for the current runtime state of the App. The App developer is never exposed

to low level synchronization details like two way sync, one way device sync, etc. It coordinates managing

the Push service. It carries the smartness to track the type of data being pushed along with which installed

App on the device needs the notification. The App developer does not have to write any special code to

receive notifications. The moment the data channel for the App is established, all synchronizations andpush notifications are automatically handled by the OfflineApp service.

Mobile RPC

Mobile RPC facilitates making synchronous RPC (Remote Procedure Call) invocations from the device

to the server side 'MobileServiceBean' components.

Network Network service manages establishing a network connection with the Cloud Server. It manages the

communication channel needed to receive Push notifications from the server. It carries the smartness to

track coverage and establishes proper connections automatically. This is a very low-level service and an

App developer never has to deal with using it directly. The App developer is shielded from any low level

connection establishment, security, protocol details, etc by using the higher level Mobile Data Framework

components.

Local Storage Local Storage service manages local data storage details for Apps. Depending on the platform in question

it uses the corresponding storage facilities. It is designed to coordinate storage among the suite of Apps/

Moblets installed on the device. It provides thread-safe concurrent access to the Apps. Just like the Network

service, its a low-level service used by the Mobile Data Framework components.


11/47

Architecture

7

Cloud Server Stack

This is a software stack that is installed on the server-side. It provides the following services to Mobile

Apps: Sync, Push, Secure Socket-Based Data Service, Mobile RPC , Security, Management Console

Sync

Sync service synchronizes device side App state changes with the backend services where the data actually

originates. It provides a plugin framework to mobilize the backend data. It uses the concept of a data

"Channel" which mobilizes the data in the form of "MobileBean" instances.

Push

Push service monitors data "Channels" for updates. The moment updates are detected, corresponding

Comet-based notifications are sent back to the device. If the device is out of coverage or disconnected for

some reason, it waits in a queue, and delivers the push the moment the device connects back to the network.Clarification: The push service does not depend on any special infrastructure like a Blackberry Enterprise

Server to achieve its functionality. Its a pure Comet-based approach via a socket channel with the device.

Secure Socket-Based Data Service

Secure Socket-Based Data Service is a high performance socket server based on Java NIO. The service

uses the Apache MINA [http://mina.apache.org/] network application framework. It provides both, a plain

socket server , and a SSL-based socket server, depending on the security requirements of the Apps.

http://mina.apache.org/http://mina.apache.org/


12/47

Architecture

8

Mobile RPC

Mobile RPC service on the server-side provides a Remote Procedure Call framework for invoking coarse

grained business services of an App. The components are plugged in as MobileService Beans and the

device-side Mobile RPC service invokes them via a simple synchronous request/response based approach.

Security

Security component provides authentication and authorization services to make sure mobile devices

connecting to the Cloud Server are in fact allowed to access the system. Every device must be first securely

provisioned with the system before it can be used. After the device is registered, it is challenged for proper

credentials when the device itself needs to be activated. Once the device is activated, all Cloud requests

are properly authenticated/authorized going forward.

Management Console

Every instance of a Cloud Server ships with a Command Line application called the Management Console.

The console provides user and device provisioning functionalities. In the future, this same component will

have more device management features like remote data wipe, remote locking, remote tracking, etc.


13/47


14/47

Get Started: CRUD App in Action

10

Install CRUD App on 2 devices

• Step 1: Locate the CRUD App in the OpenMobster distribution under: Samples/CRUD.apk

• Step 2: Install the CRUD App on the device connected to your computer using: adb install -r CRUD.apk

• Step 3: Repeat Step 2 on the other device as well

App Activation

For security purposes, every OpenMobster based App must be first activated successfully with the Cloud

Server. When the CRUD App is started on each device, it brings up the App Activation Dialog. You must

provide the following information:

• Server: The IP or Domain name of the Cloud Server

• Port: Port of the Cloud Server. [Default: 1502]

• Email: The email address you want to associate to uniquely identify you with the system

• Password: A password to be used for authentication with the system

In case of two devices, you will do an activation on both devices. You can use the same email address

on both devices, or you can input a different email address for each device. Either way, your data will be

replicated across both devices.

CRUD App Features

Here is a list of what to expect from the CRUD App functionality

• Enteprise Data Sync: On the Cloud Side, data stored in a HSQDLB database is mobilized and synced

with the App. All the CRUD (Create/Read/Update/Delete) operations on the App data is synced back to the Cloud database.

• Enteprise Data Push: In case of multi-device access, data changes made on one device are

automatically and silently pushed to other devices.

• Offline Workflow Support: The App Data is fully available even when a network connection is

not available between the device and the Cloud Server. All the CRUD (Create/Read/Update/Delete)

functions are available when the device is offline. In case, the device is disconnected, the Sync Engine

queues all data changes to be synchronized back with the Cloud database as soon as a network connection

is established with the Cloud Server.

CRUD App Help• The data was pushed from one device to another, but the new data is not showing up? This is a

screen refresh issue. The App does not refresh the screen automatically to keep the coding simple to

follow. You can refresh your screen manually from the Option in the App Menu.

• How do I 'Create' a new ticket? The "New Ticket" option is available in the App Menu.

• How do I 'Update' a ticket? The "Update" option is available when you click the ticket to be updated

in the list


15/47

Get Started: CRUD App in Action

11

• How do I 'Delete' a ticket? The "Delete" option is available when you click the ticket to be deleted

from the list


16/47

12

Chapter 5. Show me the Codeopenmobster at gmail.com

A native Mobile App runs within the constraints of its local runtime. A major advantage of this environmentis access to local storage for data associated with the App. If logic is the nervous system of an App, data

is its life blood. Without the data, an App is lifeless. Local Storage brings an App to life instantaneously.

The closer this data is stored, the faster and better is the performance of the App.

A typical Mobile App has the following data-oriented requirements

• Data originates in the Cloud.

• App related data is synchronized from the Cloud with the local storage over a network connection.

• Any data state changes (add/update/delete) via the App are synchronized with the Cloud.

• Any data state changes (add/update/delete) on the Cloud are pushed/synchronized with the device.

• This data is available to the mobile App even in the event the Cloud is unavailable.

The OpenMobster Cloud Platform uses a "Channel" component on the Cloud-side and a MobileBean

component on the Device-side to provide the above mentioned offline capabilities to an App

Tutorial

Cloud-Side: Channel Development

A Channel serves as a gateway for integrating on-device model/data objects with the server-side backend

storage systems such as relational databases, content repositories, or Enterprise systems like CRMs, ERPsetc. It provides a simple CRUD (Create, Read, Update, and Delete) interface to expose the backend data.

The Channel is specifically designed such that the Developer does not have to worry about any low-level

state management, and synchronization issues.

Step 1:

Define a simple MobileBean to represent a data entity being mobilized. This MobileBean should adhere

to the MobileBean specification covered here: Specification

import java.io.Serializable;

import org.openmobster.cloud.api.sync.MobileBean;

import org.openmobster.cloud.api.sync.MobileBeanId;

/**

* A 'Ticket' instance represents tickets entered into the CRM db managed by

*

* It is also marked as a 'MobileBean' instance so that it can be managed by

*

* @author [email protected]


17/47

Show me the Code

13

*/

public class Ticket implements MobileBean,Serializable

{

private static final long serialVersionUID = -13825574505549274L;

private long id; //oid

@MobileBeanId

private String ticketId; //uniquely identifies the ticket to the mobile eng

private String title;

private String comment;

private String customer;

private String specialist;

public Ticket()

{

}

public long getId()

{

return id;

}

public void setId(long id)

{

this.id = id;

}

public String getTicketId()

{

return ticketId;

}

public void setTicketId(String ticketId)

{

this.ticketId = ticketId;

}

public String getTitle()

{

return title;

}

public void setTitle(String title)

{

this.title = title;

}

public String getComment()

{

return comment;

}


18/47

Show me the Code

14

public void setComment(String comment)

{

this.comment = comment;

}

public String getCustomer() {

return customer;

}

public void setCustomer(String customer)

{

this.customer = customer;

}

public String getSpecialist()

{

return specialist;

}

public void setSpecialist(String specialist)

{

this.specialist = specialist;

}

}

Step 2:

Provide a Channel implementation that exposes this MobileBean via a CRUD interface.

@ChannelInfo(uri="crm_ticket_channel", mobileBeanClass="org.crud.cloud.crm.T

public class TicketChannel implements Channel

bootup

This method provides a subset of the "MobileBean" instances associated with the said device. They provide

just enough information for an App to be functional. This helps with avoiding very long synchronization

sessions. The other beans are loaded on-demand from there on

public List


19/47

Show me the Code

15

{

bootup.add(all.get(0));

}

return bootup;

}

readAll

This method provides all the "MobileBean" instances associated with the said device.

/**

* Reads all the instances stored in the db

*/

public List


20/47

Show me the Code

16

String syncid=this.ds.create(local);

//Signal to the NewBeanDetector that a new ticket was added to the system,

//this will push this ticket to other devices

newTicketDetector.addSyncId(device,syncid);

return syncid;}

update

Synchronizes the updated state of a bean from the device with the state on the Cloud.

/**

* Synchronizes device side update with the backend db

*/

public void update(MobileBean mobileBean)

{ Ticket local = (Ticket)mobileBean;

Ticket stored = this.ds.readByTicketId(local.getTicketId());

local.setId(stored.getId());

this.ds.update(local);

}

delete

Deletes a bean instance that is user confirmed to be deleted from the device.

/**

* Deletes any instances that are deleted on the device side

*/

public void delete(MobileBean mobileBean)

{

Ticket local = (Ticket)mobileBean;

this.ds.delete(local);

}

scanForNew

Scans the backend database looking for new entries added to the system. If new instances are found, the

new data is pushed down to the respective devices immediately. This makes sure the data on the devices

is always current with respect to the backend

/**

* 'Pushes' any new instances that are created in the db down to the device

*/

public String[] scanForNew(Device device, Date lastScanTimestamp)


21/47

Show me the Code

17

{

Set newBeans = newTicketDetector.scan(device);

if(newBeans != null && !newBeans.isEmpty())

{

return newBeans.toArray(new String[0]);

}

return null;}

Step 3:

Provide the META-INF/openmobster-config.xml that will deploy the "Channel" into the Cloud Server.

/crm/bootstrap/data


22/47

Show me the Code

18

Step 4:

Package the the above classes and the corresponding META-INF/openmobster-config.xml into a simple

jar file.

Step 5:

Deploy this jar file into the "deploy" directory of your JBoss AS instance

Putting it all together

The end-to-end Channel Example is located in the binary distribution at: Samples/crud/cloud

App/Device-Side Programming

On the device side, you build your App on top of the OpenMobster Device SDK. The SDK provides the

runtime engine and an API to integrate with the mobilized data and services. This tutorial will cover the

various steps needed to integrate with the Device SDK.

Step 1: Bootstrap the SDK runtime and services

@Override

protected void onStart()

{

super.onStart();

//Bootstrap the OpenMobster Service in the main activity of your App

CloudService.getInstance().start(this);

}

Before you can use the services in the OpenMobster SDK, you must bootstrap the service. You must

bootstrap the OpenMobster SDK in the onStart method of your App's Main Activity.

Step 2: Perform Activation with the Cloud Server

@Override

protected void onResume()

{

super.onResume();

//Check to make sure the App is activated with the OpenMobster Backend

boolean isDeviceActivated = CloudService.getInstance().isDeviceActivated();

if(!isDeviceActivated)

{

this.startDeviceActivation();

return;

}

this.showTicket();

}


23/47

Show me the Code

19

Once the SDK is bootstrapped, you must make sure the App is activated with the Cloud Server. For security

reasons, only Apps activated with the Cloud Server are allowed to access the Cloud Data Services. Hence,

in your onResume of the Main Activity, you must perform App Activation process if the App has not

been activated with the Cloud Server.

Step 3: Start accessing the mobilized data

public void showTicket()

{

//Read all the CRM Ticket instances synced locally with the device

if(MobileBean.isBooted("crm_ticket_channel"))

{

activeBeans = MobileBean.readAll("crm_ticket_channel");

ArrayList mylist = new ArrayList 25)

{

customer = customer.substring(0, 22)+"...";

}

if(title.length() > 25)

{

title = title.substring(0, 22)+"...";

}

map.put("customer", customer);

map.put("title", title);

mylist.add(map);

}

}

SimpleAdapter ticketAdapter = new SimpleAdapter(HomeScreen.this, mylist,R.

listView.setAdapter(ticketAdapter);

listView.setOnItemClickListener(new MyItemClickListener(activeBeans));

}

else

{

//Tickets not found...put up a Sync in progress message and wait for data

//from the Backend

if(!HomeScreen.syncInProgress && !HomeScreen.syncComplete)

{

HomeScreen.syncInProgress = true;

SyncInProgressAsyncTask task = new SyncInProgressAsyncTask();


24/47

Show me the Code

20

task.execute();

}

}

}

On the device side, the mobilized data is accessible via the

org.openmobster.android.api.sync.MobileBean component. The device-side MobileBean is a generic

component which exposes a Cloud-side MobileBean information through a robust interface. Device-side

MobileBean component semantic are covered here:Specification

readAll: Returns all MobileBean instances associated with a channel. Chances are some of the instances

are only proxies that will be loaded seamlessly when they are really needed on-demand . This process

happens behind the scenes and there is nothing special a programmer needs to do.

getValue: Reads the value associated with a field/property of an instance of a bean. A property expression

is provided to access this information.

Step 4: Save a MobileBean instance to be synchronized with the

Cloud

@Override

protected Void doInBackground(Void... arg0)

{

message = handler.obtainMessage();

try{

mobileBean.save();

message.what = 1;

}catch(Exception ex){

}

return null;}

You can modify/add to your local store of MobileBean instances using the save method. This is a local

operation and is permitted even when the device is offline without any network coverage. This method

integrates with the low-level Sync Engine and makes sure instances are synchronized with the Cloud

whenever a network connection is active.

Step 5: Delete a MobileBean instance to be synchronized with theCloud

@Override

protected Void doInBackground(Void... arg0)

{

message = handler.obtainMessage();

try{

mobileBean.delete();

message.what = 1;

}catch(Exception ex){


25/47

Show me the Code

21

}

return null;

}

You can delete MobileBean instances from your local store using the delete method. This is a local

operation and is permitted even when the device is offline without any network coverage. This method

integrates with the low-level Sync Engine and makes sure instances are synchronized with the Cloud

whenever a network connection is active.

Step 5: Proper configuration in AndroidManifest.xml


26/47

Show me the Code

22


27/47

Show me the Code

23

Putting it all together

The end-to-end Sample App is located in the binary distribution at: Samples/crud/app-android


28/47

24

Chapter 6. AppCreatoropenmobster at gmail.com

Start writing your own AppDownload an OpenMobster distribution from here: Downloads [http://code.google.com/p/openmobster/

downloads/list] .

In your distribution, go to the directory AppCreator. Inside the directory, use a tool called the

'appcreator.bat' (Windows), 'appcreator.sh' (Linux and Mac) to generate a skeleton project

appcreator.bat

This will generate a skeleton for the Mobile App. Each generated project has the following modules:

• cloud: Contains the src for the Cloud-side components. Java code is located under src/main/java, and

configuration is located under src/main/resources.

• app-android: Contains the src for the Android App. Java code is located under src, Configuration is

located under src/openmobster-app.xml. Besides the OpenMobster component setup, the Android SDK

specific setup is located under AndroidManifest.xml. This is an Eclipse project and can be smoothly

imported into your Eclipse Workspace.

app-android

• Step 1: Import the Android Project stored under "app-android" into your Eclipse workspace. Make sure

you select, Import > Existing Android Code into Workspace. Rest of the instructions should be self-

explanatory

• Step 2: Run As Android Application from Eclipse. This will compile and install the Android App on

the connected device or simulator.

cloud

On the Cloud-side of things, there is a fully functional Standalone "Development Mode" Cloud Server

provided that you can run right inside your Maven environment. Here are some of the Maven commands

that are used during development

• Build All including testsuite execution

mvn clean install

• Command to run the standalone "Development Mode" Cloud Server

mvn -PrunCloud integration-test

http://code.google.com/p/openmobster/downloads/listhttp://code.google.com/p/openmobster/downloads/listhttp://code.google.com/p/openmobster/downloads/listhttp://code.google.com/p/openmobster/downloads/list


29/47

AppCreator

25

• Command to run the standalone "Development Mode" Cloud Server in *debug mode*

mvn -PdebugCloud integration-test

Eclipse Project Setup

• Import the Cloud project stored under "cloud" into your Eclipse workspace. Make sure you select,

Import > Maven > Existing Maven Projects

• In case, you do not have the Eclipse Maven Plugin installed, you can open the "cloud" project as a regular

Java Project. But, before you do that, you execute the following command from the commandline:

mvn eclipse:eclipse

JBoss AS DeploymentOnce your "cloud" jar file is tested end-to-end in the Maven based Cloud Server, you must deploy the jar

file into a JBoss 5.1.0.GA App Server. The deployment is quite simple. You just copy the "cloud" jar file

from the "cloud/target" folder into the JBOSS_HOME/server/openmobster/deploy" folder.


30/47

26

Chapter 7. MobileBeanopenmobster at gmail.com

MobileBeanMobileBean is a managed Mobile Component which carries the state of the domain object that it represents

on the server. It is propagated from the Cloud Server to the mobile device via its corresponding Channel

on the server. The Mobile Data Framework shields the App developer from state management issues like,

offline access, receiving push notifications related to state changes on the server, synchronizing locally

modified beans back with the server, etc.

The concept of a MobileBean applies to both sides of the world, Cloud-Side as well as Device-Side.

Cloud-SideOn the Cloud-Side the MobileBean is a simple Java Object that implements the

org.openmobster.cloud.api.sync.MobileBean interface. The MobileBean is processed byits corresponding Channel. Through the channel instances of these beans are serialized into wire format

and propagated to their respective devices. In order to be successfully serialized/deserialized, they should

follow the proper specification.

Specification

• The system successfully processes the following properties of a bean: Simple Property, Nested Property,

One-Dimensional Array property, and Parameterized java.util.List properties of Concrete

Types.

• Array PropertiesMUST NOT contain Null elements.

• MUST contain an empty constructor

• MUST contain provide public get and set methods for each one of its properties

Device-SideOn the Device-Side the MobileBeans from a channel are made accessible via the Mobile Data Framework .

The genericorg.openmobster.android.api.sync.MobileBean component is used to extract

the state associated with each instance. It provides various state-oriented operations. The individual

properties of a bean are accessed using simple and intuitive expressions.

Accessing a Simple Property

For a simple property myName on a bean, the following expression is used:

MobileBean.getValue("myName");

Accessing a Nested Property

For a nested property myAddress.myStreet on a bean, the following expression is used:


31/47

MobileBean

27

MobileBean.getValue("myAddress.myStreet");

Accessing an Indexed Property (One-Dimensional Array

or a java.util.List)For an indexed property "myName" on the "third element" of an Array or List named "users" on

a bean, the following expression is used:

MobileBean.getValue("users[2].myName");

Iterating through an Indexed Property (One-DimensionalArray or a java.util.List)

private void iterateEmails(MobileBean mobileBean)

{

BeanList emails = mobileBean.readList("emails");

for(int index=0; index


32/47

28

Chapter 8. Push Programmingopenmobster at gmail.com

Sending a Push NotificationYou can send a push notification from the cloud using the Push API. This API is located on the

org.openmobster.cloud.api.push.PushService object. On this object you use the following method

/**

* A device agnostic Push method. Push is associated with the user a

*

* @param identity user that must receive this message

* @param appId unique application id this push is associated with

* @param message message to be sent

* @param title title of the message * @param details any other details associated with the message

*/

public void push(String identity, String appId, String message, Stri

Push Setup on an Android App

You can setup Push Notification support in your app via two configuration files. Before we go into those

details you must understand that there are two types of push notifications. User Initiated Push notification

using the PushService API, and Sync Initiated Push Notification which is generated by the Sync Engine.

Configuration:AndroidManifest.xml


33/47


34/47

Push Programming

30

// Add the view controller's view to the window and display.

[self.window addSubview:viewController.view];

[self.window makeKeyAndVisible];

//Bootstrap the Cloud services

[self startCloudService];

//This registers the App for Push Notifications

[[UIApplication sharedApplication]

registerForRemoteNotificationTypes:

(UIRemoteNotificationTypeAlert |

UIRemoteNotificationTypeBadge |

UIRemoteNotificationTypeSound)];

return YES;

}

If the registation is successful a callback is invoked on the delegate. It goes as follows:

- (void)application:(UIApplication *)app didRegisterForRemoteNoti

{

NSString *deviceTokenStr = [NSString stringWithFormat:@"%@",device

deviceTokenStr = [StringUtil replaceAll:deviceTokenStr :@"" :@""]

NSLog(@"DeviceToken: %@",deviceTokenStr);

@try

{

SubmitDeviceToken *submit = [SubmitDeviceToken withInit];

[submit submit:deviceTokenStr];

}

@catch (SystemException * syse)

{

UIAlertView *dialog = [[UIAlertView alloc]

initWithTitle:@

message:@"Devic

delegate:nil

cancelButtonTit

dialog = [dialog autorelease];

[dialog show];

}

}

These two operations registers the Application for Push notifications both on the device and on the

OpenMobster? Push Service.


35/47

Push Programming

31

• Step 2: Upload the certificate .p12 file

• Login to the Management Console: http://cloud-server-address/console

• Select Push Setup

• Find the App associated with this certificate

• Upload the certificate and supply its password

• If successfull, the icon next to the App will turn green

• Step 3: Send a Test Push

• Click on the App

• Click the 'Test Push' button

• Select the 'Device' where it should be sent

• You should receive a Push alert on your phone


36/47

32

Chapter 9. iOS + OpenMobsterintegration


Introduction

As of version 2.2-M1, iOS is fully supported by OpenMobster. Here are some tips related to iOS and

OpenMobster integration

Prepare the mobilecloudlib static library

• Open the mobilecloudlib XCode project by opening: iPhone/mobilecloudlib/

mobilecloudlib.xcodeproj

• Build the project in XCode

For some reason, building the mobilecloudlib fail to compile if your XCode code location is set to the

recommended setting of "Derived Data". You must change this option to "Location Specified By Targets".

Please take a look at this thread for details: https://groups.google.com/forum/#!searchin/openmobster-

users/mobilecloudlib/openmobster-users/zJhJKbFekLs/WiNWtKfG_RcJ

Start a View-based App

• Go to File>New Project. In the displayed project templates select the View-based Application and

follow the wizard

Create a Group called OpenMobster

• Create a New group named OpenMobster

• From the mobilecloudlibproject, DragnDrop/Copy all the resources located under the app-bundle

group

Add the libraries and Frameworks

In the Frameworks group add the following library and Frameworks

• libmobilecloudlib.a - OpenMobster static library

• CoreData.framework

• CFNetwork.framework

• CoreGraphics.framework

• UIKit.framework

https://groups.google.com/forum/#!searchin/openmobster-users/mobilecloudlib/openmobster-users/zJhJKbFekLs/WiNWtKfG_RcJhttps://groups.google.com/forum/#!searchin/openmobster-users/mobilecloudlib/openmobster-users/zJhJKbFekLs/WiNWtKfG_RcJ


37/47

iOS + OpenMobster integration

33

Add OpenMobster bootstrap code

Before OpenMobster runtime can be used within an App. It must be bootstrapped and started. The

following code shows how this bootstrapping process works.

The bootstrapping functionsStart Cloud Service

-(void)startCloudService

{

@try

{

CloudService *cloudService = [CloudService getInstance];

[cloudService startup];

} @catch (NSException * e)

{

//something caused the kernel to crash

//stop the kernel

[self stopCloudService];

}

}

Stop Cloud Service

-(void)stopCloudService

{

@try

{


[cloudService shutdown];

}

@catch (NSException *e)

{

}

}

Start Device Activation if it is not activated with the Cloud already

-(void)startActivation


38/47


34

{

@try

{


[cloudService forceActivation:self.window.rootViewController];

}

@catch (NSException * e){

//something caused the kernel to crash

//stop the kernel


}

}

Do a Sync at Startup

-(void)sync

{

CommandContext *commandContext = [CommandContext withInit:self.viewContr

BackgroundSyncCommand *syncCommand = [BackgroundSyncCommand withInit];

[commandContext setTarget:syncCommand];

CommandService *service = [CommandService getInstance];

[service execute:commandContext];

}

Integrating the bootstrapping function with the AppDelegate

- (BOOL) application:(UIApplication*)applicationdidFinishLaunchingWithOptions:(NSDictionary*)launchOptions

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptio

{

//OpenMobster bootstrapping

[self startCloudService];

[self sync];

self.window = [[[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bo

// Override point for customization after application launch.

if ([[UIDevice currentDevice] userInterfaceIdiom] == UIUserInterfaceIdio

{

self.viewController = [[[ViewController alloc] initWithNibName:@"Vie


39/47


35

}

else

{

self.viewController = [[[ViewController alloc] initWithNibName:@"Vie

}

//setup the NavigationController self.navigationController = [[UINavigationController alloc] initWithRoot

//Add the CloudManager button to the navbar

UIBarButtonItem *button = [[UIBarButtonItem alloc] initWithTitle:@"Cloud Ma

self.navigationController.topViewController.navigationItem.leftBarButtonIte

[button release];

//Add the Create button to the nav bar

UIBarButtonItem *create = [[UIBarButtonItem alloc] initWithTitle:@"Creat

self.navigationController.topViewController.navigationItem.rightBarButtonIt

[create release];

self.window.rootViewController = self.navigationController;

[self.window makeKeyAndVisible];


[self startActivation];

//Register the App for Push notifications





UIRemoteNotificationTypeSound)];

return YES;

}

-(void)applicationWillEnterForeground:(UIApplication *)application

- (void)applicationWillEnterForeground:(UIApplication *)application

{

/*

Called as part of the transition from the background to the inactive st

*/


[self sync];


40/47


36

if(!self.pushRegistered)

{





UIRemoteNotificationTypeSound)]; }

}

-(void)applicationWillTerminate:(UIApplication *)application

- (void)applicationWillTerminate:(UIApplication *)application

{

/* Called when the application is about to terminate.

Save data if appropriate.

See also applicationDidEnterBackground:.

*/



}

Integrating the CloudManager

As an App Developer you can integrate the CloudManager functionality within your App. The

CloudManager is an administrative GUI tool that allows some provisioning functions. You can activate

your device with the Cloud and you can manage the Sync Channels used by your App. This can come in

handy when you want to do some Manual Syncing in case there are issues happening with the automatic

Sync process.

This GUI layer integration is done by activating the Modal,View,Controller CloudManager component.

Here are the integration steps

Integrate the CloudManager button on the View

//setup the NavigationController

self.navigationController = [[UINavigationController alloc] initWithRootView

//Add the CloudManager button to the navbar

UIBarButtonItem *button = [[UIBarButtonItem alloc] initWithTitle:@"Cloud Man

self.navigationController.topViewController.navigationItem.leftBarButtonItem

[button release];


41/47


37

Implement the action behind the button

-(IBAction)launchCloudManager:(id)sender

{

//Launch the CloudManager App

[CloudManager modalCloudManager:self];

}

Sample App

In the OpenMobster distribution, you can find an iOS/OpenMobster Sync App under iphone/SampleApp.

On the Cloud Side, the App to run is located under iphone/showcase/cloud. You run the Cloud Serverusing the command



42/47

38

Chapter 10. iOS + OpenMobsterSample App


Introduction

This chapter covers the steps involved in running the iOS + OpenMobster based Sample App

Prepare the mobilecloudlib static library

• Open the mobilecloudlib XCode project by opening: iPhone/mobilecloudlib/

mobilecloudlib.xcodeproj

• Build the project in XCode

For some reason, building the mobilecloudlib fail to compile if your XCode code location is set to the

recommended setting of "Derived Data". You must change this option to "Location Specified By Targets".

Please take a look at this thread for details: https://groups.google.com/forum/#!searchin/openmobster-

users/mobilecloudlib/openmobster-users/zJhJKbFekLs/WiNWtKfG_RcJ

Run the Cloud Server

Go to iphone/showcase/cloud. Under this directory issue the following command to start the Cloud Server

required by the sample app


Run the SampleApp

Open the XCode project located under iphone/SampleApp. Build the project to make sure there are no

errors. Once the Build is successful, Run the project. If this is the first time running the App, it will present

a device activation screen. This is to securely setup your Cloud account so that you can acess the Enterprise

resources in the Cloud. It asks the following information

Cloud IP: The IP address of the Cloud Server

Port: The port that the Cloud Server is running on (1502, by default)

Email Address: Your email address to uniquely identify you with the Cl

Password: Your password to authenticate with the Cloud

This is a one time activation across all your apps.

https://groups.google.com/forum/#!searchin/openmobster-users/mobilecloudlib/openmobster-users/zJhJKbFekLs/WiNWtKfG_RcJhttps://groups.google.com/forum/#!searchin/openmobster-users/mobilecloudlib/openmobster-users/zJhJKbFekLs/WiNWtKfG_RcJ


43/47

39

Chapter 11. Mobile RPC (RemoteProcedure Call) Development

openmobster at gmail.com The MobileService component on the Device-side is used to make synchronous remote service invocations

on registered MobileServerBean instances on the Cloud Server.

At this time, this is a very simple request/response based system whose main design goal is to shield the

App developer from any low level details like making network connections, security, resolving remote

services, marshalling/unmarshalling payload, protocol details, etc.

The next iteration of this component will involve introducing more robust features based on a REST-based

architecture.

Cloud-Side: MobileServiceBeanimplementation

MobileServiceBean is a simple interface

org.openmobster.cloud.api.rpc.MobileServiceBean with a single "invoke" method.

This implementation should carry coarse grained business process logic.

@ServiceInfo(uri="/demo/mobile-rpc")

public class DemoMobileBeanService implements MobileServiceBean

{

private static Logger log = Logger.getLogger(DemoMobileBeanService.class);

public DemoMobileBeanService()

{

}

public Response invoke(Request request)

{

log.info("-------------------------------------------------");

log.info(this.getClass().getName()+" successfully invoked...");

Response response = new Response();

String[] names = request.getNames();

for(String name: names)

{

String value = request.getAttribute(name);

log.info("Name="+name+", Value="+value);

response.setAttribute(name, "response://"+value);

}

log.info("-------------------------------------------------");

return response;

}


44/47

Mobile RPC (Remote

Procedure Call) Development

40

}

Cloud-Side: Configuration

Provide the META-INF/openmobster-config.xml that will deploy the "MobileServiceBean" instance into

the Cloud Server.


45/47

41

Chapter 12. Clusteringopenmobster at gmail.com

Clustering the Cloud ServerYou can setup the OpenMobster Cloud as a highly available Clustered environment.

High Availability

The high availability cluster consists of multiple JBoss nodes of the OpenMobster Cloud Server. Out

of these nodes there is a single node that serves as the Master node. All the incoming traffic is directed to

this Master node. The Master node is not a single point of failure because if the Master node goes down,

one of the other nodes immediately becomes a Master node. This process keeps going till all the nodes are

used up. This is how you can get a highly available cluster running since at any given time there is always

one master node processing requests from the mobile devices.

Load Balancing

At this point in time the Master node processes all the incoming requests. It does not delegate any requests

to its other nodes to balance the load. This feature will be supported in a future release. This is a challenge

because it needs to replicate local state among the cluster members. At this point, the Sync service does

not support this replication except data sharing via the shared database. This is not enough and will require

some re-architecting to make the service truly stateless. From here on out, all new services developed will

support load balancing to get the best out of a clustered setup.

Setup

This will cover the steps for setting up an OpenMobster Cloud in a clustered environment

Configuration

In your JBoss server open the following file: deploy/openmobster.last/clustering-2.4-SNAPSHOT.jar/

META-INF/openmobster-config.xml. Make sure the file looks as the following to activate the node as

a Cluster node


46/47

Clustering

42

Starting the Cluster

To start the cluster you start one node at a time. The first started node starts off as the Master node. The

other nodes remain in standby to become the Master node when/if it goes down. You start the node using

the standard JBoss command:

./run.sh -c {server-name} -b {node-ipaddress}


47/47

Chapter 13. Management Consoleopenmobster at gmail.com

OpenMobster, comes with a GWT/SmartGWT based GUI Management Console. This Console can beused to administrate users, devices, and push services. This tool will evolve over time to include some

management functionality like remote wipe, remote lockdown, etc

GUI Functionality

Create Account

This lets you create an 'Admin' account. This creation has to be approved by another administrator before

you can login.

DevicesThis lets you manage your devices such activation, deactivation, etc. As the software matures it may add

more system level functions like remote wipe, remote lock down, etc.

Activate/De-Activate

Activates or Deactivates the 'Device' account. If de-activated, none of the Cloud services will be available

to the device. They will be available as soon as the account is activated.

Re-assign

De-activates the 'Device' account and makes it available to be assigned to another user. This is so that

when a user leaves, his device can be re-assigned to another user.

Administrators

Used for managing the 'Admin' accounts.

Activate/De-Activate

Activates and De-Activates the 'Admin' account.

Push Setup

This is used to configure the Apple Push Notification service. As part of the system, a security certificate

has to be assigned to an application before messages can be pushed to it. This is where your certificate can

be uploaded and assigned to an App. Once this is successful, you can send a test push to your iPhone.

Documents

App Developer Guide 2.4 M3