Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

staging for release.

  • Loading branch information...
commit 25908b02e96f8d614585311e52723ad230676866 1 parent 47bea22
stephen mallette spmallette authored
Showing with 2,677 additions and 0 deletions.
  1. +15 −0 doc/wiki/Acknowledgments.textile
  2. +82 −0 doc/wiki/Batch-Implementation.textile
  3. +92 −0 doc/wiki/Code-Examples.textile
  4. +19 −0 doc/wiki/Desired-Implementations.textile
  5. +109 −0 doc/wiki/Dex-Implementation.textile
  6. +52 −0 doc/wiki/Event-Implementation.textile
  7. +124 −0 doc/wiki/GML-Reader-and-Writer-Library.textile
  8. +53 −0 doc/wiki/Graph-Indices.textile
  9. +22 −0 doc/wiki/Graph-Morphisms.textile
  10. +55 −0 doc/wiki/Graph-Transactions.textile
  11. +194 −0 doc/wiki/GraphML-Reader-and-Writer-Library.textile
  12. +310 −0 doc/wiki/GraphSON-Reader-and-Writer-Library.textile
  13. +93 −0 doc/wiki/Home.textile
  14. +48 −0 doc/wiki/Id-Implementation.textile
  15. +20 −0 doc/wiki/Implementations.textile
  16. +7 −0 doc/wiki/InfiniteGraph-Implementation.textile
  17. +63 −0 doc/wiki/JUNG-Ouplementation.textile
  18. +60 −0 doc/wiki/Neo4j-Implementation.textile
  19. +62 −0 doc/wiki/Neo4jBatch-Implementation.textile
  20. +17 −0 doc/wiki/Neo4jHa-Implementation.textile
  21. +63 −0 doc/wiki/OrientDB-Implementation.textile
  22. +7 −0 doc/wiki/Ouplementations.textile
  23. +38 −0 doc/wiki/Partition-Implementation.textile
  24. +22 −0 doc/wiki/Property-Graph-Implementations.textile
  25. +106 −0 doc/wiki/Property-Graph-Model-Test-Suite.textile
  26. +25 −0 doc/wiki/Property-Graph-Model.textile
  27. +16 −0 doc/wiki/ReadOnly-Implementation.textile
  28. +398 −0 doc/wiki/Release-Notes.textile
  29. +15 −0 doc/wiki/Rexster-Implementation.textile
  30. +113 −0 doc/wiki/Sail-Implementation.textile
  31. +198 −0 doc/wiki/Sail-Ouplementation.textile
  32. +11 −0 doc/wiki/The-Benefits-of-Blueprints.textile
  33. +79 −0 doc/wiki/The-Major-Differences-Between-Blueprints-1.x-and-2.x.textile
  34. +54 −0 doc/wiki/TinkerGraph.textile
  35. +35 −0 doc/wiki/Vertex-Query.textile
15 doc/wiki/Acknowledgments.textile
View
@@ -0,0 +1,15 @@
+<img width="100" src="https://github.com/tinkerpop/blueprints/raw/master/doc/images/blueprints-character-2.png"/>
+
+This section provides a list of the people that have contributed in some way to the creation of Blueprints.
+
+# "Marko A. Rodriguez":http://markorodriguez.com -- designed, developed, tested, and documented Blueprints.
+# "Luca Garulli":http://orientechnologies.com -- developed the OrientDB implementatio (@OrientGraph@).
+# "Joshua Shinavier":http://fortytwo.net -- developed Blueprints Sail (@GraphSail@).
+# "Darrick Weibe":http://github.com/pangloss -- tests, bug fixes, and transaction work.
+# "Stephen Mallette":http://stephen.genoprime.com -- develops @RexsterGraph@ and other components.
+# "Sergio Gómez Villamor":http://github.com/sgomezvillamor -- developed the Dex implementation (@DexGraph@).
+# "Pierre De Wilde":http://www.linkedin.com/in/pierredewilde -- designs and tests new features.
+# "Ketrina Yim":http://www.ketrinayim.com/ -- designed the Blueprints logo.
+# "Matthias Broecheler":http://www.matthiasb.com/ -- designed many of the TinkerPop 2 API changes.
+
+Please review Blueprints' "pom.xml":http://github.com/tinkerpop/blueprints/blob/master/pom.xml. Blueprints would not be possible without the work done by others to create these useful packages.
82 doc/wiki/Batch-Implementation.textile
View
@@ -0,0 +1,82 @@
+[[http://www.stacymakescents.com/wp-content/uploads/haystack-clip-art.gif|width=250px]]
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-core</artifactId>
+ <version>??</version>
+</dependency>
+```
+
+@BatchGraph@ wraps any @TransactionalGraph@ to enable batch loading of a large number of edges and vertices by chunking the entire load into smaller batches and maintaining a memory-efficient vertex cache so that intermediate transactional states can be flushed after each chunk is loaded to release memory.
+
+
+@BatchGraph@ is *ONLY* meant for loading data and does not support any retrieval or removal operations. That is, BatchGraph only supports the following methods:
+* @addVertex()@ for adding vertices
+* @addEdge()@ for adding edges
+* @getVertex()@ to be used when adding edges
+* Property getter, setter and removal methods for vertices and edges as well as @getId()@
+
+An important limitation of @BatchGraph@ is that edge properties can only be set immediately after the edge has been added. If other vertices or edges have been created in the meantime, setting, getting or removing properties will throw exceptions. This is done to avoid caching of edges which would require a great amount of memory.
+
+@BatchGraph@ wraps @TransactionalGraph@. To wrap arbitrary graphs, use @BatchGraph.wrap()@ which will additionally wrap non-transactional graphs.
+
+@BatchGraph@ can also automatically set the provided element ids as properties on the respective element. Use @setVertexIdKey()@ and @setEdgeIdKey()@ to set the keys for the vertex and edge properties respectively. This is useful when the graph implementation ignores supplied ids and allows to make the loaded graph compatible for later wrapping with @IdGraph@ (see [[Id Implementation]]) when setting the vertex and edge Id keys to @IdGraph.ID@.
+
+As an example, suppose we are loading a large number of edges defined by a String array with four entries called _quads_:
+
+# The out vertex id
+# The in vertex id
+# The label of the edge
+# A string annotation for the edge, i.e. an edge property
+
+Assuming this array is very large, loading all these edges in a single transaction is likely to exhaust main memory. Furthermore,
+one would have to rely on the database indexes to retrieve previously created vertices for a given id. @BatchGraph@ addresses
+both of these issues.
+
+```java
+BatchGraph bgraph = new BatchGraph(graph, BatchGraph.IdType.STRING, 1000);
+for (String[] quad : quads) {
+ Vertex[] vertices = new Vertex[2];
+ for (int i=0;i<2;i++) {
+ vertices[i] = bgraph.getVertex(quad[i]);
+ if (vertices[i]==null) vertices[i]=bgraph.addVertex(quad[i]);
+ }
+ Edge edge = bgraph.addEdge(null,vertices[0],vertices[1],quad[2]);
+ edge.setProperty("annotation",quad[3]);
+}
+```
+
+First, a @BatchGraph@ _bgraph_ is created wrapping an existing _graph_ and setting the id type to @IdType.STRING@ and the batch size to 1000.
+@BatchGraph@ maintains a mapping from the external vertex ids, in our example the first two entries in the String array describing th edge,
+to the internal vertex ids assigned by the wrapped grahp database. Since this mapping is maintained in memory, it is potentially much faster
+than the database index. By specifying the @IdType@, @BatchGraph@ chooses the most memory-efficient mapping data structure and applies compression
+algorithms if possible. There are four different @IdTypes@:
+
+* _OBJECT_ : For arbitrary object vertex ids. This is the most generic and least space efficient type.
+* _STRING_ : For string vertex ids. Attempts to apply string compression and prefixing strategies to reduce the memory footprint.
+* _URL_ : For string vertex ids that parse as URLs. Applies URL specific compression schemes that are more efficient than generic string compression.
+* _NUMBER_ : For numeric vertex ids. Uses primitive data structures that requires significantly less memory.
+
+The last argument in the constructor is the batch size, that is, the number of vertices and edges to load before committing a transaction and starting a
+new one.
+
+The for-loop then iterates over all the quad String arrays and creates an edge for each by first retrieving or creating the vertex end points
+and then creating the edge. Note, that we set the edge property immediately after creating the edge. This is required because
+edges are only kept in memory until the next edge is created for efficiency reasons.
+
+h2. Incremental Loading
+
+The above describes how @BatchGraph@ can be used to load data into a graph under the assumption that the wrapped graph is initially empty. @BatchGraph@ can also be used to incrementally batch load edges and vertices into a graph with existing data. In this case, vertices may already exist for given ids.
+
+If the wrapped graph does not ignore ids, then enabling incremental batch loading is as simple as calling @setLoadingFromScratch(false)@, i.e. to disable the assumption that data is loaded into an empty graph. If the wrapped graph does ignore ids, then one has to tell @BatchGraph@ how to find existing vertices for a given id by specifying the vertex id key using @setVertexIdKey(uid)@ where _uid_ is some string for the property key. Also, uid must be "key indexed":https://github.com/tinkerpop/blueprints/wiki/Graph-Indices for this to work.
+
+```java
+graph.createKeyIndex("uid",Vertex.class);
+BatchGraph bgraph = new BatchGraph(graph, BatchGraph.IdType.STRING, 1000);
+bgraph.setVertexIdKey("uid);
+bgraph.setLoadingFromScratch(false);
+//Load data as shown above
+```
+
+Note, that incremental batch loading is more expensive than loading from scratch because @BatchGraph@ has to call on the wrapped graph to determine whether a vertex exists for a given id.
92 doc/wiki/Code-Examples.textile
View
@@ -0,0 +1,92 @@
+This section will provide a collection of basic code examples that work with the Blueprints graph API. The in-memory [[TinkerGraph]] database will be used throughout the examples. Please feel free to alter the graph constructor to work with different graph databases.
+
+# "Create a Simple Graph":#create
+# "Iterate through the Elements of a Graph":#elements
+# "Iterate through the Edges of a Vertex":#edge
+
+<a name="create"></a>
+
+h2(#create). Create a Simple Graph
+
+Create a graph. Add two vertices. Set the @name@ property of each vertex. Create an @knows@ edge between the two vertices. Print the components of the graph.
+
+```java
+import com.tinkerpop.blueprints.impls.tg.TinkerGraph;
+import com.tinkerpop.blueprints.Graph;
+import com.tinkerpop.blueprints.Vertex;
+import com.tinkerpop.blueprints.Edge;
+import com.tinkerpop.blueprints.Direction;
+
+Graph graph = new TinkerGraph();
+Vertex a = graph.addVertex(null);
+Vertex b = graph.addVertex(null);
+a.setProperty("name", "marko");
+b.setProperty("name", "peter");
+Edge e = graph.addEdge(null, a, b, "knows");
+System.out.println(e.getVertex(Direction.OUT).getProperty("name") + "--" + e.getLabel() + "-->" + e.getVertex(Direction.IN).getProperty("name"));
+```
+
+The @System.out@ after the code executes is:
+
+bc. marko--knows-->peter
+
+<a name="elements"></a>
+
+h2(#elements). Iterate through the Elements of a Graph
+
+Load the TinkerPop play graph diagrammed in [[Property Graph Model]]. Iterate through all the vertices and print them to @System.out@. Iterate through all the edges and print them to @System.out@.
+
+```java
+public void testIteratingGraph() {
+ Graph graph = TinkerGraphFactory.createTinkerGraph();
+ System.out.println("Vertices of " + graph);
+ for (Vertex vertex : graph.getVertices()) {
+ System.out.println(vertex);
+ }
+ System.out.println("Edges of " + graph);
+ for (Edge edge : graph.getEdges()) {
+ System.out.println(edge);
+ }
+}
+```
+
+The @System.out@ after the code executes is:
+
+bc. Vertices of tinkergraph[vertices:6 edges:6]
+v[3]
+v[2]
+v[1]
+v[6]
+v[5]
+v[4]
+Edges of tinkergraph[vertices:6 edges:6]
+e[10][4-created->5]
+e[7][1-knows->2]
+e[9][1-created->3]
+e[8][1-knows->4]
+e[11][4-created->3]
+e[12][6-created->3]
+
+<a name="edge"></a>
+
+h2(#edge). Iterate through the Edges of a Vertex
+
+Load the TinkerPop play graph diagrammed in [[Property Graph Model]]. Get vertex @1@ from the graph by its @id@. Print some information about the vertex. Iterate through the outgoing edges of the vertex and print the edges.
+
+```java
+Graph graph = TinkerGraphFactory.createTinkerGraph();
+Vertex a = graph.getVertex("1");
+System.out.println("vertex " + a.getId() + " has name " + a.getProperty("name"));
+for(Edge e : a.getEdges(OUT)) {
+ System.out.println(e);
+}
+```
+
+The @System.out@ after the code executes is:
+
+bc. vertex 1 has name marko
+e[7][1-knows->2]
+e[9][1-created->3]
+e[8][1-knows->4]
+
+<a name="index"></a>
19 doc/wiki/Desired-Implementations.textile
View
@@ -0,0 +1,19 @@
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/blueprints-bob-the-builder.png!
+
+It is a time consuming process to maintain Blueprints implementations as graph database/framework versions and features change. Many developers focusing on a particular implementation is an ideal way of ensuring that Blueprints has wide reach and is always consistent with the latest developments. If there is a graph database/framework that is currently not supported by Blueprints and you are an expert with that system, please contribute an implementation. To get a feel of what is required, see [[Property Graph Model]] and [[Property Graph Model Test Suite]].
+
+Below is a list of desired implementations. This list is not intended to be exhaustive. Please feel free to add to the list.
+
+* "db4o":http://developer.db4o.com
+* "Versant Object Database":http://www.versant.com
+* "InfoGrid":http://infogrid.org/
+* "vertexdb":http://www.dekorte.com/projects/opensource/vertexdb/
+* "Redis":http://code.google.com/p/redis/ - see "Blueredis":https://github.com/dmitriid/blueredis
+* "AvocadoDB":http://www.avocadodb.org/
+* "Lucene":http://lucene.apache.org/core/ - see "Lumeo":https://github.com/karussell/lumeo
+* "Azure Table Storage":http://www.windowsazure.com/en-us/home/features/storage/
+* Sail-based RDF Stores (very easy to do as only a @Sail@ constructor is needed)
+** "4Store":http://4store.org/
+** "AllegroGraph":http://www.franz.com/agraph/allegrograph/
+** "OpenVirtuoso":http://virtuoso.openlinksw.com/
+** "OWLim":http://www.ontotext.com/owlim/
109 doc/wiki/Dex-Implementation.textile
View
@@ -0,0 +1,109 @@
+[[http://www.sparsity-technologies.com/images/sparsity_logo_web.png]]
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-dex-graph</artifactId>
+ <version>??</version>
+</dependency>
+```
+
+```java
+Graph graph = new DexGraph("/tmp/graph.dex");
+```
+
+"Dex":http://www.sparsity-technologies.com/dex is a graph database developed by "Sparsity Technologies":http://www.sparsity-technologies.com/. For a fine summary of the Dex graph database, please review the following "presentations":http://www.sparsity-technologies.com/dex_tutorials. The software can be downloaded from "here":http://www.sparsity-technologies.com/dex_downloads and be used with the default evaluation license (which restricts the amount of information Dex can deal with).
+
+h2. Vertex label
+
+As edges, Dex vertices have a label too. Thus, when adding a vertex to the database, its label can be set as follows:
+
+```java
+((DexGraph)graph).label.set("people");
+Vertex v = graph.addVertex(null)
+assertTrue(v.getProperty(StringFactory.LABEL).equals("people"));
+```
+
+The @DexGraph#label@ property is also relevant for other methods. Go to the javadoc of each of the following methods to see how:
+* @DexGraph#addVertex@
+* @DexGraph#createKeyIndex(String, Class<T>)@
+* @DexGraph#getEdges(String, Object)@
+* @DexGraph#getVertices(String, Object)@
+
+h2. Memory Configuration
+
+Dex memory is not managed by the JVM heap, so an specific memory configuration must be set for Dex in order to set the maximum amount of memory to be used by a Dex application.
+
+Specifically, users should set @dex.io.cache.maxsize@ as is explained [[here|http://www.sparsity-technologies.com/downloads/javadoc-java/com/sparsity/dex/gdb/DexConfig.html]].
+
+h2. Managment of @Iterable@ collections
+
+As before, since Dex resources are not managed by the JVM heap, Dex-based blueprints applications should take into account the management of @Iterable@ collections and explicitly close them in order to free native resources.
+
+For example, if we execute a long traversal like this:
+
+```java
+for (final Vertex vertex : graph.getVertices()) {
+ for (final Edge edge : vertex.getOutEdges()) {
+ final Vertex vertex2 = edge.getInVertex();
+ for (final Edge edge2 : vertex2.getOutEdges()) {
+ ...
+ }
+ }
+}
+```
+
+all retrieved collections won't be closed until the graph database is stopped. Of course, keep active this amount of resources will have a negative impact in the performance.
+
+To avoid this, all retrieved collections from methods in the Dex implementation implement @CloseableIterable@. Thus, we could implement the previous traversal as follows:
+
+```java
+CloseableIterable<Vertex> vv = (CloseableIterable<Vertex>)graph.getVertices();
+for (final Vertex vertex : vv) {
+ CloseableIterable<Edge> ee = (CloseableIterable<Edge>)vertex.getOutEdges();
+ for (final Edge edge : ee) {
+ final Vertex vertex2 = edge.getInVertex();
+ CloseableIterable<Edge> ee2 = (CloseableIterable<Edge>)vertex2.getOutEdges();
+ for (final Edge edge2 : ee2) {
+ ...
+ }
+ ee2.close();
+ }
+ ee.close();
+}
+vv.close();
+```
+
+h2. DexGraph Feature List
+
+```
+supportsDuplicateEdges = true;
+supportsSelfLoops = true;
+isPersistent = true;
+isRDFModel = false;
+supportsVertexIteration = true;
+supportsEdgeIteration = true;
+supportsVertexIndex = false;
+supportsEdgeIndex = false;
+ignoresSuppliedIds = true;
+supportsTransactions = false;
+supportsIndices = false;
+
+supportsSerializableObjectProperty = false;
+supportsBooleanProperty = true;
+supportsDoubleProperty = true;
+supportsFloatProperty = true;
+supportsIntegerProperty = true;
+supportsPrimitiveArrayProperty = false;
+supportsUniformListProperty = false;
+supportsMixedListProperty = false;
+supportsLongProperty = false;
+supportsMapProperty = false;
+supportsStringProperty = true;
+
+isWrapper = false;
+supportsKeyIndices = true;
+supportsVertexKeyIndex = true;
+supportsEdgeKeyIndex = true;
+supportsThreadedTransactions = false;
+```
52 doc/wiki/Event-Implementation.textile
View
@@ -0,0 +1,52 @@
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-core</artifactId>
+ <version>??</version>
+</dependency>
+```
+
+@EventGraph@ and @EventIndexableGraph@ wrap any @Graph@ or @IndexableGraph@, respectively. The purpose of an @EventGraph@ is to raise events to one or more @GraphChangedListener@ as changes to the underlying @Graph@ occur. The obvious limitation is that events will only be raised to listeners if the changes to the @Graph@ occur within the same process.
+
+@EventTransactionalGraph@ and @EventTransactionalIndexableGraph@ wrap any @TransactionalGraph@. These wrappers behave in the same fashion as the aforementioned @EventGraph@ and @EventIndexableGraph@, but respect the concept of transactions, such that the events that are triggered during a transaction are queued until the transaction is successfully committed. Once committed, the events will fire in the order that they were queued. If the transaction is rolled back the event queue is reset.
+
+The following events are raised:
+
+* New vertex
+* New edge
+* Vertex property changed
+* Edge property changed
+* Vertex property removed
+* Edge property removed
+* Vertex removed
+* Edge removed
+* Graph cleared
+
+To start processing events from a @Graph@ first implement the @GraphChangedListener@ interface. An example of this implementation is the @ConsoleGraphChangedListener@ which writes output to the console for each event.
+
+To add a listener to the @EventGraph@:
+
+```java
+EventGraph graph = new EventGraph(TinkerGraphFactory.createTinkerGraph());
+graph.addListener(new ConsoleGraphChangedListener(graph));
+
+Vertex v = graph.addVertex(100);
+v.setProperty("name", "noname");
+
+for (Edge edge : graph.getEdges()) {
+ edge.removeProperty("weight");
+}
+```
+
+The following output would appear in the console:
+
+```text
+Vertex [v[100]] added to graph [eventgraph[tinkergraph[vertices:6 edges:6]]]
+Vertex [v[4]] property [name] set to value of [noname] in graph [eventgraph[tinkergraph[vertices:6 edges:6]]]
+Edge [e[10][4-created->5]] property [weight] with value of [1.0] removed in graph [eventgraph[tinkergraph[vertices:6 edges:6]]]
+Edge [e[7][1-knows->2]] property [weight] with value of [0.5] removed in graph [eventgraph[tinkergraph[vertices:6 edges:6]]]
+Edge [e[9][1-created->3]] property [weight] with value of [0.4] removed in graph [eventgraph[tinkergraph[vertices:6 edges:6]]]
+Edge [e[8][1-knows->4]] property [weight] with value of [1.0] removed in graph [eventgraph[tinkergraph[vertices:6 edges:6]]]
+Edge [e[11][4-created->3]] property [weight] with value of [0.4] removed in graph [eventgraph[tinkergraph[vertices:6 edges:6]]]
+Edge [e[12][6-created->3]] property [weight] with value of [0.2] removed in graph [eventgraph[tinkergraph[vertices:6 edges:6]]]
+```
124 doc/wiki/GML-Reader-and-Writer-Library.textile
View
@@ -0,0 +1,124 @@
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-core</artifactId>
+ <version>??</version>
+</dependency>
+```
+
+The "GML":http://www.fim.uni-passau.de/en/fim/faculty/chairs/theoretische-informatik/projects.html reader and writer package allows an entire graph to be streamed to and from GML (Graph Modelling Language).
+
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/graph-example-1.jpg!
+
+The following example shows the format of the graph diagram above in GML:
+
+```text
+graph [
+ node [
+ id 1
+ blueprintsId "3"
+ name "lop"
+ lang "java"
+ ]
+ node [
+ id 2
+ blueprintsId "2"
+ name "vadas"
+ age 27
+ ]
+ node [
+ id 3
+ blueprintsId "1"
+ name "marko"
+ age 29
+ ]
+ node [
+ id 4
+ blueprintsId "6"
+ name "peter"
+ age 35
+ ]
+ node [
+ id 5
+ blueprintsId "5"
+ name "ripple"
+ lang "java"
+ ]
+ node [
+ id 6
+ blueprintsId "4"
+ name "josh"
+ age 32
+ ]
+ edge [
+ source 6
+ target 5
+ label "created"
+ blueprintsId "10"
+ weight 1.0
+ ]
+ edge [
+ source 3
+ target 2
+ label "knows"
+ blueprintsId "7"
+ weight 0.5
+ ]
+ edge [
+ source 3
+ target 1
+ label "created"
+ blueprintsId "9"
+ weight 0.4
+ ]
+ edge [
+ source 3
+ target 6
+ label "knows"
+ blueprintsId "8"
+ weight 1.0
+ ]
+ edge [
+ source 6
+ target 1
+ label "created"
+ blueprintsId "11"
+ weight 0.4
+ ]
+ edge [
+ source 4
+ target 1
+ label "created"
+ blueprintsId "12"
+ weight 0.2
+ ]
+]
+```
+
+h1. Usage
+
+To output a graph in GML format, pass the graph into the @GMLWriter@ constructor, then call @outputGraph@:
+
+```java
+Graph graph = ...
+OutputStream out = ...
+
+GMLWriter.outputGraph(graph, out);
+```
+
+The @GMLReader@ works in a similar format. Simply pass what would likely be an empty graph into the constructor, then call @inputGraph@:
+
+```java
+Graph graph = ...
+InputStream in = ...
+
+GMLReader.inputGraph(graph, in);
+```
+By default, the @id@ property is used for vertex and edge ids. In GML edges may not have id, in this case an integer id will be generated. The @label@ property is used for edge labels and "undefined" if not present. The properties used for the vertex id, the edge id and the edge label can be set using.
+
+```java
+reader.setVertexId("propertyToUseAsVertexId");
+reader.setEdgeId("propertyToUseAsEdgeId");
+reader.setEdgeLabel("propertyToUseAsEdgeLabel");
+```
+If set manually the reader assumes that the ids are unique. There are a number of static method overloads that offer more options and control.
53 doc/wiki/Graph-Indices.textile
View
@@ -0,0 +1,53 @@
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/indices-example.png!
+
+And index is a data structure that supports the fast lookup of elements by some key/value pair. Lookups are usually in @log(n)@ time where @n@ is the number of elements in the index. There are two types of indexing structures supported by Blueprints. These are reflected in the two respective interfaces: @KeyIndexableGraph@ and @IndexableGraph@.
+
+h2. KeyIndexableGraph and Fast LookUp of Elements by Key/Value Pairs
+
+A @KeyIndexableGraph@ is a graph that supports the automatic indexing of a vertex or edges by its key/value pair properties. When a method requires access to an element by a key/value, then an appropriate key index can be retrieved. Otherwise, a linear scan must take place. Such methods include @Graph.getVertices(String key, Object value)@ and @Graph.getEdges(String key, Object value)@. The methods of @KeyIndexableGraph@ are provided below.
+
+```java
+public <T extends Element> void dropKeyIndex(String key, Class<T> elementClass);
+public <T extends Element> void createKeyIndex(String key, Class<T> elementClass);
+public <T extends Element> Set<String> getIndexedKeys(Class<T> elementClass);
+```
+
+h2. IndexableGraph and Putting, Getting, and Removing Elements
+
+An @IndexableGraph@ is a @Graph@ that supports the indexing of its vertices and edges. An index is a data structure that allows for the fast retrieval of an element by a particular key/value pair. The @IndexableGraph@ interface has the following methods:
+
+```java
+public <T extends Element> Index<T> createIndex(String indexName, Class<T> indexClass, Parameter... indexParameters);
+public <T extends Element> Index<T> getIndex(String indexName, Class<T> indexClass);
+public Iterable<Index<? extends Element>> getIndices();
+public void dropIndex(String indexName);
+```
+
+An index requires the developer to manually put, get, and remove elements from the index. To create a manual index of vertices, do the following:
+
+```java
+Index<Vertex> index = graph.createIndex("test-idx", Vertex.class);
+```
+
+The @Index@ interface has the following methods:
+
+```java
+public long count(String key, Object value);
+public String getIndexName();
+public Class<T> getIndexClass();
+public void put(String key, Object value, T element);
+public Iterable<T> get(String key, Object value);
+public Iterable<T> query(String key, Object value);
+public void remove(String key, Object value, T element);
+```
+
+Given the @index@ object created previous, to add, get, query, and remove a vertex from this index, do the following:
+
+```java
+index.put("name","peter",vertex);
+Iterable<Vertex> results = index.get("name","peter");
+Iterable<Vertex> results = index.query("name", "PeTeR"); // assuming some case-insensitive index
+index.remove("name","peter",vertex);
+```
+
+Finally, The index construction method @createIndex()@ has a @Parameter@ "var arg" as its final argument. Some underlying graph implementations support the passing of parameters to tweak the underlying indexing model -- e.g. case insensitive querying. Please refer to the specifics of each @IndexableGraph@ implementation for their respective support parameters.
22 doc/wiki/Graph-Morphisms.textile
View
@@ -0,0 +1,22 @@
+In the world of graphs, there are numerous "graph types":http://en.wikipedia.org/wiki/Graph_%28mathematics%29. The diagram below describes the important feature of a collection of common graph types. Note that many of these types can be mixed and matched. For example, the [[property graph model]] of Blueprints can be seen as a *vertex/edge-labeled/attributed, directed, multi-graph*.
+
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/graph-types.jpg!
+
+* *half-edge graph*: a unary edge graph where an edge connects only one vertex.
+* *multi-graph*: when edges are labeled, the various ways in which vertices are related can be denoted.
+* *simple graph*: the prototypical graph where an edge connects two vertices and no loops are allowed.
+* *weighted graph*: used to represent strength of ties or transition probabilities.
+* *vertex-labeled graph*: most every graph makes use of labeled vertices (e.g. an identifier)
+* *semantic graph*: used to model cognitive structures such as the relationship between concepts and instances of a concept.
+* *vertex-attributed*: used in applications where it is desirable to append non-relational metadata to a vertex.
+* *edge-labeled graph*: provides the ability to denote the way in which two vertices are related (e.g. friendships, kinships, etc.).
+* *directed graph*: orders the vertices connected by an edge to denote directionality.
+* *hypergraph*: generalizes a binary graph to allow an edge to connect to an arbitrary number of vertices.
+* *undirected graph*: the typical graph that is used when the relationship is symmetrical (e.g. friendship).
+* *resource description framework graph*: a graph standard developed by the the World Wide Web consortium that denotes vertices and edges by Uniform Resource Identifiers (see [[Sail Implementation]] and [[Sail Ouplementation]]).
+* *edge-attributed graph*: used in applications where its desirable to append non-relational metadata to an edge.
+* *pseudo graph*: generally allowed in most disciplines to denote a reflexive relationship.
+
+The [[property graph model]] is a convenient graph data model as it is easy to represent other graph types. The following diagram provides the "morphisms":http://en.wikipedia.org/wiki/Morphism that go from one graph type to another. Note that a "hypergraph":http://en.wikipedia.org/wiki/Hypergraph can be modeled using a property graph, though its not as straightforward as modeling other graph types.
+
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/graph-types-morphisms.jpg!
55 doc/wiki/Graph-Transactions.textile
View
@@ -0,0 +1,55 @@
+A @Graph@ that implements the @TransactionalGraph@ or @ThreadedTransactionalGraph@ interfaces must natively support "transaction handling":http://en.wikipedia.org/wiki/Database_transaction. A transaction describes a coherent and complete unit of work comprised of multiple read and write operations to be executed against the database together or not at all. In addition, transactions are needed to handle conflicts and consistency issues that arise when multiple users interact with the @Graph@ concurrently. The exact "ACID":http://en.wikipedia.org/wiki/ACID and "isolation":http://en.wikipedia.org/wiki/Isolation_(database_systems) level guarantees extended by a @TransactionalGraph@ or @ThreadedTransactionalGraph@ depend on the specific implementation.
+
+h2. TransactionalGraph and Starting and Stopping Transactions
+
+A @TransactionalGraph@ has just one method for terminating the transaction:
+
+```java
+public void stopTransaction(Conclusion conclusion);
+```
+
+Transactions are automatically started with the first operation on the graph, that is, any read or write operation. Transactions need to be manually closed to mark the end of a transactional context and to inform the graph database whether the transaction was successful or not, by passing @Conclusion.SUCCESS@ or @Conclusion.FAILURE@ to @stopTransaction@, respectively.
+
+Transactions are bound to the current thread, which means that any graph operation executed by the thread occurs in the context of that transaction and that there may only be one thread executing in a single transaction. For thread independent transactions that allow concurrent thread access, use @ThreadedTransactionalGraph@.
+
+When a transaction is started, all the subsequent read and write operations occur within this transaction context. When the transaction is successfully stopped, those mutations operations are persisted and visible to other contexts interacting with the graph and all locks are released. If a transaction is failed, then the mutation operations are "rolled back" to when the transaction was started.
+
+@TransactionalGraph@ makes no assumptions about how transactions are implemented by a graph database. Hence, a transaction may fail at any point if a conflict arises that could not be resolved.
+
+Note, that a @TransactionalGraph.shutdown()@ will automatically successfully commit any open transaction. Also note, that keeping transactions open for a long time may result in @OutOfMemoryException@ if too many mutations have occurred and possible dead-locks if locks are held for too long in multi-user environments.
+
+Note, that element references created in a transactional context may not be accessed outside the transactional context. Doing so may cause an exception. A transaction marks a complete unit of work and after it is stopped, its state may be discarded. Moreover, concurrently running transaction can render such references out-of-sync. Any references created during the transaction may therefore no longer be alive. Hence, the following code snippet may cause an exception:
+
+```java
+Vertex v = graph.addVertex(null);
+//More operations inside the transaction
+stopTransaction(Conclusion.SUCCESS);
+//Other code
+v.setProperty("name","marko");
+```
+
+In such cases, the transactional context should be extended until all operations have been completed. In other words, the @stopTransaction(Conclusion.SUCCESS)@ call should be moved after the @v.setProperty("name","marko");@ write operation.
+In cases where the element reference needs to be accessed outside its original transactional context, it should be re-instantiated based on the element id. For example:
+
+```java
+Vertex v = graph.addVertex(null);
+//More operations inside the transaction
+stopTransaction(Conclusion.SUCCESS);
+//Other code
+startTransaction();
+v = graph.getVertex(v.getId());
+v.setProperty("name","marko");
+```
+
+h2. ThreadedTransactionalGraph and Multi-Threads for One Transaction
+
+@ThreadedTransactionalGraph@ provides more fine grained control over the transactional context. While @TransactionalGraph@ binds each transaction to the executing thread, @ThreadedTransactionalGraph.startTransaction()@ returns a @TransactionalGraph@ that represents its own transactional context independent of the executing thread.
+Hence, one can have multiple threads operating against a single transaction represented by the returned TransactionalGraph object. This is useful for parallelizing graph algorithms.
+
+A @ThreadedTransactionalGraph@ extends @TransactionalGraph@ with a single method.
+
+```java
+public TransactionalGraph startThreadTransaction()
+```
+
+The returned transaction represented by a @TransactionalGraph@ object needs to be explicitly closed by calling @TransactionalGraph.stopTransaction(Conclusion conclusion)@. Calling @TransactionalGraph.shutdown()@ will successfully commit the transaction without closing the underlying graph database.
194 doc/wiki/GraphML-Reader-and-Writer-Library.textile
View
@@ -0,0 +1,194 @@
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-core</artifactId>
+ <version>??</version>
+</dependency>
+```
+
+Besides being able to query and manipulate the underlying data management system with Blueprints, a "GraphML":http://graphml.graphdrawing.org reader and writer package is provided with Blueprints for streaming XML graph representations into and out of the underlying graph framework. The GraphML package uses "StAX":http://stax.codehaus.org to process a GraphML graph. This section discusses the use of the GraphML library for reading and writing XML-encoded graphs.
+
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/graph-example-1.jpg!
+
+Below is the GraphML representation of the graph diagrammed above. Here are some of the important XML elements to recognize.
+
+* *graphml*: the root element of the GraphML document
+ ** *key*: a type description for graph element properties
+ ** *graph*: the beginning of the graph representation
+ **** *node*: the beginning of a vertex representation
+ **** *edge*: the beginning of an edge representation
+ ****** *data*: the key/value data associated with a graph element
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<graphml xmlns="http://graphml.graphdrawing.org/xmlns">
+ <key id="weight" for="edge" attr.name="weight" attr.type="float"/>
+ <key id="name" for="node" attr.name="name" attr.type="string"/>
+ <key id="age" for="node" attr.name="age" attr.type="int"/>
+ <key id="lang" for="node" attr.name="lang" attr.type="string"/>
+ <graph id="G" edgedefault="directed">
+ <node id="1">
+ <data key="name">marko</data>
+ <data key="age">29</data>
+ </node>
+ <node id="2">
+ <data key="name">vadas</data>
+ <data key="age">27</data>
+ </node>
+ <node id="3">
+ <data key="name">lop</data>
+ <data key="lang">java</data>
+ </node>
+ <node id="4">
+ <data key="name">josh</data>
+ <data key="age">32</data>
+ </node>
+ <node id="5">
+ <data key="name">ripple</data>
+ <data key="lang">java</data>
+ </node>
+ <node id="6">
+ <data key="name">peter</data>
+ <data key="age">35</data>
+ </node>
+ <edge id="7" source="1" target="2" label="knows">
+ <data key="weight">0.5</data>
+ </edge>
+ <edge id="8" source="1" target="4" label="knows" >
+ <data key="weight">1.0</data>
+ </edge>
+ <edge id="9" source="1" target="3" label="created">
+ <data key="weight">0.4</data>
+ </edge>
+ <edge id="10" source="4" target="5" label="created">
+ <data key="weight">1.0</data>
+ </edge>
+ <edge id="11" source="4" target="3" label="created">
+ <data key="weight">0.4</data>
+ </edge>
+ <edge id="12" source="6" target="3" label="created">
+ <data key="weight">0.2</data>
+ </edge>
+ </graph>
+</graphml>
+```
+
+Note that line breaks and indentation have been added for clarity. The default output contains no unnecessary whitespace, but @GraphMLWriter@ does include an option to actually insert the whitespace, as well as ordering elements in the output (see below).
+
+h2. Usage
+
+To read GraphML data into a graph, pass the graph into the @GraphMLReader@ constructor, then call @inputGraph@:
+
+```java
+Graph graph = ...
+InputStream in = ...
+
+GraphMLReader.inputGraph(graph, in);
+```
+
+Note that @inputGraph@ is also overloaded with a "buffer size" parameter. Several setter methods are provided for customizing the property keys which @GraphMLReader@ uses to map the GraphML data into the Property Graphs model. If used, these should be called before @inputGraph@, e.g.
+
+```java
+GraphMLReader reader = new GraphMLReader(graph);
+reader.setVertexIdKey("_id");
+reader.setEdgeIdKey("_id");
+reader.setEdgeLabelKey("_label");
+reader.inputGraph(in);
+```
+
+To output a graph in GraphML format, pass the graph into the @GraphMLWriter@ constructor, then call @outputGraph@:
+
+```java
+Graph graph = ...
+OutputStream out = ...
+
+GraphMLWriter.outputGraph(graph, out);
+```
+
+If you have a large graph and you know the key and value type of all vertex and/or edge properties used in your graph, you can speed up @outputGraph@ by first specifying those properties, e.g.
+
+```java
+Map<String, String> vertexKeyTypes = new HashMap<String, String>();
+vertexKeyTypes.put("age", GraphMLTokens.INT);
+vertexKeyTypes.put("lang", GraphMLTokens.STRING);
+vertexKeyTypes.put("name", GraphMLTokens.STRING);
+Map<String, String> edgeKeyTypes = new HashMap<String, String>();
+edgeKeyTypes.put("weight", GraphMLTokens.FLOAT);
+
+GraphMLWriter writer = new GraphMLWriter(graph);
+writer.setVertexKeyTypes(vertexKeyTypes);
+writer.setEdgeKeyTypes(edgeKeyTypes);
+writer.outputGraph(out);
+```
+
+There is an additional @GraphMLWriter@ method, described below, for enabling normalized GraphML output for use with versioning tools.
+
+h2. Normalizing GraphMLWriter output
+
+@GraphMLWriter@ 's default output is sufficient for saving all of the information in a graph in an interoperable format, which can be loaded in @GraphMLReader@ in order to re-create the graph. However, another important use case for @GraphMLWriter@ has to do with versioning and collaborative editing of graphs. If you call the @setNormalize@ method before calling @outputGraph@, @GraphMLWriter@ will apply additional formatting and constraints to the output so as to make it compatible with line-based versioning tools such as "Subversion":http://subversion.apache.org/ and "Git":http://git-scm.com/, e.g.
+
+```java
+GraphMLWriter writer = new GraphMLWriter(graph);
+writer.setNormalize(true);
+writer.outputGraph(out);
+```
+
+The following is an example of normalized GraphML output. Key definitions appear in alphabetical order, as do vertices and edges (according to the string representation of the id) and vertex and edge properties. The XML is indented consistently, with one start and/or end tag per line:
+
+```xml
+<?xml version="1.0" ?>
+<graphml xmlns="http://graphml.graphdrawing.org/xmlns">
+ <key id="age" for="node" attr.name="age" attr.type="int"></key>
+ <key id="lang" for="node" attr.name="lang" attr.type="string"></key>
+ <key id="name" for="node" attr.name="name" attr.type="string"></key>
+ <key id="weight" for="edge" attr.name="weight" attr.type="float"></key>
+ <graph id="G" edgedefault="directed">
+ <node id="1">
+ <data key="age">29</data>
+ <data key="name">marko</data>
+ </node>
+ <node id="2">
+ <data key="age">27</data>
+ <data key="name">vadas</data>
+ </node>
+ <node id="3">
+ <data key="lang">java</data>
+ <data key="name">lop</data>
+ </node>
+ <node id="4">
+ <data key="age">32</data>
+ <data key="name">josh</data>
+ </node>
+ <node id="5">
+ <data key="lang">java</data>
+ <data key="name">ripple</data>
+ </node>
+ <node id="6">
+ <data key="age">35</data>
+ <data key="name">peter</data>
+ </node>
+ <edge id="10" source="4" target="5" label="created">
+ <data key="weight">1.0</data>
+ </edge>
+ <edge id="11" source="4" target="3" label="created">
+ <data key="weight">0.4</data>
+ </edge>
+ <edge id="12" source="6" target="3" label="created">
+ <data key="weight">0.2</data>
+ </edge>
+ <edge id="7" source="1" target="2" label="knows">
+ <data key="weight">0.5</data>
+ </edge>
+ <edge id="8" source="1" target="4" label="knows">
+ <data key="weight">1.0</data>
+ </edge>
+ <edge id="9" source="1" target="3" label="created">
+ <data key="weight">0.4</data>
+ </edge>
+ </graph>
+</graphml>
+```
+
+This format permits line diffs to be used to capture incremental changes to graphs, so that graphs can be conveniently checked in to a version control repository. You can then commit changes to the graph and roll back to previous versions of the graph, just as you would do with a piece of source code. Forking and merging graphs is also possible within certain limits.
+
+Note that normalizing output in @GraphMLWriter@ is a memory-intensive process, so it is best used in connection with small to medium-sized graphs.
310 doc/wiki/GraphSON-Reader-and-Writer-Library.textile
View
@@ -0,0 +1,310 @@
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-core</artifactId>
+ <version>??</version>
+</dependency>
+```
+
+The GraphSON reader and writer package allows an entire graph to be streamed to and from the standard "JSON":http://json.org format which is utilized across the TinkerPop stack. The format comes in two flavors: one that uses explicit data typing within the JSON and one that does not. For most scenarios, standard JSON without data typing should generally be acceptable. Using the more verbose outputting of explicit data types only provides the added value of ensuring that numeric values are converted properly (ie. float versus double).
+
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/graph-example-1.jpg!
+
+The following example shows the format without explicit data types:
+
+```javascript
+{
+ "graph": {
+ "vertices": [
+ {
+ "name": "lop",
+ "lang": "java",
+ "_id": "3",
+ "_type": "vertex"
+ },
+ {
+ "name": "vadas",
+ "age": 27,
+ "_id": "2",
+ "_type": "vertex"
+ },
+ {
+ "name": "marko",
+ "age": 29,
+ "_id": "1",
+ "_type": "vertex"
+ },
+ {
+ "name": "peter",
+ "age": 35,
+ "_id": "6",
+ "_type": "vertex"
+ },
+ {
+ "name": "ripple",
+ "lang": "java",
+ "_id": "5",
+ "_type": "vertex"
+ },
+ {
+ "name": "josh",
+ "age": 32,
+ "_id": "4",
+ "_type": "vertex"
+ }
+ ],
+ "edges": [
+ {
+ "weight": 1,
+ "_id": "10",
+ "_type": "edge",
+ "_outV": "4",
+ "_inV": "5",
+ "_label": "created"
+ },
+ {
+ "weight": 0.5,
+ "_id": "7",
+ "_type": "edge",
+ "_outV": "1",
+ "_inV": "2",
+ "_label": "knows"
+ },
+ {
+ "weight": 0.4000000059604645,
+ "_id": "9",
+ "_type": "edge",
+ "_outV": "1",
+ "_inV": "3",
+ "_label": "created"
+ },
+ {
+ "weight": 1,
+ "_id": "8",
+ "_type": "edge",
+ "_outV": "1",
+ "_inV": "4",
+ "_label": "knows"
+ },
+ {
+ "weight": 0.4000000059604645,
+ "_id": "11",
+ "_type": "edge",
+ "_outV": "4",
+ "_inV": "3",
+ "_label": "created"
+ },
+ {
+ "weight": 0.20000000298023224,
+ "_id": "12",
+ "_type": "edge",
+ "_outV": "6",
+ "_inV": "3",
+ "_label": "created"
+ }
+ ]
+ }
+}
+```
+
+The following example shows the format with explicit data types:
+
+```javascript
+{
+ "embeddedTypes":true,
+ "vertices": [
+ {
+ "name": {
+ "type": "string",
+ "value": "lop"
+ },
+ "lang": {
+ "type": "string",
+ "value": "java"
+ },
+ "_id": "3",
+ "_type": "vertex"
+ },
+ {
+ "name": {
+ "type": "string",
+ "value": "vadas"
+ },
+ "age": {
+ "type": "integer",
+ "value": 27
+ },
+ "_id": "2",
+ "_type": "vertex"
+ },
+ {
+ "name": {
+ "type": "string",
+ "value": "marko"
+ },
+ "age": {
+ "type": "integer",
+ "value": 29
+ },
+ "_id": "1",
+ "_type": "vertex"
+ },
+ {
+ "name": {
+ "type": "string",
+ "value": "peter"
+ },
+ "age": {
+ "type": "integer",
+ "value": 35
+ },
+ "_id": "6",
+ "_type": "vertex"
+ },
+ {
+ "name": {
+ "type": "string",
+ "value": "ripple"
+ },
+ "lang": {
+ "type": "string",
+ "value": "java"
+ },
+ "_id": "5",
+ "_type": "vertex"
+ },
+ {
+ "name": {
+ "type": "string",
+ "value": "josh"
+ },
+ "age": {
+ "type": "integer",
+ "value": 32
+ },
+ "_id": "4",
+ "_type": "vertex"
+ }
+ ],
+ "edges": [
+ {
+ "weight": {
+ "type": "float",
+ "value": 1
+ },
+ "_id": "10",
+ "_type": "edge",
+ "_outV": "4",
+ "_inV": "5",
+ "_label": "created"
+ },
+ {
+ "weight": {
+ "type": "float",
+ "value": 0.5
+ },
+ "_id": "7",
+ "_type": "edge",
+ "_outV": "1",
+ "_inV": "2",
+ "_label": "knows"
+ },
+ {
+ "weight": {
+ "type": "float",
+ "value": 0.4000000059604645
+ },
+ "_id": "9",
+ "_type": "edge",
+ "_outV": "1",
+ "_inV": "3",
+ "_label": "created"
+ },
+ {
+ "weight": {
+ "type": "float",
+ "value": 1
+ },
+ "_id": "8",
+ "_type": "edge",
+ "_outV": "1",
+ "_inV": "4",
+ "_label": "knows"
+ },
+ {
+ "weight": {
+ "type": "float",
+ "value": 0.4000000059604645
+ },
+ "_id": "11",
+ "_type": "edge",
+ "_outV": "4",
+ "_inV": "3",
+ "_label": "created"
+ },
+ {
+ "weight": {
+ "type": "float",
+ "value": 0.20000000298023224
+ },
+ "_id": "12",
+ "_type": "edge",
+ "_outV": "6",
+ "_inV": "3",
+ "_label": "created"
+ }
+ ]
+}
+```
+
+There are a few differences between the formats. If types are embedded, the JSON must start with an @embeddedTypes@ key with a value of @true@. This key acts as a hint to the reader that it must extract property values in a different manner. If the key is omitted, that setting is assumed to be false.
+
+All values of keys, short of the values for reserved keys that start with an underscore, must contain an object that has two keys: @type@ and @value@. The @type@ must be one of the following: @boolean@, @string@, @integer@, @long@, @float@, @double@, @list@, or @map@.
+
+If the type is a @map@ or a @list@, then each component object that make up that key must use that same format. For example:
+
+```javascript
+"someMap": {
+ "name": {"type":"string", "value":"william"},
+ "age": {"type":"int", "value":76}
+},
+"someList" [{"type":"int", "value":1},{"type":"int", "value":2},{"type":"int", "value":3}]
+```
+
+Please note that complex objects stored as properties will be converted to strings by way of the object's @toString@ method.
+
+h1. Usage
+
+To output a graph in JSON format, pass the graph into the @GraphSONWriter@ constructor, then call @outputGraph@:
+
+```java
+Graph graph = ...
+OutputStream out = ...
+
+GraphSONWriter.outputGraph(graph, out);
+```
+
+The @GraphSONReader@ works in a similar format. Simply pass what would likely be an empty graph into the constructor, then call @inputGraph@:
+
+```java
+Graph graph = ...
+InputStream in = ...
+
+GraphSONReader.inputGraph(graph, in);
+```
+
+There are a number of static method overloads that offer more options and control.
+
+h1. GraphSONUtility Usage
+
+The @GraphSONUtility@ class is used by both @GraphSONReader@ and @GraphSONWriter@ to convert individual graph elements (vertices and edges) to and from the GraphSON format with conversion options to both a "Jettison":http://jettison.codehaus.org/ @JSONObject@ and a "Jackson":http://jackson.codehaus.org/ @ObjectNode@. Usage is as follows:
+
+```java
+Vertex v = graph.getVertex(1);
+JSONObject json = GraphSONUtility.jsonFromElement(v);
+System.out.println(json.toString())
+
+Vertex convertedBack = GraphSONUtility.vertexFromJson(json, new GraphElementFactory(graph), false, null);
+```
+
+The @GraphElementFactory@ is an implementation of the @ElementFactory@ class, that utilizes a @Graph@ instance to construct @Vertex@ and @Edge@ instances. In most cases, the @GraphElementFactory@ is all that is needed to use the @GraphSONUtility@, though in cases where vertices or edges need to be constructed outside of the context of a @Graph@ implementation, it might be necessary to implement a custom implementation.
93 doc/wiki/Home.textile
View
@@ -0,0 +1,93 @@
+[[https://github.com/tinkerpop/blueprints/raw/master/doc/images/blueprints-logo.png|height=152px]]
+
+[[https://github.com/tinkerpop/rexster/raw/master/doc/images/rexster-system-arch.png|width=350px|height=375px|align=right|float]]
+
+Blueprints is a collection of interfaces, implementations, ouplementations, and test suites for the property graph data model. Blueprints is analogous to the "JDBC":http://en.wikipedia.org/wiki/Java_Database_Connectivity, but for "graph databases":http://en.wikipedia.org/wiki/Graph_database. As such, it provides a common set of interfaces to allow developers to plug-and-play their graph database backend. Moreover, software written atop Blueprints works over all Blueprints-enabled graph databases. Within the TinkerPop software stack, Blueprints serves as the foundational technology for:
+
+* "Pipes":http://pipes.tinkerpop.com: A lazy, data flow framework
+* "Gremlin":http://gremlin.tinkerpop.com: A graph traversal language
+* "Frames":http://frames.tinkerpop.com: An object-to-graph mapper
+* "Furnace":http://furnace.tinkerpop.com: A graph algorithms package
+* "Rexster":http://rexster.tinkerpop.com: A graph server
+
+The documentation herein will provide information regarding the use of Blueprints.[1] Please join the Gremlin users group at "http://groups.google.com/group/gremlin-users":http://groups.google.com/group/gremlin-users for all "TinkerPop":http://tinkerpop.com related discussions.
+
+Blueprints JavaDoc: "2.1.0":http://tinkerpop.com/docs/javadocs/blueprints/2.1.0/
+Older JavaDocs (2.x): "2.0.0":http://tinkerpop.com/docs/javadocs/blueprints/2.0.0/
+Older JavaDocs (1.x): "1.2":http://tinkerpop.com/maven2/com/tinkerpop/blueprints/blueprints/1.2/api/ - "1.1":http://tinkerpop.com/maven2/com/tinkerpop/blueprints/blueprints/1.1/api/ - "1.0":http://tinkerpop.com/maven2/com/tinkerpop/blueprints/blueprints/1.0/api/ - "0.9":http://tinkerpop.com/maven2/com/tinkerpop/blueprints/blueprints/0.9/api/ - "0.8":http://tinkerpop.com/maven2/com/tinkerpop/blueprints/blueprints/0.8/api/ - "0.7":http://tinkerpop.com/maven2/com/tinkerpop/blueprints/blueprints/0.7/api/ - "0.6":http://tinkerpop.com/maven2/com/tinkerpop/blueprints/blueprints/0.6/api/ - "0.5":http://tinkerpop.com/maven2/com/tinkerpop/blueprints/0.5/api/ - "0.4":http://tinkerpop.com/maven2/com/tinkerpop/blueprints/0.4/api/ - "0.3":http://tinkerpop.com/maven2/com/tinkerpop/blueprints/0.3/api/ - "0.2":http://tinkerpop.com/maven2/com/tinkerpop/blueprints/0.2/api/ - "0.1":http://tinkerpop.com/maven2/com/tinkerpop/blueprints/0.1/api/
+
+!https://secure.travis-ci.org/tinkerpop/blueprints.png!:http://travis-ci.org/tinkerpop/blueprints
+
+==<hr/>==
+
+```xml
+<!-- neo4j used in this example -->
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-neo4j-graph</artifactId>
+ <version>2.1.0</version>
+</dependency>
+```
+
+Non-Maven users can get the raw jars from Apache's "Central Repository":http://search.maven.org/#browse%7C1398694123.
+
+```java
+Graph graph = new Neo4jGraph("/tmp/my_graph");
+Vertex a = graph.addVertex(null);
+Vertex b = graph.addVertex(null);
+a.setProperty("name","marko");
+b.setProperty("name","peter");
+Edge e = graph.addEdge(null, a, b, "knows");
+e.setProperty("since", 2006);
+graph.shutdown();
+```
+*[[The Major Differences Between Blueprints 1.x and 2.x]]*
+
+==<hr/>==
+
+* Introduction
+ ** [[The Benefits of Blueprints]]
+ ** [[Property Graph Model]]
+ ** [[Graph Morphisms]]
+ ** [[Property Graph Model Test Suite]]
+ ** [[Code Examples]]
+* Advanced Graph Handling
+ ** [[Graph Transactions]]
+ ** [[Graph Indices]]
+ ** [[Vertex Query]]
+* [[Implementations]]
+ ** [[TinkerGraph]] (@TinkerGraph@)
+ ** [[Neo4j Implementation]] (@Neo4jGraph@)
+ **** [[Neo4jHA Implementation]] (@Neo4jHaGraph@)
+ **** [[Neo4jBatch Implementation]] (@Neo4jBatchGraph@)
+ ** [[Sail Implementation]] (@SailGraph@)
+ ** [[OrientDB Implementation]] (@OrientGraph@)
+ ** [[Dex Implementation]] (@DexGraph@)
+ ** [[InfiniteGraph Implementation]] (@IGGraph@)
+ ** "Titan Implementation":http://thinkaurelius.github.com/titan/ (@TitanGraph@)
+ ** "MongoDB Implementation":https://github.com/datablend/blueprints-mongodb (@MongoDBGraph@)
+ ** [[Rexster Implementation]] (@RexsterGraph@)
+ ** [[Desired Implementations]] (*help contribute*)
+* [[Ouplementations]]
+ ** [[JUNG Ouplementation]] (@GraphJung@)
+ ** [[Sail Ouplementation]] (@GraphSail@)
+* Utilities
+ ** Import/Export
+ *** [[GML Reader and Writer Library]]
+ *** [[GraphML Reader and Writer Library]]
+ *** [[GraphSON Reader and Writer Library]]
+ ** Wrappers
+ *** [[Batch Implementation]] (@BatchGraph@)
+ *** [[ReadOnly Implementation]] (@ReadOnlyGraph@)
+ *** [[Event Implementation]] (@EventGraph@)
+ *** [[Partition Implementation]] (@PartitionGraph@)
+ *** [[Id Implementation]] (@IdGraph@)
+* Conclusion
+ ** [[Acknowledgments]]
+ ** [[Release Notes]]
+
+==<hr/>==
+
+<a name="fn1"></a>
+
+fn1. Blueprints documentation is up to date with the current Blueprints "codebase":http://github.com/tinkerpop/blueprints/tree/master, not with the latest Blueprints "release":http://github.com/tinkerpop/blueprints/downloads.
48 doc/wiki/Id-Implementation.textile
View
@@ -0,0 +1,48 @@
+[[http://upload.wikimedia.org/wikipedia/commons/2/2c/Fingerprintforcriminologystubs2.png|width=100px]]
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-core</artifactId>
+ <version>??</version>
+</dependency>
+```
+
+@IdGraph@ is a graph wrapper which affords complete control over element ids. Some @Graph@ implementations, such as @TinkerGraph@, allow you to specify your own ids when you create elements, e.g.
+
+```java
+Graph g = new TinkerGraph();
+Vertex v = g.addVertex("42");
+System.out.println(v.getId()); // prints "42"
+```
+
+Other graph implementations, however, choose element ids for you, e.g.
+
+```java
+Graph g = new Neo4jGraph("/tmp/neo");
+Vertex v = g.addVertex("42");
+System.out.println(v.getId()); // prints "0"
+```
+
+This means that ids are generally not conserved when you move data between graph instances and implementations, to XML and back again, etc. So for applications which need it, there is @IdGraph@. Using vertex and edge indices under the hood, @IdGraph@ enables custom ids regardless of whether the underlying Graph implementation allows them. The only requirement is that the underlying graph is an instance of @IndexableGraph@. E.g.
+
+```java
+IndexableGraph g0 = new Neo4jGraph("/tmp/neo");
+Graph g = new IdGraph(g0);
+Vertex v = g.addVertex("42");
+System.out.println(v.getId()); // prints "42"
+```
+
+When a non-null id is passed to @IdGraph.addVertex@ or @IdGraph.addEdge@, that id will be used to uniquely identify the element. When @null@ is passed in, @IdGraph@ will generate an id for you. By default, the generated id is a pseudo-random UUID string. However, you can supply your own id factory when instantiating @IdGraph@:
+
+```java
+final Random random = new Random();
+IdIndexGraph.IdFactory f = new IdIndexGraph.IdFactory() {
+ public Object createId() {
+ return random.nextInt();
+ }};
+IndexableGraph g0 = new Neo4jGraph("/tmp/neo");
+Graph g = new IdGraph(g0, f);
+Vertex v = g.addVertex(null);
+System.out.println(v.getId()); // prints the random integer id of the vertex
+```
20 doc/wiki/Implementations.textile
View
@@ -0,0 +1,20 @@
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/impls.png!
+
+In order to connect a graph database to Blueprints, the Blueprints property graph interfaces must be implemented. For non-native Blueprints graph databases, the raw graph database API and the Blueprints API need to be coupled. For native Blueprints graph databases, no such coupling is needed as only the interfaces need to be implemented. Each subsection discusses the various implementations of the Blueprints interfaces maintained by the main Blueprints distribution.
+
+*DEPENDENCY NOTE*: It is important to note that including a @<dependency/>@ to Blueprints does not entail all the respective graph database/framework dependencies distributed with Blueprints. The reason for this is that it allows users to include only those graph implementations they wish for their particular projects (e.g. based on licensing, size, performance, etc.).
+
+h1. Developer Notes
+
+This section defines the general rules and standards by which Blueprints implementations are expected to work. By following these implementation details, developers implementing the Blueprints API can expect consistent operations throughout the TinkerPop stack. Many of these details are enforced by the Blueprints test suite, so there will be little choice in those areas when it comes to implementation, however others are merely convention and not explicitly enforced. Choosing not to following convention will introduce risk that the implementation will not work as expected elsewhere in the stack.
+
+h2. getVertex/Edge
+
+The @getVertex@ and @getEdge@ methods on the @Graph@ class accept an @object@ type as the parameter for the respective vertex or edge identifier. Always coerce that identifier to its expected type. If the underlying graph, only expects a @long@ as an identifier, then ensure that the parameter is converted to a long (as it may come in as a @String@ or other such value). If the identifier cannot be coerced to its expected type then simply return @null@.
+
+The identifier parameter cannot be @null@ and if it is an exception should immediately be thrown:
+
+```java
+if (null == id)
+ throw ExceptionFactory.vertexIdCanNotBeNull();
+```
7 doc/wiki/InfiniteGraph-Implementation.textile
View
@@ -0,0 +1,7 @@
+!https://download.infinitegraph.com/images/Objy-InfiniteGraph-with-slogan_Brandmark.png!
+
+"InfiniteGraph":http://www.infinitegraph.com/ is a distributed graph database that provides an implementation of the Blueprints API. This implementation is not distributed with Blueprints, but instead, with InfiniteGraph. The InfiniteGraph implementation may not be completely faithful to the Blueprints API. Please see this "Wiki Page":http://wiki.infinitegraph.com/2.1/w/index.php?title=Understanding_InfiniteGraph_Blueprints_Capabilities_and_Limitations for known limitations.
+
+```java
+Graph graph = new IGGraph("myGraph.boot")
+```
63 doc/wiki/JUNG-Ouplementation.textile
View
@@ -0,0 +1,63 @@
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/jung-visualization.png!
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-graph-jung</artifactId>
+ <version>??</version>
+</dependency>
+```
+
+Blueprints provides an implementation of the "JUNG":http://jung.sourceforge.net/ @edu.uci.ics.jung.graph.Graph<Vertex, Edge>@ interface called @com.tinkerpop.blueprints.pgm.oupl.jung.GraphJung@.
+
+bq. The Java Universal Network/Graph Framework is a software library that provides a common and extensible language for the modeling, analysis, and visualization of data that can be represented as a graph or network. It is written in Java, which allows JUNG-based applications to make use of the extensive built-in capabilities of the Java API, as well as those of other existing third-party Java libraries. -- "JUNG Development Team":http://jung.sourceforge.net/team.html
+
+The benefits of @GraphJung@ is that any application that is written to talk to a JUNG @edu.uci.ics.jung.graph.Graph<Vertex, Edge>@ can now, indirectly, talk to a Blueprints @com.tinkerpop.blueprints.pgm.Graph@. Exciting applications include the use of the JUNG visualization and algorithms packages (see "JUNG JavaDoc":http://jung.sourceforge.net/doc/api/index.html) over any Blueprints-enabled graph database/framework. An example use case involving the JUNG algorithms package is provided below.
+
+```java
+Graph graph = ... // construct a particular Blueprints graph implementation
+PageRank<Vertex,Edge> pageRank = new PageRank<Vertex, Edge>(new GraphJung(graph), 0.15d);
+pageRank.evaluate();
+for (Vertex vertex : graph.getVertices()) {
+ System.out.println("The PageRank score of " + vertex + " is: " + pageRank.getVertexScore(vertex));
+}
+```
+
+For those interested in visualization, the visualization provided at the beginning of this page is done with the following.
+
+```java
+public static void main(String[] args) {
+ GraphJung graph = new GraphJung(TinkerGraphFactory.createTinkerGraph());
+ Layout<Vertex, Edge> layout = new CircleLayout<Vertex, Edge>(graph);
+ layout.setSize(new Dimension(300, 300));
+ BasicVisualizationServer<Vertex, Edge> viz = new BasicVisualizationServer<Vertex, Edge>(layout);
+ viz.setPreferredSize(new Dimension(350, 350));
+
+ Transformer<Vertex, String> vertexLabelTransformer = new Transformer<Vertex, String>() {
+ public String transform(Vertex vertex) {
+ return (String) vertex.getProperty("name");
+ }
+ };
+
+ Transformer<Edge, String> edgeLabelTransformer = new Transformer<Edge, String>() {
+ public String transform(Edge edge) {
+ return edge.getLabel();
+ }
+ };
+
+ viz.getRenderContext().setEdgeLabelTransformer(edgeLabelTransformer);
+ viz.getRenderContext().setVertexLabelTransformer(vertexLabelTransformer);
+
+ JFrame frame = new JFrame("TinkerPop");
+ frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
+ frame.getContentPane().add(viz);
+ frame.pack();
+ frame.setVisible(true);
+}
+```
+
+<br/>
+<hr/>
+<br/>
+
+*NOTE*: JUNG is a library that was developed for in-memory graph structures. As such, many of the aspects of its various classes are memory based. For instance, given the above @PageRank@ example, the method @pageRank.getVertexScore()@ is pulling from an in-memory @Map<Vertex,Double>@ that contains the score for each vertex. If the number of vertices in the graph is large, then such in-memory structures will ultimately throw an @OutOfMemoryError@. As such, be wary of such situations when using @GraphJung@.
60 doc/wiki/Neo4j-Implementation.textile
View
@@ -0,0 +1,60 @@
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/neotech-logo.png!:http://neotechnology.com
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-neo4j-graph</artifactId>
+ <version>??</version>
+</dependency>
+```
+
+```java
+Graph graph = new Neo4jGraph("/tmp/neo4j");
+```
+
+h2. Neo4jGraph Feature List
+
+"Neo Technology":http://neotechnology.com are the developers of the "Neo4j graph database":http://neo4j.org. Neo4j natively supports the property graph data model. Note that Neo4j requires that the value objects in the property map of an element be Java primitives, @java.lang.String@ values, or arrays of primitives and @java.lang.String@ values. @Neo4jElement@ will also accept a @Collection@ of like primitives or @java.lang.String@ values and will convert those to the appropriate array type for storage in Neo4j.
+
+```
+supportsDuplicateEdges: true
+supportsSelfLoops: true
+supportsSerializableObjectProperty: false
+supportsBooleanProperty: true
+supportsDoubleProperty: true
+supportsFloatProperty: true
+supportsIntegerProperty: true
+supportsPrimitiveArrayProperty: true
+supportsUniformListProperty: true
+supportsMixedListProperty: false
+supportsLongProperty: true
+supportsMapProperty: false
+supportsStringProperty: true
+ignoresSuppliedIds: true
+isPersistent: true
+isRDFModel: false
+isWrapper: false
+supportsIndices: true
+supportsVertexIndex: true
+supportsEdgeIndex: true
+supportsKeyIndices: true
+supportsVertexKeyIndex: true
+supportsEdgeKeyIndex: true
+supportsEdgeIteration: true
+supportsVertexIteration: true
+supportsTransactions: true
+supportsThreadedTransactions: false
+```
+
+h2. Indices with Neo4jGraph
+
+It is possible to parameterize the indices created through Blueprints. Learn more about the types of indices supported by Neo4j at "this location":http://docs.neo4j.org/chunked/milestone/indexing-create-advanced.html.
+
+```java
+Index<Vertex> index = graph.createIndex("myIdx", Vertex.class, new Parameter("analyzer", LowerCaseKeywordAnalyzer.class.getName()));
+Vertex a = graph.addVertex(null);
+a.setProperty("name", "marko");
+index.put("name", "marko", a);
+Iterator itty = graph.getIndex("myIdx", Vertex.class).query("name", "MaRkO").iterator();
+assertEquals(itty.next(), a);
+```
62 doc/wiki/Neo4jBatch-Implementation.textile
View
@@ -0,0 +1,62 @@
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-neo4jbatch-graph</artifactId>
+ <version>??</version>
+</dependency>
+```
+
+```java
+Graph graph = new Neo4jBatchGraph("/tmp/neo4j");
+// do your batch insertion
+graph.shutdown();
+graph = new Neo4jGraph("/tmp/neo4j");
+```
+
+@Neo4jBatchGraph@ provides support for the bulk insertion of data into a "Neo4j":http://neo4j.org graph. This Blueprints implementation is single-threaded and non-transactional. It is meant for initial dumps of raw data into a Neo4j graph and is much faster than doing the equivalent process using @Neo4jGraph@ (see [[Neo4j Implementation]]).
+
+*Note*: This is not a pure Blueprints implementation. Consider the following issues when using @Neo4jBatchGraph@:
+
+# Delete methods (except for @Element.removeProperty()@) are not supported.
+# Key indices are not available until after the graph has been shutdown.
+
+Unlike @Neo4jGraph@, and like @TinkerGraph@, @Neo4jBatchGraph@ can accept a @long@ id on vertex creation:
+
+```java
+long id = 1L;
+graph.addVertex(id)
+```
+
+When utilizing @Neo4jBatchGraph@ it is important to make use of the @flush@ method on @Neo4jBatchIndex@. This method must be called before querying the index for data to ensure that it returns results consistently. This method is not a standard @Index@ API method and thus, be sure to typecast the index to @Neo4jBatchIndex@. Note that calling @flush@ (and using indices in general) has a noticeable impact on the performance when writing to the graph. Finally, see @Neo4jBatchGraph.flushIndices()@ for flushing all indices at once.
+
+h2. Neo4jBatchGraph Feature List
+
+```
+supportsDuplicateEdges: true
+supportsSelfLoops: true
+supportsSerializableObjectProperty: false
+supportsBooleanProperty: true
+supportsDoubleProperty: true
+supportsFloatProperty: true
+supportsIntegerProperty: true
+supportsPrimitiveArrayProperty: true
+supportsUniformListProperty: true
+supportsMixedListProperty: false
+supportsLongProperty: true
+supportsMapProperty: false
+supportsStringProperty: true
+ignoresSuppliedIds: false
+isPersistent: true
+isRDFModel: false
+isWrapper: false
+supportsIndices: true
+supportsVertexIndex: true
+supportsEdgeIndex: true
+supportsKeyIndices: true
+supportsVertexKeyIndex: true
+supportsEdgeKeyIndex: true
+supportsEdgeIteration: false
+supportsVertexIteration: false
+supportsTransactions: false
+supportsThreadedTransactions: false
+```
17 doc/wiki/Neo4jHa-Implementation.textile
View
@@ -0,0 +1,17 @@
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-neo4j-graph</artifactId>
+ <version>??</version>
+</dependency>
+```
+
+```java
+Map<String, String> configuration = new HashMap<String, String>();
+configuration.put("ha.machine_id", "1");
+configuration.put("ha.server", "localhost:6001");
+configuration.put("ha.zoo_keeper_servers", "localhost:2181,localhost:2182,localhost:2183");
+Graph graph = new Neo4jHaGraph("/tmp/neo4j", configuration);
+```
+
+@Neo4jHaGraph@ provides support for the Neo4j "High Availability Cluster (HA)":http://docs.neo4j.org/chunked/stable/ha.html which provides a fault-tolerant database structure and horizontal scaling capability. Instantiating the @Neo4jHaGraph@ class requires several configuration elements as shown in the sample above as well as a running "Zookeeper":http://zookeeper.apache.org/ cluster for HA coordination. Setting up the cluster is described "here":http://docs.neo4j.org/chunked/stable/ha.html.
63 doc/wiki/OrientDB-Implementation.textile
View
@@ -0,0 +1,63 @@
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/orientdb-logo.png!
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-orient-graph</artifactId>
+ <version>??</version>
+</dependency>
+```
+
+```java
+Graph graph = new OrientGraph("local:/tmp/orient");
+```
+
+"Orient Technologies":http://www.orientechnologies.com/ are the developers of "OrientDB":http://www.orientechnologies.com/orient-db.htm.
+
+h2. OrientGraph Feature List
+
+```
+supportsDuplicateEdges: true
+supportsSelfLoops: true
+supportsSerializableObjectProperty: true
+supportsBooleanProperty: true
+supportsDoubleProperty: true
+supportsFloatProperty: true
+supportsIntegerProperty: true
+supportsPrimitiveArrayProperty: true
+supportsUniformListProperty: true
+supportsMixedListProperty: true
+supportsLongProperty: true
+supportsMapProperty: true
+supportsStringProperty: true
+ignoresSuppliedIds: true
+isPersistent: true
+isRDFModel: false
+isWrapper: false
+supportsIndices: true
+supportsVertexIndex: true
+supportsEdgeIndex: true
+supportsKeyIndices: true
+supportsVertexKeyIndex: true
+supportsEdgeKeyIndex: true
+supportsEdgeIteration: true
+supportsVertexIteration: true
+supportsTransactions: true
+supportsThreadedTransactions: false
+```
+
+h2. Notes on Caching and Concurrency
+
+By default, "OrientDB keeps a per-database instance cache":http://code.google.com/p/orient/wiki/Caching of vertices and their properties. This can cause issues with concurrent access to the database where different threads will receive inconsistent results when querying the database after writes.
+
+A way around this is to disable OrientDB's L1 cache. This option can slow performance when doing certain graph operations. You can do this in code, before you create your graph with:
+
+```java
+OGlobalConfiguration.CACHE_LEVEL1_ENABLED.setValue(false);
+```
+
+A more fine grained option is to have Orient force reload vertices when appropriate using ODocument's reload() command:
+
+```java
+((ODocument)((OrientVertex)vertex).getRawElement()).reload();
+```
7 doc/wiki/Ouplementations.textile
View
@@ -0,0 +1,7 @@
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/oupls.png!
+
+Blueprints is a collection of interfaces. If these interfaces are implemented, then the underlying graph database is "Blueprints-enabled." In many situations, its desirable to not expose a Blueprints-enabled graph database, but instead, to expose an implementation of another set of interfaces. In the package @com.tinkerpop.blueprints.pgm.oupls@, there are "outplementations" for other popular interfaces. In this way, any Blueprints-enabled graph database can be framed within the context of that set of interfaces.
+
+The naming convention for @impls@ and @oupls@ is as such.
+ * @XXXGraph@: An implementation of the @Graph@ interface. @XXX@ is modeled as a @Graph@.
+ * @GraphXXX@: An ouplementation of the @Graph@ interface to @XXX@. @Graph@ is modeled as an @XXX@.
38 doc/wiki/Partition-Implementation.textile
View
@@ -0,0 +1,38 @@
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/partition-graph.png!
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-core</artifactId>
+ <version>??</version>
+</dependency>
+```
+
+@PartitionGraph@ is a graph wrapper that partitions the elements (vertices/edges) of a graph into @String@ named partitions (i.e. buckets, subgraphs, etc.). The idea behind @PartitionGraph@ is presented in the image above where each element is in a single partition (represented by its color). Partitions can be read from, written to, and linked/joined by edges that span one or two partitions (e.g. a tail vertex in one partition and a head vertex in another).
+
+@PartitionGraph@ is simple to use. There are three primary variables in @PartitionGraph@:
+
+ # *Partition Key*: The property key that denotes a @String@ value representing a partition.
+ # *Write Partition*: A @String@ denoting what partition all future written elements will be in.
+ # *Read Partitions*: A @Set<String>@ of partitions that can be read from.
+
+The best way to understand @PartitionGraph@ is via an example.
+
+```java
+PartitionGraph graph = new PartitionGraph(rawGraph, "_partition", "a"); // reading and writing is to partition "a"
+Vertex v1 = graph.addVertex(null); // v1 has a property of {_partition:"a"}
+graph.setWritePartition("b");
+Vertex v2 = graph.addVertex(null); // v2 has a property of {_partition:"b"}
+graph.getVertices(); // only v1 is in the iterator
+graph.addReadPartition("b");
+graph.getVertices() // both v1 and v2 are in the iterator
+graph.removeReadPartition("a");
+graph.removeReadPartition("b");
+graph.getVertices(); // no vertices are in the iterator
+
+graph.setWritePartition("c");
+Edge e1 = graph.addEdge(null, v1, v2, "knows"); // e1 has a property of {_partition:"c"}
+graph.getEdges(); // e1 is in the iterator
+```
+
+By writing elements to particular partitions and then restricting read partitions, the developer is able to create multiple graphs within a single address space. Moreover, by supporting references between partitions, it is possible to merge those multiple graphs (i.e. join partitions). Finally, there also exists @PartitionIndexableGraph@ with read partition respective index @get()@ and @count()@ methods.
22 doc/wiki/Property-Graph-Implementations.textile
View
@@ -0,0 +1,22 @@
+In order to connect a graph database to Blueprints, the Blueprints property graph interfaces must be implemented. As such, the graph database API and the Blueprints API need to be coupled. Each subsection discusses the various implementations of the Blueprints interfaces maintained by the main Blueprints distribution.
+
+*DEPENDENCY NOTE*: It is important to note that including a @<dependency/>@ to Blueprints does not entail all the respective graph database dependencies. The reason for this is that it allows users to include only those graph database implementations they wish for their particular projects (e.g. based on licensing, size, performance, etc.). However, if all dependencies are desired, then the following @<dependency/>@ can be added to your project's @pom.xml@.
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop</groupId>
+ <artifactId>graphdb-deps-all</artifactId>
+ <version>0.3</version>
+ <packaging>pom</packaging>
+</dependency>
+```
+
+To tailor to particular implementations, please see the @<dependency/>@ snippets in the subsections that follow in this documentation.
+
+```xml
+<repository>
+ <id>tinkerpop-repository</id>
+ <name>TinkerPop Maven2 Repository</name>
+ <url>http://tinkerpop.com/maven2</url>
+</repository>
+```
106 doc/wiki/Property-Graph-Model-Test-Suite.textile
View
@@ -0,0 +1,106 @@
+Blueprints comes with a suite of test cases to ensure that any implementation of the [[property graph model]] interfaces behaves as required in order to work seamlessly within applications that depend on Blueprints. This section will discuss the test suites and how to build a simple JUnit test class to validate an implementation of this model.
+
+There currently exists the following test suites:
+
+# *GraphTestSuite*: ensure that vertices and edges work together properly.
+# *VertexTestSuite*: ensure that vertices and their properties are added and removed properly.
+# *EdgeTestSuite*: ensure that edges and their properties are added and removed properly.
+# *GraphMLReaderTestSuite*: ensure that GraphML files are read properly from disk and represented properly.
+# *GMLReaderTestSuite*: ensure that GML files are read properly from disk and represented properly.
+# *GraphSONReaderTestSuite*: ensure that GraphSON files are read properly from disk and represented properly.
+# *KeyIndexableGraphTestSuite*: ensures that graphs that support automatic key indices work properly.
+# *IndexableGraphTestSuite*: ensures that graphs that support indices behave properly.
+# *IndexTestSuite*: ensure that the index system works properly.
+# *TransactionalGraphTestSuite*: ensures that graphs that support transactions behave properly.
+
+h2. Blueprints-Tests Dependency
+
+It is necessary that the Blueprints test suite is depended when testing a Blueprints-enabled graph framework. Simply import the @blueprints-tests@. With this dependency the test suite is available.
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-tests</artifactId>
+ <version>??</version>
+ <scope>test</scope>
+</dependency>
+```
+
+h2. Testing a Property Graph Model Implementation
+
+To ensure that an implementation of the [[property graph model]] is implemented correctly, a simple "JUnit":http://www.junit.org/ test case of the following form will determine its compliance. Unfortunately, there is no perfect general interface solution that will work regardless of the underlying graph framework, while being specific enough to be useful. For this reason, be sure the @Features@ of the respective @Graph@ implementations are set correctly as this allows the test suite to dynamically alter is testing behavior to account for the various nuances of an implementation.
+
+```java
+public class TinkerGraphTest extends GraphTest {
+
+ public void testVertexTestSuite() throws Exception {
+ this.stopWatch();
+ doTestSuite(new VertexTestSuite(this));
+ printTestPerformance("VertexTestSuite", this.stopWatch());
+ }
+
+ public void testEdgeTestSuite() throws Exception {
+ this.stopWatch();
+ doTestSuite(new EdgeTestSuite(this));
+ printTestPerformance("EdgeTestSuite", this.stopWatch());
+ }
+
+ public void testGraphTestSuite() throws Exception {
+ this.stopWatch();
+ doTestSuite(new GraphTestSuite(this));
+ printTestPerformance("GraphTestSuite", this.stopWatch());
+ }
+
+ public void testKeyIndexableGraphTestSuite() throws Exception {
+ this.stopWatch();
+ doTestSuite(new KeyIndexableGraphTestSuite(this));
+ printTestPerformance("KeyIndexableGraphTestSuite", this.stopWatch());
+ }
+
+ public void testIndexableGraphTestSuite() throws Exception {
+ this.stopWatch();
+ doTestSuite(new IndexableGraphTestSuite(this));
+ printTestPerformance("IndexableGraphTestSuite", this.stopWatch());
+ }
+
+ public void testIndexTestSuite() throws Exception {
+ this.stopWatch();
+ doTestSuite(new IndexTestSuite(this));
+ printTestPerformance("IndexTestSuite", this.stopWatch());
+ }
+
+ public void testGraphMLReaderTestSuite() throws Exception {
+ this.stopWatch();
+ doTestSuite(new GraphMLReaderTestSuite(this));
+ printTestPerformance("GraphMLReaderTestSuite", this.stopWatch());
+ }
+
+ public void testGMLReaderTestSuite() throws Exception {
+ this.stopWatch();
+ doTestSuite(new GMLReaderTestSuite(this));
+ printTestPerformance("GMLReaderTestSuite", this.stopWatch());
+ }
+
+ public void testGraphSONReaderTestSuite() throws Exception {
+ this.stopWatch();
+ doTestSuite(new GraphSONReaderTestSuite(this));
+ printTestPerformance("GraphSONReaderTestSuite", this.stopWatch());
+ }
+
+ public Graph generateGraph() {
+ return new TinkerGraph();
+ }
+
+ public void doTestSuite(final TestSuite testSuite) throws Exception {
+ String doTest = System.getProperty("testTinkerGraph");
+ if (doTest == null || doTest.equals("true")) {
+ for (Method method : testSuite.getClass().getDeclaredMethods()) {
+ if (method.getName().startsWith("test")) {
+ System.out.println("Testing " + method.getName() + "...");
+ method.invoke(testSuite);
+ }
+ }
+ }
+ }
+}
+```
25 doc/wiki/Property-Graph-Model.textile
View
@@ -0,0 +1,25 @@
+[[https://github.com/tinkerpop/blueprints/raw/master/doc/images/graph-example-1.jpg|height=486px]]
+
+Blueprints provides a set of interfaces for the property graph data model. An example instance is diagrammed above. In order to make a data management system "Blueprints-enabled," the Blueprints interfaces must be implemented. However, note that there are various @Graph@ interfaces, each with different types of functionality. For example, if an application only needs a @Graph@, then a @TransactionalGraph@ implementation is not required of the underlying graph.
+
+The following diagram identifies the names of the different components of a @Graph@. In general, these are the basic components of a property graph.
+
+* *Graph*: An object that contains vertices and edges.
+** *Element*: An object that can have any number of key/value pairs associated with it (i.e. properties)
+*** *Vertex*: An object that has incoming and outgoing edges.
+*** *Edge*: An object that has a tail and head vertex.
+
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/property-graph-model.jpg!
+
+A property graph has these elements:
+ # a set of vertices
+ ** each vertex has a unique identifier.
+ ** each vertex has a set of outgoing edges.
+ ** each vertex has a set of incoming edges.
+ ** each vertex has a collection of properties defined by a map from key to value.
+ # a set of edges
+ ** each edge has a unique identifier.
+ ** each edge has an outgoing tail vertex.
+ ** each edge has an incoming head vertex.
+ ** each edge has a label that denotes the type of relationship between its two vertices.
+ ** each edge has a collection of properties defined by a map from key to value.
16 doc/wiki/ReadOnly-Implementation.textile
View
@@ -0,0 +1,16 @@
+!http://icons.iconarchive.com/icons/dryicons/aesthetica-2/128/lock-icon.png!
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-core</artifactId>
+ <version>??</version>
+</dependency>
+```
+
+@ReadOnlyGraph@ and @ReadOnlyIndexableGraph@ wraps any @Graph@ or @IndexableGraph@, respectively. The purpose of a @ReadOnlyGraph@ is to ensure that the graph is not mutated by a mutating method invocation. The following methods throw an @UnsupportedOperationException@:
+
+* *Graph*: @addVertex()@, @removeVertex()@, @addEdge()@, @removeEdge()@, @shutdown()@
+* *IndexableGraph*: @dropIndex()@, @createIndex()@
+* *Element*: @setProperty()@, @removeProperty()@
+* *Index*: @put()@, @remove()@
398 doc/wiki/Release-Notes.textile
View
@@ -0,0 +1,398 @@
+Blueprints: A Property Graph Model Interface
+"http://blueprints.tinkerpop.com":http://blueprints.tinkerpop.com
+
+h2. Blueprints 2.y.z
+
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/blueprints-2.png!
+
+h3. Version 2.1.0 (August 4, 2012)
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-core</artifactId>
+ <version>2.1.0</version>
+</dependency>
+```
+
+* Enable tests for @KeyIndexableGraph@ under @RexsterGraph@. Issue with casting index values resolved.
+* Optimized the pom.xml for both the parent and child projects
+* Added Travis continuous integration support
+* Made @OrientGraph@ and @Neo4jGraph@ Element constructors public
+* Provided a method to turn on/off @Neo4jGraph@ transaction consistency checking. Default behavior being native Neo4j.
+* Removed @TransactionalGraph.startTransaction()@ as transactions are auto-started
+* Bumped to support Dex 4.6.0
+* Bumped to support Neo4j 1.8.M06
+* An @Element@ can not have a property key that is the empty string
+* Update @RexsterGraph@ to utilize Vertex Query API of Rexster.
+* Renaming of GraphSONFactory to GraphSONUtility and various method renaming within that class.
+* Fixed an iterable consistency issue in @Neo4jGraph@
+* Removed unneeded Exception catching in both @Neo4jGraph@ and @OrientGraph@
+* Bumped to support Orient 1.1.0
+
+==<hr/>==
+
+h3. Version 2.0.0 (May 23, 2012)
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-core</artifactId>
+ <version>2.0.0</version>
+</dependency>
+```
+
+* Added a var args based @ElementHelper.setProperties()@ method
+* Added GML Reader/Writer utility
+* Bumped to support Neo4j 1.8.M02
+* @RexsterGraph@ supports Rexster Authentication
+* @Neo4jElement@ will accept a @Collection@ as a property (as long as all items within it are of the same data type), internally converting it to an array for storage in Neo4j
+* Fixed a couple of API naming convention errors in @PartitionGraph@
+* Updated core @Vertex@ API to support the notion of 'push down predicates' (lower level element filtering)
+* Added internal support for Neo4j's @Node@ var args of @RelationshipTypes@
+* Speed improvements to the much used @MultiIterable@
+* Removed @CloseableSequence@ and replaced with @CloseableIterable@ (now real Java @Iterable@ semantics respected)
+* Redesign to @IndexableGraph@ where @AutomaticIndex@ no longer exists as is default
+* Introduced new interface called @KeyIndexedGraph@ for basic key/value property indexing
+* Reduce the number of vertices/edges created in various test suites to speed up testing
+* Added @Features@ so developers can learn about the various quirks of any @Graph@ implementation
+* Support for Neo4j's native automatic indices in @Neo4jGraph@
+* Support for Neo4j's native automatic indices in @Neo4jBatchGraph@
+* Added @ExceptionFactory@ so all exceptions have the same message and type amongst graph implementations
+* Removed superfluous @util@ packages on all @Graph@ implementations
+* @EventGraph@ wrapper set now includes @EventTransactionalGraph@ which will fire queued sets of events in conjunction with successful commits to the graph.
+* Added @IdGraph@ to support the user defined ids for those @Graphs@ that ignore user supplied ids
+* Added @ThreadTransactionalGraph@ to support multiple threads within a single transaction
+* Changed the @Vertex@ API to only have three methods: @getEdges()@, @getVertices()@, and @query()@
+* Bumped to support OrientDB 1.0.1
+* Added @BatchGraph@ to support bulk loading of data
+
+==<hr/>==
+
+h2. Blueprints 1.x
+
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/blueprints-bluesky.png!
+
+h3. Version 1.2 (Blue Sky -- February 28, 2012)
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-core</artifactId>
+ <version>1.2</version>
+</dependency>
+```
+
+* Fixed @Neo4jGraph@ index object caching bug which was made salient with multiple threads
+* Fixed @SailGraph@ to now commit transactions on shutdown
+* Updated @Neo4jGraph@ to use @GlobalGraphOperations@ methods for @getAllNodes()@ and @getAllRelationships()@
+* Bumped to support Neo4j 1.6.1
+* Fixed "fresh"-constructor bug in @Neo4jGraph@
+* Added method support for named graphs in @SailGraph@
+* Fixed named graph bug in @SailGraph@
+* @Neo4jBatchGraph@ now has nearly analogous behavior to any @IndexableGraph@ except for the ability to delete
+* Fixed issue with Neo4j's native automatic index and @Neo4jGraph.dropIndex()@
+* Added @PartitionGraph@ utility to allow for graph partitions
+* Renamed packages where there is now @util.io@ and @util.wrappers@ for I/O and wrapper-based utilities
+* Added support for index parameters in @IndexableGraph@ (provided as optional parameters, thus backwards compatible)
+* Optimized how @TinkerGraph@ stores its vertices' edges in memory (grouping on label)
+
+==<hr/>==
+
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/blueprints-blueberry.png!
+
+h3. Version 1.1 (Blueberry -- December 7, 2011)
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-core</artifactId>
+ <version>1.1</version>
+</dependency>
+```
+
+* Fixed index consistency issue in @OrientGraph@
+* Added @Neo4jHaGraph@ allowing a more direct way to utilize Neo4j High Availability mode
+* General API consistency improvements
+** Graphs attempt to create directories structures for graph persistence
+** GetVertex/Edge throw @IllegalArgumentException@ if passed a null identifier as a parameter
+** GetVertex/Edge return @null@ if the element cannot be found, if the identifier does not match the expected format of the underlying graph database or if the underlying graph database throws exceptions during the lookup
+* @RexsterGraph@ utilizes the @application/vnd.rexster.typed+json@ custom mime type
+* The @EventGraph.addEdge()@ method now properly fires the @onEdgeAdded@ event with improved test cases
+* Added @WrappedGraph@ as a template for how to build stackable graph implementations
+* Added @SparqlRepositorySailGraph@ to support a @Graph@ representation of any SPARQL endpoint
+* Renamed @GraphJSONxxx@ to @GraphSONxxx@ to promote as standardized JSON graph format
+* Bumped to support OrientDB 1.0rc7
+* Bumped to support Neo4j 1.5
+
+==<hr/>==
+
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/blueprints-blueprints.png!
+
+h3. Version 1.0 (Blueprints -- September 18, 2011)
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-core</artifactId>
+ <version>1.0</version>
+</dependency>
+```
+
+* Bumped to support Neo4j 1.5.M01
+* Bumped to support OrientDB 1.0rc5
+* @RexsterGraph@ uses the actual count REST API instead of pulling back all results first and checking size
+* @GraphJSONReader@ and @GraphJSONWriter@ utility classes
+* Updated @TransactionalGraph@ API to support transaction buffers
+** Removed @TransactionalGraphHelper.CommitManager@ as it is no longer relevant
+** Changed @TransactionalGraph.close()@ to @Conclusion.SUCCESS@ any open transactions
+* Fixed a @ConcurrentModificationException@ in @TinkerGraph@ and added respective test cases for all graphs
+* Added @StringFactory.graphString()@ for a unified @String@ representation of a Blueprints graph
+* Added @Neo4jBatchGraph@ to support bulk inserting of graph data into a Neo4j instance
+
+h2. Blueprints 0.x
+
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/blueprints-marvin.png!
+
+h3. Version 0.9 (Marvin -- August 1, 2011)
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-core</artifactId>
+ <version>0.9</version>
+</dependency>
+```
+
+* Updated Vertex API to have @getOutEdges(String...)@ and @getInEdges(String...)@
+* Updated @TinkerGraph@ to be @ConcurrentModificationException@ safe
+* Bumped to support Neo4j 1.4
+* Bumped to support OrientDB 1.0rc4
+* @IndexableGraph.getIndex()@ now return @null@ for non-existent indices instead of @RuntimeException@
+* Added support for statement deduplication (now the default) in @GraphSail@
+* Refactored @GraphMLReader@ and @GraphMLWriter@ to use a more typical pattern for readers and writers (rather than continuing to overload @inputGraph()@ and @outputGraph()@). Added normalizing functionality to @GraphMLWriter@, enabling graph versioning
+* Changed the property graph schema of @GraphSail@ to more closely resemble the @SailGraph@ schema
+* Extended @GraphSail@ to support Sesame-style inferencing
+* @SailGraph@ dangling connection issue fixed
+* Updated @Index.toString()@ to make it more readable and compact
+* Updated @graph.getVertex/Edge(null)@ to ensure that @null@ is returned
+
+==<hr/>==
+
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/blueprints-winnie.png!
+
+h3. Version 0.8 (Winnie -- June 15, 2011)
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-core</artifactId>
+ <version>0.8</version>
+</dependency>
+```
+
+* Added @EventGraph@ implementation
+* @RexsterGraph@ improvements
+** Use of POST for REST Service Requests
+** Better implementation URL encoding
+* Change JSON library from json-simple to jettison to be more in line with the rest of the TinkerPop stack.
+* A more robust implementation of the @TransactionalGraph@ implementation for @Neo4jGraph@, @OrientGraph@, and @SailGraph@.
+* Bumped to Neo4j 1.4.M04
+* Bumped to Orient 1.0rc2-SNAPSHOT
+* Bumped to Sail 2.4.0
+
+ ==<hr/>==
+
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/blueprints-patrick.png!
+
+h3. Version 0.7 (Patrick -- May 8, 2011)
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-core</artifactId>
+ <version>0.7</version>
+</dependency>
+```
+
+* Updated @RexsterGraph@ to work with latest Rexster REST API changes
+* Bumped to Neo4j 1.4.M01
+* Bumped to OrientDB 1.0rc1
+* Bumped to Sail 2.3.3
+
+
+==<hr/>==
+
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/blueprints-oscar.png!
+
+h3. Version 0.6 (Oscar -- April 4, 2011)
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-core</artifactId>
+ <version>0.6</version>
+</dependency>
+```
+
+* Refactored to create a Maven multiproject with one module per major Blueprints component
+* Added @DexGraph@ implementation ("Sparsity Technologies":http://www.sparsity-technologies.com/)
+* Bumped to OrientDB 1.0rc1-SNAPSHOT
+* Bumped to Neo4j 1.3M05
+* Fixed equals() and hashCode() bug in @ReadOnlyGraph@
+* Bumped to supporting JUNG 2.0.1
+* Added @Index.count()@ method to Blueprints core API.
+
+==<hr/>==
+
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/blueprints-scooby.png!
+
+h3. Version 0.5 (Scooby -- March 2, 2011)
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop</groupId>
+ <artifactId>blueprints</artifactId>
+ <version>0.5</version>
+</dependency>
+```
+
+* Updated index model
+** Changed the API and semantics of @AutomaticIndex@
+** Changed the API of @IndexableGraph@
+* Fixed index related bug in @RexsterGraph@
+* Added numerous utilities to @util@ package
+** Added support for bulk processing with @CommitManager@
+* Added UTF-8 writer to @GraphMLWriter@
+* Updates to @OrientGraph@ implementation
+* Fixed bug in @Neo4jGraph@ index loader
+* Added @toString()@ method to indices
+* Added experimental Lucene query syntax support for @Neo4jGraph@
+* Bumped version support to Neo4j 1.3.M03
+* Added performance benchmark for Neo4j @GraphDatabaseService@ vs. Blueprints @Neo4jGraph@
+* Added performance benchmark for OrientDB @OGraphDatabase@ vs. Blueprints @OrientGraph@
+* Added @Vertex.getOutEdges(String label)@ and @Vertex.getInEdges(String label)@
+* Rewrote OrientDB implementation from scratch (significant reduction in code) (Luca)
+* Added @ReadOnlyGraph@ and @ReadOnlyIndexableGraph@ to prevent graph mutations
+
+==<hr/>==
+
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/blueprints-elmo.png!
+
+h3. Version 0.4 (Elmo -- January 22, 2011)
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop</groupId>
+ <artifactId>blueprints</artifactId>
+ <version>0.4</version>
+</dependency>
+```
+
+* Added support for Neo4j 1.2
+* Added edge label indexing to @AutomaticIndex@
+* Added concept of "ouplementation"
+** Repackaged JUNG ouplementation as @GraphJung@
+** Added Sail ouplementation as @GraphSail@
+* Created @util@ utility package
+** Repackaged GraphML library in @util.graphml@
+
+
+==<hr/>==
+
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/blueprints-smurf.png!
+
+h3. Version 0.3 (Smurf -- December 14, 2010)
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop</groupId>
+ <artifactId>blueprints</artifactId>
+ <version>0.3</version>
+</dependency>
+```
+
+* Moved to @graphdb-deps-*@ database dependency management model
+** Neo4j 1.2.M05
+** OrientDB 0.9.24.1
+** Sail 2.3.1
+** Rexster 0.1
+* Removed object document model to focus Blueprints specifically on property graphs
+** Removed support for TinkerDoc, MongoDB, and CouchDB
+* @OrientGraph@ now implements @TransactionalGraph@ interface
+* Many updates to @TransactionalGraphTestSuite@
+** Large transactions now tested
+** Added timing tests to all tests
+* Updated @Index@ semantics where @get()@ no elements returns an empty iterator, not @null@
+* Updated the @toString()@ method of @TinkerGraph@ to display both vertex and edge counts
+* Added support for multiple indices
+** Added @IndexableGraph@, @Index@, and @AutomaticIndex@ interfaces
+** Added numerous test cases to the test suite
+* Updated @GraphMLReader@
+** More efficient implementation
+** Can specify ids and labels through @_id@ and @_label@ data properties
+* Added @GraphMigrator@ to stream the data in one graph to another
+* Added @RexsterGraph@ to connect to remote graphs over HTTP-REST
+* Added JavaDoc to all property graph model interfaces
+
+==<hr/>==
+
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/blueprints-kermi.png!
+
+h3. Version 0.2 (Kermit -- September 22, 2010)
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop</groupId>
+ <artifactId>blueprints</artifactId>
+ <version>0.2</version>
+</dependency>
+```
+
+* Removed Blueprints Pipes BETA and put it into a separate project
+* @Neo4jGraph@ constructor can be passed in a Neo4j properties map
+* @Neo4jGraph@ constructor can be passed in a live @GraphDatabaseService@
+* Updated @GraphMLWriter@ to write all vertices and then all edges
+* Added RDF load functionality to @SailGraph@
+* Added SPARQL functionality to @SailGraph@
+* Fixed sever @GraphMLReader@ bug
+* Added OrientDB (@OrientGraph@) as a property graph implementation
+* Added support for @Graph.getEdge(Object id)@
+* Added support for @kind@ in the Sail implementation of Blueprints
+* Made iterating edges in @SailGraph@ faster and more memory efficient
+* Support for transactions through @TransactionalGraph@
+
+==<hr/>==
+
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/blueprints-bob-the-builder.png!
+
+h3. Version 0.1.1 (Bob the Builder -- March 7, 2010)
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop</groupId>
+ <artifactId>blueprints</artifactId>
+ <version>0.1.1</version>
+</dependency>
+```
+
+* Added Blueprints Pipes BETA to the distribution
+* Changed all the OpenRDF Sesame dependencies to version 2.3.1
+* Added performance timing printouts to model test cases
+* Neo4j dependency was changed for 1.0-rc to 1.0
+* Added object document interfaces
+* Added TinkerDoc implementation of the object document interfaces
+* Added MongoDB implementation of the object document interfaces
+
+h3. Version 0.1 (Bob the Builder -- February 9, 2010)
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop</groupId>
+ <artifactId>blueprints</artifactId>
+ <version>0.1</version>
+</dependency>
+```
+
+* Initial release providing the property graph model
+* Code originally packaged with "Gremlin":http://gremlin.tinkerpop.com
15 doc/wiki/Rexster-Implementation.textile
View
@@ -0,0 +1,15 @@
+!https://github.com/tinkerpop/rexster/raw/master/doc/images/rexster-logo.png!
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-rexster-graph</artifactId>
+ <version>??</version>
+</dependency>
+```
+
+"Rexster":http://rexster.tinkerpop.com is a RESTful graph shell that exposes any Blueprints graph through a standalone HTTP server. @RexsterGraph@ talks to a Rexster-exposed graph via the "Rexster RESTful API":https://github.com/tinkerpop/rexster/wiki/Basic-REST-API. Thus, @RexsterGraph@ can be used to communicate with a remote graph with complete HTTP-transparency to the user. @RexsterGraph@ is composed of HTTP calls (through @java.net.*@) and "JSON":http://json.org/ parsing.
+
+```java
+Graph graph = new RexsterGraph("http://localhost:8182/graphs/tinkergraph");
+```
113 doc/wiki/Sail-Implementation.textile
View
@@ -0,0 +1,113 @@
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/openrdf-logo.png!:http://www.openrdf.org
+
+"OpenRDF":http://www.openrdf.org is the creator of the "Sail":http://www.openrdf.org/doc/sesame2/2.3.0/users/ch08.html interface (Storage and Inference Layer). Any triple or quad-store developer can implement the Sail interfaces in order to allow third-party developer to work with different stores without having to change their code. This is very handy as different RDF-store implementations are optimized for different types of use cases. In analogy, Sail is like the "JDBC":http://java.sun.com/javase/technologies/database/ of the RDF database world.
+
+bq.. The Storage And Inference Layer (Sail) API is a low level System API (SPI) for RDF stores and inferencers. Its purpose is to abstract from the storage and inference details, allowing various types of storage and inference to be used. The Sail API is mainly of interest for those who are developing Sail implementations, for all others it suffices to know how to create and configure one. There are several implementations of the Sail API, for example the MemoryStore which stores RDF data in main memory, and the NativeStore which uses dedicated on-disk data structures for storage. (source "OpenRDF Sesame Users Guide":http://www.openrdf.org/doc/sesame2/2.3.0/users/index.html)
+
+p. Many triple and quad-store developers have implemented the Sail interface. Supported implementations are provided below.
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-sail-graph</artifactId>
+ <version>??</version>
+</dependency>
+```
+
+* "OpenRDF":http://www.openrdf.org ("MemoryStore":http://www.openrdf.org/doc/sesame2/2.3.0/users/ch08.html#d0e705, "NativeStore":http://www.openrdf.org/doc/sesame2/2.3.0/users/ch08.html#d0e746)
+
+```java
+Graph graph = new MemoryStoreSailGraph();
+Graph graph = new NativeStoreSailGraph("/tmp/nativestore");
+```
+
+* "Linked Data Sail":https://github.com/joshsh/ripple/wiki/LinkedDataSail
+
+```java
+Graph graph = new LinkedDataSailGraph(new MemoryStoreSailGraph());
+Vertex v = graph.getVertex("http://dbpedia.org/resource/Graph_Database");
+```
+
+* "SPARQL Repository":http://www.openrdf.org/doc/sesame2/api/org/openrdf/repository/sparql/SPARQLRepository.html
+
+```java
+Graph graph = new SparqlRepositorySailGraph("http://dbpedia.org/sparql");
+```
+
+Any of these stores can be manipulated with Blueprints through their Sail interfaces. Here is a list of aspects of RDF that should be understood when dealing with Blueprints over an RDF store.
+
+# *No duplicate edges*: RDF considers two edges the same if they share the same subject, predicate, object, and graph. Thus, edges with these in common are, in fact, the same edge.
+# *No indices*: There are no indices as no elements have properties that can not be accessed simply by using referencing their id (i.e. their URI, blank node, or literal string).
+# *Infinite vertices*: RDF is edge based and as such, every possible vertex exists. It is only when finding outgoing or incoming edges to some vertex do you recognize it within a larger graph structure. For this reason, you can not iterate over all vertices in the graph.
+
+==<hr/>==
+
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/rdf-logo.gif!:http://www.w3.org/RDF/
+
+The "Resource Description Framework":http://www.w3.org/RDF/ can be modeled as a property graph. Moreover, it is possible to model "RDF quads":http://www.w3.org/2004/03/trix/ (triples within a named graph) as a property graph. This page articulates the mapping between RDF quads and the property graph model.
+
+h2. Mapping RDF to a Property Graph
+
+An RDF quad statement is denoted by a subject, a predicate, an object, and a named graph (the "spog" model for short). The set of subjects is the set of all Uniform Resource Identifiers (URIs) and blank nodes. The set of predicates is the set of all URIs. The set of objects is the set of all URIs, blank nodes, and literals. Finally, the set of named graphs is the set of all URIs and blank nodes. The following diagram demonstrates how RDF is modeled using the [[property graph model]].
+
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/rdf-graph-model.jpg!
+
+The identifier (@id@) of a vertex is the string representation of the RDF value that it is modeling/representing. A few examples are provided below:
+
+# URI
+ ** @http://markorodriguez.com@
+ ** @http://tinkerpop.com#ripple@
+ ** @urn:uuid:aa9d07d7-8ccf-454a-b08a-5e5a8c560154@
+# Blank Node
+ ** @_:A12345@
+ ** @_:anonymous-node@
+# Literal
+ ** @"hello"@
+ ** @"hello"@ @@en@
+ ** @"hello"^^<http://www.w3.org/2001/XMLSchema#string>@
+
+All vertices have a *kind* property (@kind@) that is either @uri@, @literal@, or @bnode@. Only literal-based vertices have three other vertex properties. Only two of which can be set. These properties are the *language* (@lang@), the *datatype* (@type@), and the *typecasted value* (@value@) of the literal label. Note that in RDF, a literal can have either a language, a datatype, or neither. Never can a literal have both a language and a datatype. The typecasted value is the object created by the casting of the label of the literal by its datatype. In other words the @value@ of @"6"^^<http://www.w3.org/2001/XMLSchema#int>@ is the integer 6.
+
+Finally, an edge in the [[property graph model]] represents an RDF statement. The identifier of an edge is the string representation of the RDF statement. Two examples are provided below. One where the RDF statement is a triple and the other where the statement is a quad.
+
+# Statement
+ ** @(http://tinkerpop.com#marko, http://someontology.com#age, "30"^^<http://www.w3.org/2001/XMLSchema#int>)@
+ ** @(http://tinkerpop.com#marko, http://www.w3.org/2002/07/owl#sameAs, http://markorodrigue.com#marko) [http://tinkerpop.com#graph]@
+
+Statements can only have a single property. Namely, the named graph property (@ng@).
+
+The graph diagrammed in [[GraphML Reader and Writer Library]] would be represented in an RDF property graph as the following.
+
+!https://github.com/tinkerpop/gremlin/raw/master/doc/images/graph-example-1-rdf.jpg!
+
+h2. SailGraph Feature List
+
+```
+supportsDuplicateEdges: false
+supportsSelfLoops: true
+supportsSerializableObjectProperty: false
+supportsBooleanProperty: false
+supportsDoubleProperty: false
+supportsFloatProperty: false
+supportsIntegerProperty: false
+supportsPrimitiveArrayProperty: false
+supportsUniformListProperty: false
+supportsMixedListProperty: false
+supportsLongProperty: false
+supportsMapProperty: false
+supportsStringProperty: false
+ignoresSuppliedIds: false
+isPersistent: false
+isRDFModel: true
+isWrapper: false
+supportsIndices: false
+supportsVertexIndex: false
+supportsEdgeIndex: false
+supportsKeyIndices: false
+supportsVertexKeyIndex: false
+supportsEdgeKeyIndex: false
+supportsEdgeIteration: true
+supportsVertexIteration: false
+supportsTransactions: true
+supportsThreadedTransactions: false
+```
198 doc/wiki/Sail-Ouplementation.textile
View
@@ -0,0 +1,198 @@
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/openrdf-logo.png!
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-graph-sail</artifactId>
+ <version>??</version>
+</dependency>
+```
+
+
+"Sail":http://www.openrdf.org/doc/sesame2/api/org/openrdf/sail/Sail.html is an "RDF":http://www.w3.org/RDF/ triple/quad store interface developed by "OpenRDF":http://openrdf.org. Any database the implements the Sail interfaces properly is a valid RDF triple/quad store. A graph database is a great way to build a triple/quad store because its possible to mix indexing and graph traversals to solve the RDF "pattern match" problem. To go from @Graph@ to @Sail@, simply use @GraphSail@. @GraphSail@ requires an @IndexableGraph@ (e.g. @TinkerGraph@, @Neo4jGraph@, @OrientGraph@). The examples below use [[TinkerGraph]] and expose it as a @GraphSail@ and thus, a @Sail@. While some basic examples are provided, please refer to the "OpenRDF":http://openrdf.org Sail documentation for a complete review of the framework.
+
+*NOTE ON TRANSACTION SAFETY:* as of Blueprints 2.0, there are issues in the @Neo4jGraph@ and @OrientGraph@ implementations which affect the transaction safety of GraphSail (see "here":https://github.com/tinkerpop/blueprints/issues/236, and "here":https://github.com/tinkerpop/blueprints/issues/268), among other applications. There is a workaround for the Neo4jGraph issue (see below), while the OrientGraph issue has yet to be resolved. In the meantime, please "contact us":mailto:josh@fortytwo.net if you encounter any problems, and we will do our best to come up with a targeted solution.
+
+To ensure the transaction safety of Neo4jGraph, use the @setCheckElementsInTransaction@ method, e.g.
+
+```java
+Neo4jGraph graph = new Neo4jGraph("/path/to/db");
+graph.setCheckElementsInTransaction(true);
+Sail sail = new GraphSail(graph);
+sail.initialize();
+```
+
+h2. Basic Statement Handling
+
+A statement in RDF is a triple or quad. The components of a statement are called: subject, predicate, object, and graph/context. The subject can be a URI or blank node. The predicate can only be a URI. The object can be a URI, blank node, or literal. Finally, the graph (or context) can be a URI or blank node.
+
+```java
+TinkerGraph graph = new TinkerGraph();
+Sail sail = new GraphSail(graph);
+sail.initialize();
+SailConnection sc = sail.getConnection();
+ValueFactory vf = sail.getValueFactory();
+sc.addStatement(vf.createURI("http://tinkerpop.com#1"), vf.createURI("http://tinkerpop.com#knows"), vf.createURI("http://tinkerpop.com#3"), vf.createURI("http://tinkerpop.com"));
+sc.addStatement(vf.createURI("http://tinkerpop.com#1"), vf.createURI("http://tinkerpop.com#name"), vf.createLiteral("marko"), vf.createURI("http://tinkerpop.com"));
+sc.addStatement(vf.createURI("http://tinkerpop.com#3"), vf.createURI("http://tinkerpop.com#name"), vf.createLiteral("josh"), vf.createURI("http://tinkerpop.com"));
+
+System.out.println("get statements: ?s ?p ?o ?g");
+CloseableIteration<? extends Statement, SailException> results = sc.getStatements(null, null, null, false);
+while(results.hasNext()) {
+ System.out.println(results.next());
+}
+
+System.out.println("\nget statements: http://tinkerpop.com#3 ?p ?o ?g");
+results = sc.getStatements(vf.createURI("http://tinkerpop.com#3"), null, null, false);
+while(results.hasNext()) {
+ System.out.println(results.next());
+}
+
+sc.close();
+graph.shutdown();
+sail.shutDown();
+```
+
+```text
+get statements: ?s ?p ?o ?g
+(http://tinkerpop.com#1, http://tinkerpop.com#knows, http://tinkerpop.com#3) [http://tinkerpop.com]
+(http://tinkerpop.com#3, http://tinkerpop.com#name, "josh") [http://tinkerpop.com]
+(http://tinkerpop.com#1, http://tinkerpop.com#name, "marko") [http://tinkerpop.com]
+
+get statements: http://tinkerpop.com#3 ?p ?o ?g
+(http://tinkerpop.com#3, http://tinkerpop.com#name, "josh") [http://tinkerpop.com]
+```
+
+h2. Using SPARQL
+
+"SPARQL":http://www.w3.org/TR/rdf-sparql-query/ is the standard query language for RDF stores. OpenRDF provides a SPARQL query engine that can be used over any @Sail@. An example is provided below. Assume that the same statements from the previous example exist in the @GraphSail@ below.
+
+```java
+SPARQLParser parser = new SPARQLParser();
+CloseableIteration<? extends BindingSet, QueryEvaluationException> sparqlResults;
+String queryString = "SELECT ?x ?y WHERE { ?x <http://tinkerpop.com#knows> ?y }";
+ParsedQuery query = parser.parseQuery(queryString, "http://tinkerPop.com");
+
+System.out.println("\nSPARQL: " + queryString);
+sparqlResults = sc.evaluate(query.getTupleExpr(), query.getDataset(), new EmptyBindingSet(), false);
+while (sparqlResults.hasNext()) {
+ System.out.println(sparqlResults.next());
+}
+```
+
+```text
+SPARQL: SELECT ?x ?y WHERE { ?x <http://tinkerpop.com#knows> ?y }
+[y=http://tinkerpop.com#3;x=http://tinkerpop.com#1]
+```
+
+h2. Moving Between Sail and Graph
+
+Its possible to get the @Graph@ that is being modeled as a @Sail@ and work from the Blueprints API perspective. In this way, its possible to leverage the tools provided for both @Sail@ and Blueprints @Graph@.
+
+```java
+Graph graph = ((GraphSail) sail).getGraph();
+System.out.println();
+for (Vertex v : graph.getVertices()) {
+ System.out.println("------");
+ System.out.println(v);
+ for (String key : v.getPropertyKeys()) {
+ System.out.println(key + "=" + v.getProperty(key));
+ }
+}
+for (Edge e : graph.getEdges()) {
+System.out.println("------");
+System.out.println(e);
+for (String key : e.getPropertyKeys()) {
+ System.out.println(key + "=" + e.getProperty(key));
+}
+```
+
+```text
+------
+v[2]
+value=http://tinkerpop.com#3
+kind=uri
+------
+v[1]
+value=http://tinkerpop.com#1
+kind=uri
+------
+v[0]
+value=urn:com.tinkerpop.blueprints.pgm.oupls.sail:namespaces
+------
+v[6]
+value=josh
+kind=literal
+------
+v[4]
+value=marko
+kind=literal
+------
+e[3][1-http://tinkerpop.com#knows->2]
+cp=U http://tinkerpop.com U http://tinkerpop.com#knows
+c=U http://tinkerpop.com
+p=U http://tinkerpop.com#knows
+------
+e[7][2-http://tinkerpop.com#name->6]
+cp=U http://tinkerpop.com U http://tinkerpop.com#name
+c=U http://tinkerpop.com
+p=U http://tinkerpop.com#name
+------
+e[5][1-http://tinkerpop.com#name->4]
+cp=U http://tinkerpop.com U http://tinkerpop.com#name
+c=U http://tinkerpop.com
+p=U http://tinkerpop.com#name
+```
+
+h2. Inferencing support
+
+Blueprints Sail implements "NotifyingSail":http://www.openrdf.org/doc/sesame2/api/org/openrdf/sail/NotifyingSail.html, produces "InferencerConnections":http://www.openrdf.org/doc/sesame2/api/org/openrdf/sail/inferencer/InferencerConnection.html, and does all of the right things under the hood to support Sesame-based reasoning/inferencing tools such as "ForwardChainingRDFSInferencer":http://www.openrdf.org/doc/sesame2/api/org/openrdf/sail/inferencer/fc/ForwardChainingRDFSInferencer.html, with no extra plumbing required. For example:
+
+```java
+ Sail reasoner = new ForwardChainingRDFSInferencer(new GraphSail(new TinkerGraph()));
+ reasoner.initialize();
+```
+
+How it works: a reasoner such as @ForwardChainingRDFSInferencer@ is expected to listen for RDF statements added to or removed from the base @Sail@ (here: an instance of @GraphSail@) and to manage a collection of "inferred" statements accordingly. The inferred statements are stored along with the explicitly asserted RDF statements in the base @Sail@. In Blueprints Sail, these statements are marked with a special property, @inferred@, which when present has the boolean value @true@, so you can see which edges "you" have added, and which edges the reasoner has added, when traversing the underlying Property Graph. The following is a more detailed example:
+
+```java
+Resource beijing = new URIImpl("http://example.org/things/Beijing");
+Resource city = new URIImpl("http://example.org/terms/city");
+Resource place = new URIImpl("http://example.org/terms/place");
+
+Graph graph = new TinkerGraph();
+Sail reasoner = new ForwardChainingRDFSInferencer(new GraphSail(graph));
+reasoner.initialize();
+
+try {
+ SailConnection c = reasoner.getConnection();
+ try {
+ c.addStatement(city, RDFS.SUBCLASSOF, place);
+ c.addStatement(beijing, RDF.TYPE, city);
+ c.commit();
+
+ CloseableIteration<? extends Statement, SailException> i
+ = c.getStatements(beijing, null, null, true);
+ try {
+ while (i.hasNext()) {
+ System.out.println("statement " + i.next());
+ }
+ } finally {
+ i.close();
+ }
+ } finally {
+ c.close();
+ }
+} finally {
+ reasoner.shutDown();
+}
+
+graph.shutdown();
+```
+
+Output of the example:
+```
+statement (http://example.org/things/Beijing, http://www.w3.org/1999/02/22-rdf-syntax-ns#type, http://www.w3.org/2000/01/rdf-schema#Resource)
+statement (http://example.org/things/Beijing, http://www.w3.org/1999/02/22-rdf-syntax-ns#type, http://example.org/terms/place)
+statement (http://example.org/things/Beijing, http://www.w3.org/1999/02/22-rdf-syntax-ns#type, http://example.org/terms/city)
+```
11 doc/wiki/The-Benefits-of-Blueprints.textile
View
@@ -0,0 +1,11 @@
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/blueprints-logo.png!
+
+Blueprints is a generic Java graph "API":http://en.wikipedia.org/wiki/Application_programming_interface that binds to various graph backends (i.e. frameworks and "databases":http://en.wikipedia.org/wiki/Graph_database). Below is a list of reasons for using Blueprints.
+
+* Blueprints makes it relatively easy to swap in and out different graph backends. In this way, its possible to avoid "vendor lock-in":http://en.wikipedia.org/wiki/Vendor_lock-in.
+* Blueprints has connectors to popular graph databases including "Neo4j":http://neo4j.org/, "OrientDB":http://www.orientechnologies.com/orient-db.htm, "DEX":http://www.sparsity-technologies.com/dex, and "InfiniteGraph":http://www.infinitegraph.com/.
+* Blueprints has connectors to popular graph frameworks including "RDF":http://en.wikipedia.org/wiki/Triplestore Sail and "JUNG":http://jung.sourceforge.net/.
+* Blueprints graph backends work with any software written to the Blueprints API (e.g. all the tools in the "TinkerPop":http://tinkerpop.com stack).
+* Blueprints comes with a large library of utilities to make it easy to manipulate a graph.
+* Blueprints has support for reading various file formats including "GraphML":http://graphml.graphdrawing.org/, "GML":http://en.wikipedia.org/wiki/Graph_Modelling_Language, and GraphSON.
+* Blueprints, and the rest of the TinkerPop stack, is open source and free to use under a liberal "BSD license":http://en.wikipedia.org/wiki/BSD_licenses.
79 doc/wiki/The-Major-Differences-Between-Blueprints-1.x-and-2.x.textile
View
@@ -0,0 +1,79 @@
+[[https://github.com/tinkerpop/blueprints/raw/master/doc/images/blueprints-character-1.png|width=130px]] [[https://github.com/tinkerpop/blueprints/raw/master/doc/images/blueprints-character-2.png|width=100px]] [[https://github.com/tinkerpop/blueprints/raw/master/doc/images/blueprints-character-3.png|width=118px]]
+
+Blueprints 2 introduced numerous changes to the Blueprints API. This page helps to explain these differences so updating code from Blueprints 1.x to Blueprints 2.x is as easy as possible.
+
+h2. A Change to the Package Name
+
+In the early days of Blueprints, there were two notions:
+ * Property Graphs Model
+ * Object Document Model
+
+To account for these two models, there were two packages: @com.tinkerpop.blueprints.pgm@ and @com.tinkerpop.blueprints.odm@. Blueprints has since focused solely on the [[property graph model]] and as such, in Blueprints 2.x, there is no more @pgm@, it is simply @com.tinkerpop.blueprints@.
+
+h2. KeyIndexableGraph and the new AutomaticIndices
+
+There is no more notion of @AutomaticIndex@ in Blueprints 2. Many graph databases such as @DexGraph@, @IGGraph@, and @TitanGraph@ do not support the notion of arbitrary indexing. Instead, they simply allow an element to be indexed by its key/value property pairs. As such, @KeyIndexableGraph@ provides an interface to this basic indexing functionality (see [[Graph Indices]]). To index the @name@ key of all vertices, simply do:
+
+```java
+graph.createKeyIndex("name", Vertex.class);
+```
+
+Now, when @graph.getVertices("name", "stephen")@ is evaluated, the @name@ index is used. If no such key index was created, then a linear scan of all the vertices in the graph would occur. Thus, be sure to add the appropriate indices to make an @n@-lookup a @log(n)@-lookup.
+
+For "manual indexing," there is still the notion of @IndexableGraph@ and the @Index@ class. This is used by graph engines like @Neo4jGraph@, @OrientGraph@, and @TinkerGraph@.
+
+h2. Vertex/Edge API and the Direction Enum
+
+In Blueprints 1.x, there existed the following @Vertex@ methods.
+
+```java
+Vertex.getOutEdges(String... labels)
+Vertex.getInEdges(String... labels)
+```
+
+As of Blueprints 2.x, there are now the following @Vertex@ methods.
+
+```java
+Vertex.getEdges(Direction direction, String... labels)
+Vertex.getVertices(Direction direction, String... labels)
+```
+
+With @Vertex.getEdges()@, it is possible to get the incoming, outgoing, or both incident edges to a vertex filtered by their edge label. With @Vertex.getVertices()@, it is possible to get the incoming, outgoing, or both adjacent vertices to a vertex filtered by the edge label of the adjoining edges. Likewise, in a similar fashion, @Edge@ has been updated with the following method.
+
+```java
+Edge.getVertex(Direction direction)
+```
+
+h2. Vertex Query
+
+There is a new method in the @Vertex@ class called @Vertex.query()@. This method returns a @Query@ object that has a "fluent interface":http://en.wikipedia.org/wiki/Fluent_interface. The @Query@ object is a way of intelligently selecting adjacent vertices or incident edges to a vertex. Please learn more about @Query@ on the [[Vertex Query]] wiki page.
+
+h2. BatchGraph and the Removal of TransactionalGraph Buffers
+
+In Blueprints 1.x, @TransactionalGraph@ had the following methods.
+
+```java
+TransactionalGraph.setMaxBufferSize(long size)
+TransactionalGraph.getMaxBufferSize();
+TransactionalGraph.getCurrentBufferSize()
+```
+
+These methods were used to automatically commits "chunks" of data. Those chunks were the size of the buffer. This functionality was deemed too specific a use case and should not be mixed in with @TransactionalGraph@. As such, this behavior has now been relegated to @BatchGraph@ (see [[Batch Implementation]]).
+
+h2. TransactionalGraph Semantics and ThreadedTransactionalGraph
+
+In @TransactionalGraph@ each transaction is bound to an executing thread and a transaction is automatically started with the first operation on the graph (read or write). Hence, @TransactionalGraph.startTransaction()@ is not needed and has been removed. The user only needs to mark the end of a transaction by calling @TransactionalGraph.stopTransaction(Conclusion conclusion)@.
+To allow multiple threads to execute in one transaction, which is useful when implementing parallelized graph algorithms, the @ThreadedTransactionalGraph@ interface has been added. It's @startTransaction()@ method returns a @TransactionalGraph@ object which represents a single transaction and can be accessed concurrently from multiple threads.
+
+h2. WrapperGraph and MetaGraph
+
+There are two types of "wrapping" Blueprints implementations.
+ # @WrapperGraph@: The underlying graph is a Blueprints @Graph@
+ # @MetaGraph@: The underlying graph is a vendor specific API.
+
+Blueprints provides numerous @WrapperGraph@ implementations that allow users add-on functionality to their graph. Examples include @ReadOnlyGraph@, @IdGraph@, @BatchGraph@, etc. Next, most vendors make use of @MetaGraph@ where their Blueprints implementation wraps their native API. Thus, there are two methods to be aware of in these respective interfaces.
+
+```java
+T extends Graph WrapperGraph.getBaseGraph() // can recursively go down if T is a WrapperGraph
+T MetaGraph.getRawGraph() // returns the raw vendor specific graph object
+```
54 doc/wiki/TinkerGraph.textile
View
@@ -0,0 +1,54 @@
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/tinkerpop-logo-small.jpg!
+
+```xml
+<dependency>
+ <groupId>com.tinkerpop.blueprints</groupId>
+ <artifactId>blueprints-core</artifactId>
+ <version>??</version>
+</dependency>
+```
+
+TinkerG