Warning Unreleased Docs! - You may be viewing documentation that reflects an upcoming release and the functionality described may not be in the current version you are using. Change the version above to the most recent version.

Android Java Client

Getting started
RhoConnectClient initialization
Object Model
Packaging RhoConnect Client
Release procedure

Getting started

The RhoConnect Client is part of the Rhoconnect-client repository. You can get it on github (select the latest ‘rhoconnect-client’ package).
The RhoConnect Client for Android contains two files:

** rhoimpl.jar - Java part of RhoConnect Client library

** librhoconnectclient.so - native part of RhoConnect Client library

These can be build from /rhoconnect-client directory with next command

$>rake android:default

Create new Android project or open existing one in Eclipse. Add rhoimple.jar to your project build path and copy librhoconnectclient.so to /libs/armeabi, so both Java and native parts of RhoConnect Client library will link with your project.
Copy all files and subfolders from /rhoconnect-client/Java/RhoConnect/assets to assets folder of your Android project.

RhoConnectClient initialization

Load native library before any RhoConnect client usage. Example of appropriate place to do so is Android application’s onCreate method

:::java

import android.app.Application; public class SampleApplication extends Application { public void onCreate() { System.loadLibrary(“rhoconnectclient”); } }
Configure and initialize RhoConnect library. Example of appropriate place to do so is main Activity onCreate method

:::cplusplus public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.main);

  ApplicationInfo appInfo = getApplicationInfo();

  try {
      RhoFileApi.initRootPath(appInfo.dataDir, appInfo.sourceDir);
      RhoFileApi.init(this.getApplicationContext());

      RhoLogConf.setMinSeverity(0);
      RhoLogConf.setEnabledCategories("*");

      RhoConnectClient.nativeInit();
  } catch (Exception e) {
      Logger.E(TAG, e.getMessage());
  }
  mSyncClient = new RhoConnectClient();
  mModels = new RhomModel[]{
          new RhomModel("Customer", RhomModel.SYNC_TYPE_INCREMENTAL),
          new RhomModel("Product", RhomModel.SYNC_TYPE_INCREMENTAL)
      };
  mSyncClient.initialize(mModels);
  mSyncClient.setPollInterval(0);
  mSyncClient.setSyncServer("http://rhodes-store-server.heroku.com/application");
  mSyncClient.setBulkSyncState(1);
  mSyncClient.loginWithUserAsync("", "", new RhoConnectNotify.IDelegate() {
      public void call(RhoConnectNotify notify) { onLogin(notify); } });

} public void onLogin(RhoConnectNotify notify) { // Handle login event }

Note: RhoConnect callbacks (like passed to RhoConnectClient.loginWithUserAsync method in example above) may and most possibly will be called from another thread. It is up to application developer to care about synchronizing or forwarding call to an appropriate thread like GUI thread or Service thread.

Object Model

Intro

RhoConnect Client Android Java API resides at com.rhomobile.rhoconnect package. It contains two main classes: RhoConnectClient and RhomModel. The package also contains two classes which represent results of call to the API. These are RhoConnectNotify and RhoConnectObjectNotify. Also several utility classes from com.rhomobile.rhodes package can be used. These are RhoConf, RhoLogConf, Logger.

RhoConnectClient

package com.rhomobile.rhoconnect;
public class RhoConnectClient{
    /// Call this method before create and use the client. It sets up directory structure and makes necessary native library initialization.
    public static native void nativeInit();
    /// Creates instance of RhoConnectClient singlethon (yes, it's only one instance of RhoConnectClient allowed).
    public RhoConnectClient();
    /// Call this method to close network connections and release any resources gracefully
    public synchronized void close();
    /// Makes db models initialization. This call must be made just after RhoConnectClient construction and before any other calls to RhoConnectClient object.
    public native void initialize(RhomModel models[]);
    /// Sets up server URL to sync (RhoConnect server)  
    public native void setSyncServer(String url);
    /// Forces synchronous or asynchronous RhoConnectClient mode
    /// true - asynchronous mode (default)
    /// false - synchronous mode
    public native void setThreadedMode(boolean mode);
    /// Sets/gets auto sync interval. 0 - disable auto sync
    public native void setPollInterval(int interval);
    public native int getPollInterval();
    ///
    public native void setBulkSyncState(int state);
    public native int getBulkSyncState();
    /// Set get various configuration parameters.
    public native void setConfigString(String name, String param);
    public native String getConfigString(String name);
    /// Reset all data for all models in local database, also perform logout
    public native void databaseFullResetAndLogout();
    /// Checks does login session exists in the database
    public native boolean isLoggedIn();
    /// Logins to RhoConnect server and keep login session in database
    public native RhoConnectNotify loginWithUserSync(String user, String pass);
    /// Logins to RhoConnect server and keep login session in database.
    /// callback will be called when operation has finished.
    public native void loginWithUserAsync(String user, String pass, RhoConnectNotify.IDelegate callback);
    /// Runs sync of all models
    public native RhoConnectNotify syncAll();
}

RhomModel

package com.rhomobile.rhoconnect;
public class RhomModel {
    /// Possible model types
    public final static int MODEL_TYPE_PROPERTY_BAG = 0;
    public final static int MODEL_TYPE_FIXED_SCHEMA = 1;
    /// Possible sync types
    public final static int SYNC_TYPE_NONE = 0;
    public final static int SYNC_TYPE_INCREMENTAL = 1;
    public final static int SYNC_TYPE_BULK_ONLY = 2;
    /// Constructor        
    public RhomModel(String name, int syncType);
    /// Returns the model name    
    public String getName() { return mName; }
    /// Returns the model type
    public int getModelType() { return mModelType; }
    /// Sets the model type
    public void setModelType(int type) { mModelType = type; }
    // Returns the model sync type
    public int getSyncType() { return mSyncType; } 
    /// Sets the model sync type
    public void setSyncType(int type) { mSyncType = type; }
    /// Returns the model sync priority
    public int getSyncPriority() { return mSyncPriority; }
    /// Sets the model sync priority
    public void setSyncPriority(int prio) { mSyncPriority = prio; }
    /// Returns the model partition
    public String getPartition() { return mPartition; }
    /// Sets the model partition
    public void setPartition(String part) { mPartition = part; }
    /// Runs sync of the model
    public RhoConnectNotify sync();
    /// Creates model object with properties and save to database, object id will be generated automatically if not set
    public void create(Map<String, String> props);
    /// Finds object by object id
    public Map<String, String> find(String objectId)
    /// Saves changes to existing object
    public void save(Map<String, String> item);
    /// Destroys existing object
    public void destroy(Map<String, String> item) {

    // Returns first object which matches the condition
    public Map<String, String> findFirst(Map<String, String> condition);
    // Returns all objects which matched the condition
    public Collection<Map<String, String> > findAll(Map<String, String> condition);

    public void startBulkUpdate();
    public void stopBulkUpdate();
}

RhoConnectNotify

package com.rhomobile.rhoconnect;
public class RhoConnectNotify {
    public int getTotalCount() { return mTotalCount; }
    public int getProcessedCount() { return mProcessedCount; }
    public int getCumulativeCount() { return mCumulativeCount; }
    public int getSourceId() { return mSourceId; }
    public int getErrorCode() { return mErrorCode; }
    public String getSourceName() { return mSourceName; }
    public String getStatus() { return mStatus; }
    public String getSyncType() { return mSyncType; }
    public String getErrorMessage()
    public String getCallbackParams() { return mParams; }
    /// Developer need to implement and pass reference to this interface
    /// in order to get call back when asynchronous operation has completed
    public static interface IDelegate {
        public void call(RhoConnectNotify notify); 
    }
}

RhoConnectObjectNotyfy

package com.rhomobile.rhoconnect;
public interface RhoConnectObjectNotify {
    public String[] getDeletedObjects();
    public String[] getUpdatedObjects();
    public String[] getCreatedObjects();

    public int[] getDeletedSourceIds();
    public int[] getUpdatedSourceIds();
    public int[] getCreatedSourceIds();

    /// Developer need to implement and pass reference to this interface
    /// in order to get call back when objects are created, updated or destroyed at sync server
    public static interface IDelegate {
        public void call(RhoConnectObjectNotify notify); 
    }
}

Samples

See android_store sample rhoconnect-client\Samples\Java\android_store as an example.
See android test Eclipse project rhoconnect-client\Java\Android\test as another example.

Packaging RhoConnect Client

To package the RhoConnect Client archive for distribution, go to the top of the rhodes repository and run:

$ rake build:rhoconnect_client

This will produce a zipfile in the folder called rhoconnect-client-<someversion>.zip where <someversion> is the version of the client.

Release procedure

Unzip package to some folder
Open project rhoconnect-client\ObjectiveC\Tests\RhoConnectClientTest in xcode and run. See log - SUCCESS should be at the end of log
Open project rhoconnect-client\Samples\ObjectiveC\store in xcode and run. Press Login, you should see several items, click on item, you should see details