Author: claude
Date: Sun Sep 1 08:39:31 2013
New Revision: 1519250
URL: http://svn.apache.org/r1519250
Log:
JENA-380
Added documentation
Added:
jena/Experimental/new-test/src/test/java/com/hp/hpl/jena/graph/README
Modified:
jena/Experimental/new-test/src/test/java/com/hp/hpl/jena/graph/AbstractGraphProducer.java
jena/Experimental/new-test/src/test/java/com/hp/hpl/jena/graph/AbstractGraphProducerUser.java
jena/Experimental/new-test/src/test/java/com/hp/hpl/jena/graph/GraphProducerInterface.java
Modified:
jena/Experimental/new-test/src/test/java/com/hp/hpl/jena/graph/AbstractGraphProducer.java
URL:
http://svn.apache.org/viewvc/jena/Experimental/new-test/src/test/java/com/hp/hpl/jena/graph/AbstractGraphProducer.java?rev=1519250&r1=1519249&r2=1519250&view=diff
==============================================================================
---
jena/Experimental/new-test/src/test/java/com/hp/hpl/jena/graph/AbstractGraphProducer.java
(original)
+++
jena/Experimental/new-test/src/test/java/com/hp/hpl/jena/graph/AbstractGraphProducer.java
Sun Sep 1 08:39:31 2013
@@ -3,12 +3,28 @@ package com.hp.hpl.jena.graph;
import java.util.ArrayList;
import java.util.List;
+/**
+ * An abstract implementation of the GraphProducerInterface.
+ *
+ * This class handles tracking of the created graphs and closing them.
+ * It also provides a callback for the implementing class to perform extra
cleanup when
+ * the graph is closed.
+ *
+ */
public abstract class AbstractGraphProducer implements GraphProducerInterface {
+ /**
+ * The list of graphs that have been opened in this test.
+ */
protected List<Graph> graphList = new ArrayList<Graph>();
+ /**
+ * The method to create a new graph.
+ * @return a newly constructed graph of type under test.
+ */
abstract protected Graph createNewGraph();
+
@Override
final public Graph newGraph() {
Graph retval = createNewGraph();
@@ -17,13 +33,13 @@ public abstract class AbstractGraphProdu
}
/**
- * Method called before the graph is closed
- * @param g The graph to be closed
- */
- protected void beforeClose( Graph g ) {};
-
- /**
- * Method called after the graph is closed
+ * Method called after the graph is closed. This allows the
implementer to
+ * perform extra cleanup activities, like deleting the file associated
with a
+ * file based graph.
+ * <p>
+ * By default this does nothing.
+ * </p>
+ *
* @param g The graph that is closed
*/
protected void afterClose( Graph g ) {};
@@ -33,7 +49,6 @@ public abstract class AbstractGraphProdu
for (Graph g : graphList) {
if (!g.isClosed())
{
- beforeClose( g );
g.close();
}
afterClose( g );
Modified:
jena/Experimental/new-test/src/test/java/com/hp/hpl/jena/graph/AbstractGraphProducerUser.java
URL:
http://svn.apache.org/viewvc/jena/Experimental/new-test/src/test/java/com/hp/hpl/jena/graph/AbstractGraphProducerUser.java?rev=1519250&r1=1519249&r2=1519250&view=diff
==============================================================================
---
jena/Experimental/new-test/src/test/java/com/hp/hpl/jena/graph/AbstractGraphProducerUser.java
(original)
+++
jena/Experimental/new-test/src/test/java/com/hp/hpl/jena/graph/AbstractGraphProducerUser.java
Sun Sep 1 08:39:31 2013
@@ -2,10 +2,20 @@ package com.hp.hpl.jena.graph;
import org.junit.After;
+/**
+ * An abstract class that provides the GraphProducerInterface implementation
and
+ * handles closing all the graphs after a test is complete.
+ *
+ */
public abstract class AbstractGraphProducerUser {
+ /**
+ * The graph producer to use for the tests.
+ * @return
+ */
abstract protected GraphProducerInterface getGraphProducer();
+
@After
final public void closeGraphs() {
getGraphProducer().closeGraphs();
Modified:
jena/Experimental/new-test/src/test/java/com/hp/hpl/jena/graph/GraphProducerInterface.java
URL:
http://svn.apache.org/viewvc/jena/Experimental/new-test/src/test/java/com/hp/hpl/jena/graph/GraphProducerInterface.java?rev=1519250&r1=1519249&r2=1519250&view=diff
==============================================================================
---
jena/Experimental/new-test/src/test/java/com/hp/hpl/jena/graph/GraphProducerInterface.java
(original)
+++
jena/Experimental/new-test/src/test/java/com/hp/hpl/jena/graph/GraphProducerInterface.java
Sun Sep 1 08:39:31 2013
@@ -1,14 +1,14 @@
package com.hp.hpl.jena.graph;
/**
- * Creates the graph for testing
+ * Creates the graph for testing. Implementations should track the creation
of graphs
+ * created with newGraph and close them when clodeGraphs is called.
*
*/
public interface GraphProducerInterface {
/**
- * Returns a Graph to take part in the test. Must be overridden in a
- * subclass.
+ * Returns a new Graph to take part in the test.
*
* @return The graph implementation to test.
*/
@@ -16,6 +16,9 @@ public interface GraphProducerInterface
/**
* provides a hook to close down graphs.
+ * When called all graphs created by the newGraph() method should be
closed.
+ * Note that some graphs may have been closed during the test, so
graphs should
+ * be tested for being closed prior to closing.
*/
public abstract void closeGraphs();
}
Added: jena/Experimental/new-test/src/test/java/com/hp/hpl/jena/graph/README
URL:
http://svn.apache.org/viewvc/jena/Experimental/new-test/src/test/java/com/hp/hpl/jena/graph/README?rev=1519250&view=auto
==============================================================================
--- jena/Experimental/new-test/src/test/java/com/hp/hpl/jena/graph/README
(added)
+++ jena/Experimental/new-test/src/test/java/com/hp/hpl/jena/graph/README Sun
Sep 1 08:39:31 2013
@@ -0,0 +1,95 @@
+Testing guidelines/suggestions
+
+Interface tests are built so that developers may test that implementations
meet the contract
+set out in the interface and accompanying documentation.
+
+The major items under test use an instance of the GraphProducerInterface to
create the graph
+being tested. An implementation of GraphProducerInterface must track all the
tests created
+during the test and close all of them when requested. There is an
AbstractGrapProducer that
+handles most of that functionality but requires a createNewGraph()
implementation.
+
+TESTS
+=====
+
+Interface tests are noted as Abstract(INTERFACENAME)Test. Tests generally
extend the
+AbstractGraphProducerUser class. This class handles cleaning up all the
graphs at the end of
+the tests and provides a hook for implementers to plug in their
GraphProducerInterface.
+
+In general to implement a test requires a few lines of code as is noted in the
example below
+where the new Foo graph implementation is being tested.
+
+<code>
+public class FooGraphTest extends AbstractGraphTest {
+
+ // the graph producer to use while running
+ GraphProducerInterface graphProducer = new FooGraphTest.GraphProducer();
+
+ @Override
+ protected GraphProducerInterface getGraphProducer() {
+ return graphProducer;
+ }
+
+ // the implementation of the graph producer.
+ public static class GraphProducer extends AbstractGraphProducer {
+ @Override
+ protected Graph createNewGraph() {
+ return new FooGraph();
+ }
+ }
+
+}
+</code>
+
+SUITES
+======
+
+Test suites are named as Abstract(INTERFACENAME)Suite. Suites contain several
tests that
+excersize all of the tests for the components of the object under test. For
example the graph
+suite includes tests for the graph iteself, the reifier, finding literals,
recursive subgraph
+extraction, event manager, and transactions. Running the suites is a bit more
complicated then
+running the tests.
+
+Suites are created using the JUnit 4 @RunWith(Suite.class) and
@Suite.SuiteClasses({ })
+annotations. This has several effects that the developer should know about:
+1. The suite class does not get instantiated during the run.
+2. The test class names must be known at coding time (not run time) as they
are listed in the
+ annotation.
+3. Configuration of the tests has to occur during the static initialization
phase of class
+ loading.
+
+To meet these requirements the AbstractGraphSuite has a static variable that
holds the instance
+of the GraphProducerInterface and a number of local static implementations of
the Abstract tests that
+implement the "getGraphProducer()" method by returning the static instance.
The names of the
+local graphs are then used in the @Suite.SuiteClasses annotation. This makes
creating an
+instance of the AbstractGraphSuite for a graph implementation fairly simple as
is noted below.
+
+<code>
+public class FooGraphSuite extends AbstractGraphSuite {
+
+ @BeforeClass
+ public static void beforeClass() {
+ setGraphProducer(new GraphProducer());
+ }
+
+ public static class GraphProducer extends AbstractGraphProducer {
+ @Override
+ protected Graph createNewGraph() {
+ return new FooGraph();
+ }
+ }
+
+}
+</code>
+
+Note that the beforeClass() method is annotated with @BeforeClass. the
@BeforeClass causes it
+to be run once before any of the test methods in the class. This will set the
static
+instance of the graph producer before the suite is run so that it is provided
to the enclosed
+tests.
+
+
+
+
+
+
+
+
