org.apache.tinkerpop.gremlin

Interface GraphProvider

All Known Implementing Classes:

AbstractGraphProvider

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 multiple GraphProvider implementations to mix and match with multiple test suite implementations. For example, create one GraphProvider that has no indices defined and a separate GraphProvider that has indices. Then create separate test suite implementations for each GraphProvider. This approach will have the test suites executed once for each GraphProvider ensuring that the Graph 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)

Field Summary

Fields

Modifier and Type	Field and Description
static Set<Class>	CORE_IMPLEMENTATIONS Implementations from gremlin-core that need to be part of the clear process.

Method Summary

Modifier and Type	Method and Description
default void	clear(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, Configuration configuration) Clears a Graph of all data and settings.
default Object	convertId(Object id) Converts an identifier from a test to an identifier accepted by the Graph instance.
default String	convertLabel(String label) Converts an label from a test to an label accepted by the Graph instance.
Set<Class>	getImplementations() Get the set of concrete implementations of certain classes and interfaces utilized by the test suite.
void	loadGraphData(Graph graph, LoadGraphWith loadGraphWith, Class testClass, String testName) Tests are annotated with a LoadGraphWith annotation.
default Configuration	newGraphConfiguration(String graphName, Class<?> test, String testMethodName) 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.
Configuration	newGraphConfiguration(String graphName, Class<?> test, String testMethodName, Map<String,Object> configurationOverrides) 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(Configuration config) Creates a new Graph instance from the Configuration object using GraphFactory.
default <ID> ID	reconstituteGraphSONIdentifier(Class<? extends Element> clazz, Object id) Converts the GraphSON representation of an identifier to the implementation's representation of an identifier.
default Configuration	standardGraphConfiguration(Class<?> test, String testMethodName) Gets the org.apache.commons.configuration.Configuration object that can construct a Graph instance from GraphFactory.
default Graph	standardTestGraph(Class<?> test, String testMethodName) Creates a new Graph instance using the default org.apache.commons.configuration.Configuration from standardGraphConfiguration(Class, String).
default GraphTraversalSource	traversal(Graph graph) Create a GraphTraversalSource from a Graph instance.
default GraphTraversalSource	traversal(Graph graph, TraversalStrategy... strategies) Create a GraphTraversalSource from a Graph instance.

Field Detail

CORE_IMPLEMENTATIONS

static final Set<Class> CORE_IMPLEMENTATIONS

Implementations from gremlin-core that need to be part of the clear process. This does not exempt vendors 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 a GraphTraversalSource from a Graph instance. The default implementation uses the StandardTraversalEngine so vendors should override as necessary if their implementation is testing something that requires a different engine type, like those tests for TraversalEngine.Type.

traversal

default GraphTraversalSource traversal(Graph graph,
                                       TraversalStrategy... strategies)

Create a GraphTraversalSource from a Graph instance. The default implementation uses the StandardTraversalEngine so vendors should override as necessary if their implementation is testing something that requires a different engine type, like those tests for TraversalEngine.Type.
Implementations should apply strategies as necessary to the GraphTraversalSource.Builder before calling it's create method.

standardTestGraph

default Graph standardTestGraph(Class<?> test,
                                String testMethodName)

Creates a new Graph instance using the default org.apache.commons.configuration.Configuration from standardGraphConfiguration(Class, String). The default implementation converts the passes the

openTestGraph

default Graph openTestGraph(Configuration config)

Creates a new Graph instance from the Configuration object using GraphFactory. The assumption here is that the Configuration has been created by one of the newGraphConfiguration(String, Class, String) methods and has therefore already been modified by the implementation as necessary for Graph creation.

standardGraphConfiguration

default Configuration standardGraphConfiguration(Class<?> test,
                                                 String testMethodName)

Gets the org.apache.commons.configuration.Configuration object that can construct a Graph instance from GraphFactory. Note that this method should create a Graph using the graphName of "standard", meaning it should always return a configuration instance that generates the same Graph from the GraphFactory.

clear

default void clear(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 calls #clear(org.apache.tinkerpop.gremlin.structure.Graph, org.apache.commons.configuration.Configuration) with a null graph argument.

Throws:

Exception

clear

void clear(Graph graph,
           Configuration configuration)
    throws Exception

Clears a Graph of all data and settings. Implementations will have different ways of handling this. 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 the Graph, 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.

Throws:

Exception

convertId

default Object convertId(Object id)

Converts an identifier from a test to an identifier accepted by the Graph instance. Test that try to utilize an Element identifier will pass it to this method before usage.

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

Configuration newGraphConfiguration(String graphName,
                                    Class<?> test,
                                    String testMethodName,
                                    Map<String,Object> configurationOverrides)

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 a org.apache.commons.configuration.Configuration that will generate a graph unique to that graphName.

Parameters:

graphName - a unique test graph name

test - the test class

testMethodName - the name of the test

configurationOverrides - settings to override defaults with.

newGraphConfiguration

default Configuration newGraphConfiguration(String graphName,
                                            Class<?> test,
                                            String testMethodName)

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 a org.apache.commons.configuration.Configuration that will generate a graph unique to that graphName.

Parameters:

graphName - a unique test graph name

test - the test class

testMethodName - the name of the test

loadGraphData

void loadGraphData(Graph graph,
                   LoadGraphWith loadGraphWith,
                   Class testClass,
                   String testName)

Tests are annotated with a LoadGraphWith 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 the Graph implementation's API. Implementers can use the testClass and testName arguments to implement test specific configurations to their graphs.

Parameters:

graph - the Graph instance to load data into constructed by this GraphProvider

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 executed

testName - the name of the test method being executed

reconstituteGraphSONIdentifier

default <ID> ID reconstituteGraphSONIdentifier(Class<? extends Element> clazz,
                                               Object id)

Converts the GraphSON representation of an identifier to the implementation's representation of an identifier. When serializing a mapper identifier type to GraphSON an implementer will typically specify a mapper serializer in Graph.Io. That will serialize the identifier to a GraphSON representation. When the GraphSON is deserialized, the identifier is written to an Attachable object where it is passed to a user supplied conversion Function that ultimately processes it. It is in this conversion process that vendor specific identifier conversion would occur (if desired). This method mimics that conversion by providing the mechanism that a test can use to do the conversion.

Type Parameters:

ID - The type of the identifier.

Parameters:

clazz - The Element class that represents the identifier.

id - The identifier to convert.

Returns:

The reconstituted identifier.

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_O_P_PA_S_SE_SL_Traverser
• Property
• B_O_PA_S_SE_SL_Traverser
• Traversal
• Traverser
• Vertex
• VertexProperty

The test suite only enforces registration of the following core structure interfaces (i.e. these classes must be registered or the tests will fail to execute):

• Edge
• Element
• Graph
• Graph.Variables
• Property
• Vertex
• VertexProperty

The remaining interfaces and classes should be registered however as failure to do so, might cause failures in the Groovy environment testing suite.
Internally speaking, tests that make use of this method should bind in CORE_IMPLEMENTATIONS to the Set because these represent gremlin-core implementations that are likely not registered by the vendor implementations.