--- /dev/null
+# Intro\r
+\r
+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.\r
+\r
+A reading user perceives the combined model and the virtual graph information can be specifically queried if necessary.\r
+\r
+A modifying user needs to specify in which virtual graph the modifications are made.\r
+\r
+Virtual graphs are manipulated via the following interfaces\r
+\r
+* **org.simantics.db.service.VirtualGraphSupport**, for management\r
+* **org.simantics.db.request.WriteTraits**, for identifying the graph to write into\r
+\r
+## Specification\r
+\r
+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:\r
+\r
+* New resources are created into the given virtual graph\r
+* Claim statements are added into the given virtual graph\r
+* Value changes are applied into the given virtual graph\r
+* When the virtual graph provided to the WriteRequest is:\r
+** **null**:\r
+*** 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.\r
+** **non-null**:\r
+*** Statements are only removed from the virtual graph specified for the write request\r
+\r
+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.\r
+\r
+## Examples\r
+\r
+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.\r
+\r
+~~~\r
+package org.simantics.db.tests.api.support.virtualGraphSupport;\r
+\r
+import org.simantics.db.ReadGraph;\r
+import org.simantics.db.RequestProcessor;\r
+import org.simantics.db.Resource;\r
+import org.simantics.db.Session;\r
+import org.simantics.db.Statement;\r
+import org.simantics.db.VirtualGraph;\r
+import org.simantics.db.WriteGraph;\r
+import org.simantics.db.common.request.ReadRequest;\r
+import org.simantics.db.common.request.WriteRequest;\r
+import org.simantics.db.common.request.WriteResultRequest;\r
+import org.simantics.db.common.utils.NameUtils;\r
+import org.simantics.db.exception.DatabaseException;\r
+import org.simantics.db.service.VirtualGraphSupport;\r
+import org.simantics.layer0.Layer0;\r
+\r
+public class VirtualGraphExample {\r
+\r
+ public Resource createLibrary(RequestProcessor processor, VirtualGraph vg, final String libraryName)\r
+ throws DatabaseException {\r
+ return processor.syncRequest(new WriteResultRequest<Resource>(vg) {\r
+ @Override\r
+ public Resource perform(WriteGraph graph) throws DatabaseException {\r
+ Layer0 L0 = Layer0.getInstance(graph);\r
+ Resource r = graph.newResource();\r
+ graph.claim(r, L0.InstanceOf, null, L0.Library);\r
+ graph.claimLiteral(r, L0.HasName, libraryName);\r
+ return r;\r
+ }\r
+ });\r
+ }\r
+\r
+ public void testVirtualGraphs(Session session) throws DatabaseException {\r
+ VirtualGraphSupport vgSupport = session.getService(VirtualGraphSupport.class);\r
+ VirtualGraph memory = vgSupport.getMemoryPersistent("memory");\r
+ VirtualGraph workspace = vgSupport.getWorkspacePersistent("workspace");\r
+ // NOTICE: resource are created in difference virtual graphs in separate\r
+ // transactions through Session.syncRequest.\r
+ Resource memResource = createLibrary(session, memory, "memory");\r
+ Resource workspaceResource = createLibrary(session, workspace, "workspace");\r
+ printVirtualGraphs(session);\r
+ }\r
+\r
+ public void testMultipleVirtualGraphsInSameTransaction(Session session) throws DatabaseException {\r
+ final VirtualGraphSupport vgSupport = session.getService(VirtualGraphSupport.class);\r
+ session.syncRequest(new WriteRequest() {\r
+ @Override\r
+ public void perform(WriteGraph graph) throws DatabaseException {\r
+ VirtualGraph memory = vgSupport.getMemoryPersistent("memory");\r
+ VirtualGraph workspace = vgSupport.getWorkspacePersistent("workspace");\r
+ // NOTICE: resource are created in different virtual graphs in\r
+ // the same transaction through WriteGraph.syncRequest\r
+ Resource memResource = createLibrary(graph, memory, "memory");\r
+ Resource workspaceResource = createLibrary(graph, workspace, "workspace");\r
+ }\r
+ });\r
+ printVirtualGraphs(session);\r
+ }\r
+\r
+ public void printVirtualGraphs(Session session) throws DatabaseException {\r
+ session.syncRequest(new ReadRequest() {\r
+ @Override\r
+ public void run(ReadGraph graph) throws DatabaseException {\r
+ VirtualGraphSupport vgSupport = graph.getService(VirtualGraphSupport.class);\r
+ for (VirtualGraph vg : vgSupport.listGraphs()) {\r
+ for (Statement stm : vgSupport.listStatements(vg)) {\r
+ System.out.println("Statement: " + NameUtils.toString(graph, stm));\r
+ }\r
+ for (Resource r : vgSupport.listValues(vg)) {\r
+ System.out.println("Literal value: " + graph.getValue(r));\r
+ }\r
+ }\r
+ }\r
+ });\r
+ }\r
+\r
+}\r
+~~~\r
+\r
+## Debugging\r
+\r
+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:\r
+;DB: when the statement is in the persistent graph\r
+;'name' (W): when the statement is in a named workspace-persistent virtual graph\r
+;'name' (M): when the statement is in a named memory-persistent (transient) virtual graph\r
+\r
+[[Image:GraphDebuggerVG.png|frame|center|Graph debugger example with statements in virtual graphs.]]\r
Code Review / simantics / platform.git / blobdiff