README

Firebase4j

Note: THIS PROJECT IS STILL IN ALPHA.


REQUIREMENTS

	In order to use this project, you must first acquire a Firebase workspace-
	url. You can obtain a workspace-url by signing up for early-access to their
	private-beta.
	
	Alternatively, you can run through their tutorial and then use the auto-
	generated workspace-url the tutorial provides you with. This url, however, 
	is transient so don't put any data in there you want to keep around.
	
	You should also review the Firebase documentation and tutorial, as this 
	interface is only meant to provide a thin wrapper around their REST API.
	
	Their REST API documentation can be found at:
		http://www.firebase.com/docs/rest-api.html
		
	Their tutorial can be found at:
		http://www.firebase.com/tutorial/
	
	
CURRENT FUNCTIONALITY	

	This project currently supports GET, PUT, POST, and DELETE to perform real-
	time notifications to clients from the back-end.  However, the reverse is 
	not true; so, if a client updates the firebase-data, the back-end will not 
	automatically be aware of it.
	
	You could theoretically implement some sort of polling and delta-parsing on 
	the back-end in order to accomplish this, but this wrapper does not (yet?) 
	take care of that for you.
	
	Of course, if your clients are also subscribing directly to the firebase-
	data, they would naturally be made aware of any changes by another client 
	since this is existing native behavior of the Firebase API.
	
	
"LOOK, MA, NO HANDS!" (but they aren't tied either!)

	The goal of this project is to do all of the mundane-lifting for you, but 
	efforts have been made to do this in a flexible enough way that it doesn't 
	limit you too much either.  
	
	So, this project allows you to interact with the firebase exclusively using 
	Map<String, Object>.
	
	However, should you need or want to, you can opt to both provide your own 
	JSON as well as work directly with the JSON returned by the firebase.
	
	Hopefully I have achieved the best balance between ease-of-use and 
	flexibility; please feel free to contact me with your input if you think I 
	can do a better job of achieving that goal.
	
	
EXAMPLE (for more example-code, refer to the Demo.java file)

	// create the firebase
	Firebase firebase = new Firebase( your_firebase_workspace_url );
	
	// PUT a map of some data into the firebase
	Map<String, Object> dataMap = new LinkedHashMap<String, Object>();
	dataMap.put( "PUT", "This was PUT into your workspace root" );
	response = firebase.put( dataMap );
	
	// GET the map back out of the firebase
	response = firebase.get();
	System.out.println( response );
	
	// alternatively, you can get a few details about the response
	response.getSuccess(); 	// true/false if method finished successfully
	response.getCode(); 	// http-code of method-request
	response.getBody();	// a map of the data returned
	response.getRawBody();	// the data returned in it's raw-form (ie: JSON)
	
	// another alternative, you can PUT/POST your own JSON if you want
	response = firebase.put( "PUT2", "{ 'key': 'Some value' }" );
	
	
HELP

	Please submit usage-questions to: brandon@thegreshams.net
	

BUGS

	Please submit all bugs to: https://github.com/bane73/firebase4j/issues
	
	
COPYRIGHT

	Copyright (c) 2012 by Brandon Gresham.  See LICENSE.txt for details.