rhoconnect 3.0.5 → 3.0.6

data/doc/client.txt

@@ -83,6 +83,20 @@ Rhoconnect Client is a library to add sync data capability to your applications.
     - (void) clearObjectNotification;
     //add object to track changes: create, update, delete
     - (void) addObjectNotify: (int) nSrcID szObject:(NSString*) szObject;
+
+    //To process 'create-error' errors from server:
+    //Action may be "delete" or "recreate"
+    //"delete" just remove object from client, "recreate" will push this object to server again at next sync.
+    - (void) onCreateError: (RhoConnectNotify*)notify action: (NSString*)action;
+
+    //To process 'update-error' errors from server:
+    //Action may be "retry" or "rollback". 
+    //"retry" will push update object operation to server again at next sync, "rollback" will write rollback objects(comes from server) to client database.
+    - (void) onUpdateError: (RhoConnectNotify*)notify action: (NSString*)action;
+
+    //To process 'delete-error' errors from server:
+    //Action may be "retry" - will push delete object operation to server again at next sync.
+    - (void) onDeleteError: (RhoConnectNotify*)notify action: (NSString*)action;
     
 #### RhomModel
 
@@ -151,6 +165,11 @@ This class provides access to sync notification objects as describe [here](/rhod
 	@property(assign) NSString* error_message;
 	@property(assign) NSString* callback_params;
 
+    - (Boolean) hasCreateErrors;
+    - (Boolean) hasUpdateErrors;
+    - (Boolean) hasDeleteErrors;
+    - (Boolean) isUnknownClientError;
+
 #### RhoConnectObjectNotify
 
 This class provides access to sync object notification as describe [here](/rhodes/synchronization#notifications): 
@@ -192,6 +211,7 @@ See [rhoconnect-client\Samples\ObjectiveC\store](http://github.com/rhomobile/rho
 
 #### Initialization of Schema model
 
+	:::cplusplus
 	RhomModel* product = [[RhomModel alloc] init];
 	product.name = @"Product_s";
     product.model_type = RMT_PROPERTY_FIXEDSCHEMA;
@@ -203,9 +223,13 @@ To create schema model tables edit database schema file:
 * Edit file syncdb.schema : add create table statment for each schema model. Note that mandatory object column should be in each table:
 
     "object" varchar(255) PRIMARY KEY
+
+** NOTE: Do not use NOT NULL statement in column definitions. RhoConnect client delete object attributes by setting value to null, when all object attributes become nulls, object deleted. So objects with NOT NULL columns will not be deleted. **
+
     
 * Open 'Copy bundle resources' build phase in project target and point it to local project db folder
 
+
 #### Login
 
 	:::cplusplus
@@ -241,6 +265,114 @@ To create schema model tables edit database schema file:
 	
     [sclient addObjectNotify: [[item objectForKey:@"source_id"] intValue] szObject:[item valueForKey:@"object"] ];
 
+#### Processing unknown-client error
+Unknown client error return by server after resetting server database, removing particular client id from database or any other cases when server cannot find client id(sync server unique id of device).
+Note that login session may still exist on server, so in this case client does not have to login again, just create new client id.
+Processing of this error contain 2 steps:
+
+* When unknown client error is come from server, client should call database_client_reset and start new sync, to register new client id.
+
+* If login session also deleted or expired on the server, then customer has to login again.
+
+Example:
+	:::cplusplus
+	
+    - (void)syncAllCalback:(RhoConnectNotify*) notify
+    {
+        NSString* status = notify.status;
+        NSString* error = notify.error_message;
+        int err_code = notify.error_code;
+        
+        NSLog(@"syncAll DONE, status: '%s' , error_msg: '%s' , error_code: %d",
+              [status cStringUsingEncoding: NSUTF8StringEncoding],
+              [error cStringUsingEncoding: NSUTF8StringEncoding],
+              err_code
+              );
+        
+	    if ( [notify.status compare:@"in_progress"] == 0) {
+            
+	    } else if ([notify.status compare:@"complete"] == 0) {
+            
+		    [[RhoConnectEngine sharedInstance].syncClient clearNotification];
+            
+	    } else if ([notify.status compare:@"error"] == 0) {
+            
+	            if([notify isUnknownClientError]) {
+	                [[RhoConnectEngine sharedInstance].syncClient database_client_reset]; 
+	                [[RhoConnectEngine sharedInstance].syncClient setNotification: @selector(syncAllCalback:) target:self];
+	                [[RhoConnectEngine sharedInstance].syncClient syncAll];
+	            } else if( err_code == RHO_ERR_CLIENTISNOTLOGGEDIN
+	                    || err_code == RHO_ERR_UNATHORIZED) {
+    	
+	                NSLog(@"GO TO LOGIN PAGE!");
+	                // real code to trigger view transition goes here.. 
+	            }
+	    }
+    }
+    
+#### Processing server errors
+* create-error: 
+has to be handled in sync callback. Otherwise sync will stop on this model. To fix create errors you should call Model.on_sync_create_error or SyncEngine.on_sync_create_error:
+
+* update-error:
+If not handled, local modifications, which were failing on server, will never sync to server again.
+So sync will work fine, but nobody will know about these changes.
+
+* delete-error:
+If not handled, local modifications, which were failing on server, will never sync to server again.
+So sync will work fine, but nobody will know about these changes.
+
+Example:
+	:::cplusplus
+	
+    - (void)syncAllCalback:(RhoConnectNotify*) notify
+    {
+        NSString* status = notify.status;
+        NSString* error = notify.error_message;
+        int err_code = notify.error_code;
+        
+        NSLog(@"syncAll DONE, status: '%s' , error_msg: '%s' , error_code: %d",
+              [status cStringUsingEncoding: NSUTF8StringEncoding],
+              [error cStringUsingEncoding: NSUTF8StringEncoding],
+              err_code
+              );
+        
+	    if ( [notify.status compare:@"in_progress"] == 0) {
+            
+	    } else if ([notify.status compare:@"complete"] == 0) {
+            
+		    [[RhoConnectEngine sharedInstance].syncClient clearNotification];
+            
+	    } else if ([notify.status compare:@"error"] == 0) {
+            
+            if([notify isUnknownClientError]) {
+                [[RhoConnectEngine sharedInstance].syncClient database_client_reset]; 
+                [[RhoConnectEngine sharedInstance].syncClient setNotification: @selector(syncAllCalback:) target:self];
+                [[RhoConnectEngine sharedInstance].syncClient syncAll];
+            } else if( err_code == RHO_ERR_CLIENTISNOTLOGGEDIN
+                || err_code == RHO_ERR_UNATHORIZED) {
+
+                NSLog(@"GO TO LOGIN PAGE!");
+                // real code to trigger view transition goes here.. 
+            }else
+            {
+                //This is mandatory:
+                if([notify hasCreateErrors]) {
+                    [[RhoConnectEngine sharedInstance].syncClient onCreateError: notify action:@"delete"];        
+                }
+                //These are optional:
+                /*
+                if([notify hasUpdateErrors]) {
+                    [[RhoConnectEngine sharedInstance].syncClient onUpdateError: notify action:@"rollback"];        
+                }
+                if([notify hasDeleteErrors]) {
+                    [[RhoConnectEngine sharedInstance].syncClient onDeleteError: notify action:@"retry"];        
+                }
+                */
+            }
+	    }
+    }
+    
 #### Run SQL query on Schema model
 
 	:::cplusplus

data/doc/extending-rhoconnect-server.txt

@@ -0,0 +1,79 @@
+Extending Rhoconnect Application with custom routes
+===
+
+Extending Rhoconnect Application with custom routes
+---
+
+You can provide custom routes support in your Rhoconnect application while you still fully utilize the powerful features provided by the default Rhoconnect server implementation. To do this, create a custom server class inherited from `Rhoconnect::Server` and define all of your custom routes in this extended server class.
+
+The following example illustrates how to add a sample `my_custom_route' to the existing Rhoconnect application.
+
+1) create `my_server.rb` class in your Rhoconnect application's root directory:
+
+	:::ruby
+	class MyServer < Rhoconnect::Server
+	  get '/my_custom_route' do
+	    if current_user
+	      send_file 'public/my_file.png'
+	    end
+	    nil
+	  end
+	end
+
+The above custom route implementation will respond to client's GET request, verifies the current_user (which will be extracted from the Rhoconnect session cookie)
+and returns a static PNG file (which can be later used in BLOB syncs)
+
+
+2) Replace the default server instance with the new extended one in the `config.ru` file of your Rhoconnect application:
+
+	:::ruby
+	# Setup the url map
+	run Rack::URLMap.new \
+		"/"         => MyServer.new,
+		"/resque"   => Resque::Server.new, # If you don't want resque frontend, disable it here
+		"/console"  => RhoconnectConsole::Server.new # If you don't want rhoconnect frontend, disable it here
+		
+
+Using the New Custom route in BLOB syncs
+---
+
+After you create the new custom routes and replace the default server instance with the new extended one, you can reference and use them from standard Rhodes applications.
+For example, suppose you have a Rhodes app with a Product model. To use a custom route in BLOB syncs, define the following property in the Rhodes Product model (file: `app/Product/product.rb`):
+
+	:::ruby
+	# The model has already been created by the framework, and extends Rhom::RhomObject
+	# You can add more methods here
+	class Product
+	  include Rhom::PropertyBag
+
+	  # Uncomment the following line to enable sync with Product.
+	  enable :sync
+
+	  #add model specifc code here
+	  property :my_custom_blob_field, :blob, :overwrite 
+	end
+	
+To see the static image, modify the `app/Product/show.erb` file for the Product model in your Rhodes application:
+
+	:::html
+	<li>
+        <div class="itemLabel">My Static Field Image</div>
+        <div class="itemValue"><img src="<%=Rho::RhoApplication::get_blob_path(@product.my_custom_field)%>"></img></div>
+    </li>
+	
+Then, modify your Rhoconnect source adapter (in `rhoconnect_app/sources/product.rb`) to provide BLOB's url for the `my_custom_blob_field`:
+
+	:::ruby
+	def query(params=nil)
+    	parsed = JSON.parse(RestClient.get("#{@base}.json").body)
+
+	    @result={}
+	    parsed.each do |item|
+	      item["product"]["my_custom_field-rhoblob"] = "http://localhost:9292/my_custom_route"
+	      @result[item["product"]["id"].to_s] = item["product"]
+	    end if parsed    
+  	end
+
+This way, your `my_custom_field` would be getting the BLOB image data from the custom route defined in your Rhoconnect extension server.
+
+For more information on BLOB syncs, see [this section](http://docs.rhomobile.com/rhoconnect/blob-sync). 

data/doc/install.txt

@@ -17,7 +17,7 @@ You can now skip to the [generating a new application instructions](/rhoconnect/
 
 3. Ruby Web Server - We test with [thin](http://code.macournoyer.com/thin/), and [passenger](http://www.modrails.com/).  WEBrick, the web server that ships with ruby, is known to cause issues with HTTP headers/cookies and is ***not*** recommended.
 
-4. [Redis 2.4.1+](http://redis.io/) - RhoConnect includes a simple [rake task](/rhoconnect/command-line#rake-tasks) `redis:install` to install redis, covered in the [Rake Tasks section](/rhoconnect/command-line#rake-tasks). Alternatively, you can [install redis directly](http://redis.io/download).
+4. [Redis 2.4.x](http://redis.io/) - RhoConnect includes a simple [rake task](/rhoconnect/command-line#rake-tasks) `redis:install` to install redis, covered in the [Rake Tasks section](/rhoconnect/command-line#rake-tasks). Alternatively, you can [install redis directly](http://redis.io/download).
 
 ### Installing RhoConnect Gem
 

data/doc/java-plugin.txt

@@ -0,0 +1,291 @@
+RhoConnect-Java
+===
+
+RhoConnect-Java library is designed for the [RhoConnect](http://rhomobile.com/products/rhoconnect/) App Integration Server.
+
+Using the RhoConnect-Java plugin, your [Spting 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/).
+
+## 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.
+
+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.
+
+### Adding Dependencies to Your Maven 2 Project
+
+Add dependencies to your Apache Maven 2 project object model (POM): apache common beanutils, and Jackson JSON mapper. In the RhoconnectJavaSample application, this code is in the pom.xml file.
+
+    :::xml
+    <!-- apache commons beanutils -->  
+    <dependency>  
+        <groupId>commons-beanutils</groupId>  
+    	<artifactId>commons-beanutils</artifactId>  
+        <version>1.8.3</version>  
+    </dependency>
+    <!-- Jackson JSON Mapper -->  
+    <dependency>  
+        <groupId>org.codehaus.jackson</groupId>  
+        <artifactId>jackson-mapper-asl</artifactId>  
+        <version>1.9.0</version>  
+        <type>jar</type>  
+        <optional>false</optional>  
+    </dependency>  
+
+### Updating Your Servlet XML Configuration File
+
+Update your servlet xml configuration file to include rhoconnect-java metadata: the packages, converters, and beans. In the RhoconnectJavaSample, this code is in comments in the src/main/webapp/WEB-INF/spring-servlet.xml file.
+
+    :::xml
+    <!-- rhoconnect-java plugin packages -->
+    <context:component-scan base-package="com.rhomobile.rhoconnect.controller" /> 
+
+    <!-- rhoconnect-java plugin converters -->
+    <bean class="org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter">
+     	<property name="order" value="1" />
+     	<property name="messageConverters">
+         	<list>
+             	<ref bean="stringHttpMessageConverter"/>
+             	<ref bean="jsonConverter" />
+         	</list>
+     	</property>
+    </bean>
+
+    <bean id="jsonConverter" class="org.springframework.http.converter.json.MappingJacksonHttpMessageConverter">
+     	<property name="supportedMediaTypes" value="application/json" />
+    </bean>
+
+    <bean id="stringHttpMessageConverter" class="org.springframework.http.converter.StringHttpMessageConverter">
+    </bean>
+    
+    <bean id="restTemplate" class="org.springframework.web.client.RestTemplate">
+     	<property name="messageConverters">
+         	<list>
+             	<ref bean="jsonConverter" />
+             	<ref bean="stringHttpMessageConverter"/>
+         	</list>
+     	</property>
+    </bean>    
+
+    <!-- rhoconnect-java plugin beans -->
+    <bean id="rhoconnect" class = "com.rhomobile.rhoconnect.RhoconnectImpl" />
+    
+    <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" />
+    </bean>
+
+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.
+
+<table border="1">
+  <tr>
+	<td><code>endpointUrl</code></td>
+	<td>rhoconnect server's url, for example <code>http://localhost:9292</code>.</td>
+  </tr>
+  <tr>
+	<td><code>appEndpoint</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>
+  </tr>
+</table>
+
+
+### Adding rhoconnect-java to the Build Path
+
+You must add the rhoconnect-java jar to your apache maven 2 build classpath. In the RhoconnectJavaSample application, you would add this code to the pom.xml file, putting in the path to your rhoconnect-java jar into the systemPath.
+
+    :::xml
+    <dependency>
+        <groupId>rhoconnect-java</groupId>
+        <artifactId>rhoconnect-java</artifactId>
+        <version>0.0.1</version>
+        <scope>system</scope>
+        <!-- Set absolute path to your rhoconnect-java jar -->
+        <systemPath>/path-to-jar-directory/rhoconnect-java-0.0.1.jar</systemPath> 
+    </dependency>
+
+
+### Establishing communication from the RhoConnect server to java back-end application
+
+You need to establish communication from the RhoConnect instance to your java back-end application by implementing Rhoconnect interface.
+
+    :::java
+    package com.rhomobile.rhoconnect;
+    import java.util.Map;
+
+    public interface Rhoconnect {
+        boolean authenticate(String login, String password, Map<String, Object> attribures);
+        
+        Map<String, Object> query_objects(String resource, String partition);
+        Integer create(String resource, String partition, Map<String, Object> attributes);
+        Integer update(String resource, String partition, Map<String, Object> attributes);
+        Integer delete(String resource, String partition, Map<String, Object> attributes);
+    }
+
+For example, `RhoconnectJavaSample` application implementation is based on `contactService` API:
+
+    :::java
+    /**
+    * RhoconnectImpl.java 
+    */
+    package com.rhomobile.rhoconnect;
+
+    import java.util.HashMap;
+    import java.util.Iterator;
+    import java.util.List;
+    import java.util.Map;
+
+    import org.apache.commons.beanutils.BeanUtils;
+    import org.springframework.beans.factory.annotation.Autowired;
+
+    import com.rhomobile.contact.form.Contact;
+    import com.rhomobile.contact.service.ContactService;
+
+    public class RhoconnectImpl implements Rhoconnect {
+
+        @Autowired
+        private ContactService contactService;	
+
+        @Override
+        public boolean authenticate(String login, String password, Map<String, Object> attribures) {
+            // TODO: your authentication code goes here ...
+            return true;
+        }
+	
+        @Override
+        public Map<String, Object> query_objects(String resource, String partition) {
+            Map<String, Object> h = new HashMap<String, Object>();
+            List<Contact> contacts =  contactService.listContact();		
+            Iterator<Contact> it = contacts.iterator( );
+            while(it.hasNext()) {
+                Contact c =(Contact)it.next();
+          	    h.put(c.getId().toString(), c);
+            }
+            return h;
+        }
+
+        @Override
+        public Integer create(String resource, String partition, Map<String, Object> attributes) {
+            Contact contact = new Contact();
+            try {
+                BeanUtils.populate(contact, attributes);
+                int id = contactService.addContact(contact);
+                return id;
+            } catch(Exception e) {
+                e.printStackTrace();
+            }
+            return null;
+        }
+
+        @Override
+        public Integer update(String resource, String partition, Map<String, Object> attributes) {
+            Integer id = Integer.parseInt((String)attributes.get("id"));
+            Contact contact = contactService.getContact(id);
+            try {
+                BeanUtils.populate(contact, attributes);
+    		    contactService.updateContact(contact);
+    		    return id;
+            } catch(Exception e) {
+                e.printStackTrace();
+            }
+            return null;
+        }
+
+        @Override
+        public Integer delete(String resource, String partition, Map<String, Object> attributes) {
+            String objId = (String)attributes.get("id");
+            Integer id = Integer.parseInt(objId);
+            contactService.removeContact(id);		
+            return id;
+        }
+    }
+
+### Establishing communication from java back-end application to the RhoConnect server
+
+You also must to establish the communication from your java back-end application to the RhoConnect instance by autowiring your data access (DAO) service layer with RhoconnectClient bean and inserting notifications hooks there.
+
+    :::java
+    package com.rhomobile.rhoconnect;
+    
+    public class RhoconnectClient {
+        // ...
+        public boolean notifyOnCreate(String sourceName, String partition, Object objId, Object object);
+        public boolean notifyOnUpdate(String sourceName, String partition, Object objId, Object object);
+        public boolean notifyOnDelete(String sourceName, String partition, Object objId);
+        // ...
+    }
+
+For example, `RhoconnectJavaSample` application uses the following implementation:
+
+    :::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;
+
+    import com.rhomobile.rhoconnect.RhoconnectClient;
+    //import org.apache.log4j.Logger;
+
+    @Service
+    public class ContactServiceImpl implements ContactService {
+
+        @Autowired
+        private ContactDAO contactDAO;
+
+        @Autowired
+        private RhoconnectClient client;
+
+        //private static final Logger logger = Logger.getLogger(ContactServiceImpl.class);
+
+        private static final String sourceName  = "Contact"; // name of DAO model
+        
+        // Data partitioning: i.e. your user name for filtering data on per user basis 
+        private static final String partition  = "your_partition";
+	
+        @Transactional
+        public int addContact(Contact contact) {
+            int id = contactDAO.addContact(contact);
+            client.notifyOnCreate(sourceName, partition, Integer.toString(id), contact);
+            return id;
+        }
+
+        @Transactional
+        public void updateContact(Contact contact) {
+            contactDAO.updateContact(contact);
+            client.notifyOnUpdate(sourceName, partition, Integer.toString(contact.getId()), contact);		
+        }
+
+        @Transactional
+        public void removeContact(Integer id) {
+            contactDAO.removeContact(id);
+            client.notifyOnDelete(sourceName, partition, Integer.toString(id));
+        }
+
+        @Transactional
+        public List<Contact> listContact() {
+            return contactDAO.listContact();
+        }
+
+        @Transactional
+        public Contact getContact(Integer id) {
+            return contactDAO.getContact(id);
+        }
+     }
+
+For more information about RhoConnect partitions, please refer to the [RhoConnect docs](http://docs.rhomobile.com/rhosync/source-adapters#data-partitioning).
+
+
+## Meta
+Created and maintained by Alexander Babichev.
+
+Released under the [MIT License](http://www.opensource.org/licenses/mit-license.php).

data/doc/rest-api.txt

@@ -337,6 +337,7 @@ Return content of a given document (client or source).
 
 ### `set_db_doc`
 Sets the content of the specified server document. Data should be either a string or hash of hashes. Data type should be set accordingly.
+If `append` flag is set to `true` , the data is appended to the current doc (if it exists) instead of replacing it.
 
 	:::ruby
 	RestClient.post(
@@ -345,7 +346,8 @@ Sets the content of the specified server document. Data should be either a strin
 		:api_token => token, 
 		:doc => doc, 
 		:data => data, 
-		:data_type => data_type 
+		:data_type => data_type,
+		:append => false
 	  }.to_json, 
 	  :content_type => :json
     )