Export

RushOrm can export your RushObjects to JSON

              	
    List<ExampleObject> objects;

    /* Create json string from objects */
    String jsonString = RushCore.getInstance().serialize(objects);

    /* Below is an example of the JSON structure that is produced. 
        The name of the root element can be changed from the class 
        name by adding @RushClassSerializationName annotation to the class */
	
    {
    	"co.uk.rushexample.testobjects.TestObject": [
        {
            	"rush_id": "35c4b394-49db-45e1-bb0f-9de7ac788e07",
            	"rush_version": 1,
            	"stringField": "string",
            	"doubleField": "0.0",
            	"intField": "0",
            	"longField": "0",
            	"shortField": "0",
            	"booleanField": "false",
            	"dateField":"1424625767166",      
            	"childObject": {
                	"rush_id": "90a68ea5-bbcf-4e22-b835-1a0f7c72594c",
                	"rush_version": 1,
                	"stringField": "string",
            		"doubleField": "0.0",
            		"intField": "0",
            		"longField": "0",
            		"shortField": "0"
            	}    	            	            	
         } ,
         {
            	"rush_id": "925d4a4d-dbf1-4f90-8257-d249233305c0",
            	"rush_version": 1,
            	"stringField": "string",
            	"doubleField": "0.0",
            	"intField": "0",
            	"longField": "0",
            	"shortField": "0",
            	"booleanField": "false",   	            	            	
         }]
    }
    
    
					
				

Import

RushOrm can import your RushObejcts from JSON

              	

    /* Create objects from JSON string */
    List<Rush> objects jsonString = RushCore.getInstance().deserialize(jsonString);

    /* The JSON format must match the export format */

    /* Once imported the object still need to be saved.
        Using this method rather than another library registers 
        the rush_id and rush_version with RushCore so that when
        saved the objects will update any objects already in the
        database with the same id. If your objects are deserialize
        in another way RushOrm will treat them as new objects */

					
				

Conflicts

RushOrm uses object versioning to detect Conflicts

              	

    /* RushOrm classes an object in conflict if its version number 
        is below that in the database. Every time an object is saved 
        it's version number is increased. If an object can be saved
        from multiple places without being reloaded checking for conflicts
        may be helpful. The main reason for checking for conflicts is if
        your data is shared between devices, using export and import. */
        
    List<Rush> objects jsonString = RushCore.getInstance().deserialize(jsonString);

    List<RushConflict> conflicts = RushCore.getInstance().saveOnlyWithoutConflict(objects);

    List<Rush> resolvedObjects = new ArrayList<>(); 
    for(RushConflict conflict : conflicts) {
        Rush toBeSaved = conflict.getToBeSaved();
        Rush inDataBase = conflict.getInDataBase();
        /* Pick which one you want or perform any logic to combined changes */
			
        if(/* Picked toBeSaved */) {
            conflict.resolve();
            resolvedObjects(toBeSaved);
        }
    }
    /* If you are worried the objects in the database 
        could have been updated during the resolution process
        you can repeat saveOnlyWithoutConflict if not just call save */
    
    List<RushConflict> conflicts = RushCore.getInstance().saveOnlyWithoutConflict(objects);

    /* Note saveOnlyWithoutConflict is far slower than save
        so should only be used if you care about conflicts */
					
				

Transitions

Objects and their children are saved in transitions by default but lists of RushObjects can also be saved in a transition.

              	
    List<ExampleObject> objects;

    /* Save synchronously */
    RushCore.getInstance().save(objects);

    /* Save asynchronously */
    RushCore.getInstance().save(objects, new RushCallback() {
        @Override
        public void complete() {
            /* Callback is on the thread objects where saved on, 
                not thread that called save */
        }
    });
					
				

Upgrading

When an upgrade is run, RushOrm difs the new class structure against the database, updating the database as required. This include creating new tables and fields then removing old ones. In debug mode RushOrm will perform an upgrade on ever run making development easy. Debug mode is set in the manifest see setup. The other way to cause an upgrade is to increate the database version.

              	
    /* RushOrm also supports renaming of classes or fields,
        to do so add @RushRenamed annotation to the class 
        or field thats name has change listing all possible old names */
						
    /* Old class names must include package */ 						
    @RushRenamed(names = {"co.uk.rushorm.ExampleObject"})
    public class RenamedExampleObject extends RushObject {
											
        @RushRenamed(names = {"stringField"})
        private String renamedStringField;							
    }
				
			
If a more complex upgrade is required you can implement your own RushUpgradeManager and run custom SQL onUpgrade.


Customise

RushOrm can have many elements of it customised to fit any purpose. To see the full list of interfaces that define RushOrm, see RushCore. If rush does not fit your needs it is likely that reimplementing one of these interfaces will achieve them.

              	
    /* The most common extension to make is to implement custom columns.
	    This can be done by injecting your own RushColumns into initialize */ 
              	
    AndroidInitializeConfig config = new AndroidInitializeConfig(getApplicationContext());
    config.addRushColumn(new MyColumn());
    RushCore.initialize(config);
              	
    /* Below is an example of creating a custom field */          	
    public class MyClass {
        public String name;
    }
              	
    private class MyColumn implements RushColumn<MyClass> {
        @Override
        public String sqlColumnType() {
            return "varchar(255)";
        }

        @Override
        public String serialize(MyClass object, RushStringSanitizer stringSanitizer) {
            return stringSanitizer.sanitize(object.name);
        }

        @Override
        public MyClass deserialize(String value) {
            MyClass myClass = new MyClass();
            myClass.name = value;
            return myClass;
        }

        @Override
        public Class[] classesColumnSupports() {
            return new Class[]{MyClass.class};
        }
    }
					
				

Troubleshooting

RushOrm has a known issue with a select number of other libraries. Rush loops through every class in the dex file then loads it to check if it implements Rush, this prosess seems to cause problems with some libaries. Unfortunatly there does not seem to be a way of finding classes without causing this problem.

                

    /* Luckly there is a very simple work around. 
      Simple set your classes on the config object and this problem is resolved. */
    List<Class<? extends Rush>> classes = ArrayList<>();
    // Add classes
    classes.add(Example.class);
    ... 

    AndroidInitializeConfig config = new AndroidInitializeConfig(getApplicationContext());
    config.setClasses(classes);
    RushCore.initialize(config);

          
        

Contributing

Please get in touch with any feedback or bugs, it is very much appreciated. Its also great to know if you found the project useful.

Author
Stuart Campbell | @stu_cams