Mailing-List: contact commits-help@jena.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@jena.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r1729645 -
 /jena/site/trunk/content/documentation/notes/datasetgraph.md
Date: Wed, 10 Feb 2016 16:32:47 -0000
To: commits@jena.apache.org
From: andy@apache.org
Message-Id: <20160210163247.DA65C3A05D9@svn01-us-west.apache.org>

Author: andy
Date: Wed Feb 10 16:32:47 2016
New Revision: 1729645

URL: http://svn.apache.org/viewvc?rev=1729645&view=rev
Log:
Notes on DatasetGraph class hierarchy

Modified:
    jena/site/trunk/content/documentation/notes/datasetgraph.md

Modified: jena/site/trunk/content/documentation/notes/datasetgraph.md
URL: http://svn.apache.org/viewvc/jena/site/trunk/content/documentation/notes/datasetgraph.md?rev=1729645&r1=1729644&r2=1729645&view=diff
==============================================================================
--- jena/site/trunk/content/documentation/notes/datasetgraph.md (original)
+++ jena/site/trunk/content/documentation/notes/datasetgraph.md Wed Feb 10 16:32:47 2016
@@ -1,4 +1,4 @@
-Title: The `DatasetGraph` hierarchy.
+Title: The DatasetGraph hierarchy.
 
 _These notes were written February 2016._
 
@@ -10,39 +10,42 @@ of implementation and adding specific fu
 The hierarchy of the significant classes is:
 (there are others adding special features)
 
-```
-DatasetGraph - the interface
-    DatasetGraphBase
-        DatasetGraphBaseFind
-            DatasetGraphCollection
-                DatasetGraphMapLink - ad hoc collection of graphs
-            DatasetGraphOne
-            DatasetGraphTriplesQuads
-                DatasetGraphInMemory - fully transactional in-memory.
-                DatasetGraphMap
-        DatasetGraphQuads 
-    DatasetGraphTrackActive - transaction support 
-        DatasetGraphTransaction - This is the main TDB dataset.
-        DatasetGraphWithLock - MRSW support
-    DatasetGraphWrapper
-        DatasetGraphTxn - TDB usage
-        DatasetGraphViewGraphs
-```
 
+    DatasetGraph - the interface
+        DatasetGraphBase
+            DatasetGraphBaseFind
+                DatasetGraphCollection
+                    DatasetGraphMapLink - ad hoc collection of graphs
+                DatasetGraphOne
+                DatasetGraphTriplesQuads
+                    DatasetGraphInMemory - fully transactional in-memory.
+                    DatasetGraphMap
+            DatasetGraphQuads 
+        DatasetGraphTrackActive - transaction support 
+            DatasetGraphTransaction - This is the main TDB dataset.
+            DatasetGraphWithLock - MRSW support
+        DatasetGraphWrapper
+            DatasetGraphTxn - TDB usage
+            DatasetGraphViewGraphs
 
 Other important classes:
 
-```
-GraphView
-```
+    GraphView
+
+### DatasetGraph
+
+This is the interface. Includes `Transactional` operations.
+
+There are two markers for transaction features supported.
 
-## DatasetGraph
+If `begin`, `commit` and `end` are supported (which is normally the case)
+`supportsTransactions` returns true.
 
-The interface.
+If, further, `abort` is suported, then `supportsTransactionAbort` is true.
 
-## General hierarchy
+### General hierarchy
 
-### DatasetGraphBase
+**DatasetGraphBase**
 
 This provides some basic machinery and provides implementations of
 operations that have alternative styles.  It converts `add(G,S,P,O)` to
@@ -56,7 +59,7 @@ It provides a Lock (LockMRSW) and the Co
 From here on down, the storage aspect of the hierarchy splits depending on
 implementation style.
 
-### DatasetGraphBaseFind
+**DatasetGraphBaseFind**
 
 This is the beginning of the hierarchy for DSGs that store using different units for default graph and named graphs.
 This class splits find/4 into the following variants:
@@ -70,7 +73,7 @@ This class splits find/4 into the follow
     findInAnyNamedGraphs
 ```
 
-### DatasetGraphTriplesQuads
+**DatasetGraphTriplesQuads**
 
 This is the beginning of the hierarchy for DSGs implemented as a set of triples for the default graph and a set of quads for all the named graphs.
 
@@ -90,7 +93,7 @@ and makes
 copy-in operations - triples are copied into the graph or removed from the
 graph, rather than the graph being shared.
 
-###  DatasetGraphInMemory
+** DatasetGraphInMemory**
 
 The main in-memory implementation, providing full transactions (serializable isolation, abort).
 
@@ -98,7 +101,7 @@ Use this one!
 
 This class backs `DatasetFactory.createTxnMem()`.
 
-### DatasetGraphMap
+**DatasetGraphMap**
 
 The in-memory implementation using in-memory Graphs as the storage for Triples.
 It provides MRSW-transactions (serializable isolation, no real abort).
@@ -106,12 +109,12 @@ Use this if a single threaded applicatio
 
 This class backs `DatasetFactory.create()`.
 
-### DatasetGraphCollection
+**DatasetGraphCollection**
 
 Operations split into operations on a collection of Graphs, one for the default graph, and a map of (Node,Graph) for the named graphs.
 It provides MRSW-transactions (serializable isolation, no real abort).
 
-### DatasetGraphMapLink
+**DatasetGraphMapLink**
 
 This implementation is manages Graphs provided by the application.
 
@@ -121,13 +124,13 @@ modifying them via the DatasetGraph inte
 
 This class backs `DatasetFactory.createGeneral()`.
 
-### DatasetGraphWrapper
+**DatasetGraphWrapper**
 
 Indirection to another `DatasetGraph`.
 
 Surprisingly useful.
 
-### DatasetGraphViewGraphs
+**DatasetGraphViewGraphs**
 
 A small class that provides the "get a graph" operations over a
 `DatasetGraph` using `GraphView`.
@@ -140,14 +143,14 @@ Do not use with an implementations that
 (e.g. `DatasetGraphMap`, `DatasetGraphMapLink`) because it goes into an
 infinite recursion if they use GraphView internally.
 
-### GraphView
+**GraphView**
 
 Implementation of the Graph interface as a view of a DatasetGraph including
 providing a basic implementation of the union graph.  Subclasses can, and do,
 provide a better mechanisms for the union graph based on their internal
 indexes.
 
-### DatasetGraphOne
+**DatasetGraphOne**
 
 An implement that only provides a default graph, given at creation time.
 This is a fixed - the app can't add named graphs.
@@ -157,7 +160,7 @@ Cuts through all the machinery to be a s
 Backs up `DatasetGraphFactory.createOneGraph` but not
 `DatasetFactory.create(Model)` which provided are adding named graphs.
 
-### DatasetGraphQuads
+**DatasetGraphQuads**
 
 Root for implementations based on just quad storage, no special triples in
 the default graph (e.g. the default graph is always the calculated union of
@@ -165,11 +168,11 @@ named graphs).
 
 Not used currently.
 
-### DatasetGraphTrackActive
+**DatasetGraphTrackActive**
 
 Framework for implementing transactions.  Provides checking.
 
-### DatasetGraphWithLock
+**DatasetGraphWithLock**
 
 Provides transactions, without abort by default, using a lock.  If the lock
 is LockMRSW, we get multiple-readers or a single writer at any given moment
@@ -186,20 +189,20 @@ Read-commited needs synchronization safe
 co-ordinated changes to several place at once (ConcurrentHashMap isn't
 enough - need to update 2 or more ConcurrentHashMaps together).
 
-## TDB
+### TDB
 
-### DatasetGraphTDB
+**DatasetGraphTDB**
 
 `DatasetGraphTDB` is concerned with the storage
 historical and not used directly by applications.
 
-### DatasetGraphTransaction
+**DatasetGraphTransaction**
 
 This is the class returned by `TDBFactory`, wrapped in `DatasetImpl`.
 
 Different in TDB2 - DatasetGraphTransaction not used, DatasetGraphTDB is transactional.
 
-### DatasetGraphTxn
+**DatasetGraphTxn**
 
 This is the TDB per-transaction `DatasetGraph` using the transaction view
 of indexes.  For the application, it is held in the transactions