X-Git-Url: https://gerrit.simantics.org/r/gitweb?p=simantics%2Fplatform.git;a=blobdiff_plain;f=docs%2FDeveloper%2FDatabase%2FVirtualGraphs.md;fp=docs%2FDeveloper%2FDatabase%2FVirtualGraphs.md;h=66c20ee85b4c95593d765713d3a4a8bd79ae6f94;hp=0000000000000000000000000000000000000000;hb=a9ec58f08ccc02e65b1cab6aedff25e0cf3c6444;hpb=5998374f7e179cfaf451c220216adc18c823047f

diff --git a/docs/Developer/Database/VirtualGraphs.md b/docs/Developer/Database/VirtualGraphs.md
new file mode 100644
index 000000000..66c20ee85
--- /dev/null
+++ b/docs/Developer/Database/VirtualGraphs.md
@@ -0,0 +1,121 @@
+# Intro
+
+The Simantics database client allows for defining memory-based and disk-based graph fragments which are applied on top of the server-based semantic graph.
+
+A reading user perceives the combined model and the virtual graph information can be specifically queried if necessary.
+
+A modifying user needs to specify in which virtual graph the modifications are made.
+
+Virtual graphs are manipulated via the following interfaces
+
+* **org.simantics.db.service.VirtualGraphSupport**, for management
+* **org.simantics.db.request.WriteTraits**, for identifying the graph to write into
+
+## Specification
+
+A write request has a single graph into which it writes. This is determined by *WriteTraits* and usually as a parameter to *WriteRequest*. If null is provided, the client applies modifications into the persistent graph. The following rules apply:
+
+* New resources are created into the given virtual graph
+* Claim statements are added into the given virtual graph
+* Value changes are applied into the given virtual graph
+* When the virtual graph provided to the WriteRequest is:
+** **null**:
+*** For denied statements the location of the statement is determined and the statement is removed from that virtual graph. If the denied statement is not a part of any virtual graph, it is removed from the persistent graph.
+** **non-null**:
+*** Statements are only removed from the virtual graph specified for the write request
+
+The user can perform modifications into multiple virtual graphs within a single transaction. This is accomplished by issuing a new synchronous modification (WriteGraph.sync) into a new virtual graph.
+
+## Examples
+
+The following code examples show in practice how to write into virtual graphs, both memory- and disk-based. Writing to several virtual graphs within the same write transaction is also demonstrated.
+
+~~~
+package org.simantics.db.tests.api.support.virtualGraphSupport;
+
+import org.simantics.db.ReadGraph;
+import org.simantics.db.RequestProcessor;
+import org.simantics.db.Resource;
+import org.simantics.db.Session;
+import org.simantics.db.Statement;
+import org.simantics.db.VirtualGraph;
+import org.simantics.db.WriteGraph;
+import org.simantics.db.common.request.ReadRequest;
+import org.simantics.db.common.request.WriteRequest;
+import org.simantics.db.common.request.WriteResultRequest;
+import org.simantics.db.common.utils.NameUtils;
+import org.simantics.db.exception.DatabaseException;
+import org.simantics.db.service.VirtualGraphSupport;
+import org.simantics.layer0.Layer0;
+
+public class VirtualGraphExample {
+
+    public Resource createLibrary(RequestProcessor processor, VirtualGraph vg, final String libraryName)
+            throws DatabaseException {
+        return processor.syncRequest(new WriteResultRequest<Resource>(vg) {
+            @Override
+            public Resource perform(WriteGraph graph) throws DatabaseException {
+                Layer0 L0 = Layer0.getInstance(graph);
+                Resource r = graph.newResource();
+                graph.claim(r, L0.InstanceOf, null, L0.Library);
+                graph.claimLiteral(r, L0.HasName, libraryName);
+                return r;
+            }
+        });
+    }
+
+    public void testVirtualGraphs(Session session) throws DatabaseException {
+        VirtualGraphSupport vgSupport = session.getService(VirtualGraphSupport.class);
+        VirtualGraph memory = vgSupport.getMemoryPersistent("memory");
+        VirtualGraph workspace = vgSupport.getWorkspacePersistent("workspace");
+        // NOTICE: resource are created in difference virtual graphs in separate
+        // transactions through Session.syncRequest.
+        Resource memResource = createLibrary(session, memory, "memory");
+        Resource workspaceResource = createLibrary(session, workspace, "workspace");
+        printVirtualGraphs(session);
+    }
+
+    public void testMultipleVirtualGraphsInSameTransaction(Session session) throws DatabaseException {
+        final VirtualGraphSupport vgSupport = session.getService(VirtualGraphSupport.class);
+        session.syncRequest(new WriteRequest() {
+            @Override
+            public void perform(WriteGraph graph) throws DatabaseException {
+                VirtualGraph memory = vgSupport.getMemoryPersistent("memory");
+                VirtualGraph workspace = vgSupport.getWorkspacePersistent("workspace");
+                // NOTICE: resource are created in different virtual graphs in
+                // the same transaction through WriteGraph.syncRequest
+                Resource memResource = createLibrary(graph, memory, "memory");
+                Resource workspaceResource = createLibrary(graph, workspace, "workspace");
+            }
+        });
+        printVirtualGraphs(session);
+    }
+
+    public void printVirtualGraphs(Session session) throws DatabaseException {
+        session.syncRequest(new ReadRequest() {
+            @Override
+            public void run(ReadGraph graph) throws DatabaseException {
+                VirtualGraphSupport vgSupport = graph.getService(VirtualGraphSupport.class);
+                for (VirtualGraph vg : vgSupport.listGraphs()) {
+                    for (Statement stm : vgSupport.listStatements(vg)) {
+                        System.out.println("Statement: " + NameUtils.toString(graph, stm));
+                    }
+                    for (Resource r : vgSupport.listValues(vg)) {
+                        System.out.println("Literal value: " + graph.getValue(r));
+                    }
+                }
+            }
+        });
+    }
+
+}
+~~~
+
+## Debugging
+
+The standard Simantics Graph Debugger view shows for every statement which virtual graph it belongs to. This information is visible on the *Graph* column of the statement table. The Graph column will show:
+;DB: when the statement is in the persistent graph
+;'name' (W): when the statement is in a named workspace-persistent virtual graph
+;'name' (M): when the statement is in a named memory-persistent (transient) virtual graph
+
+[[Image:GraphDebuggerVG.png|frame|center|Graph debugger example with statements in virtual graphs.]]