docs/Developer/Database/VirtualGraphs.md

   1 # Intro\r
   2 \r
   3 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
   4 \r
   5 A reading user perceives the combined model and the virtual graph information can be specifically queried if necessary.\r
   6 \r
   7 A modifying user needs to specify in which virtual graph the modifications are made.\r
   8 \r
   9 Virtual graphs are manipulated via the following interfaces\r
  10 \r
  11 * **org.simantics.db.service.VirtualGraphSupport**, for management\r
  12 * **org.simantics.db.request.WriteTraits**, for identifying the graph to write into\r
  13 \r
  14 ## Specification\r
  15 \r
  16 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.\r
  17 \r
  18 The following rules apply:\r
  19 \r
  20 * New resources are created into the given virtual graph\r
  21 * Claim statements are added into the given virtual graph\r
  22 * Value changes are applied into the given virtual graph\r
  23 * When the virtual graph provided to the WriteRequest is:\r
  24   * **null**:\r
  25     * 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
  26   * **non-null**:\r
  27     * Statements are only removed from the virtual graph specified for the write request\r
  28 \r
  29 The user can perform modifications into multiple virtual graphs within a single transaction. This is accomplished by issuing a new synchronous modification `WriteGraph.sync[Request]` into a new virtual graph.\r
  30 \r
  31 ## Examples\r
  32 \r
  33 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
  34 \r
  35 ~~~\r
  36 package org.simantics.db.tests.api.support.virtualGraphSupport;\r
  37 \r
  38 import org.simantics.db.ReadGraph;\r
  39 import org.simantics.db.RequestProcessor;\r
  40 import org.simantics.db.Resource;\r
  41 import org.simantics.db.Session;\r
  42 import org.simantics.db.Statement;\r
  43 import org.simantics.db.VirtualGraph;\r
  44 import org.simantics.db.WriteGraph;\r
  45 import org.simantics.db.common.request.ReadRequest;\r
  46 import org.simantics.db.common.request.WriteRequest;\r
  47 import org.simantics.db.common.request.WriteResultRequest;\r
  48 import org.simantics.db.common.utils.NameUtils;\r
  49 import org.simantics.db.exception.DatabaseException;\r
  50 import org.simantics.db.service.VirtualGraphSupport;\r
  51 import org.simantics.layer0.Layer0;\r
  52 \r
  53 public class VirtualGraphExample {\r
  54 \r
  55     public Resource createLibrary(RequestProcessor processor, VirtualGraph vg, final String libraryName)\r
  56             throws DatabaseException {\r
  57         return processor.syncRequest(new WriteResultRequest<Resource>(vg) {\r
  58             @Override\r
  59             public Resource perform(WriteGraph graph) throws DatabaseException {\r
  60                 Layer0 L0 = Layer0.getInstance(graph);\r
  61                 Resource r = graph.newResource();\r
  62                 graph.claim(r, L0.InstanceOf, null, L0.Library);\r
  63                 graph.claimLiteral(r, L0.HasName, libraryName);\r
  64                 return r;\r
  65             }\r
  66         });\r
  67     }\r
  68 \r
  69     public void testVirtualGraphs(Session session) throws DatabaseException {\r
  70         VirtualGraphSupport vgSupport = session.getService(VirtualGraphSupport.class);\r
  71         VirtualGraph memory = vgSupport.getMemoryPersistent("memory");\r
  72         VirtualGraph workspace = vgSupport.getWorkspacePersistent("workspace");\r
  73         // NOTICE: resource are created in difference virtual graphs in separate\r
  74         // transactions through Session.syncRequest.\r
  75         Resource memResource = createLibrary(session, memory, "memory");\r
  76         Resource workspaceResource = createLibrary(session, workspace, "workspace");\r
  77         printVirtualGraphs(session);\r
  78     }\r
  79 \r
  80     public void testMultipleVirtualGraphsInSameTransaction(Session session) throws DatabaseException {\r
  81         final VirtualGraphSupport vgSupport = session.getService(VirtualGraphSupport.class);\r
  82         session.syncRequest(new WriteRequest() {\r
  83             @Override\r
  84             public void perform(WriteGraph graph) throws DatabaseException {\r
  85                 VirtualGraph memory = vgSupport.getMemoryPersistent("memory");\r
  86                 VirtualGraph workspace = vgSupport.getWorkspacePersistent("workspace");\r
  87                 // NOTICE: resource are created in different virtual graphs in\r
  88                 // the same transaction through WriteGraph.syncRequest\r
  89                 Resource memResource = createLibrary(graph, memory, "memory");\r
  90                 Resource workspaceResource = createLibrary(graph, workspace, "workspace");\r
  91             }\r
  92         });\r
  93         printVirtualGraphs(session);\r
  94     }\r
  95 \r
  96     public void printVirtualGraphs(Session session) throws DatabaseException {\r
  97         session.syncRequest(new ReadRequest() {\r
  98             @Override\r
  99             public void run(ReadGraph graph) throws DatabaseException {\r
 100                 VirtualGraphSupport vgSupport = graph.getService(VirtualGraphSupport.class);\r
 101                 for (VirtualGraph vg : vgSupport.listGraphs()) {\r
 102                     for (Statement stm : vgSupport.listStatements(vg)) {\r
 103                         System.out.println("Statement: " + NameUtils.toString(graph, stm));\r
 104                     }\r
 105                     for (Resource r : vgSupport.listValues(vg)) {\r
 106                         System.out.println("Literal value: " + graph.getValue(r));\r
 107                     }\r
 108                 }\r
 109             }\r
 110         });\r
 111     }\r
 112 \r
 113 }\r
 114 ~~~\r
 115 \r
 116 ## Debugging\r
 117 \r
 118 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
 119 * **DB**: when the statement is in the persistent graph\r
 120 * **name (W)**: when the statement is in a named workspace-persistent virtual graph\r
 121 * **name (M)**: when the statement is in a named memory-persistent (transient) virtual graph\r
 122 \r
 123 ![Graph debugger example with statements in virtual graphs](Images/GraphDebuggerVG.png)