First test on Simantics documentation using gitbook

[simantics/platform.git] / docs / Developer / Database / ProceduralValues.md

diff --git a/docs/Developer/Database/ProceduralValues.md b/docs/Developer/Database/ProceduralValues.md
new file mode 100644 (file)
index 0000000..ec263df
--- /dev/null
+++ b/docs/Developer/Database/ProceduralValues.md
@@ -0,0 +1,71 @@
+It is possible to define procedural values in the graph and compute their values using graph interface.\r
+\r
+Currently the methods for computing the values are:\r
+* <T> T getRelatedValue2(Resource subject, Resource relation) throws DatabaseException;\r
+* <T> T getPossibleRelatedValue2(Resource subject, Resource relation) throws DatabaseException;\r
+* <T> T getRelatedValue2(Resource subject, Resource relation, Object context) throws DatabaseException;\r
+* <T> T getPossibleRelatedValue2(Resource subject, Resource relation, Object context) throws DatabaseException;\r
+* <T> T getRelatedValue2(Resource subject, Resource relation, Binding binding) throws DatabaseException;\r
+* <T> T getPossibleRelatedValue2(Resource subject, Resource relation, Binding binding) throws DatabaseException;\r
+* <T> T getRelatedValue2(Resource subject, Resource relation, Object context, Binding binding) throws DatabaseException;\r
+* <T> T getPossibleRelatedValue2(Resource subject, Resource relation, Object context, Binding binding) throws DatabaseException;\r
+\r
+These methods work like getRelatedValue and getPossibleRelatedValue -methods. They follow the given relation from the given subject and then determine the value based on the resource found. If the resource is a literal, then they work exactly like getRelatedValue and getPossibleRelatedValue. They however extend the old functionality in two ways:\r
+* If the found resource is an instance of ExternalValue, then the URI of the resource is used to find a value that is declared using extensions and Java annotations.\r
+* If the found resource is an instance of Value, the mechanism first finds the property ConvertsToValueWith of the value and uses it compute the value.\r
+These two mechanisms are detailed below.\r
+\r
+## External values\r
+\r
+External values are resources in the graph with type ExternalValue. They must have URIs. Let's consider for example\r
+ SEL.Functions.inputModifier : L0.ExternalValue\r
+defined in SelectionView -ontology.\r
+\r
+The definitions of the values are declared in the extension point `org.simantics.scl.reflection.binding` like this\r
+\r
+~~~\r
+   <extension point="org.simantics.scl.reflection.binding">\r
+      <namespace path="http://www.simantics.org/SelectionView-0.0/Functions">\r
+         <externalClass className="org.simantics.db.Resource"/>\r
+         <externalClass className="org.simantics.db.ReadGraph"/>\r
+         <externalClass className="org.simantics.db.WriteGraph"/>\r
+         <externalClass className="org.simantics.db.layer0.variable.Variable"/>\r
+         <class className="org.simantics.selectionview.function.All"/>\r
+      </namespace>\r
+   </extension>\r
+~~~\r
+\r
+The value itself is defined as:\r
+~~~\r
+public class All {\r
+  @SCLValue(type = "WriteGraph -> Variable -> a -> b -> String")\r
+  public static String inputModifier(WriteGraph graph, Variable variable, Object value, Object _binding) throws DatabaseException {\r
+    ...\r
+  }\r
+}\r
+~~~\r
+\r
+Any static method or field can be declared an external value with `@SCLValue` annotation. The SCL -type of the value is given as an attribute to the annotation. By default the method name and resource name are matched, but the method name can be overridden in the annotation with name attribute.\r
+\r
+## Contextual values\r
+\r
+External values can be used to define complex constants, in particular functions. Contextual values extend the functionality so that the value may depend on the other properties of the original subject resource that was used for finding the value resource. In some cases, even more needs to be known about the context of the computation than just a resource. Therefore some of the `getRelatedValue2` -methods take a context as a parameter. If it is not given, the default context is the subject resource.\r
+\r
+A contextual value is defined as a resource with type `Value` and properties `ConvertsToValueWith`. For example:\r
+\r
+~~~\r
+ L0.List <T L0.Value\r
+     L0.HasDescription """Represents a list of resources that may contain repetitions."""\r
+     L0.HasValueType "[Resource]"\r
+     @L0.assert L0.ConvertsToValueWith L0.Functions.listResources : L0.ExternalValue  \r
+~~~\r
+\r
+The conversion function must have type\r
+\r
+    ReadGraph => Resource -> Context -> Result\r
+\r
+The second parameter is the resource of the value itself (in this case the linked list) and the context type can be any type. Result type must be the type annotated with `HasValueType`.\r
+\r
+## Value types\r
+\r
+Types of the values must be annotated with relation `HasValueType`. The type is an SCL type in a string format. A relation may require that its range has a certain value type using `RequiresValueType` -property.\r