Permalink
Browse files

final last minuute updates from Luca. And pushing wiki.

  • Loading branch information...
1 parent 3311752 commit a7d3588d43c99b60a081c238b2a24a7b33717203 @okram okram committed Aug 1, 2011
@@ -0,0 +1,12 @@
+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@.
+# "Sergio Gómez Villamor":http://personals.ac.upc.edu/sgomez -- developed the Dex implementation (@DexGraph@).
+
+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.
+
+<small>YourKit is kindly supporting open source projects with its full-featured Java Profiler. YourKit, LLC is the creator of innovative and intelligent tools for profiling Java and .NET applications. Take a look at YourKit's leading software products: <a href="http://www.yourkit.com/java/profiler/index.jsp">YourKit Java Profiler</a> and <a href="http://www.yourkit.com/.net/profiler/index.jsp">YourKit .NET Profiler</a>.</small>
@@ -0,0 +1,93 @@
+This section will provide a collection of 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. These code examples can be found in the main Blueprints distribution "at this location":https://github.com/tinkerpop/blueprints/blob/master/blueprints-test/src/test/java/com/tinkerpop/blueprints/pgm/impls/tg/CodeExamples.java.
+
+# "Create a Simple Graph":#create
+# "Iterate through the Elements of a Graph":#elements
+# "Iterate through the Edges of a Vertex":#edge
+# "Use Indices to Get a Vertex by its Property":#index
+
+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
+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.getOutVertex().getProperty("name") + "--" + e.getLabel() + "-->" + e.getInVertex().getProperty("name"));
+```
+
+The @System.out@ after the code executes is:
+
+bc. marko--knows-->peter
+
+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]
+
+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.getOutEdges()) {
+ 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]
+
+h2(#index). Use Indices to Get a Vertex by its Property
+
+Load the TinkerPop play graph diagrammed in [[Property Graph Model]]. [[TinkerGraph]] implements the @IndexableGraph@ interface. Get the standard vertex index and then get all vertices named @marko@. Given that there is only one, we can simple next the first vertex out of the returned iterable. Print some information about the vertex.
+
+```java
+Graph graph = TinkerGraphFactory.createTinkerGraph();
+Vertex a = ((IndexableGraph)graph).getIndex(Index.VERTICES, Vertex.class).get("name", "marko").iterator().next();
+System.out.println("vertex " + a.getId() + " has age " + a.getProperty("age"));
+```
+
+The @System.out@ after the code executes is:
+
+bc. vertex 1 has age 29
@@ -0,0 +1,18 @@
+!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
+* "InfiniteGraph":http://www.infinitegraph.com/ (currently in development)
+* "InfoGrid":http://infogrid.org/
+* "sones":http://www.sones.com/
+* "vertexdb":http://www.dekorte.com/projects/opensource/vertexdb/
+* "Redis":http://code.google.com/p/redis/ (see "Blueredis":https://github.com/dmitriid/blueredis)
+* 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/
@@ -0,0 +1,67 @@
+[[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).
+
+DEX natively supports the property graph data model defined by Blueprints. However, there are a few peculiarities.
+
+# *No user defined element identifiers*: DEX is the gatekeeper and creator of vertex and edge identifiers. Thus, when creating a new vertex or edge instance, the provided object identifier is ignored.
+# *Vertices are labeled too*: When adding vertices, the user can set @DEXGraph#LABEL@ to be used as the label of the vertex to be created. Also, the label of a vertex (or even an element) can be retrieved through the @DEXElement#LABEL_PROPERTY@ property.
+
+@DexGraph@ implements @IndexableGraph@. However, the use of indices is limited when working with DEX and is explained as follows:
+
+# There is no support to create indices.
+# By default, there is an @AutomaticIndex@ for each existing label which corresponds to the name of the index. Also, each index contains a key for each existing property.
+
+*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/edu/upc/dama/dex/utils/DEXConfig.html]].
+
+*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, we should implement something like this:
+
+```java
+DexIterable<Vertex> vv = (DexIterable<Vertex>)graph.getVertices();
+for (final Vertex vertex : vv) {
+ DexIterable<Edge> ee = (DexIterable<Edge>)vertex.getOutEdges();
+ for (final Edge edge : ee) {
+ final Vertex vertex2 = edge.getInVertex();
+ DexIterable<Edge> ee2 = (DexIterable<Edge>)vertex2.getOutEdges();
+ for (final Edge edge2 : ee2) {
+ ...
+ }
+ ee2.close();
+ }
+ ee.close();
+}
+vv.close();
+```
@@ -0,0 +1,53 @@
+```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.
+
+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");
+}
+
+graph.clear();
+```
+
+The following output would appear in the console:
+
+```text
+Vertex [v[100]] added to graph [(event)tinkergraph[vertices:6 edges:3]]
+Vertex [v[4]] property [name] set to value of [noname] in graph [(event)tinkergraph[vertices:6 edges:6]]
+Edge [e[10][4-created->5]] property [weight] with value of [1.0] removed in graph [(event)tinkergraph[vertices:6 edges:6]]
+Edge [e[7][1-knows->2]] property [weight] with value of [0.5] removed in graph [(event)tinkergraph[vertices:6 edges:6]]
+Edge [e[9][1-created->3]] property [weight] with value of [0.4] removed in graph [(event)tinkergraph[vertices:6 edges:6]]
+Edge [e[8][1-knows->4]] property [weight] with value of [1.0] removed in graph [(event)tinkergraph[vertices:6 edges:6]]
+Edge [e[11][4-created->3]] property [weight] with value of [0.4] removed in graph [(event)tinkergraph[vertices:6 edges:6]]
+Edge [e[12][6-created->3]] property [weight] with value of [0.2] removed in graph [(event)tinkergraph[vertices:6 edges:6]]
+Graph [(event)tinkergraph[vertices:0 edges:0]] cleared.
+```
@@ -0,0 +1,15 @@
+A "helper class" in Blueprints is provided in the @com.tinkerpop.blueprints.pgm.util@ package. Helper classes provide (usually) static methods that yield high-level support for manipulating various Blueprints objects. Of particular interest to this page of documentation, there are a collection of helper classes for handling indices.
+
+h2. AutomaticIndexHelper
+
+@AutomaticIndexHelper@ provides high-level methods for adding, removing, and reindexing elements in an @AutomaticIndex@. Here is an example.
+
+```java
+graph = TinkerGraphFactory.createTinkerGraph();
+indexKeys = new HashSet<String>();
+indexKeys.add("name");
+index = graph.createAutomaticIndex("test-idx", Vertex.class, indexKeys);
+index.get("name","marko"); // returns an empty iterator
+index = AutomaticIndexHelper.reIndexElements(graph, index, graph.getVertices()); // reindex all the vertices in the graph
+index.get("name","marko"); // returns an iterator with v[1] in it
+```
@@ -0,0 +1,73 @@
+!https://github.com/tinkerpop/blueprints/raw/master/doc/images/indices-example.png!
+
+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> createAutomaticIndex(String indexName, Class<T> indexClass, Set<String> indexKeys);
+public <T extends Element> Index<T> createManualIndex(String indexName, Class<T> indexClass);
+public <T extends Element> Index<T> getIndex(String indexName, Class<T> indexClass);
+public Iterable<Index<? extends Element>> getIndices();
+public void dropIndex(String indexName);
+```
+
+h2. Manual Indices
+
+There are two types of indices: @Type.AUTOMATIC@ and @Type.MANUAL@. A manual 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.createManualIndex("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 Type getIndexType();
+public void put(String key, Object value, T element);
+public Iterable<T> get(String key, Object value);
+public void remove(String key, Object value, T element);
+```
+
+Given the @index@ object created previous, to add, query, and remove a vertex from this index, do the following:
+
+```java
+index.put("name","peter",vertex);
+Iterable<Vertex> results = index.get("name","peter");
+index.remove("name","peter",vertex);
+```
+
+With manual indices, the developer must be cognizant of maintaining the index with these methods.
+
+h2. Automatic Indices
+
+When the developer does not wish to maintain an index, the developer can rely on indices of @Type.AUTOMATIC@. An automatic index will automatically @put@ and @remove@ elements from an index as the element mutates. That is, an automatic index indexes the properties of an element where the property key is the key and the property value is the value. As these properties change, an automatic index automatically reflects these changes. To create an automatic index, do the following:
+
+```java
+Set<String> indexKeys = ...
+AutomaticIndex<Vertex> autoIndex = graph.createAutomaticIndex("test-aidx", Vertex.class, indexKeys);
+```
+
+The @AutomaticIndex@ interface extends @Index@ and provides, along with the @Index@ methods, the following method:
+
+```java
+public Set<String> getAutoIndexKeys();
+```
+
+An @AutomaticIndex@ will index all newly created elements by the provide set of auto index keys. If this set of auto index keys is @null@, then all keys will be indexed. Here is an example of all this together:
+
+```java
+Set<String> indexKeys = new HashSet<String>();
+indexKeys.add("name");
+AutomaticIndex<Vertex> autoIndex = graph.createAutomaticIndex("test-aidx", Vertex.class, indexKeys);
+Vertex a = graph.addVertex(null);
+a.setProperty("name","pavel");
+a.setProperty("country","belarus");
+Iterable<Vertex> results = autoIndex.get("name","pavel");
+// results contains vertex a
+results = autoIndex.get("country","belarus");
+// results does not contain vertex a
+```
+
+*Note*: When an @IndexableGraph@ is created a new (not constructed, but when there is no historic persistence), it comes with two automatic indices named @Index.VERTICES@ and @Index.EDGES@ that index all properties (constructed with @null@ indexKeys argument). These indices automatically index any created vertices and edges, respectively. If these indices are not desired, simply @graph.dropIndex(Index.VERTICES)@ and @graph.dropIndex(Index.EDGES)@ before adding elements.
@@ -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. From the standpoint of a property graph its 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!
Oops, something went wrong.

0 comments on commit a7d3588

Please sign in to comment.