jena-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From a...@apache.org
Subject [6/8] jena git commit: JENA-1381: NamedGraph; use in DatasetGraphMap, GraphView.
Date Thu, 24 Aug 2017 21:31:32 GMT
JENA-1381: NamedGraph; use in DatasetGraphMap, GraphView.

Adjust javadoc in DatasetFactory.


Project: http://git-wip-us.apache.org/repos/asf/jena/repo
Commit: http://git-wip-us.apache.org/repos/asf/jena/commit/03a1c35a
Tree: http://git-wip-us.apache.org/repos/asf/jena/tree/03a1c35a
Diff: http://git-wip-us.apache.org/repos/asf/jena/diff/03a1c35a

Branch: refs/heads/master
Commit: 03a1c35abd3c40c05e950c86608d2da668721034
Parents: b358603
Author: Andy Seaborne <andy@apache.org>
Authored: Sat Aug 19 17:56:54 2017 +0100
Committer: Andy Seaborne <andy@apache.org>
Committed: Sat Aug 19 17:56:54 2017 +0100

----------------------------------------------------------------------
 .../org/apache/jena/query/DatasetFactory.java   | 56 +++++++------
 .../jena/sparql/core/DatasetGraphFactory.java   | 82 ++++++++++++--------
 .../jena/sparql/core/DatasetGraphMap.java       | 12 +--
 .../jena/sparql/core/DatasetGraphMapLink.java   |  9 ++-
 .../org/apache/jena/sparql/core/GraphView.java  |  3 +-
 .../org/apache/jena/sparql/core/NamedGraph.java | 46 +++++++++++
 .../jena/sparql/core/NamedGraphWrapper.java     | 44 +++++++++++
 7 files changed, 186 insertions(+), 66 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/jena/blob/03a1c35a/jena-arq/src/main/java/org/apache/jena/query/DatasetFactory.java
----------------------------------------------------------------------
diff --git a/jena-arq/src/main/java/org/apache/jena/query/DatasetFactory.java b/jena-arq/src/main/java/org/apache/jena/query/DatasetFactory.java
index 84fb9dd..42f960b 100644
--- a/jena-arq/src/main/java/org/apache/jena/query/DatasetFactory.java
+++ b/jena-arq/src/main/java/org/apache/jena/query/DatasetFactory.java
@@ -39,35 +39,22 @@ import org.apache.jena.util.FileManager;
  */
 public class DatasetFactory {
 
-    /** Create an in-memory, non-transactional Dataset.
+    /** Create an in-memory {@link Dataset}.
      * <p>
      * See also {@link #createTxnMem()} for a transactional dataset.
      * <p>
      * This implementation copies models when {@link Dataset#addNamedModel(String, Model)}
is called.
+     * <p>
+     * This implementation does not support serialized transactions (it only provides MRSW
locking). 
+     * 
+     * @see #createTxnMem
      */
     public static Dataset create() {
         return wrap(DatasetGraphFactory.create()) ;
     }
     
-	/** Create an in-memory, non-transactional Dataset.
-	 * <p>
-	 * See also {@link #createTxnMem()} for a transactional dataset.
-	 * <p>
-	 * Use {@link #createGeneral()} when needing to add graphs with mixed charcateristics, 
-	 * e.g. inference graphs, specific graphs from TDB.
-	 * <p>    
-     * <em>This operation is marked "deprecated" because the general purpose "add named
graph of any implementation"
-     * feature will be removed; this feature is now provided by {@link #createGeneral()}.
-     * </em>
-	 * @deprecated Prefer {@link #createGeneral()} or {@link #createTxnMem()} or {@link #create()}
-	 */
-	@Deprecated
-	public static Dataset createMem() {
-		return createGeneral() ;
-	}
-
 	/**
-     * Create an in-memory. transactional Dataset.
+     * Create an in-memory. transactional {@link Dataset}.
      * <p> 
      * This fully supports transactions, including abort to roll-back changes.
      * It provides "autocommit" if operations are performed
@@ -75,7 +62,7 @@ public class DatasetFactory {
      * (the implementation adds a begin/commit around each add or delete
      * so overheads can accumulate).
      * 
-     * @return a transactional, in-memory, modifiable Dataset which
+     * @return a transactional, in-memory, modifiable Dataset
      * 
      */
 	public static Dataset createTxnMem() {
@@ -83,21 +70,44 @@ public class DatasetFactory {
 	}
 
 	/**
-	 * Create a general-purpose Dataset.<br/>
+	 * Create a general-purpose  {@link Dataset}.<br/>
 	 * Any graphs needed are in-memory unless explciitly added with {@link Dataset#addNamedModel}.
 	 * </p>
-	 * This dataset can contain graphs from any source when added via {@link Dataset#addNamedModel}.
+	 * This dataset type can contain graphs from any source when added via {@link Dataset#addNamedModel}.
 	 * These are held as links to the supplied graph and not copied.
 	 * <p> 
-	 * This dataset does not support transactions. 
+	 * <em>This dataset does not support the graph indexing feature of jena-text.</em>
+     * <p>
+	 * This dataset does not support serialized transactions (it only provides MRSW locking).

 	 * <p>
 	 * 
+	 * @see #createTxnMem
 	 * @return a general-purpose Dataset
 	 */
 	public static Dataset createGeneral() {
 		return wrap(DatasetGraphFactory.createGeneral()); 
 	}
 
+    /** Create an in-memory {@link Dataset}.
+     * <p>
+     * See also {@link #createTxnMem()} for a transactional dataset.
+     * <p>
+     * Use {@link #createGeneral()} when needing to add graphs with mixed characteristics,

+     * e.g. inference graphs, or specific graphs from TDB.
+     * <p>    
+     * <em>It does not support the graph indexing feature of jena-text.</em>
+     * <p>
+     * <em>This factory operation is marked "deprecated" because the general purpose
"add named graph of any implementation"
+     * feature will be removed; this feature is now provided by {@link #createGeneral()}.
+     * </em>
+     * @deprecated Prefer {@link #createTxnMem()} or {@link #create()} or, for special cases,
{@link #createGeneral()}.
+     * @see #createTxnMem
+     */
+    @Deprecated
+    public static Dataset createMem() {
+        return createGeneral() ;
+    }
+
     /**
 	 * @param model The model for the default graph
 	 * @return a dataset with the given model as the default graph

http://git-wip-us.apache.org/repos/asf/jena/blob/03a1c35a/jena-arq/src/main/java/org/apache/jena/sparql/core/DatasetGraphFactory.java
----------------------------------------------------------------------
diff --git a/jena-arq/src/main/java/org/apache/jena/sparql/core/DatasetGraphFactory.java b/jena-arq/src/main/java/org/apache/jena/sparql/core/DatasetGraphFactory.java
index 321055e..68e680f 100644
--- a/jena-arq/src/main/java/org/apache/jena/sparql/core/DatasetGraphFactory.java
+++ b/jena-arq/src/main/java/org/apache/jena/sparql/core/DatasetGraphFactory.java
@@ -19,64 +19,78 @@
 package org.apache.jena.sparql.core;
 
 import java.util.Iterator ;
+import java.util.Objects ;
 
 import org.apache.jena.graph.Graph ;
 import org.apache.jena.graph.Node ;
 import org.apache.jena.query.Dataset ;
+import org.apache.jena.rdf.model.Model ;
 import org.apache.jena.sparql.core.mem.DatasetGraphInMemory;
 import org.apache.jena.sparql.graph.GraphFactory ;
 
 public class DatasetGraphFactory
 {
-    /** Create an in-memory {@link DatasetGraph}.
-     * This implementation copies the triples of an added graph into the dataset. 
+    /** Create an in-memory {@link Dataset}.
      * <p>
-     * See also {@link #createTxnMem()}
-     * <br/>
-     * See also {@link #createGeneral()}
+     * See also {@link #createTxnMem()} for a transactional dataset.
+     * <p>
+     * This implementation copies models when {@link Dataset#addNamedModel(String, Model)}
is called.
+     * <p>
+     * This implementation does not support serialized transactions (it only provides MRSW
locking). 
      * 
      * @see #createTxnMem
-     * @see #createGeneral
      */
-    
     public static DatasetGraph create() {
         return new DatasetGraphMap() ;
     }
 
     /**
-     * Create a general-purpose, non-transactional Dataset.<br/>
+     * Create an in-memory. transactional {@link Dataset}.
+     * <p> 
+     * This fully supports transactions, including abort to roll-back changes.
+     * It provides "autocommit" if operations are performed
+     * outside a transaction but with a performance impact
+     * (the implementation adds a begin/commit around each add or delete
+     * so overheads can accumulate).
      * 
-     * This dataset can contain graphs from any source when added via {@link Dataset#addNamedModel}.
-     * Any graphs needed are in-memory unless explicitly added with {@link DatasetGraph#addGraph}.
+     * @return a transactional, in-memory, modifiable Dataset
+     * 
+     */
+    public static DatasetGraph createTxnMem() { return new DatasetGraphInMemory(); }
+
+    /**
+     * Create a general-purpose  {@link Dataset}.<br/>
+     * Any graphs needed are in-memory unless explciitly added with {@link Dataset#addNamedModel}.
      * </p>
+     * This dataset type can contain graphs from any source when added via {@link Dataset#addNamedModel}.
      * These are held as links to the supplied graph and not copied.
      * <p> 
-     * This dataset does not support transactions. 
+     * <em>This dataset does not support the graph indexing feature of jena-text.</em>
+     * <p>
+     * This dataset does not support serialized transactions (it only provides MRSW locking).

      * <p>
      * 
-     * @return a general-purpose DatasetGraph
+     * @see #createTxnMem
+     * @return a general-purpose Dataset
      */
     public static DatasetGraph createGeneral() { return new DatasetGraphMapLink(graphMakerMem)
; }
 
-    /**
-     * @return a DatasetGraph which features transactional in-memory operation
-     */
-    public static DatasetGraph createTxnMem() { return new DatasetGraphInMemory(); }
-
-    /** Create an in-memory, non-transactional DatasetGraph.
+    /** Create an in-memory {@link Dataset}.
      * <p>
      * See also {@link #createTxnMem()} for a transactional dataset.
      * <p>
      * Use {@link #createGeneral()} when needing to add graphs with mixed characteristics,

-     * e.g. inference graphs, specific graphs from TDB.
+     * e.g. inference graphs, or specific graphs from TDB.
      * <p>    
-     * <em>This operation is marked "deprecated" because the general purpose 
-     * "add named graph of any implementation"
+     * <em>It does not support the graph indexing feature of jena-text.</em>
+     * <p>
+     * <em>This factory operation is marked "deprecated" because the general purpose
"add named graph of any implementation"
      * feature will be removed; this feature is now provided by {@link #createGeneral()}.
      * </em>
-     * @deprecated Prefer {@link #createGeneral()} or {@link #createTxnMem()}
+     * @deprecated Prefer {@link #createTxnMem()} or {@link #create()} or, for special cases,
{@link #createGeneral()}.
+     * @see #createTxnMem
      */
-    @Deprecated
+   @Deprecated
     public static DatasetGraph createMem() { return createGeneral() ; }
     
     /** Create a DatasetGraph based on an existing one;
@@ -89,9 +103,11 @@ public class DatasetGraphFactory
         return cloneStructure(dsg) ;
     }
     
-    /** Clone the structure of a DatasetGraph
+    /** 
+     * Clone the structure of a {@link DatasetGraph}.
      */
     public static DatasetGraph cloneStructure(DatasetGraph dsg) {
+        Objects.requireNonNull(dsg, "DatasetGraph must be provided") ;
         DatasetGraphMapLink dsg2 = new DatasetGraphMapLink(dsg.getDefaultGraph()) ;
         for ( Iterator<Node> names = dsg.listGraphNodes() ; names.hasNext() ; ) {
             Node gn = names.next() ;
@@ -126,15 +142,17 @@ public class DatasetGraphFactory
     /** Interface for making graphs when a dataset needs to add a new graph.
      *  Return null for no graph created.
      */
-    public interface GraphMaker { public Graph create() ; }
+    public interface GraphMaker { public Graph create(Node name) ; }
 
-    /** A graph maker that doesn't make graphs */
-    public static GraphMaker graphMakerNull = () -> null ;
+    /** A graph maker that doesn't make graphs. */
+    public static GraphMaker graphMakerNull = (name) -> null ;
 
-//    /** @deprecated Use graphMakerMem */
-//    @Deprecated 
-//    public static GraphMaker memGraphMaker = () -> GraphFactory.createDefaultGraph()
;
+    /** A graph maker that creates unnamed Jena default graphs */ 
+    /*package*/ static GraphMaker graphMakerMem = (name) -> GraphFactory.createDefaultGraph()
;
     
-    /** A graph maker that create Jena default graphs */ 
-    public static GraphMaker graphMakerMem = () -> GraphFactory.createDefaultGraph() ;
+    /** A graph maker that create {@link NamedGraph}s around a Jena default graphs */ 
+    public static GraphMaker graphMakerNamedGraphMem = (name) -> {
+        Graph g = GraphFactory.createDefaultGraph() ;
+        return new NamedGraphWrapper(name, g);
+    };
 }

http://git-wip-us.apache.org/repos/asf/jena/blob/03a1c35a/jena-arq/src/main/java/org/apache/jena/sparql/core/DatasetGraphMap.java
----------------------------------------------------------------------
diff --git a/jena-arq/src/main/java/org/apache/jena/sparql/core/DatasetGraphMap.java b/jena-arq/src/main/java/org/apache/jena/sparql/core/DatasetGraphMap.java
index dc06ca7..24d3e04 100644
--- a/jena-arq/src/main/java/org/apache/jena/sparql/core/DatasetGraphMap.java
+++ b/jena-arq/src/main/java/org/apache/jena/sparql/core/DatasetGraphMap.java
@@ -52,17 +52,17 @@ public class DatasetGraphMap extends DatasetGraphTriplesQuads
     /**  DatasetGraphMap defaulting to storage in memory.
      */
     public DatasetGraphMap() {
-        this(DatasetGraphFactory.graphMakerMem) ; 
+        this(DatasetGraphFactory.graphMakerNamedGraphMem) ; 
     }
     
     /**  DatasetGraphMap with a specific policy for graph creation.
      *   This allows control over the storage. 
      */
     public DatasetGraphMap(GraphMaker graphMaker) {
-        this(graphMaker.create(), graphMaker) ;
+        this(graphMaker.create(null), graphMaker) ;
     }
     
-    public DatasetGraphMap(Graph defaultGraph, GraphMaker graphMaker) {
+    private DatasetGraphMap(Graph defaultGraph, GraphMaker graphMaker) {
         this.defaultGraph = defaultGraph ;
         this.graphMaker = graphMaker ;
     }
@@ -144,7 +144,7 @@ public class DatasetGraphMap extends DatasetGraphTriplesQuads
         // Not a special case.
         Graph g = graphs.get(graphNode);
         if ( g == null ) {
-            g = getGraphCreate();
+            g = getGraphCreate(graphNode);
             if ( g != null )
                 graphs.put(graphNode, g);
         }
@@ -155,8 +155,8 @@ public class DatasetGraphMap extends DatasetGraphTriplesQuads
      * Return null for "nothing created as a graph".
      * Sub classes can reimplement this.  
      */
-    protected Graph getGraphCreate() { 
-        Graph g = graphMaker.create() ;
+    protected Graph getGraphCreate(Node graphNode) { 
+        Graph g = graphMaker.create(graphNode) ;
         if ( g == null )
             throw new ARQException("Can't make new graphs") ;
         return g ;

http://git-wip-us.apache.org/repos/asf/jena/blob/03a1c35a/jena-arq/src/main/java/org/apache/jena/sparql/core/DatasetGraphMapLink.java
----------------------------------------------------------------------
diff --git a/jena-arq/src/main/java/org/apache/jena/sparql/core/DatasetGraphMapLink.java b/jena-arq/src/main/java/org/apache/jena/sparql/core/DatasetGraphMapLink.java
index 345efc0..c6d455b 100644
--- a/jena-arq/src/main/java/org/apache/jena/sparql/core/DatasetGraphMapLink.java
+++ b/jena-arq/src/main/java/org/apache/jena/sparql/core/DatasetGraphMapLink.java
@@ -106,7 +106,7 @@ public class DatasetGraphMapLink extends DatasetGraphCollection
      * DatasetFactory.createGeneral.
      */
     /*package*/ DatasetGraphMapLink(GraphMaker graphMaker) {
-        this(graphMaker.create(), graphMaker) ;
+        this(graphMaker.create(null), graphMaker) ;
     }
 
     /** A {@code DatasetGraph} that uses the given graph for the default graph
@@ -146,6 +146,7 @@ public class DatasetGraphMapLink extends DatasetGraphCollection
 
     @Override
     public Graph getGraph(Node graphNode) {
+        // Same as DatasetMap.getGraph but we inherit differently.
         if ( Quad.isUnionGraph(graphNode) ) 
             return new GraphUnionRead(this) ;
         if ( Quad.isDefaultGraph(graphNode))
@@ -153,7 +154,7 @@ public class DatasetGraphMapLink extends DatasetGraphCollection
         // Not a special case.
         Graph g = graphs.get(graphNode);
         if ( g == null ) {
-            g = getGraphCreate();
+            g = getGraphCreate(graphNode);
             if ( g != null )
                 graphs.put(graphNode, g);
         }
@@ -163,8 +164,8 @@ public class DatasetGraphMapLink extends DatasetGraphCollection
     /** Called from getGraph when a nonexistent graph is asked for.
      * Return null for "nothing created as a graph"
      */
-    protected Graph getGraphCreate() { 
-        return graphMaker.create() ;
+    protected Graph getGraphCreate(Node graphNode) { 
+        return graphMaker.create(graphNode) ;
     }
 
     @Override

http://git-wip-us.apache.org/repos/asf/jena/blob/03a1c35a/jena-arq/src/main/java/org/apache/jena/sparql/core/GraphView.java
----------------------------------------------------------------------
diff --git a/jena-arq/src/main/java/org/apache/jena/sparql/core/GraphView.java b/jena-arq/src/main/java/org/apache/jena/sparql/core/GraphView.java
index 41a9195..ab20c0c 100644
--- a/jena-arq/src/main/java/org/apache/jena/sparql/core/GraphView.java
+++ b/jena-arq/src/main/java/org/apache/jena/sparql/core/GraphView.java
@@ -44,7 +44,7 @@ import org.apache.jena.util.iterator.WrappedIterator ;
  *  @see GraphUnionRead
  */ 
 
-public class GraphView extends GraphBase implements Sync
+public class GraphView extends GraphBase implements NamedGraph, Sync
 {
     // Beware this implements union graph - implementations may wish
     // to do better so see protected method below.
@@ -80,6 +80,7 @@ public class GraphView extends GraphBase implements Sync
      * Return the graph name for this graph in the dataset it is a view of.
      * Returns {@code null} for the default graph.
      */
+    @Override
     public Node getGraphName() {
         return (gn == Quad.defaultGraphNodeGenerated) ? null : gn ;
     }

http://git-wip-us.apache.org/repos/asf/jena/blob/03a1c35a/jena-arq/src/main/java/org/apache/jena/sparql/core/NamedGraph.java
----------------------------------------------------------------------
diff --git a/jena-arq/src/main/java/org/apache/jena/sparql/core/NamedGraph.java b/jena-arq/src/main/java/org/apache/jena/sparql/core/NamedGraph.java
new file mode 100644
index 0000000..77db174
--- /dev/null
+++ b/jena-arq/src/main/java/org/apache/jena/sparql/core/NamedGraph.java
@@ -0,0 +1,46 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.jena.sparql.core;
+
+import org.apache.jena.graph.Graph ;
+import org.apache.jena.graph.Node ;
+
+/**
+ * A graph with an associated name.
+ * <p>
+ * Sometimes there is an associated name with a graph, where it lives on the web,
+ * or the name in a dataset.
+ * <p>
+ * This interface is for graph that have one associated name.
+ * What "associated" means is left open.  
+ * 
+ * @see GraphView
+ * @see NamedGraphWrapper
+ */
+
+public interface NamedGraph extends Graph {
+    /**
+     * Return the graph name for this graph.
+     * Blank nodes can be used.
+     * <p>
+     * A named graph of "null" is discouraged - use {@link Quad#defaultGraphIRI} 
+     * for a default graph in the context of use.
+     */
+    public Node getGraphName();
+}

http://git-wip-us.apache.org/repos/asf/jena/blob/03a1c35a/jena-arq/src/main/java/org/apache/jena/sparql/core/NamedGraphWrapper.java
----------------------------------------------------------------------
diff --git a/jena-arq/src/main/java/org/apache/jena/sparql/core/NamedGraphWrapper.java b/jena-arq/src/main/java/org/apache/jena/sparql/core/NamedGraphWrapper.java
new file mode 100644
index 0000000..7b826c6
--- /dev/null
+++ b/jena-arq/src/main/java/org/apache/jena/sparql/core/NamedGraphWrapper.java
@@ -0,0 +1,44 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.jena.sparql.core;
+
+import org.apache.jena.graph.Graph ;
+import org.apache.jena.graph.Node ;
+import org.apache.jena.sparql.graph.GraphWrapper ;
+
+/**
+ * Add a name to a graph.
+ * 
+ * @see GraphView
+ */
+
+public class NamedGraphWrapper extends GraphWrapper implements NamedGraph {
+
+    private final Node graphName ;
+
+    public NamedGraphWrapper(Node graphName, Graph graph) {
+        super(graph) ;
+        this.graphName = graphName;
+    }
+
+    @Override
+    public Node getGraphName() {
+        return graphName ;
+    }
+}


Mime
View raw message