- Configure your application
- Create model classes
- Log in to application
- Use database
- Synchronize data
- Push notifications
This document will provide you with detailed documentation about creating Mobeelizer client application on Android platform.
In this document we assumes that you are familiar with:
- JAVA language
- Basics of Android application development (see android developer page)
- Key concepts of Mobeelizer platform (see)
Attach necessary resources
To work with Mobeelizer cloud first you have to download Mobeelizer SDK. Then include downloaded JAR file into your application classpath.
Next, download XML file of your application created in App Designer and put it in your assets directory. If you use default setting then name of this file should be application.xml. You can use other name - but then you have to set MOBEELIZER_DEFINITION_ASSET property (see below)
Modify manifest file
The last thing is to configure manifest file. Open it (or create if you don't have it yet) and add Mobeelizer as your application subclass.
- Add to <application> tag:
- Then add permissions required by Mobeelizer:
Add configuration meta-data:
To make Mobeelizer SDK works properly you have to configure some general parameters. To configure parameter add to your manifest file:
Available parameters are:
There are three possible development modes:
This parameter is required only in 'development' mode - it is ignored on other modes.
Normally while login method system receives role of user. But as you can read above login method is off-line in development mode so you have to provide user role manually - as value of this parameter.
Package of your model classes.
Name of the device category. See this document for more explanation.
Name of the XML file with application definition. Default value is application.xml.
Version of database. Default value is 1. When you increase this number old database is dropped and new one is created.
Create model classes
Last thing to make your application work is to create models. For all the models you have defined in App Center and that are in downloaded XML file you have to create corresponding JAVA class. While creating these classes you have to remember about few things:
Must be the same as defined in MOBEELIZER_PACKAGE parameter.
- Name of class
Should be the same as name of corresponding model - but with first letter capitalized!
- Should be a JavaBean
Created class should comply with JavaBeans Component Design Conventions.
- Special fields
Every model class must have guid identifier and can have some optional special fields:
Main object identifier
Information about owner of object
This field will be true if record was modified by user - but not synchronized yet.
This field will be true if object is conflicted. See here to read more about conflicts.
To delete entity set this field to true.
Remember about getter and setter methods!
- Model fields
Beside special fields you have to add class fields for every defined in App Designer model field. Name of these field must be the same as name of model fields - but with lowercased first letter.
Type of fields must be one of listed below:
|Model type||Available class field types|
|date||Date, Calendar, Long, long|
|decimal||Double, double, Float, float, BigDecimal|
|integer||Integer, int, Short, short, Byte, byte, Long, long, BigInteger|
Log in to application
Before using any of Mobeelizer features you have to make user log in to your cloud application. Any activity - like accessing database - before login will have effect in throwing an exception!
You can do that by calling one of login static methods from Mobeelizer object. There are four version of this method:
- synchronous, with default environment name (see doc)
- asynchronous, with default environment name (see doc)
- synchronous, with environment name (see doc)
- asynchronous, with environment name (see doc)
You have to remember, that when you log in any user for the first time your client application must be on-line (except 'development' mode.) Also first login can take long time to perform - because of initial synchronization processes that are automatically triggered after login verification. So better supply user with nice looking loading indicator. And remember - DO NOT call synchronous methods in main thread - you application will freeze and will be killed by operating system after some time (see this document for more details).
Also you may wonder what is the environment name. Firstly see this document to read about environments. As you can read there, when you create an app, then two environments are created - one for test and one for production purpose. They are named accordingly "test" and "production". When you want to connect to these instances use default environment name method. But if you want to connect with environment manually created - you have to provide its name.
To change user you should use logout method. Remember to finish all background processes before calling it - logging out while synchronization process can effect with unpredictable connector behavior!
Obtaining database object
Database can be accessed using object MobeelizerDatabase which can be obtained by calling method
MobeelizerDatabase object allows you to easily perform basic database operations. Let say you have model 'Product' defined in Product.class.
Then you can write:
For more information see javadoc documentation.
To define relation you have to add 'belongs to' type field to model. Lets say you have models Order and OrderPosition. To connect these objects with relation you have to add 'belongs to' field to OrderPosition - let's name it Order.
As you can read above 'belongs to' type has to be mapped as String field. This field will contain identifier of related object. So you can write:
All binary data are wrapped inside MobeelizerFile object. Lets assume that you have OrderWithAttachment object. And it have attachment field of file type. Then you can access content of file by coding:
To create new MobeelizerFile instance you can:
Remember about changing order file field:
Advanced database queries
Advanced queries can be accessed by MobeelizerCriteriaBuilder class.To get criteria object just call method:
Next define your query (see below). After that you can:
While creating query you can:
- Limit result objects number:
- Set the first result:
- Add order
- Add restrictions
For more informations about restrictions see MobeelizerResrictions javadoc.
You can also combine many elements to create more complicated queries:
For more information see MobeelizerCriteriaBuilder javadoc.
Synchronizing data with cloud cannot be easier! Just call one of sync methods on Mobeelizer object.
Synchronization process can take long time, so if you want to block application on this time - better supply user with nice-looking loading indicator.
And remember - DO NOT call synchronous method in main thread - you application will freeze and will be killed by operating system after some time.
Full synchronization is a process which removes all data and downloads all data from cloud. It is triggered automatically when user logs in for the first time - but you can call it manually. Just call syncAll method (or asynchronous version).
You should block all user actions for this process (database will be erased). And once again remember not to call synchronous method in main thread.
In full synchronization process user-modified data is not send to cloud, so all not synchronized data (with modified flag) will be lost! To prevent this perform normal synchronization before.
You can register listener for all notifications about sync status changes. To do it create and configure BroadcastReceiver. Then register it for sync event:
In your BroadcastReceiver onReceive method you can write:
See MobeelizerSyncStatus javadoc for more information about available statuses.
To learn about Push notification see Push notifications key concept page.
Push notifications on Android devices are provided Google Cloud Messaging (GCM). Basic knowledge of it's mechanisms are necessary to understand following reference documentation.
- Register Google account
To send push notifications to Android devices you must configure Google account for Android Cloud to Device Messaging. Just follow below getting started tutorial to obtain API key.
- Configure application in App Designer
In App Designer in 'Create' mode click "Push notifications" button on the left. There you can configure your application for push notifications by inserting API key of configured account.
Registering to receive push notifications
If you want Android device to be able to receive push notifications you must follow instructions from getting started documentation. Also you have to send registration token to Mobeelizer server by calling method:
To unregister your application from receiving push navigation just call:
Sending push notification
To send Push notification call one of methods on Mobeelizer object:
- sendRemoteNotification(Map notification)
- sendRemoteNotificationToDevice(Map notification, String device)
- sendRemoteNotificationToUsers(Map notification, List users)
- sendRemoteNotificationToUsersOnDevice(Map notification, List users, String device)
- sendRemoteNotificationToGroup(Map notification, String group)
- sendRemoteNotificationToGroupOnDevice(Map notification, String group, String device)