rhoconnect 3.1.1 → 3.1.2

data/bench/blobapp/config.ru

@@ -26,8 +26,7 @@ Rhoconnect::Server.set     :root,        ROOT_PATH
 Rhoconnect::Server.use     Rack::Static, :urls => ["/data"], :root => Rhoconnect::Server.root
 
 # Load our rhoconnect application
-$:.unshift ROOT_PATH if RUBY_VERSION =~ /1.9/ # FIXME: see PT story #16682771
-require 'application'
+require "#{ROOT_PATH}/application"
 
 # Setup the url map
 run Rack::URLMap.new \

data/bench/blobapp/spec/spec_helper.rb

@@ -19,19 +19,6 @@ include Rhoconnect
 
 require 'rhoconnect/test_methods'
 
-# Monkey patch to fix the following issue:
-# /Library/Ruby/Gems/1.8/gems/rspec-core-2.5.1/lib/rspec/core/shared_example_group.rb:45:
-# in `ensure_shared_example_group_name_not_taken': Shared example group '...' already exists (ArgumentError)
-module RSpec
-  module Core
-    module SharedExampleGroup
-    private
-      def ensure_shared_example_group_name_not_taken(name)
-      end
-    end
-  end
-end
-
 shared_examples_for "SpecHelper" do
   include Rhoconnect::TestMethods
   

data/bench/lib/bench/aws_utils.rb

@@ -3,7 +3,6 @@ $:.unshift File.join(File.dirname(__FILE__), '..', '..','..','lib')
 require 'rubygems'
 require 'yaml'
 
-require 'readline'
 require 'xmlsimple'
 
 module Bench

data/bench/spec/bench_spec_helper.rb

@@ -12,7 +12,7 @@ require 'bench/logging'
 require 'bench/mock_client'
 require 'bench/utils'
 require 'bench/result'
-require File.join(File.dirname(__FILE__), '..', '..', 'spec', 'support', 'shared_examples')
+require File.join(File.dirname(__FILE__), '..', '..', 'spec', 'spec_helper')
 
 include Bench
 

data/doc/java-plugin.txt

@@ -1,41 +1,88 @@
 RhoConnect-Java
 ===
 
-RhoConnect-Java library is designed for the [RhoConnect](http://rhomobile.com/products/rhoconnect/) Application Integration Server.
+The RhoConnect-Java library is designed for the [RhoConnect](http://rhomobile.com/products/rhoconnect/) Application Integration Server.
 
-Using the RhoConnect-Java plugin, your [Spring 3 MVC](http://www.springsource.org/) application's data will transparently synchronize with a mobile application built on the [Rhodes framework](http://rhomobile.com/products/rhodes), or any of the available [RhoConnect clients](http://rhomobile.com/products/rhoconnect/).
+Using the RhoConnect-Java plugin jar file, your [Spring 3 MVC](http://www.springsource.org/) application's data will transparently synchronize with a mobile application built on the [Rhodes framework](http://rhomobile.com/products/rhodes), or any of the available [RhoConnect clients](http://rhomobile.com/products/rhoconnect/).
+
+<img src='https://s3.amazonaws.com/rhodocs/rhoconnect-service/rhoconnect-plugin-java.jpg' alt='image' />
 
 ## Prerequisites
 
 * Java (1.6)
 * Maven2 (2.2.1)
 * Git
-* [Rhoconncect-java](https://github.com/downloads/rhomobile/rhoconnect-java/rhoconnect-java-1.0.1.jar) plugin jar file
+* [Rhoconnect-java](https://github.com/downloads/rhomobile/rhoconnect-java/rhoconnect-java-1.0.1.jar) plugin jar file
 
-## Getting started
+## Getting Started
 
-We assume that you have a complete java end-to-end application using Spring 3.0 MVC as the front end technology and Hibernate as backend ORM. For this application we will also use Maven2 for build and dependency management and some database to persist the data. The database is accessed by a Data Access (DAO) layer.
+We assume that you have a complete java end-to-end application using Spring 3.0 MVC as the front end technology and Hibernate as the backend ORM. For this application, we will also use Maven2 for build and dependency management and a database to persist the data. The database is accessed by a Data Access (DAO) layer.
 
-Copy [Rhoconncect-java](https://github.com/downloads/rhomobile/rhoconnect-java/rhoconnect-java-1.0.1.jar) plugin jar file to your PC.
-You can also create target rhoconnect-java plugin jar from sources by cloning rhoconnect-java repository 
+## A Sample Java Spring 3.0 MVC Backend Application
 
-    :::term
-    $ git clone https://github.com/rhomobile/rhoconnect-java.git
+The instructions in the following steps show how to install the `rhoconnect-java` plugin jar file into an existing Java end-to-end application using Sprint 3.0 MVC as the front end technology, and Hibernate as the backend ORM. For an example, you can download and install the [RhoconnectJavaSample](https://github.com/shurab/RhoconnectJavaSample) application.
 
-and executing in cloned project directory the following commands:
+This sample Java application was created using Sprint 3.0 MVC, using [this tutorial to Create Spring 3 MVC Hibernate 3 Example using Maven in Eclipse](http://viralpatel.net/blogs/2010/11/spring3-mvc-hibernate-maven-tutorial-eclipse-example.html).
 
-    :::term
-    $ mvn clean
-    $ mvn compile
-    $ mvn jar:jar
+To install this sample application, navigate in your web browser to [https://github.com/shurab/RhoconnectJavaSample](https://github.com/shurab/RhoconnectJavaSample) and download it as a zip file. Unzip it and rename the unzipped folder to RhoconnectJavaSample.
+
+Navigate into the `RhoconnectJavaSample` folder and run these commands to run the sample Java application.
+
+	:::term
+	$ mvn clean
+	$ mvn jetty:run
+
+When you see `[INFO] Started Jetty Server`, open a web browser and navigate to `http://localhost:8080/contacts/index` to see this application running.
+
+<img src="http://rhodocs.s3.amazonaws.com/rhoconnect-plugin/java-backend-running.png">
+
+## Settings for the Client App
+
+Your client application needs to have its model match the model used in your Java Sprint 3.0 MVC backend application. For example, you can generate a Rhodes application for a Contact model to match the RhoconnectJavaSample application:
+
+	:::term 
+	$ rhodes app contact-app
+	$ cd contact-app
+	$ rhodes model contact lastname,firstname,email,telephone
 
-The archived rhoconnect-java-x.y.z.jar file will be created in the project target/ directory.
 
-For testing and evaluation purposes you can use [RhoconnectJavaSample](https://github.com/shurab/RhoconnectJavaSample) application as a starting point before continuing with the following steps. 
+Edit the `rhoconfig.txt` configuration file to point to your RhoConnect server, where <your_rhoconnect_server_url> is the url for your RhoConnect server.
 
-### Adding Dependencies to Your Maven 2 Project
+	:::term
+	syncserver = 'http://<your_rhoconnect_server_url>/application'
 
-Add dependencies to your Apache Maven 2 project object model (POM): log4j, Apache common beanutils, and Jackson JSON mapper. In the RhoconnectJavaSample application, this code is in the pom.xml file.
+And edit the `app/index.erb` view file to say Contacts:
+
+	:::html
+	...
+	<li><a href="Contact">Contacts</a></li>
+	...
+
+And edit `app/Contact/contact.rb` file to enable sync.
+
+	:::ruby
+	...
+	enable :sync
+	...
+
+## Settings for the RhoConnect Server App
+
+You must generate a RhoConnect server application and edit its settings for the RhoConnect Java plugin.
+
+	:::term 
+	$ rhoconnect app syncserver
+	$ cd syncserver; bundle install
+
+Edit the `settings/settings.yml` development section to add an api\_token key/value pair. This value is the same as the api\_token that you will set in the `WEB-INF/spring-servlet.xml` file for your Java backend application.
+
+	:::term
+	:development:
+	   ...
+	   :api_token: rhoconnect_api_token
+
+## Adding Dependencies to Your Java Application Maven 2 POM
+
+Add dependencies to the Apache Maven 2 project object model (POM) in your Java application by plugging the code below into the `pom.xml` file. This adds dependencies for log4j, Apache common beanutils, and Jackson JSON mapper.
 
     :::xml
     <!-- Log4j -->
@@ -60,14 +107,18 @@ Add dependencies to your Apache Maven 2 project object model (POM): log4j, Apach
         <optional>false</optional>  
     </dependency>
 
-You must also add the rhoconnect-java jar to your Maven 2 project. At this moment rhoconnect-plugin jar is not available in Maven public repositories and you need install the jar manually into your Maven's local repository.
-Download the `rhoconnect-java-1.0-SNAPSHOT.jar` jar file and put it into your hard drive, and issue the following Maven's command:
+## Adding the rhoconnect-java Plugin Jar File to Your Java Backend Application
+
+At this time, the rhoconnect-java plugin jar file is not available in Maven public repositories, so you need to manually install this jar into your Maven's local repository. 
+
+Download the [Rhoconnect-java](https://github.com/downloads/rhomobile/rhoconnect-java/rhoconnect-java-1.0.1.jar) plugin jar file to your PC.
+
+Use the following Maven command to add the rhoconnect-java plugin jar file to your Java backend application. Replace `path-to-jar` with the path to where you have the rhoconnect-java plugin jar file.
 
     :::term
 	$ mvn install:install-file -Dfile=/path-to-jar/rhoconnect-java-1.0.1.jar -DgroupId=com.rhomobile.rhoconnect  -DartifactId=rhoconnect-java -Dversion=1.0.1 -Dpackaging=jar
 
-Now, the `rhoconnect-java` jar library is included into your Maven local repository.
-In the RhoconnectJavaSample application, you would add this code to the pom.xml file.
+Now that the rhoconnect-java jar library is included in your Maven local repository, you must add it as a dependency by adding the following code to the `pom.xml` file. Make sure the version number matches the version number in the jar file name.
 
     :::xml
     <!-- Rhoconnect-java plugin -->
@@ -78,9 +129,25 @@ In the RhoconnectJavaSample application, you would add this code to the pom.xml
     	<type>jar</type>
 	</dependency>
 
-### Updating Your Servlet XML Configuration File
+### Creating the rhoconnect-java Pluigin Jar File from the rhoconnect-java Repository
 
-Update your servlet xml configuration file to include rhoconnect-java metadata: the packages, converters, and beans. In the RhoconnectJavaSample, the following code is added to src/main/webapp/WEB-INF/spring-servlet.xml file.
+Instead of downloading the rhoconnect-java plugin jar file, you can generate it from sources by cloning the `rhoconnect-java` repository:
+
+    :::term
+    $ git clone https://github.com/rhomobile/rhoconnect-java.git
+
+and executing the following commands in your cloned rhoconnect-java project directory:
+
+    :::term
+    $ mvn clean
+    $ mvn compile
+    $ mvn jar:jar
+
+The archived `rhoconnect-java-x.y.z.jar` file will be created in the project's `target` directory.
+
+## Updating Your Servlet XML Configuration File
+
+Update your servlet xml configuration file in your Java backend application folder to include rhoconnect-java metadata: the packages, converters, and beans. In your Java application folder (such as the RhoconnectJavaSample folder), add the following code to `src/main/webapp/WEB-INF/spring-servlet.xml`.
 
     :::xml
     <!-- rhoconnect-java plugin packages -->
@@ -114,33 +181,35 @@ Update your servlet xml configuration file to include rhoconnect-java metadata:
     <bean id="dispatcher" class = "com.rhomobile.rhoconnect.RhoconnectDispatcher"></bean>
     <bean id="rhoconnectClient" class = "com.rhomobile.rhoconnect.RhoconnectClient" init-method="setAppEndpoint" >
      	<property name="restTemplate"><ref bean="restTemplate"/></property>
-     	<property name="endpointUrl" value="your_rhoconnect_server_url" />
-     	<property name="appEndpoint" value="your_spring_app_url" />
-     	<property name="apiToken" value="rhoconnect_api_token" />
+     	<property name="endpointUrl" value="<your_rhoconnect_server_url>" />
+     	<property name="appEndpoint" value=app_endpoint_url" />
+     	<property name="apiToken" value="api_token" />
     </bean>
     
     <!--The following bean handles the application's authentication routine and should be implemented by you -->
     <bean id="authenticate" class = "com.rhomobile.contact.ContactAuthenticate" />
 
+### Configuring Properties in the setAppEndpoint Method
+
 The `setAppEndpoint` method in the `rhoconnectClient` bean in the above code sample is a main point in establishing the communication 
-link between the `Rhoconnect` server and the Spring 3 MVC application. It has the following properties that you need to configure.
+link between the `Rhoconnect` server and your Java Spring 3 MVC backend application. It has the following properties that you need to configure.
 
 <table border="1">
   <tr>
-	<td><code>endpointUrl</code></td>
+	<td><code>your_rhoconnect_server_url</code></td>
 	<td>rhoconnect server's url, for example <code>http://localhost:9292</code></td>
   </tr>
   <tr>
-	<td><code>appEndpoint</code></td>
+	<td><code>app_endpoint_url</code></td>
 	<td>your Spring 3 MVC app url, for example <code>http://localhost:8080/contacts</code></td>
   </tr>
   <tr>
 	<td><code>apiToken</code></td>
-	<td>rhoconnect server's api_token, for example <code>sometokenforme</code></td>
+	<td>rhoconnect server's api_token, for example <code>rhoconnect_api_token</code></td>
   </tr>
 </table>
 
-The `authenticate` bean will be called by rhoconnect server to authenticate users, and has to implement `Rhoconnect` interface provided by rhoconnect-java plugin: 
+The `authenticate` bean will be called by the RhoConnect server to authenticate users, so it has to implement the `Rhoconnect` interface provided by the rhoconnect-java plugin: 
 
     :::java
     package com.rhomobile.rhoconnect;
@@ -150,7 +219,7 @@ The `authenticate` bean will be called by rhoconnect server to authenticate user
         String authenticate(String userName, String password, Map<String, Object> attributes);
     }
 
-For example:
+For example, in the RhoConnectJavaSample example, in `src/main/java/com/rhomobile/contact/ContactAuthenticate.java`, you can code the ContactAuthentication class as follows, replacing the TODO comment with authentication code (this example just returns "app").
 
     :::java
     package com.rhomobile.contact;
@@ -177,9 +246,9 @@ For example:
         }
     }
 
-### Establishing communication from the RhoConnect server to java back-end application
+## Establishing communication from the RhoConnect server to the java backend application
 
-You need to establish communication from the RhoConnect instance to your java back-end application by mixing RhoconnectResource interface in your data access (DAO) service class:
+You need to establish communication from the RhoConnect instance to your java backend application by mixing the RhoconnectResource interface in your data access (DAO) service class. This interface is in the Java plugin, `rhoconnect-java/src/main/java/com/rhomobile/rhoconnect/RhoconnectResource.java`. (Note that you do not change the code in `RhoconnectResource.java`.)
 
     :::java
 	package com.rhomobile.rhoconnect;
@@ -190,37 +259,84 @@ You need to establish communication from the RhoConnect instance to your java ba
 		Map<String, Object> rhoconnectQuery(String partition);
 		Integer rhoconnectCreate(String partition, Map<String, Object> attributes);
 		Integer rhoconnectUpdate(String partition, Map<String, Object> attributes);
-		Integer rhoconnetDelete(String partition, Map<String, Object> attributes);
+		Integer rhoconnectDelete(String partition, Map<String, Object> attributes);
 	}
 
-To help rhoconnect-java plugin correctly do mapping of model name to service bean you should take into account the following conventions:
+To help the rhoconnect-java plugin correctly map the model name to the service bean, you should take into account the following conventions when you write the code in your Java backend application to establish communication to the RhoConnect server:
 
-* Name of the DAO service bean (class) should be model name followed by `ServiceImpl` suffix (i. e. `ContactServiceImpl` for model `Contact`)  
-* Service bean should be auto-wired into corresponding controller via @Autowired annotation 
+* The name of the DAO service bean (class) in your java backend application should be the model name followed by `ServiceImpl` suffix (i. e. `ContactServiceImpl` for model `Contact`)  
+* The service bean should be auto-wired into the corresponding controller via @Autowired annotation 
 
 Data partitioning in your code should be based on filtering data for unique user (i.e. your user name) or per application (shared dataset for all users).
 For more information about RhoConnect partitions, please refer to the [RhoConnect docs](http://docs.rhomobile.com/rhosync/source-adapters#data-partitioning).
 
-### Establishing communication from java back-end application to the RhoConnect server
+## Establishing communication from java backend application to the RhoConnect server
+
+You must establish the communication from your java backend application to the RhoConnect server by auto-wiring the `RhoconnectClient` bean into your DAO service class and inserting notifications hooks into the data access (create/update/delete) methods. 
+
+After you generate a Sprint 3.0 MVC application, you have a DAO service class similar to the RhoconnectJavaSample file of `ContactServiceImpl.java`, located in `src/main/java/com/rhomobile/contact/service`.
+
+	:::java
+	package com.rhomobile.contact.service;
+	
+	import java.util.List;
+	
+	import org.springframework.beans.factory.annotation.Autowired;
+	import org.springframework.stereotype.Service;
+	import org.springframework.transaction.annotation.Transactional;
+	
+	import com.rhomobile.contact.dao.ContactDAO;
+	import com.rhomobile.contact.form.Contact;
+	
+	@Service
+	public class ContactServiceImpl implements ContactService {
+	
+		@Autowired
+		private ContactDAO contactDAO;
+	
+		@Transactional
+		public int addContact(Contact contact) {
+			return contactDAO.addContact(contact);
+		}
+	
+		@Transactional
+		public List<Contact> listContact() {
+			return contactDAO.listContact();
+		}
+	
+		@Transactional
+		public void removeContact(Integer id) {
+			contactDAO.removeContact(id);
+		}
+	
+		@Transactional
+		public Contact getContact(Integer id) {
+	        return contactDAO.getContact(id);
+		}
+	
+		@Transactional
+		public void updateContact(Contact contact) {
+			contactDAO.updateContact(contact);		
+		}
+	}
 
-You also must to establish the communication from your java back-end application to the RhoConnect instance by auto-wiring `RhoconnectClient` bean into your DAO service class and inserting notifications hooks into data access (create/update/delete) methods. 
 `RhoconnectClient` bean is provided by rhoconnect-java plugin and responds to the following methods you have to call:
 
 * boolean notifyOnCreate(String sourceName, Object objId, Object object)
 * boolean notifyOnUpdate(String sourceName, Object objId, Object object)
 * boolean notifyOnDelete(String sourceName, Object objId)
 
-Example for `RhoconnectJavaSample` application:
+Here is an example of how you would recode the ContactServiceImpl.java for the `RhoconnectJavaSample` application. Comments are added to show where you add new code to import libraries such as `RhoconnectClient` and `RhoconnectResource`, and where you call the notifyOnCreate, notifyOnDelete, and notifyOnUpdate methods to tell the backend about changes from the RhoConnect server, and where you implement the rhoconnectQuery, rhoconnectCreate, rhoconnectUpdate, and rhoconnectDelete methods to communicate changes in the backend to the RhoConnect server.
 
-    :::java
+	:::java
 	package com.rhomobile.contact.service;
 
-	import java.util.HashMap;
-	import java.util.Iterator;
+	import java.util.HashMap;		/* import HashMap */
+	import java.util.Iterator;		/* import Iterator */
 	import java.util.List;
-	import java.util.Map;
+	import java.util.Map;			/* import Map */
 
-	import org.apache.commons.beanutils.BeanUtils;
+	import org.apache.commons.beanutils.BeanUtils;	/* import BeanUtils */
 	import org.springframework.beans.factory.annotation.Autowired;
 	import org.springframework.stereotype.Service;
 	import org.springframework.transaction.annotation.Transactional;
@@ -228,19 +344,24 @@ Example for `RhoconnectJavaSample` application:
 	import com.rhomobile.contact.dao.ContactDAO;
 	import com.rhomobile.contact.form.Contact;
 
+	/* import RhoconnectClient bean and RhoconnectResource bean */
 	import com.rhomobile.rhoconnect.RhoconnectClient;
 	import com.rhomobile.rhoconnect.RhoconnectResource;
 
+	/* add RhoConnectResource to class implementation */
 	@Service
 	public class ContactServiceImpl implements ContactService, RhoconnectResource {
 	    //private static final Logger logger = Logger.getLogger(ContactServiceImpl.class);
 
 	    @Autowired
 	    private ContactDAO contactDAO;
+	    
+	    /* Add the RhoconnectClient bean via autowire */
 	    @Autowired
 	    private RhoconnectClient client;
 	    private static final String sourceName  = "Contact"; // name of DAO model
 
+		/* Call the notifyOnCreate method from RhoconnectClient bean to tell the backend of changes from RhoConnect server */
 	    @Transactional
 	    public int addContact(Contact contact) {
 	        int id = contactDAO.addContact(contact);
@@ -248,12 +369,14 @@ Example for `RhoconnectJavaSample` application:
 	        return id;
 	    }
 
+		/* Call the notifyOnUpdate method from RhoconnectClient bean to tell the backend of changes from RhoConnect server  */
 	    @Transactional
 	    public void updateContact(Contact contact) {
 	        contactDAO.updateContact(contact);
 	        client.notifyOnUpdate(sourceName, Integer.toString(contact.getId()), contact);       
 	    }
 
+		/* Call the notifyOnDelete method from RhoconnectClient bean to tell the backend of changes from RhoConnect server  */
 	    @Transactional
 	    public void removeContact(Integer id) {
 	        contactDAO.removeContact(id);
@@ -270,6 +393,7 @@ Example for `RhoconnectJavaSample` application:
 	        return contactDAO.getContact(id);
 	    }
 
+		/* Implement the rhoconnectQuery method to communicate query in backend to the RhoConnect server */
 	    @Override
 	    @Transactional
 	    public Map<String, Object> rhoconnectQuery(String partition) {
@@ -284,6 +408,7 @@ Example for `RhoconnectJavaSample` application:
 	        return h;
 	    }
 
+		/* Implement the rhoconnectCreate method to communicate create in backend to the RhoConnect server */
 	    @Override
 	    @Transactional
 	    public Integer rhoconnectCreate(String partition, Map<String, Object> attributes) {
@@ -298,6 +423,7 @@ Example for `RhoconnectJavaSample` application:
 	        return null;
 	    }
 
+		/* Implement the rhoconnectUpdate method to communicate updates in backend to the RhoConnect server */
 	    @Override
 	    @Transactional
 		public Integer rhoconnectUpdate(String partition, Map<String, Object> attributes) {
@@ -313,9 +439,10 @@ Example for `RhoconnectJavaSample` application:
 	        return null;
 	    }
 
+		/* Implement the rhoconnectDelete method to communicate delete in backend to the RhoConnect server */
 	    @Override
 	    @Transactional
-	    public Integer rhoconnetDelete(String partition, Map<String, Object> attributes) {
+	    public Integer rhoconnectDelete(String partition, Map<String, Object> attributes) {
 	        String objId = (String)attributes.get("id");
 	        Integer id = Integer.parseInt(objId);
 	        removeContact(id);       
@@ -323,7 +450,7 @@ Example for `RhoconnectJavaSample` application:
 	    }
 	 }
 
-Click [here](https://github.com/shurab/RhoconnectJavaPluginDemo) to download full source code of Contact manager application with rhoconnect-java plugin.
+Click [here](https://github.com/shurab/RhoconnectJavaPluginDemo) to download the full source code of a Contact manager application with rhoconnect-java plugin.
 
 ## Meta
 Created and maintained by Alexander Babichev.

data/doc/net-plugin.txt

@@ -1,11 +1,24 @@
 rhoconnect.NET
 ===
 
-A .NET 4 framework library for the [Rhoconnect](http://rhomobile.com/products/rhoconnect) App Integration Server.
+The RhoConnect-Java library is designed for the [RhoConnect](http://rhomobile.com/products/rhoconnect/) Application Integration Server.
 
-Using rhoconnect.NET, your [ASP.NET MVC](http://www.asp.net/mvc/mvc4) application's data will transparently synchronize with a mobile application built on the [Rhodes framework](http://rhomobile.com/products/rhodes), or any of the available [Rhoconnect clients](http://rhomobile.com/products/rhoconnect/).
+The .NET 4 framework library is designed for the [Rhoconnect](http://rhomobile.com/products/rhoconnect) Application Integration Server.
 
-## Getting started
+Using the rhoconnect.NET plugin, your [ASP.NET MVC](http://www.asp.net/mvc/mvc4) application's data will transparently synchronize with a mobile application built on the [Rhodes framework](http://rhomobile.com/products/rhodes), or any of the available [Rhoconnect clients](http://rhomobile.com/products/rhoconnect/).
+
+<img src='https://s3.amazonaws.com/rhodocs/rhoconnect-service/rhoconnect-plugin-net.jpg' alt='image' />
+
+## Prerequisites
+
+* Windows OS
+* .NET 4 framework
+* Git
+* [ASP.NET MVC4](http://www.asp.net/mvc/mvc4) framework
+* Visual Studio 2010
+* [`rhoconnect.NET`](https://github.com/rhomobile/rhoconnect.NET) github repository
+
+## Getting Started
 
 Copy the [`rhoconnect.NET`](https://github.com/rhomobile/rhoconnect.NET) github repository to your PC:
 
@@ -14,22 +27,74 @@ Copy the [`rhoconnect.NET`](https://github.com/rhomobile/rhoconnect.NET) github
 By default, the `rhoconnect.NET` repository contains the pre-built `RhoconnectNET.dll` library in the `bin/Release` subdirectory.
 However, you can build your own library using the provided Microsoft Visual Studio .NET solution file and the source code files. 
 
-You can download and use the sample [`ASP.NET MVC4`](https://github.com/rhomobile/RhoconnectNET_MVC4_App) application to repeat the steps described below. In addition, the above sample also contains the final code in `ContactsApp_final` subdirrectory. You can just use it (you will still need to modify the `set_app_point` with your app endpoints and add the RhoconnectNET library reference to your project.)
+## A Sample ASP.NET MVC4 Backend Application
+
+You can download and use the sample [`ASP.NET MVC4`](https://github.com/rhomobile/RhoconnectNET_MVC4_App) application to repeat the steps described below. 
+
+In addition, the sample application also contains the final code (the .NET plugin is applied to it) in its `ContactsApp_final` subdirectory. You can use this final code, but you will still need to modify the `set_app_point` with your app endpoints and add the RhoconnectNET library reference to your project.
+
+To run this application, build it in Visual Studio, create a deployment package (using Project --> Build Deployment Package), then deploy it on Microsoft's IIS server to run.
+
+<img src="http://rhodocs.s3.amazonaws.com/rhoconnect-plugin/net-backend-running.png">
+
+This sample ASP.NET MVC4 application was created using similar steps to [this tutorial to create a C# application and add support for basic database operations](http://www.asp.net/mvc/tutorials/contact-manager/iteration-1-create-the-application-cs).
+
+## Settings for the Client App
+
+Your client application needs to have its model match the model used in your Java Sprint 3.0 MVC backend application. For example, you can generate a Rhodes application for a Contact model to match the sample ASP.NET MVC4 backend application:
+
+	:::term 
+	$ rhodes app contact-app
+	$ cd contact-app
+	$ rhodes model contact lastname,firstname,email,phone
+
+Edit the `rhoconfig.txt` configuration file to point to your RhoConnect server, where <your_rhoconnect_server_url> is the url for your RhoConnect server.
+
+	:::term
+	syncserver = 'http://<your_rhoconnect_server_url>/application'
+
+And edit the `app/index.erb` view file to say Contacts.
+
+	:::html
+	...
+	<li><a href="Contact">Contacts</a></li>
+	...
+
+And edit `app/Contact/contact.rb` file to enable sync.
+
+	:::ruby
+	...
+	enable :sync
+	...
+
+## Settings for the RhoConnect Server App
+
+You must generate a RhoConnect server application and edit its settings for the RhoConnect .NET plugin.
+
+	:::term 
+	$ rhoconnect app syncserver
+	$ cd syncserver; bundle install
+
+Edit the `settings/settings.yml` development section to add an api\_token key/value pair. This value is the same as the api\_token that you will set in the `WEB-INF/spring-servlet.xml` file for your ASP.NET MVC4 backend application.
+
+	:::term
+	:development:
+	   ...
+	   :api_token: rhoconnect_api_token
+
+## Including the RhoConnect.NET Library in the Backend Application
 
 In order to use `Rhoconnect.NET` functionality in your `ASP.NET MVC` application, first you need to include the `Rhoconnect.NET` library 
-as a dependency to your application. Click `Project => Add Reference` menu item in the Visual Studio and navigate to the `RhoconnectNET.dll` library.
-After this step is completed, you can add references to the `Rhoconnect.NET` namespace into the application's and Controller's files:
+as a dependency to your application. In Visual Studio, click the `Project => Add Reference` menu item and navigate to and select the `RhoconnectNET.dll` library.
+
+After this step is completed, you can add references to the `Rhoconnect.NET` namespace into the application's and Controller's files: in the case of the ASP.NET MVC4 sample application, the files are ContactsApp/Global.asax.cs and ContactsApp/Controllers/ContactController.cs.
 
 	using RhoconnectNET;
 	using RhoconnectNET.Controllers;
-	
-
 
-## Registering Rhoconnect.NET routes for your application
+## Registering Rhoconnect.NET Routes in the Backend Application
 
-To establish the communication channel between ASP.NET MVC application and Rhoconnect server, 
-you need to implement the following `init_rhoconnect` and `rhoconnect_authenticate` methods in the `Global.asax.cs` file 
-and call them from the `Application_Start` method:
+To establish the communication channel between the ASP.NET MVC application and the Rhoconnect server, you need to implement the following `init_rhoconnect` and `rhoconnect_authenticate` methods in the ASP.NET MVC application's `Global.asax.cs` file and call them from its `Application_Start` method:
 
 	protected void Application_Start()
 	{
@@ -52,10 +117,13 @@ and call them from the `Application_Start` method:
 		// this call establishes communication between Rhoconnect and ASP.NET application
 		// as a last parameter we supply authentication routine that will called 
 		// by rhoconnect server to authenticate users.
-		RhoconnectNET.Client.set_app_endpoint("my_rhoconnect_server_url", 
-											  "my_mvc_app_root_url", 
-											  "rhoconnect_api_token", 
-											  rhoconnect_authenticate);
+		// Its parameters are the rhoconnect url, the MVC app url, 
+		//    the api_token, and the authenticate method, shown here by
+		//    <parameter_name> placeholders.
+		RhoconnectNET.Client.set_app_endpoint("<your_rhoconnect_server_url>", 
+											  "<app_endpoint_url>", 
+											  "<api_token>", 
+											  <Authenticating_Routine>);
 	}
 	
 	private bool rhoconnect_authenticate(ref String username, String password, Hashtable auth_attrs)
@@ -65,26 +133,25 @@ and call them from the `Application_Start` method:
         // perform your authentication here
         return true;
 	}
-	
-`RhoconnectNET.Client.set_app_point` method is a main point
-in establishing the communication link between `Rhoconnect` server and the ASP.NET MVC application
-and it has the following parameters:
+
+The `RhoconnectNET.Client.set_app_endpoint` method is a main point
+in establishing the communication link between the `Rhoconnect` server and the ASP.NET MVC application. It has the following parameters that you need to set.
 
 <table border="1">
 	<tr>
 		<td>String</td>
-		<td><code>rhoconnect_url</code></td>
-		<td>rhoconnect server's url, for example <code>http://localhost:9292</code>.</td>
+		<td><code>your_rhoconnect_server_url</code></td>
+		<td>The RhoConnect server's url, for example <code>http://localhost:9292</code>.</td>
 	</tr>
 	<tr>
 		<td>String</td>
-		<td><code>app_endpoint</code></td>
+		<td><code>app_endpoint_url</code></td>
 		<td>your MVC app url, for example <code>http://my_pc_host/MyApp</code>.</td>
 	</tr>
 	<tr>
 		<td>String</td>
 		<td><code>api_token</code></td>
-		<td>rhoconnect server's api_token, for example <code>secrettoken</code>.</td>
+		<td>rhoconnect server's api_token, for example <code>rhoconnect_api_token</code>.</td>
 	</tr>
 	<tr>
 		<td>delegate rhoAuthHandler(ref String, String, Hashtable, bool)</td>
@@ -93,9 +160,10 @@ and it has the following parameters:
 	</tr>
 </table>
 
-`Rhoconnect.NET` installs a `/rhoconnect/authenticate` route into your application which will receive credentials from the client.  
-By providing the `rhoconnect_authenticate` method and registering it with the `Rhoconnect.NET` in the `set_app_endpoint`
-method, you map your application specific authentication to the Rhoconnect `authenticate` requests:
+## Implementing the Backend Application's Authenticate Method
+
+`Rhoconnect.NET` installs a `/rhoconnect/authenticate` route into your application which will receive credentials from the client. In the ASP.NET MVC application's `Global.asax.cs` file, you can provide the `rhoconnect_authenticate` method and register it with the `Rhoconnect.NET` in the `set_app_endpoint`
+method; this maps your application specific authentication to the Rhoconnect `authenticate` requests:
 
 	private bool rhoconnect_authenticate(ref String username, String password, Hashtable auth_attrs)
 	{
@@ -106,45 +174,49 @@ method, you map your application specific authentication to the Rhoconnect `auth
 	}
 	
 If you want your data to be partitioned by 'app' (i.e. the data will be shared among all users), you can replace
-the provided `username` parameter (which is passed by reference) to `app` - which will instruct Rhoconnect to partition
-the data accordingly. 
+the provided `username` parameter (which is passed by reference) to `app` - which will instruct Rhoconnect to partition the data accordingly. 
+
+## Establishing Communication from the RhoConnect Server to the Backend Application
 
-## Implementing CRUD functionality
-`Rhoconnect.NET` lib installs `/rhoconnect/<CRUD>` routes in your application which the Rhoconnect instance 
-invokes to perform CRUD operations on the data for the dataset you want to synchronize.
+The `Rhoconnect.NET` lib installs `/rhoconnect/<CRUD>` routes in your application which the Rhoconnect server instance invokes to perform CRUD operations on the data for the dataset you want to synchronize.
 Each of the routes is mapped to a corresponding `rhoconnect_<operation>` method in the **IRhoconnectCRUD** interface
 which you must implement in the dataset's Controller class.
 
+In the case of the sample ASP.NET MVC application, you implement these methods in `ContactsApp/Controllers/ContactController.cs`. You could start with code like this:
+
 		public class ContactController : Controller, IRhoconnectCRUD
 		{
 			... implementation of Controller routes
 	
-			// next four methods must be implemented
-			// and will be called by Rhoconnect server
+			// You must implement the next four methods
+			// These methods will be called by the Rhoconnect server
 			JsonResult rhoconnect_query_objects(String partition);
 			ActionResult rhoconnect_create(String objJson, String partition);
 			ActionResult rhoconnect_update(Dictionary<string, object> changes, String partition);
 			ActionResult rhoconnect_delete(Object objId, String partition);
-		} 
+		}
+
+And you will implement the rhoconnect_query_objects, rhoconnect_create, rhoconnect_update, and rhoconnect_delete methods.
+
+### Implement rhoconnect_query_objects to Query the Datasets
 
-## Query the datasets
-The route `/rhoconnect/query` is mapped to the `rhoconnect_query_objects` method of the **IRhoconnectCRUD**
-interface that you must implement in the corresponding dataset's Controller class. It must
-return a collection of source objects in the form of a JsonResult:
+The route `/rhoconnect/query` is mapped to the `rhoconnect_query_objects` method of the **IRhoconnectCRUD** interface. You must implement this method in the corresponding dataset's Controller class. It must return a collection of source objects in the form of a JsonResult.
+
+In the case of the sample ASP.NET MVC application, you could implement this method in the `ContactsApp/Controllers/ContactController.cs` file as follows:
 		
 		public JsonResult rhoconnect_query_objects(String partition)
 		{
 			return Json(db.Contacts.ToDictionary(c => c.ID.ToString()));
 		}
 	
-In the above example, the Contacts Db set is converted to `Dictionary<String, Object>`
-where the dictionary's key must correspond to an unique object's `ID` field.
-After dictionary is created , it is converted to JsonResult and sent to the Rhoconnect server.
+In the above example, the Contacts Db set is converted to `Dictionary<String, Object>` where the dictionary's key must correspond to an unique object's `ID` field.
+After the dictionary is created, it is converted to a JsonResult and sent to the Rhoconnect server.
+
+### Implement rhoconnect_create to Create New Objects
+
+The route `/rhoconnect/create` is mapped to the `rhoconnect_create` method of the IRhoconnectCRUD interface that you must implement in the corresponding dataset's Controller class. It should return a newly created object's id in case of success.
 
-## Create new objects
-The route `/rhoconnect/create` is mapped to the `rhoconnect_create` method of the IRhoconnectCRUD
-interface that you must implement in the corresponding dataset's Controller class. It should
-return a newly created object's id in case of success:
+In the case of the sample ASP.NET MVC application, you could implement this method in the `ContactsApp/Controllers/ContactController.cs` file as follows:
 
 		public ActionResult rhoconnect_create(String objJson, String partition)
         {
@@ -154,10 +226,12 @@ return a newly created object's id in case of success:
             return RhoconnectNET.Helpers.serialize_result(new_contact.ID);
         }
 	
-## Update existing objects
+### Implement rhoconnect_update to Update Existing Objects
+
 In the similar fashion, the route `/rhoconnect/update` is mapped to the `rhoconnect_update` method of the IRhoconnectCRUD
-interface that you must implement in the corresponding dataset's Controller class. It should
-return an updated object's id in case of success:
+interface that you must implement in the corresponding dataset's Controller class. It should return an updated object's id in case of success.
+
+In the case of the sample ASP.NET MVC application, you could implement this method in the `ContactsApp/Controllers/ContactController.cs` file as follows:
 
 		public ActionResult rhoconnect_update(Dictionary<string, object> changes, String partition)
         {
@@ -170,10 +244,11 @@ return an updated object's id in case of success:
             return RhoconnectNET.Helpers.serialize_result(contact_to_update.ID); 
         }
 
-## Delete objects from the dataset
-The route `/rhoconnect/delete` is mapped to the `rhoconnect_delete` method of the IRhoconnectCRUD
-interface that you must implement in the corresponding dataset's Controller class. It should
-return a deleted object's id in case of success:
+### Implement rhoconnect_delete to Delete Objects from the Dataset
+
+The route `/rhoconnect/delete` is mapped to the `rhoconnect_delete` method of the IRhoconnectCRUD interface that you must implement in the corresponding dataset's Controller class. It should return a deleted object's id in case of success.
+
+In the case of the sample ASP.NET MVC application, you could implement this method in the `ContactsApp/Controllers/ContactController.cs` file as follows:
 
         public ActionResult rhoconnect_delete(Object objId, String partition)
         {
@@ -185,21 +260,21 @@ return a deleted object's id in case of success:
             return RhoconnectNET.Helpers.serialize_result(key);
         }
 
-## Partitioning Datasets
+### Partitioning Datasets
+
 Each of the above methods have a partition key supplied with the CRUD request.	This partition key is used by `Rhoconnect` to uniquely identify the model dataset when it is stored in a rhoconnect instance.  It is typically an attribute on the model or related model.  `Rhoconnect` supports two types of partitions:
 
 * app - No unique key will be used, a shared dataset is synchronized for all users.
 * String partition key - unique key string identifying the partition (typically, user name).
 
-For example, the `Contact` model above might have a relationship to the User model.  This provides us a simple way to organize the `Contact` dataset for rhoconnect by reusing this relationship.  
+For example, the `Contact` model above might have a relationship to the User model. This provides us a simple way to organize the `Contact` dataset for rhoconnect by reusing this relationship.  
 In this case, your implementation might filter out data on a per user basis.
 	
 For more information about Rhoconnect partitions, please refer to the [Rhoconnect docs](http://docs.rhomobile.com/rhoconnect/source-adapters#data-partitioning).
 
-## Implementing MVC callbacks
-All of the above methods are necessary to establish the communication from the Rhoconnect instance to your ASP.NET MVC application. 
-However, to complete the implementation, it is necessary to implement a reverse way to notify the Rhoconnect instance about the changes made in your MVC app.
-Typically, your MVC Controller class reacts to the actions by implementing the CRUD POST routes, for example:
+## Notifying the RhoConnect Server of Changes Made by the Backend Application
+
+You must implement methods to notify the Rhoconnect server instance about the changes made in your MVC backend application. Typically, your MVC Controller class reacts to the actions by implementing the CRUD POST routes, for example:
 
 		[HttpPost]
 		public ActionResult Create(Contact new_contact)
@@ -214,9 +289,13 @@ Typically, your MVC Controller class reacts to the actions by implementing the C
             return View(new_contact);
         }
 
-Here, you need to insert a call which will notify the Rhoconnect instance that a new object has been created.
-For this reason, `RhoconnectNET` library provides three callback routines for CUD notifications.
-The above example will look like this after inserting the corresponding callback routine:
+You need to insert calls in your ASP.NET MVC application which will notify the Rhoconnect server instance that the backend created, updated, or deleted an object. For this reason, the `RhoconnectNET` library provides three callback routines for CUD notifications: `notify_on_create`, `notify_on_update`, and `notify_on_delete`.
+
+### Notifying the RhoConnect Server that the Backend Created a New Object
+
+You need to insert a call to `notify_on_create` to notify the Rhoconnect server instance that a new object has been created.
+
+The previous example for ActionResult Create will look like this after inserting the corresponding callback routine:
 
 		// This method is used to access current partition
 		// in Rhoconnect notification callback
@@ -246,8 +325,7 @@ The above example will look like this after inserting the corresponding callback
             return View(contact);
         }
 
-In the example above, user need to call `RhoconnectNET.Client.notify_on_create` method 
-with the following parameters:
+In the example above, you need to call the `RhoconnectNET.Client.notify_on_create` method with the following parameters:
 
 <table border="1">
 	<tr>
@@ -263,25 +341,27 @@ with the following parameters:
 	</tr>
 </table>
 
-NOTE: The above notification callback has several overloads. In its simplest form, 
+### Overriding To Pass Information Into the notify_on_create Callback Method
+
+The above notification callback has several overloads. In its simplest form, the
 `notify_on_create` callback will obtain information about the source name from the `Contact` object
 class name (since it is equal) and will get the `id` field from the object itself. If your model
-stores `id` field under the custom name, then, you can use the following override to pass its name into
+stores `id` field under the custom name, then you can use the following override to pass its name into
 the callback, where its value will be accessed through the Reflection mechanism:
 
 		// insert these lines to provide
         // notifications to Rhoconnect server
         RhoconnectNET.Client.notify_on_create(partition(), "MyContactCustomID", contact);
 
-In addition to that, if your model's class is not equal to the Rhoconnect's Source Adapter name, you can
-use the following override to pass it along:
+In addition, if your model's class is not equal to the Rhoconnect's Source Adapter name, you can use the following override to pass it along:
 
 		// insert these lines to provide
         // notifications to Rhoconnect server
         RhoconnectNET.Client.notify_on_create("MyCustomContactSourceName", partition(), "MyContactCustomID", contact);
-		
 
-In the same fashion , your dataset's Controller need to implement `Edit` and `Delete` callback notifications:
+### Notifying the RhoConnect Server that the Backend Application Edited or Deleted
+
+In the same fashion, your dataset's Controller need to implement `Edit` and `Delete` callback notifications.
 
 		[HttpPost]
         public ActionResult Edit(Contact contact)