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