A simple Java library for interacting with fluiddb
Java
Pull request Compare This branch is 5 commits ahead, 14 commits behind rossjones:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src/com/fluidinfo
tests/src/com/fluidinfo
.gitignore
AUTHORS
LICENSE
README
TODO
credentials.json.example

README

This is a direct port of FluidDB.net ( http://github.com/ntoll/FluidDB.NET/tree/master )
by Nicholas Tollervey ( http://ntoll.org/ ) from C# to Java.

See the AUTHORS file for contributors.

See the TODO file for the next things to be implemented.

Unit tests (using jUnit http://www.junit.org/) can be found in the test directories under:

tests/src/com/fluidinfo/

Test coverage is currently 92.4% (and getting better all the time).

To be able to run the unit tests you need to provide some valid credentials for the sandbox instance
of FluidDB. You can supply these by putting a credentials.json file in your home directory - the
test fixture will attempt to read this file and use the username, password and real name defined therein. 
See the credentials.json.example file for an example of the correct contents of this file.

This library is more-or-less complete. The only missing feature is the ability to process opaque
tag values. This will be added shortly.

The library is layered: the low-level FluidConnector class handles direct communication with FluidDB.
Upon this is built a comprehensive FOM (Fluid-Object-Mapper). You should only ever have to use
the FOM based classes.

As the FluidDB API is changing throughout the "Alpha" phase then you should check for new versions of
this library as we update it to keep in line with FluidDB's current state.

All feedback, patches, bug-reports are most welcome!

Example usage:

import java.io.IOException;
import com.fluidinfo.*;
import com.fluidinfo.fom.*;
import com.fluidinfo.fom.Object;
import org.json.*;

public class fluidTest {

    /**
     * Some example code for using the Fluid Object Model (FOM) classes with 
     * FluidDB
     * @throws JSONException 
     * @throws IOException 
     * @throws FluidException 
     * @throws FOMException 
     */
    public static void main(String[] args) throws FOMException, FluidException, IOException, JSONException {
        // The FluidDB class represents the instance of FluidDB you're connecting to.
        // The default constructor is set to use http://fluiddb.fluidinfo.com/ but we're
        // passing the URI to the sandbox here.
        FluidDB fdb = new FluidDB(FluidConnector.SandboxURL);
        // Login to FluidDB with your credentials
        String username = "username";
        String password = "password";
        fdb.Login(username, password);
        // Get the User object representing me
        User u = fdb.getLoggedInUser();
        // My root namespace
        Namespace root = u.RootNamespace();
        // Create a new namespace underneath my root namespace
        Namespace books = root.createNamespace("books", "For storing tags about books I might be reading.");
        // Add some tags to the new namespace
        Tag title = books.createTag("Title", "The title of a book I've read", true);
        Tag authors = books.createTag("Authors", "The author list", true);
        Tag hasRead = books.createTag("HasRead", "Indicates I've read this book", true);
        Tag rating = books.createTag("Rating", "Marks out of ten", true);
        Tag comment = books.createTag("Comment", "Some notes and commentary", false);
        
        // Create a new object
        Object seven_pillars = fdb.createObject("ISBN:0954641809");
        // Associate some tag/values with it
        // The first tag is only associating a tag *not* a value too
        seven_pillars.tag(hasRead);
        // We're associating values with the tags
        seven_pillars.tag(title, "Seven Pillars of Wisdom");
        seven_pillars.tag(authors, new String[]{"T.E.Lawrence"});
        seven_pillars.tag(rating, 8);
        seven_pillars.tag(comment, "The dreamers of the day are dangerous men, for they may act out their dreams with open eyes, to make it possible.");
        
        // A search of all objects that I have read 
        String[] result = fdb.searchObjects("has "+username+"/books/HasRead");
        // result will contain only one result... the id for the seven_pillars Object
        // Lets instantiate it and get a list of the available tags I have permission to see
        Object newObj = fdb.getObject(result[0]);
        String[] tagPaths = newObj.getTagPaths();
        // tagPaths will include my tags I created above...
        // Lets get the first tag and find out what is in it...
        Tag newTag = fdb.getTag(tagPaths[0]);
        FluidResponse r = newObj.getTagValue(newTag);
        // Assuming all is well the result is returned by calling r.getResponseContent(); 
        
        // Lets set / get some permissions
        
        // This will only give the current user and the fluiddb "superuser" account the ability
        // to create namespaces underneath the namespace "book"
        Permission p = new Permission(Policy.CLOSED, new String[]{"fluidDB", username});
        books.setPermission(Namespace.Actions.CREATE, p);
        
        // Lets get the default permission policy for the user for updating the "books/rating"
        // tag
        Permission updateTag = rating.getTagPermission(Tag.TagActions.UPDATE);
        // Calling GetPolicy() and GetExceptions() on an instance of the Permission class will
        // tell you what the permissions are (as described in the FluidDB docs)
        
        // Lets do some cleanup...
        
        // Remove the tags from the object that we created to represent the seven pillars
        newObj.deleteTag(title);
        newObj.deleteTag(authors);
        newObj.deleteTag(hasRead);
        newObj.deleteTag(rating);
        newObj.deleteTag(comment);
        
        // Now delete the tags
        title.delete();
        authors.delete();
        hasRead.delete();
        rating.delete();
        comment.delete();
        
        // and finally the namespace
        books.delete();
    }
}