Make README more instructive for managing data

Author: Anthony Nowell

README.md

@@ -127,40 +127,102 @@ Note: `setStdout(true)` is ignored if you do not have access to the algorithm so
 
 ## Working with Data
 
-Manage your data stored within Algorithmia:
+The Algorithmia Java client also provides a way to manage both Algorithmia hosted data
+and data from Dropbox or S3 accounts that you've connected to you Algorithmia account.
+
+This client provides a `DataFile` type (generally created by `client.file(uri)`)
+and a `DataDir` type (generally created by `client.dir(uri)`) that provide
+methods for managing your data.
+
+### Create directories
+
+Create directories by instantiating a `DataDirectory` object and calling `create()`:
 
 ```java
-// Create a directory "foo"
-DataDirectory foo = client.dir("data://.my/foo");
-foo.create();
+DataDirectory robots = client.dir("data://.my/robots");
+robots.create();
 
-// Create a directory with specific ACL
-DataDirectory fooLimited = client.dir("data://.my/fooLimited");
-fooLimited.create(DataAcl.PRIVATE);
+DataDirectory dbxRobots = client.dir("dropbox://robots");
+dbxRobots.create();
+```
+
+### Upload files to a directory
+
+Upload files by calling `put` on a `DataFile` object, or by calling `putFile` on a `DataDirectory` object.
+
+```java
+DataDirectory robots = client.dir("data://.my/robots");
+
+// Upload local file
+robots.putFile(new File("/path/to/Optimus_Prime.png"));
+// Write a text file
+robots.file("Optimus_Prime.txt").put("Leader of the Autobots");
+// Write a binary file
+robots.file("Optimus_Prime.key").put(new byte[] { (byte)0xe0, 0x4f, (byte)0xd0, 0x20 });
+```
+
+### Download contents of file
 
-// Or, update the directory's ACL after creation
-fooLimited.updatePermissions(DataAcl.PRIVATE);
+Download files by calling `getString`, `getBytes`, or `getFile` on a DataFile object:
+
+```java
+DataDirectory robots = client.dir("data://.my/robots");
+
+// Download file and get the file handle
+File t800File = robots.file("T-800.png").getFile();
+
+// Get the file's contents as a string
+String t800Text = robots.file("T-800.txt").getString();
+
+// Get the file's contents as a byte array
+byte[] t800Bytes = robots.file("T-800.png").getBytes();
+```
 
-// View the directory's permissions
-fooLimited.getPermissions().getReadPermissions() == DataAclType.PRIVATE
+### Delete files and directories
 
-// Upload files to "foo" directory
-foo.file("sample.txt").put("sample text contents");
-foo.file("binary_file").put(new byte[] { (byte)0xe0, 0x4f, (byte)0xd0, 0x20 });
-foo.putFile(new File("/path/to/myfile"));
+Delete files and directories by calling `delete` on their respective `DataFile` or `DataDirectory` object.
+`DataDirectories` take an optional `force` parameter that indicates whether the directory should be deleted
+if it contains files or other directories.
 
-// List files in "foo"
-for(DataFile file : foo.getFileIter()) {
-    System.out.println(file.toString() " at URL: " + file.url());
+```java
+client.file("data://.my/robots/C-3PO.txt").delete();
+client.dir("data://.my/robots").delete(false);
+```
+
+### List directory contents
+
+Iterate over the contents of a directory using the iterated returned by calling `files`, or `dirs` on a `DataDirectory` object:
+
+```java
+// List top level directories
+DataDirectory myRoot = client.dir("data://.my");
+for(DataDirectory dir : myRoot.dirs()) {
+    System.out.println("Directory " + dir.toString() + " at URL " + dir.url());
+}
+
+// List files in the 'robots' directory
+DataDirectory robots = client.dir("data://.my/robots");
+for(DataFile file : robots.files()) {
+    System.out.println("File " + file.toString() + " at URL: " + file.url());
 }
+```
 
-// Get contents of files
-String sampleText = foo.file("sample.txt").getString();
-byte[] binaryContent = foo.file("binary_file").getBytes();
-File tempFile = foo.file("myfile").getFile();
+### Manage directory permissions
 
-// Delete files and directories
-foo.file("sample.txt").delete();
-foo.delete(true); // true implies force deleting the directory and its contents
+Directory permissions may be set when creating a directory, or may be updated on already existing directories.
+
+```java
+DataDirectory fooLimited = client.dir("data://.my/fooLimited");
+
+// Create the directory as private
+fooLimited.create(DataAcl.PRIVATE);
+
+// Update a directory to be public
+fooLimited.updatePermissions(DataAcl.PUBLIC);
+
+// Check a directory's permissions
+if (fooLimited.getPermissions().getReadPermissions() == DataAclType.PRIVATE) {
+    System.out.println("fooLimited is private");
+}
 ```