rhoconnect 3.0.6 → 3.1.0.beta1

data/doc/benchmarks-running.txt

@@ -0,0 +1,140 @@
+Running RhoConnect Benchmarks
+===
+
+## Introduction
+
+You can execute benchmark tests against your deployment and verify the performance of your Rhoconnect application using the provided `rhoconnect-benchmark` command.
+During the test the Rhoconnect benchmark framework will dynamically create a special ephemeral source adapter inside of
+your application and perform the 5-step query use-case mimicking the typical device-to-server communication.
+
+Currently, the Rhoconnect Benchmark measures two primary system-wide metrics: Average Time and Throughput.
+
+- Average time (milliseconds per request) is calculated as sum_of_executed_http_request_times/number of http requests.
+- Throughput is an integral metric (number of requests per second) calculated as: cumulative_number_of_http_requests_processed/(finish_time_for_last_test - start_time_of_first_test).
+
+NOTE: Both metrics implicitly include the network latency and therefore represent the performance of the whole system `device-network-server`.
+
+## Rhoconnect Benchmark Command
+
+To execute the Rhoconnect Benchmark test, use the `rhoconnect-benchmark` command. This command has the following options:
+
+<table border="1">
+	<tr>
+		<td width="20">-u</td>
+		<td width="200"><code>--url URL</code></td>
+		<td>Use URL to specify the targeted Rhoconnect server for benchmarking. If this option is not specified, <code>http://localhost:9292</code> will be used as a default.</td>
+	</tr>
+	<tr>
+		<td width="20">-p</td>
+		<td width="200"><code>--payload NUMBER</code></td>
+		<td>This options specifies the amount of data to be simulated in the query request (in number of records). Default: 100, which roughly translates into 20 kilobytes.</td>
+	</tr>
+	<tr>
+		<td width="20">-C</td>
+		<td width="200"><code>--nclients NUMBER</code></td>
+		<td>Specifies how many concurrent clients to emulate during the test. If this option is omitted, then the number of simulated clients will be determined based on the number of available seats in your Rhoconnect application's license.</td>
+	</tr>
+	<tr>
+		<td width="20">-R</td>
+		<td width="200"><code>--niterations NUMBER</code></td>
+		<td>Specifies how many times each emulated client will perform the test. Default: 10. The more iterations you specify, the more time your test will take, but it will lessen the test result's statistical fluctuations.</td>
+	</tr>
+	<tr>
+		<td width="20">-S</td>
+		<td width="200"><code>--save PATH</code></td>
+		<td>This option saves the test results in the PATH sub-directory and run the post-processing on the saved files (for example, generate the EXCEL spreadsheet). All the results will be saved under the PATH root directory.</td>
+	</tr>
+	<tr>
+		<td width="20">-x</td>
+		<td width="200"><code>--maxpayloadloops NUMBER</code></td>
+		<td>This option runs several tests in a loop varying the payload between 1 and NUMBER. The specified interval will be split by 10. For example: -m 500 will produce 10 test executions , first for payload of 1 record, then - for 56, 112, 167, 223, 278, 334, 389, 445, and 500</td>
+	</tr>
+	<tr>
+		<td width="20">-m</td>
+		<td width="200"><code>--maxclientloops NUMBER</code></td>
+		<td>This option runs several tests in a loop varying number of concurrent clients between 1 and NUMBER. The specified interval will be split by 5. For example: -m 10 will produce 5 test executions , first for 1 client, then - for 3, 6, 8, and 10</td>
+	</tr>
+	<tr>
+		<td width="20">-A</td>
+		<td width="200"><code>--advanced</code></td>
+		<td>This convenience option combines -m 10, -x 500, and -S <cur_dir/bench_results> - thus running a matrix of tests varying in payload and number of concurrent clients. Also, it saves the results into the `bench_results` subdirectory and runs the available post-processing.</td>
+	</tr>
+	<tr>
+		<td width="20">-D</td>
+		<td width="200"><code>--distributed AWSFILE</code></td>
+		<td>This option executes the advanced benchmark test using the remote AWS EC2 clients. Currently, this option is only available for the Linux/MacOS machines. See Distributed Benchmark section below for details.</td>
+	</tr>
+</table>
+
+## Result post-processing
+By default, all results are displayed in the console during the test. However, it is possible to save all the results into the file and, additionally, generate the EXCEL files and/or PNG images using the `--save PATH` option. The results are saved for two benchmark metrics: Average Time and Throughput.
+
+### Generate EXCEL spreadsheet
+To enable the automatic generation of the EXCEL spreadsheets from the test results, please install the `spreadsheet` gem by using:
+
+	$ [sudo] gem install spreadsheet
+	
+You can read more about the `spreadsheet` gem [here](http://rubygems.org/gems/spreadsheet).
+	
+### Generate PNG images
+To enable the automatic generation of the PNG images from the test results, install the `gruff` gem.
+Installation of the GRUFF gem requires an additional installation of several components.
+Use [this](http://nubyonrails.com/pages/gruff) guide to install the GRUFF on your machine.
+
+## Distributed Benchmark test
+To fully simulate the distributed nature of the device-to-server system, the Rhoconnect Benchmark command allows to you to create distributed clients through the [AWS Cloud Formation](http://aws.amazon.com/cloudformation/).
+
+NOTE: Distributed Rhoconnect Benchmark test will be executed via the AWS Cloud Formation and EC2 services using your account and therefore you will be billed for its usage by Amazon.
+
+In order to run the distributed Benchmark test, you need to have an AWS account and specify its settings in a YAML file, which should have the following structure:
+
+	:::ruby
+	:default:
+	  :region: desired_aws_region
+	  :aws_access_key_id: your_aws_account_key_id
+	  :aws_secret_access_key: your_aws_account_secret_access_key
+	  :aws_key_pair_name: your_aws_ec2_security_key_pair
+	  :aws_ssh_pem_file: location_of_your_aws_ssh_pem_file
+
+Here is the description of each entry in the AWS settings file:
+
+<table border="1">
+	<tr>
+		<td width="300"><code>:region</code></td>
+		<td>Specify the desired AWS region for your EC2 clients. Default is 'us-west-1'. Typically, you need to specify the same region as the location of your Rhoconnect server to minimize the network impact (since communications between different regions will take more time).</td>
+	</tr>
+	<tr>
+		<td width="200"><code>:aws_access_key_id</code></td>
+		<td>Your AWS access key ID.</td>
+	</tr>
+	<tr>
+		<td width="200"><code>:aws_secret_access_key</code></td>
+		<td>Your AWS secret access key.</td>
+	</tr>
+	<tr>
+		<td width="200"><code>:aws_key_pair_name</code></td>
+		<td>In order to create EC2 clients, you will need to create EC2 KeyPair in the desired region. After that KeyPair is created, you will have its name, which should be specified here.</td>
+	</tr>
+	<tr>
+		<td width="200"><code>:aws_ssh_pem_file</code></td>
+		<td>For the above KeyPair, you will have the corresponding keypair .PEM file. Download this file to your machine and reference its location here.</td>
+	</tr>
+</table>
+	
+Once the AWS settings file is created, you need to make sure that the following gems are installed on your machine:
+
+- fog
+- net-ssh-multi
+
+You can install those gems using the `[sudo] gem install <gemname>` command.
+
+Once all the pre-requisites are met, you can run the distributed Rhoconnect Benchmark test with the following command:
+
+	$ rhoconnect-benchmark -u `server_url` -D `path_to_aws_settings_file`
+	
+
+NOTE: In order to run the distributed Benchmark test, you must provide public server's URL accessible from the outside clients.
+
+
+
+

data/doc/client-java.txt

@@ -0,0 +1,236 @@
+# Android Java Client
+
+## Getting started
+
+* The RhoConnect Client is part of the Rhodes repository. You can get it [on github](https://github.com/rhomobile/rhodes/downloads) (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 <rhodes>/rhoconnect-client directory with next command
+
+    :::shell
+    $>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 <project_root>/libs/armeabi, so both Java and native parts of RhoConnect Client library will link with your project.
+
+* Copy all files and subfolders from <rhodes>/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
+
+* Login to RhoConnect server
+
+	:::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 methodin axample 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 pakage. 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
+
+	:::cplusplus
+    package com.rhomobile.rhoconnect;
+    public class RhoConnectClient{
+        /// Call this method before create and use the client. It sets up directory structure and makes nessesary 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
+
+	:::cplusplus
+    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
+
+	:::cplusplus
+    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
+
+	:::cplusplus
+    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](http://github.com/rhomobile/rhodes/tree/master/rhoconnect-client/Samples/Java/android_store/) as an example.
+* See android test Eclipse project [rhoconnect-client\Java\Android\test](http://github.com/rhomobile/rhodes/tree/master/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:
+
+	:::term
+  	$ 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
+1. Unzip package to some folder
+
+2. Open project `rhoconnect-client\ObjectiveC\Tests\RhoConnectClientTest` in xcode and run. See log - SUCCESS should be at the end of log
+
+3. 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

data/doc/client-objc.txt

@@ -146,7 +146,8 @@ Here is the Store code for the initialization process, contained in RhoConnectEn
 		
 			sclient.sync_server = @"http://rhodes-store-server.heroku.com/application";
 			sclient.threaded_mode = TRUE;
-		
+			sclient.log_severity = 1;
+
 			loginState = [sclient is_logged_in] ? logged_in : logged_out;
 		}
 		return sharedInst;
@@ -190,6 +191,13 @@ Call the RhoConnectClient setNotification method to call a callback method that
 	:::cplusplus
 	[ [RhoConnectEngine sharedInstance].syncClient setNotification: @selector(syncAllComplete:) target:self];
 
+To perform a bulk sync *bulksync_state* configuration flag should be reset to zero. If you don't need bulk sync then just skip it.
+
+    :::cplusplus
+    // set configuration for bulk sync, it means "next sync should be performed as bulk"
+    [RhoConnectEngine sharedInstance].syncClient.bulksync_state = 0;
+    // after sync performed the it should contain value 1.
+
 Call a sync method, such as the RhoConnectClient syncAll method or the RhomModel sync method, to sync your client model data with the RhoConnect server.
 
 	:::cplusplus
@@ -391,6 +399,7 @@ The RhoConnectClient class contains the following properties and methods to buil
 
  * <a href="#threaded_mode">threaded_mode property</a>
  * <a href="#poll_interval">poll_interval property</a>
+ * <a href="#log_severity">log_severity property</a>
  * <a href="#sync_server">sync_server property</a>
  * <a href="#initDatabase">initDatabase</a>
  * <a href="#addModels">addModels</a>
@@ -403,6 +412,8 @@ The RhoConnectClient class contains the following properties and methods to buil
  * <a href="#clearNotification">clearNotification</a>
  * <a href="#is_logged_in">is\_logged\_in</a>
  * <a href="#syncAll">syncAll</a>
+ * <a href="#is_syncing">is_syncing</a> 
+ * <a href="#stop_sync">stop_sync</a> 
  * <a href="#search">search</a>
  * <a href="#setObjectNotification">setObjectNotification</a>
  * <a href="#clearObjectNotification">clearObjectNotification</a>
@@ -425,6 +436,13 @@ int. Not yet supported. Default = 0.
 	:::cplusplus
 	@property(setter=setPollInterval) int poll_interval;
 
+### <a id="log_severity"></a>log\_severity property
+
+int. Set minimal severity level for messages to log output. Default = 0.
+
+	:::cplusplus
+	@property(setter=setLogSeverity) int log_severity;
+
 ### <a id="sync_server"></a>sync\_server property
 
 NSString. Sets the RhoConnect server url, for example: "`http://<ip>:<port>/application`"
@@ -542,6 +560,20 @@ Instance method. Returns a RhoConnectNotify object after running a sync on all t
 	:::cplusplus
 	- (RhoConnectNotify*) syncAll;
 
+### <a id="is_syncing">is_syncing
+
+Instance method. Returns TRUE if syncronization is in progress
+
+	:::cplusplus
+	- (BOOL) is_syncing;
+
+### <a id="stop_sync">stop_sync
+
+Instance method. Stop current sync if running
+
+	:::cplusplus
+	- (void) stop_sync;
+
 ### <a id="search">search
 
 Instance method. Returns a RhoConnectNotify object after sending a search request to the RhoConnect server.
@@ -717,6 +749,7 @@ The RhomModel class contains the following properties and methods for setting an
  * <a href="#destroy">destroy</a>
  * <a href="#startBulkUpdate">startBulkUpdate</a>
  * <a href="#stopBulkUpdate">stopBulkUpdate</a>
+ * <a href="#is_changed">is_changed</a>
 
 ### <a id="name"></a>name property
 
@@ -924,6 +957,13 @@ Run this method when you start to create or update a bunch of models; it will op
 	:::cplusplus
 	- (void) stopBulkUpdate;
 
+### <a id="is_changed">is_changed
+
+Check does model contain non-synced local changes
+
+	:::cplusplus
+	- (BOOL) is_changed;
+
 ## RhoConnectNotify Class API
 
 Several RhoConnectClient methods return a RhoConnectNotify object. The properties for the RhoConnectNotify class provide access to sync notification objects as described [here](/rhodes/synchronization#notifications). (Developers do not set RhoConnectNotify properties, but only read them after a call to a RhoConnectClient method that returns a RhoConnectNotify object.)

data/doc/client.txt

@@ -43,6 +43,9 @@ Rhoconnect Client is a library to add sync data capability to your applications.
 	//default is 0. Not supported yet
 	@property(setter=setPollInterval) int  poll_interval;
 
+    //default is 0. Set minimal severity level for messages to log output
+	@property(setter=setLogSeverity) int log_severity;
+
 	//set rhoconnect server url, for example: "http://<ip>:<port>/application"
 	@property(assign, setter=setSyncServer) NSString* sync_server;
 
@@ -74,6 +77,12 @@ Rhoconnect Client is a library to add sync data capability to your applications.
 	// run sync of all models
 	- (RhoConnectNotify*) syncAll;
 
+	// check is sync is in progress
+    - (BOOL) is_syncing;
+    
+    //stop current sync if running
+    - (void) stop_sync;
+
 	//send search request to rhoconnect
 	- (RhoConnectNotify*) search: (NSArray*)models from: (NSString*) from params: (NSString*)params sync_changes: (BOOL) 				
 		sync_changes progress_step: (int) progress_step;
@@ -148,6 +157,9 @@ Rhoconnect Client is a library to add sync data capability to your applications.
 	//these are equivalent to start/commit transaction
 	- (void) startBulkUpdate;
 	- (void) stopBulkUpdate;
+                                                                                              
+    //check does model was modified and not yet synced
+    - (BOOL) is_changed;
 
 #### RhoConnectNotify
 

data/doc/command-line.txt

@@ -61,7 +61,9 @@ After generating the application, you might be asked to change directories to yo
 
 ### Add a New Source Adapter
 
-To generate a source for your RhoConnect application, run the `rhoconnect source` command within your application directory:
+To generate a source for your RhoConnect application, you can run the `rhoconnect source` command within your application directory.
+
+**NOTE:** You can also write the source into your backend application and [write a RhoConnect plugin](/rhoconnect/plugin-intro) in Java, .NET, or other language for that application.
 
 	:::term
 	Usage: rhoconnect source name [options] [args]
@@ -69,7 +71,7 @@ To generate a source for your RhoConnect application, run the `rhoconnect source
 	Generates a new source adapter.
 
 	Required:
-	  name        - source name(i.e. product)
+	  name        - the source name(i.e. product)
 
 
 	Options specific for this generator:
@@ -215,4 +217,11 @@ Here is a complete list of the rake tasks available in a RhoConnect application:
 	rake rhoconnect:start               # Start rhoconnect server
 	rake rhoconnect:stop                # Stop rhoconnect server
 	rake rhoconnect:war                 # Build executable WAR file to be used in Java App Servers
-	rake rhoconnect:web                 # Launch the web console in a browser - uses :syncserver: in settings.yml
+	rake rhoconnect:web                 # Launch the web console in a browser - uses :syncserver: in settings.yml
+
+## Generate Source
+
+Connecting to a backend service with RhoConnect requires that you write a small amount of code for the query, create, update and delete operations of your particular enterprise backend. The collection of the code for these operations is called a source. To generate source for your RhoConnect application:
+
+ * Generate a Ruby code [RhoConnect source adapter](/rhoconnect/source-adapters).
+ * Write the source code (the query, create, update and delete operations) into your backend application and [write a RhoConnect plugin](/rhoconnect/plugin-intro) in the language that matchs your backend application, such as Java or .NET.

data/doc/cud-conflicts.txt

@@ -0,0 +1,68 @@
+Resolving CUD conflicts
+===
+
+Rhoconnect CUD queue and potential conflicts
+---
+
+By design, your Rhoconnect application supports parallel dispatching of the multiple client's requests via the asynchronous Resque jobs. This scenario can lead to a situation where two or more clients will try to perform CUD operations at the same time, potentially creating the race condition. For example, this can happen when two users will try to insert or delete the same record simultaneously.
+To handle this situation , Rhoconnect uses the CUD queue, which is being dispatched continuously. You can inspect this queue before the CUD operation is called and mark the conflicting records for special processing. To do this, you need to override the Source Adapter `validate` method that is called before the CUD queue is dispatched. This method has the following parameters:
+
+<table border="1">
+	<tr>
+		<td>String</td>
+		<td><code>operation</code></td>
+		<td>CUD operation marker, one of three: create, update, or delete</td>
+	</tr>
+	<tr>
+		<td>Array Of Record Hashes</td>
+		<td><code>cud_queue</code></td>
+		<td>CUD queue consisting of CUD request hashes, ordered from oldest to newest. Each entry in the queue contains a hash of CUD records to process. (Each CUD client request can contain more than one record</td>
+	</tr>
+	<tr>
+		<td>Array Of Client Ids</td>
+		<td><code>client_queue</code></td>
+		<td>This array is used to map the CUD request in the above queue to a corresponding client ID. i.e. CUD_queue[N] request was issued by client_queue[N] client. Please note that there may be several entries from the same client - if they came separately in time</td>
+	</tr>
+</table>
+
+Below you can see the example of the `validate` method parameters indicating two create requests containing the conflicting records:
+
+	:::ruby
+	client_1 = 'cid_1'
+	cud_request_1 = { 'temp_cid1_1' => {'name' => 'iPhone'}, 'temp_cid1_2' => {'name' => 'Android'}}
+	client_2 = 'cid_2'
+	cud_request_2 = { 'temp_cid2_1' => {'name' => 'iPhone'}}  # this record seems to be the duplicate of the record 'temp_cid1_1'
+	
+	operation = 'create'
+	cud_queue = [ cud_request_1, cud_request_2 ]
+	client_ids = [ client_1, client_2 ]
+
+Detecting the conflict and forcing an error
+---
+
+Using the above `validate` method you can iterate through the queue and detect CUD conflicts based on the desired application logic. Once the conflicting record is found (for example, duplicate create request), you need to mark it by inserting the conflicting record parameters into the special hash structure that is returned by the `validate` method:
+
+	:::ruby
+	def validate(operation, cud_queue, client_ids)
+		resulting_meta_hash = {}
+	
+		# iterating through the queue
+		cud_queue.each_with_index do |cud_request, index|
+			cud_request_client = client_ids[index]
+			
+			# iterating through the request records
+			cud_request.each do |record_id, record_hash|
+				# ... detecting the conflict here ....
+				# !!! found a conflict - force an error
+				error_record_id = record_id
+			 	record_meta_data = { error_record_id => { :error => 'my_error_string: conflict is detected!!!' }}
+				resulting_meta_hash[index] ||= {}
+				resulting_meta_hash[index].merge!(record_meta_data)
+			end
+		end
+		
+		resulting_meta_hash
+	end
+				
+Once the `validate` method returns non-empty validation metadata hash structure, it will be used in processing the CUD queue. All marked records will not be processed, but instead an error will be sent back to the originating client with the user-provided error message.
+