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 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 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 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

      • getGraphComputer

        default GraphComputer getGraphComputer​(Graph graph)
        Create a GraphComputer from the Graph instance. The default implementation simply calls graph.compute().
        Parameters:
        graph - the graph to get the graph computer from
        Returns:
        a new graph computer
      • standardGraphConfiguration

        default org.apache.commons.configuration2.Configuration standardGraphConfiguration​(Class<?> test,
                                                                                           String testMethodName,
                                                                                           LoadGraphWith.GraphData loadGraphWith)
        Gets the 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​(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 calls clear(Graph, Configuration) with a null graph argument.

        Implementations should be able to accept an argument of null for the Configuration 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 a Graph of all data and settings. Implementations will have different ways of handling this. It is typically expected that Graph.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 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.

        Implementations should be able to accept an argument of null for the Configuration 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 the Graph 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 a 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.
        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 a 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
        loadGraphWith - 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 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
      • getWorkingDirectory

        default String getWorkingDirectory()
        Helper method for those build GraphProvider 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 the TestHelper to produce the working directory as it will create the path in the appropriate build directories.
        Returns:
        UNIX-formatted absolute directory path
      • getStaticFeatures

        default Optional<Graph.Features> getStaticFeatures()
        Gets a Graph.Features implementation that contains graph feature configuration that will never change from execution to execution of the tests given this current GraphProvider implementation. Implementing this method will allow the test suite to avoid creation of a Graph 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 the Graph instance produced by this GraphProvider can actually do or else the cost of Graph instantiation will be incurred when it doesn't need to be. It is also important that this method be faster than the cost of Graph 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 an UnsupportedOperationException from those features to let the test suite know that it cannot rely on them and the test suite will revert to using a constructed Graph instance.