Test
Graph Management Toolkits

Documentation

Reports

Download

Community

Source

Get Filament at SourceForge.net. Fast, secure and Free Open Source software downloads

Getting Started

To use Filament core library, you will need to make sure that the core.jar is in your classpath along with its dependencies. The easiest way to do this is to use a build tool like Gradle or Maven and add the appropriate dependencies. (See here for details.)

Filament Core currently depends on the following external artifacts (in Gradle dependency format):

Gradle or Maven will download those automatically.

In-memory Example

Filament comes with an in-memory implementation of its underlying persistence framework. This allows demonstration of the graph component without creating database tables or worrying about database connections. The in-memory version will mostly behave like a real JDBC-based version. There may be some subtle differences.

Creating a SimpleGraph insance

 import org.fgraph.SimpleGraph;
 import org.fgraph.base.DefaultGraph;
 import org.fgraph.util.HashTripleStore;

 ...

 SimpleGraph graph = DefaultGraph.create( HashTripleStore.FACTORY );

The following illustrates creating a simple star-graph and iterating over the connections to the central node.

Populating the graph

 Node n1 = graph.newNode();
 Node n2 = graph.newNode();
 Node n3 = graph.newNode();
 Node n4 = graph.newNode();

 graph.addEdge( n1, n2, "Demo" );
 graph.addEdge( n1, n3, "Demo" );
 graph.addEdge( n1, n4, "Demo" );

 for( Edge e : n1.edges("Demo") ) {
     System.out.println( "Connects to:" + e.otherEnd(n1) );
 }

The edge type above is the string "Demo". In the DefaultGraph implementation, this edge type can be any object that can be converted to and from a string as defined by the org.progeeks.util.Inspector class in Meta-jb Utils.

Every graph object, both Nodes and Edges, is a Map of properties. The default implementation allows a value to be any object that can be converted to/from a String as mentioned above.

Setting Object Properties

 n1.put( "name", "Node 1" );
 n1.put( "clusterRoot", Boolean.TRUE );
 n2.put( "name", "Node 2" );
 n3.put( "name", "Node 3" );

 System.out.println( "n1 properties:" + n1.entrySet() );

 int count = 0;
 for( Edge e : n1.edges("Demo") ) {
     e.put( "clusterIndex", count++ );
 }

Once set, objects can be looked up by their property values using the graph.findObjects() methods.

Traversing the Graph

The NodeTraverser and FilteredNodeTraverser classes allow configurable traversal of larger sections of the graph. Once created, a NodeTraverser can be reused to create Iterables over a traversal set.

Basic Traversal Example

 NodeTraverser basic = new NodeTraverser().out( "Demo" );

 for( GraphObject o : basic.nodes( n1 ) ) {
     System.out.println( "node:" + o.entrySet() );
 }

Output (order may be different):

 node:[name="Node 2"]
 node:[name="Node 3"]
 node:[]

Note: n4 does not have any of its properties set and so produced no output for entrySet().

If the graph had extended further from n2, n3, etc. then the traverser would have picked those up too as long as the edges were pointing out and the edge type was "Demo".

More control is provided through the steps() method that allows iterating over a set of TraversalSteps. This provides depth and visit count information as well as the number of children that will be traversed after visting a particular step.

Step Traversal Example

 for( TraversalStep step : basic.steps(n1) ) {
     System.out.println( "Target:" + step.getTarget().entrySet()
                                   + "  Edge:" + step.getEdge().entrySet() );
     System.out.println( "   depth:" + step.getDepth()
                                   + "  index:" + step.getIndex() );
     System.out.println( "   child count:" + step.getDescendantCount() );
 }

Output (order may be different):

 Target:[name="Node 2"]  Edge:[clusterIndex=1]
    depth:1  index:0
    child count: 0
 Target:[name="Node 3"]  Edge:[clusterIndex=2]
    depth:1  index:1
    child count: 0
 Target:[]  Edge:[clusterIndex=3]
    depth:1  index:2
    child count: 0

The information can be used to filter on specific steps in the traversal or to prune() entire branches.

Database Setup

The default implementation of DefaultGraph and the base SQL/JDBC store expects two tables to exist. PostgreSQL creation scripts can be found here: http://filament.svn.sourceforge.net/viewvc/filament/trunk/core/src/schema/ Oracle scripts will be added there soon.

Once those tables have been setup in the target database, the following can be used to create a graph.

Creating a DB-backed Graph

 import org.fgraph.sql.SqlStoreFactory;

 String jdbcUrl = ...
 String user = ...
 String pword = ...

 Connection conn = DriverManager.getConnection( jdbcUrl, user, pword );

 // User code has complete control over
 // transaction granularity through the JDBC
 // connection standard mechanisms
 conn.setAutoCommit(false);

 SimpleGraph graph = DefaultGraph.create( new SqlStoreFactory(conn) );

From there, the graph can be used just like with the in-memory examples. The difference is that changes will be persisted when calling conn.commit().

Other connection management idioms are supported by implementing custom TripleStoreFactories.