Package org.apache.tinkerpop.gremlin
Interface GraphProvider
-
- All Known Implementing Classes:
AbstractFileGraphProvider
,AbstractGraphProvider
,GraphManager.ManagedGraphProvider
public interface GraphProvider
Those developing Gremlin implementations must provide a GraphProvider implementation so that the different test suites know how to instantiate their implementations. Implementers may choose to have multipleGraphProvider
implementations to mix and match with multiple test suite implementations. For example, create oneGraphProvider
that has no indices defined and a separateGraphProvider
that has indices. Then create separate test suite implementations for eachGraphProvider
. This approach will have the test suites executed once for eachGraphProvider
ensuring that theGraph
implementation works under multiple configurations. Consider making these "extra" tests "integration tests" so that they don't have to be executed on every run of the build so as to save time. Run the "integration tests" periodically to ensure overall compliance.- Author:
- Stephen Mallette (http://stephen.genoprime.com)
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static interface
GraphProvider.Descriptor
An annotation to be applied to aGraphProvider
implementation that provides additional information about its intentions.static interface
GraphProvider.TestListener
-
Field Summary
Fields Modifier and Type Field Description static Set<Class>
CORE_IMPLEMENTATIONS
Implementations fromgremlin-core
that need to be part of the clear process.
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description default void
clear(org.apache.commons.configuration2.Configuration configuration)
If possible (usually with persisted graph) clear the space on disk given the configuration that would be used to construct the graph.void
clear(Graph graph, org.apache.commons.configuration2.Configuration configuration)
Clears aGraph
of all data and settings.default Object
convertId(Object id, Class<? extends Element> c)
Converts an identifier from a test to an identifier accepted by theGraph
instance.default String
convertLabel(String label)
Converts an label from a test to an label accepted by the Graph instance.default GraphComputer
getGraphComputer(Graph graph)
Create aGraphComputer
from theGraph
instance.Set<Class>
getImplementations()
Get the set of concrete implementations of certain classes and interfaces utilized by the test suite.default Optional<Graph.Features>
getStaticFeatures()
Gets aGraph.Features
implementation that contains graph feature configuration that will never change from execution to execution of the tests given this currentGraphProvider
implementation.default Optional<GraphProvider.TestListener>
getTestListener()
Returns aGraphProvider.TestListener
implementation that provides feedback to theGraphProvider
implementation.default String
getWorkingDirectory()
Helper method for those buildGraphProvider
implementations that need a standard working directory for tests (e.g.void
loadGraphData(Graph graph, LoadGraphWith loadGraphWith, Class testClass, String testName)
Tests are annotated with aLoadGraphWith
annotation.org.apache.commons.configuration2.Configuration
newGraphConfiguration(String graphName, Class<?> test, String testMethodName, Map<String,Object> configurationOverrides, LoadGraphWith.GraphData loadGraphWith)
When implementing this method ensure that a test suite can override any settings EXCEPT the "gremlin.graph" setting which should be defined by the implementer.default org.apache.commons.configuration2.Configuration
newGraphConfiguration(String graphName, Class<?> test, String testMethodName, LoadGraphWith.GraphData loadGraphWith)
When implementing this method ensure that a test suite can override any settings EXCEPT the "gremlin.graph" setting which should be defined by the implementer.default Graph
openTestGraph(org.apache.commons.configuration2.Configuration config)
default org.apache.commons.configuration2.Configuration
standardGraphConfiguration(Class<?> test, String testMethodName, LoadGraphWith.GraphData loadGraphWith)
default Graph
standardTestGraph(Class<?> test, String testMethodName, LoadGraphWith.GraphData loadGraphWith)
Creates a newGraph
instance using the defaultConfiguration
fromstandardGraphConfiguration(Class, String, LoadGraphWith.GraphData)
.default GraphTraversalSource
traversal(Graph graph)
Create aGraphTraversalSource
from aGraph
instance.default GraphTraversalSource
traversal(Graph graph, TraversalStrategy... strategies)
Create aGraphTraversalSource
from aGraph
instance.
-
-
-
Field Detail
-
CORE_IMPLEMENTATIONS
static final Set<Class> CORE_IMPLEMENTATIONS
Implementations fromgremlin-core
that need to be part of the clear process. This does not exempt providers from having to register their extensions to any of these classes, but does prevent them from having to register them in addition to their own.
-
-
Method Detail
-
traversal
default GraphTraversalSource traversal(Graph graph)
Create aGraphTraversalSource
from aGraph
instance. The default implementation does not useGraphComputer
so providers should override as necessary if their implementation is testing something that requires a different engine type, likeGraphComputer
.
-
traversal
default GraphTraversalSource traversal(Graph graph, TraversalStrategy... strategies)
Create aGraphTraversalSource
from aGraph
instance. The default implementation does not useGraphComputer
so providers should override as necessary if their implementation is testing something that requires a different engine type, likeGraphComputer
. Implementations should apply strategies as necessary to theGraphTraversalSource
before calling it'screate
method.
-
getGraphComputer
default GraphComputer getGraphComputer(Graph graph)
Create aGraphComputer
from theGraph
instance. The default implementation simply callsgraph.compute()
.- Parameters:
graph
- the graph to get the graph computer from- Returns:
- a new graph computer
-
standardTestGraph
default Graph standardTestGraph(Class<?> test, String testMethodName, LoadGraphWith.GraphData loadGraphWith)
Creates a newGraph
instance using the defaultConfiguration
fromstandardGraphConfiguration(Class, String, LoadGraphWith.GraphData)
.
-
openTestGraph
default Graph openTestGraph(org.apache.commons.configuration2.Configuration config)
Creates a newGraph
instance from theConfiguration
object usingGraphFactory
. The assumption here is that theConfiguration
has been created by one of thenewGraphConfiguration(String, Class, String, LoadGraphWith.GraphData)
methods and has therefore already been modified by the implementation as necessary forGraph
creation.
-
standardGraphConfiguration
default org.apache.commons.configuration2.Configuration standardGraphConfiguration(Class<?> test, String testMethodName, LoadGraphWith.GraphData loadGraphWith)
Gets theConfiguration
object that can construct aGraph
instance fromGraphFactory
. Note that this method should create aGraph
using thegraphName
of "standard", meaning it should always return a configuration instance that generates the sameGraph
from theGraphFactory
.
-
clear
default void clear(org.apache.commons.configuration2.Configuration configuration) throws Exception
If possible (usually with persisted graph) clear the space on disk given the configuration that would be used to construct the graph. The default implementation simply callsclear(Graph, Configuration)
with a null graph argument. Implementations should be able to accept an argument of null for theConfiguration
as well, and a proper handling is needed. Otherwise, a NullPointerException may be thrown.- Throws:
Exception
-
clear
void clear(Graph graph, org.apache.commons.configuration2.Configuration configuration) throws Exception
Clears aGraph
of all data and settings. Implementations will have different ways of handling this. It is typically expected thatGraph.close()
will be called and open transactions will be closed. For a brute force approach, implementers can simply delete data directories provided in the configuration. Implementers may choose a more elegant approach if it exists. Implementations should be able to accept an argument of null for theGraph
, in which case the only action that can be performed is a clear given the configuration. The method will typically be called this way as clean up task on setup to ensure that a persisted graph has a clear space to create a test graph. Implementations should be able to accept an argument of null for theConfiguration
as well, and a proper handling is needed. Otherwise, a NullPointerException may be thrown. Calls to this method may occur multiple times for a specific test. Develop this method to be idempotent.- Throws:
Exception
-
convertId
default Object convertId(Object id, Class<? extends Element> c)
Converts an identifier from a test to an identifier accepted by theGraph
instance. Test that try to utilize an Element identifier will pass it to this method before usage. This method should be sure to be consistent in the return value such that calling it with "x" should always return the same transformed value.
-
convertLabel
default String convertLabel(String label)
Converts an label from a test to an label accepted by the Graph instance. Test that try to utilize a label will pass it to this method before usage.
-
newGraphConfiguration
org.apache.commons.configuration2.Configuration newGraphConfiguration(String graphName, Class<?> test, String testMethodName, Map<String,Object> configurationOverrides, LoadGraphWith.GraphData loadGraphWith)
When implementing this method ensure that a test suite can override any settings EXCEPT the "gremlin.graph" setting which should be defined by the implementer. It should provide aConfiguration
that will generate a graph unique to thatgraphName
.- Parameters:
graphName
- a unique test graph nametest
- the test classtestMethodName
- the name of the testconfigurationOverrides
- settings to override defaults with.loadGraphWith
- the data set to load and will be null if no data is to be loaded
-
newGraphConfiguration
default org.apache.commons.configuration2.Configuration newGraphConfiguration(String graphName, Class<?> test, String testMethodName, LoadGraphWith.GraphData loadGraphWith)
When implementing this method ensure that a test suite can override any settings EXCEPT the "gremlin.graph" setting which should be defined by the implementer. It should provide aConfiguration
that will generate a graph unique to thatgraphName
.- Parameters:
graphName
- a unique test graph nametest
- the test classtestMethodName
- the name of the testloadGraphWith
- the data set to load and will be null if no data is to be loaded
-
loadGraphData
void loadGraphData(Graph graph, LoadGraphWith loadGraphWith, Class testClass, String testName)
Tests are annotated with aLoadGraphWith
annotation. These annotations tell the test what kind of data to preload into the graph instance. It is up to the implementation to load the graph with the data specified by that annotation. This method also represents the place where indices should be configured according the theGraph
implementation's API. Implementers can use thetestClass
andtestName
arguments to implement test specific configurations to their graphs.- Parameters:
graph
- theGraph
instance to load data into constructed by thisGraphProvider
loadGraphWith
- the annotation for the currently running test - this value may be null if no graph data is to be loaded in front of the test.testClass
- the test class being executedtestName
- the name of the test method being executed
-
getImplementations
Set<Class> getImplementations()
Get the set of concrete implementations of certain classes and interfaces utilized by the test suite. This method should return any implementations or extensions of the following interfaces or classes:Edge
Element
DefaultGraphTraversal
Graph
Graph.Variables
GraphTraversal
B_LP_O_P_S_SE_SL_Traverser
Property
B_O_S_SE_SL_Traverser
Traversal
Traverser
Vertex
VertexProperty
CORE_IMPLEMENTATIONS
to theSet
because these representgremlin-core
implementations that are likely not registered by the vendor implementations.
-
getWorkingDirectory
default String getWorkingDirectory()
Helper method for those buildGraphProvider
implementations that need a standard working directory for tests (e.g. graphs that persist data to disk). Typically, there is no need to override the default behavior of this method and if it is overridden, it is usually best to continue to use theTestHelper
to produce the working directory as it will create the path in the appropriate build directories.- Returns:
- UNIX-formatted absolute directory path
-
getTestListener
default Optional<GraphProvider.TestListener> getTestListener()
Returns aGraphProvider.TestListener
implementation that provides feedback to theGraphProvider
implementation. By default, this returns an empty listener.
-
getStaticFeatures
default Optional<Graph.Features> getStaticFeatures()
Gets aGraph.Features
implementation that contains graph feature configuration that will never change from execution to execution of the tests given this currentGraphProvider
implementation. Implementing this method will allow the test suite to avoid creation of aGraph
instance and thus speed up the execution of tests if that creation process is expensive. It is important that this static set of features be representative of what theGraph
instance produced by thisGraphProvider
can actually do or else the cost ofGraph
instantiation will be incurred when it doesn't need to be. It is also important that this method be faster than the cost ofGraph
creation in the first place or there really won't be any difference in execution speed. In cases where some features are static and others are not, simply throw anUnsupportedOperationException
from those features to let the test suite know that it cannot rely on them and the test suite will revert to using a constructedGraph
instance.
-
-