Documentation : Android References

Prelude

This document will provide you with detailed documentation about creating Mobeelizer client application on Android platform.

If you want only a quick glimpse see tutorial instead.

In this document we assumes that you are familiar with:

Configure your application

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:
<application android:name="com.mobeelizer.mobile.android.Mobeelizer">

 

  • Then add permissions required by Mobeelizer:
<uses-permissionandroid:name="android.permission.INTERNET"> 
<uses-permissionandroid:name="android.permission.READ_PHONE_STATE"> 
<uses-permissionandroid:name="android.permission.ACCESS_WIFI_STATE"> 
<uses-permissionandroid:name="android.permission.ACCESS_NETWORK_STATE"> 
<uses-permissionandroid:name="android.permission.WRITE_EXTERNAL_STORAGE">
Do I need WRITE_EXTERNAL_STORAGE permission if I'm not going to use files? Yes, you do! Mobeelizer connector needs storage to store temporary files exchanged in synchronization process.

 

  • 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:

<meta-dataandroid:name="METADATA_NAME"android:value="METADATA_VALUE" />

Available parameters are:

NameRequired

Description

MOBEELIZER_MODEYES

There are three possible development modes:

  • development - application works off-line. Login and synchronization methods are mocked - they do nothing and returning no error. This mode allows you to develop client application completely separate from cloud deployment and management. Defining MOBEELIZER_DEVELOPMENT_ROLE parameter is necessary with this mode.
  • test - application will connect to test environment.
  • production - application will connect to production environment.
MOBEELIZER_DEVELOPMENT_ROLENO

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.

MOBEELIZER_PACKAGEYES

Package of your model classes.

MOBEELIZER_DEVICEYES

Name of the device category. See this document for more explanation.

MOBEELIZER_DEFINITION_ASSETNO

Name of the XML file with application definition. Default value is application.xml.

MOBEELIZER_DB_VERSIONNO

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:

  • Package

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:

NameTypeRequired

Description

guidStringYES

Main object identifier

ownerStringNO

Information about owner of object

modifiedbooleanNO

This field will be true if record was modified by user - but not synchronized yet.

conflictedbooleanNO

This field will be true if object is conflicted. See here to read more about conflicts.

deletedbooleanNO

To delete entity set this field to true.

Remember about getter and setter methods!

Although you have to provide setter methods for every defined special field you should never modify their values manually.

 

  • 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 typeAvailable class field types
belongs toString
booleanBoolean, boolean
dateDate, Calendar, Long, long
decimalDouble, double, Float, float, BigDecimal
fileMobeelizerFile
integerInteger, int, Short, short, Byte, byte, Long, long, BigInteger
textString
Not required fields cannot be defined by primitive types like int or boolean. Use Object types like Integer and Boolean instead.

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!

Use database

Obtaining database object

Database can be accessed using object MobeelizerDatabase which can be obtained by calling method

MobeelizerDatabase database = Mobeelizer.getDatabase();
Remember that to use database user have to be logged in.
You shouldn't connect to database directly without MobeelizerDatabase object! SDK will loose track of changes tracking and synchronize functionality will not work properly!

Basic operations

MobeelizerDatabase object allows you to easily perform basic database operations. Let say you have model 'Product' defined in Product.class.

Then you can write:

List<Product> allProducts = database.list(Product.class);
long count = database.count(Product.class);
Product product = database.get(Product.class, "guidIdentifier");
boolean exists = database.exists(Product.class, "guidIdentifier");

Product product = // create product
MobeelizerErrors errors = database.save(product);
if(errors != null) {
	// notify the user about validation errors
}

database.delete(product);
database.delete(Product.class, "guidIdentifier");

For more information see javadoc documentation.

Relations

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:

// ------- create new order with positions
Order order = new Order();

// fill order fields
MobeelizerErrors orderSaveErrors = database.save(order);
OrderPosition position = new OrderPosition();

// fill position fields
position.setOrder(order.getGuid());
MobeelizerErrors positionSaveErrors = database.save(position);

// ------- get order of position:
OrderPosition position = database.get(OrderPosition.class, "positionIdentifier");
Order order = database.get(Order.class, position.getOrder());

Files

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:

OrderWithAttachment order = database.get(OrderWithAttachment.class, "orderIdentifier");
MobeelizerFile attachment = order.getAttachment();
String attachmentIdentifier = attachment.getGuid();
String attachmentName = attachment.getName();
InputStream contentStream = attachment.getInputStream();

To create new MobeelizerFile instance you can:

// ------- create new file...
InputStream contentStream = // get file content
MobeelizerFile newAttachment = Mobeelizer.createFile("newAttachmentName", contentStream);

// ------- ...or use existing one
MobeelizerFile newAttachment = Mobeelizer.createFile("newAttachmentName", "existingAtachmentGuid");

Remember about changing order file field:

OrderWithAttachment order = // get object from database or create new one
order.setAttachment(newAttachment);
MobeelizerErrors orderSaveErrors = database.save(order);

Advanced database queries

Advanced queries can be accessed by MobeelizerCriteriaBuilder class.To get criteria object just call method:

MobeelizerCriteriaBuilder query = database.find(Product.class);

Next define your query (see below). After that you can:

// get list of objects meeting query conditions
List<Product> products = query.list();

// get number of objects meeting query conditions
long count = query.count();

// get single object meeting query conditions
Product product = query.uniqueResult();

While creating query you can:

  • Limit result objects number:
query.setMaxResults(10);
  • Set the first result:
query.setFirstResult(5);
  • Add order
query.addOrder(MobeelizerOrders.asc("name")); // order ascending by name field
query.addOrder(MobeelizerOrders.desc("price")); // order descending by price field
  • Add restrictions
query.add(MobeelizerResrictions.eq("name", "table")); // name equals "table"
query.add(MobeelizerResrictions.or(
	MobeelizerResrictions.between("price", 10, 20),
	MobeelizerResrictions.isNull("price"))
); // price between 10 and 20 or no price at all

For more informations about restrictions see MobeelizerResrictions javadoc.

You can also combine many elements to create more complicated queries:

// Get products with price less than 100 order from cheaper to more expensive.
// Products with same price order alphabetically.
// Display page 3 of results (10 results on page).
List<Product> product = database.find(Product.class).add(
	MobeelizerResrictions.le("price", 100);
).addOrder(
	MobeelizerOrders.desc("price")
).addOrder(
	MobeelizerOrders.asc("name")
).setFirstResult(20).setMaxResults(10).list();

For more information see MobeelizerCriteriaBuilder javadoc.

Synchronize data

Synchronizing data with cloud cannot be easier! Just call one of sync methods on Mobeelizer object.

Normal synchronization

To perform data synchronization call sync method (or it's asynchronous version).

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

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.

Broadcast notifications

You can register listener for all notifications about sync status changes. To do it create and configure BroadcastReceiver. Then register it for sync event:

registerReceiver(broadcastReceiver,  new IntentFilter(Mobeelizer.BROADCAST_SYNC_STATUS_CHANGE));

In your BroadcastReceiver onReceive method you can write:

public void onReceive( final Context context,  final Intent intent) {
	MobeelizerSyncStatus newStatus = (MobeelizerSyncStatus) intent.getExtras()
				.getSerializable(Mobeelizer.BROADCAST_SYNC_STATUS_CHANGE_STATUS);
	// your reaction on status change
}

See MobeelizerSyncStatus javadoc for more information about available statuses.

Push notifications

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.

Configuring application

  • 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.

Test account will be used on test environments, production on production ones. You can use separate accounts or insert same data in both forms.

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:

Mobeelizer.registerForRemoteNotifications(registrationId);

To unregister your application from receiving push navigation just call:

Mobeelizer.unregisterForRemoteNotifications();

Sending push notification

To send Push notification call one of methods on Mobeelizer object: