Clone this wiki locally
Attention: this Wiki hosts an outdated version of the TinkerPop framework and Gremlin language documentation.
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.).
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 Property Graph Model 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.
To be considered a recognized Blueprints implementation (i.e. included on the Blueprints wiki as a third-party implementation, or otherwise promoted by TinkerPop), the implementation must meet these conditions:
- It must pass the Blueprints Test Suite.
- It must include a Rexster configuration class.
- It must include some form of documentation (e.g. README.md, wiki, etc.)
Those offering Blueprints implementations are encouraged to use the gremlin-users mailing list to announce their releases and feature updates, as well as a to provide support to the community on usage.
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
The identifier parameter cannot be
null and if it is an exception should immediately be thrown:
if (null == id) throw ExceptionFactory.vertexIdCanNotBeNull();
Some methods of the Blueprints API are marked as
@deprecated. While this annotation does mean that the method is bound for future removal from the API, it may be smart to implement it anyway for backward compatibility with the rest of the stack. Generally speaking other elements of the stack that depend on Blueprints, such as Rexster, will attempt to delay upgrade to newer methods over older ones in an effort to stay compatible with as many older Blueprints versions as possible. The other reason to implement the deprecated methods is to allow users with older code to easily swap in the newly built implementation without having to make a lot of changes to their code that they may not be prepared to make.
To be a complete Blueprints implementation it is important to make it possible to expose a Blueprints implementation through Rexster. Doing do has the following benefits:
- Accessibility of the implementation through to the top of the TinkerPop stack.
- Makes the implementation consumable by the widest group of possible users as Rexster enables access to the graph through any language.
- Through Rexster the implementation is consumable through other tools and frameworks, like Bulbs, Thunderdome, Faunus, etc.
Adding Rexster Support usually just involves the creation of a single class file. This blog post discusses how to create a configuration and samples of the TinkerPop maintained Blueprints implementations can be found here.
Blueprints provides a GraphFactory, which allows for a generic way to instantiate
Graph implementations. To support
GraphFactory, a the library must provide either or both of the following:
Graphimplementation constructor that takes a single argument of type
- A static factory method that has a method called
openthat takes a single argument of type
It is up to each
Graph implementation to define what the
Configuration object contains, but generally speaking, it is expected that it will contain name-value pairs.
Blueprints uses a standard whereby the name in the pair is prefixed with
blueprints.graphname, where the graphname refers to a friendly name of the
Graph implementation. For example,
Neo4jGraph has a friendly configuration name of
neo4j and therefore a complete configuration name would look like:
In addition to the Blueprints Test Suite, developers have the option to test their implementations with other test suites higher in the stack. These tests can help uncover other problems that the Blueprints tests don’t (however, efforts are made to push the logic higher level tests down to Blueprints when problems are found). Running these tests can provide additional confidence that there is consistency all the way to the top of the TinkerPop stack.
Rexster Integration Tests
Rexster has a suite of integration tests that runs across multiple graphs to validate operational consistency of implementations. It is assumed that the Blueprints implementation being tested has a configuration class so that it can be configured to run in Rexster. To run the tests:
1. Copy the jar file of the Blueprints implementation to the
1. Pull the Rexster source code from GitHub and edit the rexster.xml used by the integration tests to include the graph configuration to include in the tests.
mvn clean install -Pintegration-test from the command line.
The RexsterGraph runs the Property Graph Model Test Suite over a running instance of Rexster. By default, the tests for
RexsterGraph are disabled. It is assumed that the Blueprints implementation being tested has a configuration class so that it can be configured to run in Rexster. To run these tests:
1. Pull the source code for Blueprints from GitHub and edit the pom.xml file. Change the
-DtestRexsterGraph=true so that the tests will be enabled.
1. In Rexster, edit the
rexster.xml file to include the Blueprints implementation to be tested. By default the
rexsterGraph tests try to use a graph named
emptygraph, which is configured in the default
rexster.xml as a TinkerGraph. Either edit that configuration to be for the new graph or change the
pom.xml to point at a different graph by changing this settings:
1. Start Rexster with:
mvn clean install on
RexsterGraph from the command line.