--- /dev/null
+# Introduction
+
+When implementing an editor in Simantics platform, it is very common that the graph representation cannot be directly used, but the editor needs to create an intermediate model of the subgraph it edits. Some reasons for this are:
+* Accessing the database directly is not fast enough.
+* An editor using the database directly holds frequently long read locks and cannot operate during write transactions.
+* The editor needs to store auxiliary objects attached to the model.
+* Editor modifies the intermediate model speculatively before the modification is committed to the database or canceled.
+* The modifications in database cannot be applied in the editor immediately (for example during rendering).
+* Third-party component requires certain classes to be used.
+* Editor needs to be backend-agnostic and cannot directly use database API.
+
+There are two different approaches for implementing the intermediate model:
+1. Triangle model
+
+ The editor modifies the database directly and the changes in the database are eventually propagated to the intermediate model. The editor doesn't change the intermediate model directly.
+
+ 
+
+2. Bidirectional model
+
+ The editor operates only using the intermediate model and modifications are updated from intermediate model to the database and vice versa.
+
+ 
+
+By experience, the triangle model is easier to implement correctly, in particular when resources are linked to each other in complex fashion. The `org.simantics.objmap`-plugin tries to make the implementation of the bidirectional model easier by providing a framework for declaratively defining the update procedure between database and intermediate model. It can also be used with triangle model only for one direction or with hybrid model where some operations are implemented using the intermediate model and others modifying the database directly.
+
+# Design principles
+
+* Symmetric
+ * For every operation from database to Java objects there is a corresponding operation from Java objects to database. This makes the framework easier to learn and undestand.
+* Non-intrusive
+ * The Java objects used with the framework do not need to implement any specific interface or follow some specific naming convention. The mapping schema can be defined using annotations or separately from the class definition.
+* Support for different use scenarios
+ * bidirectional / unidirectional
+ * one shot / continuous
+ * automatic listening / manual updating
+* One-to-one
+ * For every resource there is a single corresponding Java object and vise versa. This makes the framework easier to understand. It is not a transformation framework.
+
+# Concepts
+
+*Mapping* consists of a set of resources called a *domain*, a set of Java objects called a *range* and a collection of *links*. Each link is attached to exactly one domain and range element and each domain and range element has at most one link attached to it. Additionally the link has a *link type* that contains requirements for the domain and range elements in the same link.
+
+
+
+A mapping is *up-to-date* if every domain and range element has a link and all links satisfy the requirements of their link types. The links of up-to-date mapping form a bijection from domain to range.
+
+A *mapping schema* associates all domain and range elements with a link type. It is used to add new domain and range elements to the mapping.
+
+# Mapping interface
+
+The plug-in represents a mapping with interface `org.simantics.objmap.IMapping`. The interface is symmetric in the sense that every operation on the domain of the mapping has also a counterpart that operates on the range. Typically, if one of the operations requires a read graph, its counterpart requires a write graph. We will describe only the methods operating on the domain of the mapping:
+
+ Set<Resource> getDomain();
+
+Returns the domain of the mapping. All set operations are supported. Adding a new domain element does not automatically create a link to it. Removal of a domain element removes also a link and the target element, but does not remove the element from the database.
+
+ Collection<Resource> updateDomain(WriteGraph g) throws MappingException;
+
+Updates all domain elements whose counterpart is modified and creates new domain elements for previously added range elements. Returns the collection of domain elements that were modified or created in the update process.
+
+ Object get(Resource domainElement);
+
+Returns the counterpart of a domain element or null if the element does not belong to the domain or does not have a link.
+
+ Object map(ReadGraph g, Resource domainElement) throws MappingException;
+
+A convenience method that adds a domain element to the mapping and immediately updates the mapping and returns the corresponding range element.
+
+ void domainModified(Resource domainElement);
+
+Tells the mapping that the domain element has been modified.
+
+ boolean isDomainModified();
+
+Tells if some domain elements have been modified or added.
+
+ Collection<Resource> getConflictingDomainElements();
+
+Returns a collection of domain elements which have been modified and also their counterparts in the mapping are modified. These elements are in conflict in the sense that the updating domain and range in different orders may produce different results.
+
+ void addMappingListener(IMappingListener listener);
+ void removeMappingListener(IMappingListener listener);
+
+Adds or removes a listener for domain and range modifications.
+
+# Defining a mapping schema
+
+The primary way for defining a mapping schema is to use Java annotations. The current annotation support is still lacking. Only the following annotations are supported:
+* **GraphType(uri)**
+ * Specifies the domain type that the class corresponds to.
+* **RelatedValue(uri)**
+ * Specifies a correspondence between a field and functional property.
+* **RelatedElement(uri)**
+ * Specifies a correspondence between a field and functional relation
+* **RelatedElements(uri)**
+ * Specifies a correspondence between a field and a relation. The type of the field has to be a collection.
+
+## Example
+
+Suppose we have the following annotated classes:
+
+```java
+@GraphType("http://www.simantics.org/Sysdyn#Configuration")
+static class Configuration {
+ @RelatedElements("http://www.vtt.fi/Simantics/Layer0/1.0/Relations#ConsistsOf")
+ Collection<Component> components;
+}
+
+static abstract class Component {
+}
+
+@GraphType("http://www.simantics.org/Sysdyn#Dependency")
+static class Dependency extends Component {
+ @RelatedElement("http://www.simantics.org/Sysdyn#HasTail")
+ Variable tail;
+ @RelatedElement("http://www.simantics.org/Sysdyn#HasHead")
+ Auxiliary head;
+}
+
+static abstract class Variable extends Component {
+ @RelatedValue("http://www.vtt.fi/Simantics/Layer0/1.0/Relations#HasName")
+ String name;
+}
+
+@GraphType("http://www.simantics.org/Sysdyn#Auxiliary")
+static class Auxiliary extends Variable {
+}
+```
+
+Them the schema can be defined as follows:
+
+```java
+SimpleSchema schema = new SimpleSchema();
+schema.addLinkType(MappingSchemas.fromAnnotations(g, Configuration.class));
+schema.addLinkType(MappingSchemas.fromAnnotations(g, Dependency.class));
+schema.addLinkType(MappingSchemas.fromAnnotations(g, Auxiliary.class));
+```
+
+# Using the mapping interface
+
+Assume that a mapping scheme `scheme` has already been defined and `modelRoot` is the root resource of the model that the editor edits. Then the model is created as follows:
+
+```java
+IMapping mapping = Mappings.create(scheme);
+in read transaction {
+ MyModel model = (MyModel)mapping.map(graph, modelRoot);
+}
+```
+
+There are different ways how the mapping can be updated. The following code forces update for all domain elements.
+
+```java
+in read transaction {
+ for(Resource r : mapping.getDomain())
+ mapping.domainModified(r);
+ mapping.updateRange(graph);
+}
+```
+
+If the range elements have some kind of "dirty" flags, the update can be optimized:
+
+```java
+in write transaction {
+ for(Object obj : mapping.getRange())
+ if(obj implements MyObject && ((MyObject)obj).isDirty())
+ mapping.rangeModified(obj);
+ mapping.updateDomain(graph);
+}
+```
+
+Often the editor has to update some auxiliary structures when the mapping modifies the range. This can be implemented for example as:
+
+```java
+ for(Object obj : mapping.updateRange(graph))
+ if(obj implements MyObject)
+ ((MyObject)obj).updateAuxiliary();
+```
+
+The most convenient way for updating the target would be to add graph request listeners for each domain element in the mapping. This is not yet implemented although the current interface should support this without modifications. Currently the only way to listen the database changes is to listen the request that is used to call the updateRange-method.
\ No newline at end of file
\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
+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
+\r
+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
+ * **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
+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
\r
## Examples\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
+* **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
+
\ No newline at end of file
The Simantics development and maintenance process is built to be solid and scalable from the very beginning. The objective is to aim far to the future what comes to requirements for scalability, usability, and reliability.\r
\r
This Simantics Developer Documentation is targeted to programmers and software developers developing either the platform itself or additional plug-ins to be used with or on the platform. The Simantics End User Documentation complements to documentation for the Simantics platform offering overview and detailed information about the platform from the user's point of view. The [Simantics website](https://www.simantics.org/) is the source of information for the Simantics project and related subjects.\r
+\r
+\r
--- /dev/null
+To avoid typical errors while defining ontology contributions to model browser follow the following check list:
+
+## Step 1: Ontology Plug-in
+
+Define an ontology plugin (`org.mylib.ontology`).
+
+Define dependencies from Simantics plugins in MANIFEST.MF/Dependencies/Required Plug-ins:
+
+```
+org.simantics.layer0
+org.simantics.modeling.ontology
+org.simantics.viewpoint.ontology
+org.simantics.action.ontology
+```
+
+Include the following definitions into your ontology file (*.pgraph):
+
+```
+L0 = <http://www.simantics.org/Layer0-1.1>
+VP = <http://www.simantics.org/Viewpoint-1.2>
+ACT = <http://www.simantics.org/Action-1.1>
+MOD = <http://www.simantics.org/Modeling-1.2>
+```
+
+Define a new library (www.mylib.org) for your ontology under Simantics database root (*http://*):
+
+```
+MY_LIB = <http://www.mylib.org> : L0.Library
+ @L0.new
+```
+
+Define your ontology under the library and specify its ResourceClass:
+
+```
+MY_ONTOLOGY = <http://www.mylib.org/MyOntology-1.0> : L0.Ontology
+ @L0.new
+ L0.HasResourceClass "org.mylib.MyOntologyResource" : L0.String
+```
+
+Check the Name property of ontology plugin in MANIFEST.MF/Overview/General Information. It has to match with URI (without version number) of your ontology.
+
+```
+Name: http://www.mylib.org/MyOntology
+```
+
+Export the package (org.mylib) of ResourceClass in MANIFEST.MF/Runtime/Exported Packages.
+
+Define a new context and include it into MOD.ModelingActionContext
+
+```
+MY_AC = MY_ONTOLOGY.MyActionContext : VP.BrowseContext
+VP.BrowseContext.IsIncludedIn MOD.ModelingActionContext
+```
+
+Define a new ActionContribution for each action in this context
+
+```
+MY_AC
+ VP.BrowseContext.HasActionContribution _ : VP.ActionContribution
+ L0.HasLabel "My action..."
+ VP.ActionContribution.HasAction MY_ONTOLOGY.MyAction : ACT.Action
+ VP.ActionContribution.HasNodeType
+ L0.Entity
+```
+
+## Step 2: Implementation Plug-in
+
+Define a plugin for implementation (org.mylib). Options: Generate an activator=checked, This plug-in will make contributions to the UI=checked.
+
+Define dependencies from Simantics plugins in *MANIFEST.MF/Dependencies/Required Plug-ins*
+
+```
+org.simantics.db.layer0
+```
+
+Define a new package `src/org.mylib.actions`.
+
+Define a new Java class `MyAction.java` under `org.mylib.actions` package
+
+```java
+package org.mylib.actions;
+import org.simantics.db.layer0.adapter.ActionFactory;
+import org.simantics.db.Resource;
+
+public class MyAction implements ActionFactory {
+ @Override
+ public Runnable create(Object target) {
+ if (!(target instanceof Resource))
+ return null;
+ final Resource res = (Resource) target;
+ return new Runnable() {
+ @Override
+ public void run() {
+ // TODO: put your code here
+ }
+ };
+ }
+}
+```
+
+Create a new file (`adapters.xml`, [see spec](../Database/ResourceAdaptation.md)) under implementation plugin to map URI (*unversioned*) of your action to Java class implementation. The content of the file is as follows:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<adapters>
+ <target interface="org.simantics.db.layer0.adapter.ActionFactory">
+ <resource
+ uri="http://www.mylib.org/MyOntology-0.0/MyAction"
+ class="org.mylib.actions.MyAction" />
+ </target>
+</adapters>
+```
+
+You can check correctness of URI by Graph Debugger to search a resource:
+
+```
+http://www.mylib.org/MyOntology-1.0/MyAction
+```
+
+Note! Use *versioned URI* (0.0 -> 1.0) while searching with Graph Debugger.
+
+Include `adapters.xml` into build configuration in *MANIFEST.MF/Build/Binary Build*. Also, include SCL packages and SCL modules if your use them in your implementation.
+
+Export the implementation package (`org.mylib.actions`) of MyAction.java in *MANIFEST.MF/Runtime/Exported Packages*.
+
+## Step 3: Product
+
+Include the ontology and the implementation plug-ins into your product configuration (Debug Configurations/Plug-ins) and validate Plug-ins dependencies before running the product.
\r
## Conversions\r
\r
-Conversion from version 0 to version graph:1. [[File:tg0_tg1.jar]] Usage:\r
+Conversion from version 0 to version graph:1. [tg0_tg1.jar](tg0_tg1.jar) Usage:\r
\r
java -jar tg0_tg1.jar graph input.tg output.tg\r
\r
--- /dev/null
+# Simantics XML-Schema Conversion version 0.1
+
+The bundles that implement this functionality are:
+* org.simantics.xml.sax.base
+* org.simantics.xml.sax
+* org.simantics.xml.sax.feature
+* org.simantics.xml.sax.ontology
+* org.simantics.xml.sax.ui
+
+They are located in the [simantics/interop](https://gitlab.simantics.org/simantics/interop) project.
+
+## Summary
+
+Simantics XML-Schema conversion creates:
+* Simantics ontology as .pgraph file
+* Java classes for SAX based parser
+
+Schema conversion does not support:
+* XML file export
+* Many of the XML schema definitions
+* Group definitions
+* Attribute constraining facets
+
+## Notes
+
+This work was done in PDS Integration project in co-operation with VTT and Fortum. Schema conversion was used for converting Proteus 3.6.0 XML Schema to Simantics ontology. Due to limited scope of the schema, the converter supports only limited part of the XML Schema definitions.
+
+# Ontology definitions based on XML schema concepts
+
+XML Schema conversion creates types and relations based on XML schema concepts that are used in the conversion
+
+| Hard-coded ontology definition | Notes |
+|----------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| hasAttribute <R L0.HasPropertyBase | relation for all element/attribute relations |
+| hasID <R hasAttribute | Base relation for IDs (Attributes with xsd:ID type) |
+| ComplexType <T L0.Entity | Base type for ComplexTypes |
+| hasComplexType <R L0.IsComposedOf | Base relation for containing elements that inherit the specified ComplexType |
+| AttributeGroup <T L0.Entity | Base type for AttributeGroups |
+| Element <T L0.Entity | Base type for Elements |
+| hasElement <R L0.IsComposedOf | Base relation for containing elements |
+| ElementList <T L0.List | Base type for Lists containing Elements (storing the order of the elements) |
+| hasElementList <R L0.IsComposedOf | Base relation for element containing element lists. Used for creating Element type specific lists. |
+| hasOriginalElementList <R hasElementList | Relation for element containing element lists. Stores the order of the all the child elements. |
+| hasReference <R L0.IsRelatedTo | Base relation for object references (converted ID references) |
+| hasExternalReference <R L0.IsWeaklyRelatedTo | Relation for references between data imported from different files. Note: external references must be created with post process functions, since schema conversion itself is not able to resolve references between different imports. |
+
+# Datatypes
+
+XML uses three types of attributes, Atomic, List, and Union. Current XML Schema conversion support only Atomic attributes.
+
+| XML datatype | Simantics | Notes |
+|--------------|---------------|-------|
+| Atomic | Supported | |
+| List | Not Supported | |
+| Union | Not supported | |
+
+Primitive attributes are converted to Layer0 literals. List of primitive datatypes and respective literal types is:
+
+| XML datatype | Simantics | Notes |
+|--------------|------------|-------|
+| string | L0.String | |
+| boolean | L0.Boolean | |
+| decimal | L0.Double | |
+| float | L0.Float | |
+| double | L0.Double | |
+| duration | | |
+| dateTime | | |
+| time | L0.String | |
+| date | L0.String | |
+| gYearMonth | | |
+| gYear | | |
+| gMonthDay | | |
+| gDay | | |
+| gMonth | | |
+| hexBinary | | |
+| base64Binary | | |
+| anyUri | L0.Uri | |
+| QName | | |
+| NOTATION | | |
+
+Other built-in datatypes are converted to Layer0 literal types as well:
+
+| XML datatype | Simantics | Notes |
+|--------------------|------------|----------------------------------------------------------------------------------------------------------------|
+| normalizedString | L0.String | |
+| token | L0.String | |
+| language | | |
+| NMTOKEN | L0.String | |
+| Name | | |
+| NCName | | |
+| ID | L0.String | ID attributes use XML.hasID property relation. An element is expected to have only one attribute with ID type. |
+| IDREF | L0.String | |
+| IDREFS | | |
+| ENTITY | | |
+| ENTITIES | | |
+| integer | L0.Integer | |
+| nonPositiveInteger | L0.Integer | |
+| negativeInteger | L0.Integer | |
+| long | L0.Long | |
+| int | L0.Integer | |
+| short | L0.Integer | |
+| byte | L0.Byte | |
+| nonNegativeInteger | L0.Integer | |
+| unsignedLong | L0.Long | |
+| unsignedShort | L0.Integer | |
+| unsignedByte | L0.Byte | |
+| positiveInteger | L0.Integer | |
+| yearMonthDuration | | |
+| dayTimeDuration | | |
+| dateTimeStamp | | |
+
+XML schema allows defining new attribute types with constraining facets. Constraining facets are not currently supported.
+
+| XML Constraining facets | Simantics | Notes |
+|-------------------------|-----------|-------|
+| length | | |
+| minLength | | |
+| maxLength | | |
+| pattern | | |
+| enumeration | | |
+| whitespace | | |
+| maxInclusive | | |
+| maxExclusive | | |
+| minInclusive | | |
+| minExclusive | | |
+| totalDigits | | |
+| fractionDigits | | |
+| Assertions | | |
+| explicitTimeZone | | |
+
+In addition, individual attributes can be converted to a single array with Attribute Composition rule. Supported array datatypes are:
+
+| Conversion configuration | Simantics |
+|---------------------------|----------------|
+| doubleArray | L0.DoubleArray |
+| stringArray | L0.StringArray |
+
+# Structures
+
+## Type definitions
+
+### SimpleType
+
+XML schema allows SimpleTypes to be used as Element types for elements without child elements or as attribute types.
+
+When simpleType is used as attributes, the type will be converted to functional property relation:
+
+```xml
+<xsd:simpleType name="LengthUnitsType">
+ <xsd:restriction base="xsd:NMTOKEN">
+ <xsd:enumeration value="mm"/>
+ \85
+ </xsd:restriction>
+</xsd:simpleType>
+
+<xsd:element name="UnitsOfMeasure">
+ <xsd:annotation>
+ <xsd:documentation>These are from \85</xsd:documentation>
+ </xsd:annotation>
+ <xsd:complexType>
+ <xsd:attribute name="Distance" type="LengthUnitsType" default="Millimetre">
+ </xsd:attribute>
+```
+
+```
+PRO.hasLengthUnitsType <R PRO.XML.hasAttribute : L0.FunctionalRelation
+ --> L0.String
+
+PRO.hasUnitsOfMeasure <R PRO.XML.hasElement
+PRO.hasUnitsOfMeasureList <R PRO.XML.hasElementList
+PRO.UnitsOfMeasure <T PRO.XML.Element
+PRO.UnitsOfMeasure.hasDistance <R PRO.XML.hasAttribute: L0.FunctionalRelation
+ <R PRO.hasLengthUnitsType
+```
+
+When simpleType is used as definition of Element, the definition is converted to inheritance from the base literal type. In the following example, Knot elements xsd:double base is converted to inheritance to L0.Double:
+
+```xml
+<xsd:element name="Knot" maxOccurs="unbounded">
+ <xsd:simpleType>
+ <xsd:restriction base="xsd:double">
+ <xsd:minInclusive value="0.0"/>
+ </xsd:restriction>
+ </xsd:simpleType>
+</xsd:element>
+```
+
+```
+PRO.ComplexTypes.hasKnots.Knot <R PRO.XML.hasElement
+PRO.ComplexTypes.hasKnots.KnotList <R PRO.XML.hasElementList
+PRO.ComplexTypes.Knots.Knot <T PRO.XML.Element <T L0.Double
+```
+
+### ComplexType
+
+Schema conversion creates hard-coded ComplexType entity as a base type for ComplexTypes.
+
+```
+PRO.XML.ComplexType <T L0.Entity
+```
+
+ComplexTypes that are defined in the input schema are converted to L0.Entities, which inherit the hard-coded ComplexType, and are put into \93ComplexTypes\94 library. Conversion also generates ComplexType specific generic relation for composition, and another relation for lists.
+
+Particles of a ComplexType are converted to ComplexType and particle specific relations inheriting the particle type related relation. Also, Attributes of the ComplexType are converted to the ComplexType and Attribute specific relations.
+
+For example, ComplexType \93PlantItem\94 is converted to \93ComplexTypes.PlantItem\94 entity, it has a \93ComplexTypes.hasPlantItem\94 composition relation, and \93ComplexTypes.hasPlantItemList\94 relation for lists. \93ID\94 attribute is converted to \93ComplexTypes.PlantItem.hasID\94 functional relation, and choice particle \93Presentation\94 is converted to \93ComplexTypes.PlantItem.hasPresentation\94 relation.
+
+```xml
+<xsd:complexType name="PlantItem">
+ <xsd:choice minOccurs="0" maxOccurs="unbounded">
+ <xsd:element ref="Presentation"/>
+ <xsd:element ref="Extent"/>
+ \85
+ <xsd:element name="ModelNumber" type="xsd:string"/>
+ \85
+ </xsd:choice>
+ <xsd:attribute name="ID" type="xsd:ID" use="required"/>
+ <xsd:attribute name="TagName" type="xsd:string"/>
+ \85
+ <xsd:attribute name="ComponentType">
+ <xsd:simpleType>
+ <xsd:restriction base="xsd:NMTOKEN">
+ <xsd:enumeration value="Normal"/>
+ <xsd:enumeration value="Explicit"/>
+ <xsd:enumeration value="Parametric"/>
+ </xsd:restriction>
+ </xsd:simpleType>
+ </xsd:attribute>
+ \85
+</xsd:complexType>
+```
+
+```
+PRO.ComplexTypes.PlantItem <T PRO.XML.ComplexType
+PRO.ComplexTypes.hasPlantItem <R PRO.XML.hasComplexType
+PRO.ComplexTypes.hasPlantItemList <R PRO.XML.hasElementList
+ --> PRO.ComplexTypes.PlantItem
+PRO.ComplexTypes.PlantItem.hasPresentation <R PRO.hasPresentation
+ --> PRO.Presentation
+PRO.ComplexTypes.PlantItem.hasExtent <R PRO.hasExtent
+ --> PRO.Extent
+\85
+PRO.ComplexTypes.PlantItem.hasID <R PRO.XML.hasAttribute: L0.FunctionalRelation
+ --> L0.String
+\85
+PRO.ComplexTypes.PlantItem.hasComponentType <R PRO.XML.hasAttribute: L0.FunctionalRelation
+ --> L0.String
+```
+
+## Element
+
+Element definitions are processed similarly to ComplexTypes, but the converted types are put directly into the ontology without any library. Hence, Element \93PlantModel\94 is converted to \93PlantModel\94 entity.
+
+```xml
+<xsd:element name="PlantModel">
+ <xsd:complexType>
+ <xsd:sequence>
+ <xsd:element ref="PlantInformation"/>
+ <xsd:element ref="Extent"/>
+ <xsd:any namespace="##targetNamespace" maxOccurs="unbounded"/>
+ </xsd:sequence>
+ </xsd:complexType>
+</xsd:element>
+```
+
+```
+PRO.hasPlantModel <R PRO.XML.hasElement
+PRO.hasPlantModelList <R PRO.XML.hasElementList
+PRO.PlantModel <T PRO.XML.Element
+PRO.PlantModel.hasPlantInformation <R PRO.hasPlantInformation
+ --> PRO.PlantInformation
+PRO.PlantModel.hasExtent <R PRO.hasExtent
+ --> PRO.Extent
+```
+
+When Element definition is defined with ComplexContent, ComplexContent\92s extension\92s base is converted to L0.Inheritance relation between the types. For example \93Equpiment\94 Element has \93PlantItem\94 as a base extension, so \93Equipment\94 entity is inherited from \93PlantItem\94 entity.
+
+```xml
+<xsd:element name="Equipment">
+ <xsd:complexType>
+ <xsd:complexContent>
+ <xsd:extension base="PlantItem">
+ <xsd:choice minOccurs="0" maxOccurs="unbounded">
+ <xsd:element ref="Discipline" minOccurs="0"/>
+ <xsd:element ref="MinimumDesignPressure"/>
+ \85
+ <xsd:element ref="Equipment"/>
+ \85
+ </xsd:choice>
+ <xsd:attribute name="ProcessArea" type="xsd:string"/>
+ <xsd:attribute name="Purpose" type="xsd:string"/>
+ </xsd:extension>
+ </xsd:complexContent>
+ </xsd:complexType>
+</xsd:element>
+```
+
+```
+PRO.hasEquipment <R PRO.XML.hasElement
+PRO.hasEquipmentList <R PRO.XML.hasElementList
+PRO.Equipment <T PRO.XML.Element <T PRO.PlantItem
+PRO.Equipment.hasProcessArea <R PRO.XML.hasAttribute: L0.FunctionalRelation
+ --> L0.String
+PRO.Equipment.hasPurpose <R PRO.XML.hasAttribute: L0.FunctionalRelation
+ --> L0.String
+PRO.Equipment.hasDiscipline <R PRO.hasDiscipline
+ --> PRO.Discipline
+PRO.Equipment.hasMinimumDesignPressure <R PRO.hasMinimumDesignPressure
+ --> PRO.MinimumDesignPressure
+\85
+PRO.Equipment.hasEquipment <R PRO.hasEquipment
+ --> PRO.Equipment
+\85
+```
+
+## Indicators (choice, sequence, all)
+
+When Indicators have maxOccurs larger than 1, relations generated according to particles have no multiplicity restrictions (ass all previous examples are defined). When indicator is choice with maxOccurs=1 (default value for maxOccurs), the particle relations is expected to refer to only one object that conforms to one of the specified types.
+
+For example, Element \93TrimmedCurve\94 has choice indicator with 4 elements (\93Circle\94, \93PCircle\94, \93Ellipse\94, \93PEllipse), and that choice is converted to \93TrimmedCurve.hasCircleOrPCircleOrEllipseOrPEllipse\94 relation.
+
+```xml
+<xsd:element name="TrimmedCurve" substitutionGroup="Curve">
+ <xsd:complexType>
+ <xsd:complexContent>
+ <xsd:extension base="Curve">
+ <xsd:sequence>
+ <xsd:choice>
+ <xsd:element ref="Circle"/>
+ <xsd:element ref="PCircle"/>
+ <xsd:element ref="Ellipse"/>
+ <xsd:element ref="PEllipse"/>
+ </xsd:choice>
+ <xsd:element ref="GenericAttributes" minOccurs="0"/>
+ </xsd:sequence>
+ <xsd:attribute name="StartAngle" type="xsd:double" use="required"/>
+ <xsd:attribute name="EndAngle" type="xsd:double" use="required"/>
+ </xsd:extension>
+ </xsd:complexContent>
+ </xsd:complexType>
+</xsd:element>
+```
+
+```
+PRO.hasTrimmedCurve <R PRO.XML.hasElement
+PRO.hasTrimmedCurveList <R PRO.XML.hasElementList
+PRO.TrimmedCurve <T PRO.XML.Element <T PRO.Curve
+PRO.TrimmedCurve.hasStartAngle <R PRO.XML.hasAttribute: L0.FunctionalRelation
+ --> L0.Double
+PRO.TrimmedCurve.hasEndAngle <R PRO.XML.hasAttribute: L0.FunctionalRelation
+ --> L0.Double
+PRO.TrimmedCurve.hasCircleOrPCircleOrEllipseOrPEllipse <R PRO.hasCircle <R PRO.hasPCircle <R PRO.hasEllipse <R PRO.hasPEllipse
+ --> PRO.Circle
+ --> PRO.PCircle
+ --> PRO.Ellipse
+ --> PRO.PEllipse
+PRO.TrimmedCurve.hasGenericAttributes <R PRO.hasGenericAttributes
+ --> PRO.GenericAttributes
+```
+
+Note that Model Group definitions are not currently supported!
+
+# Customization via configuration
+
+## Attribute composition
+
+Attribute composition rule allows converting separate attributes into one array. For example, following rule:
+
+```xml
+<AttributeComposition Name="XYZ" Type = "doubleArray">
+ <Attribute Name="X" Type ="double"/>
+ <Attribute Name="Y" Type ="double"/>
+ <Attribute Name="Z" Type ="double"/>
+</AttributeComposition>
+</source>
+causes \93X\94, \93Y\94 and \93Z\94 double attributes in \93Coordinate\94 Element definition
+<source lang="xml">
+<xsd:element name="Coordinate">
+ <xsd:complexType>
+ <xsd:attribute name="X" type="xsd:double" use="required"/>
+ <xsd:attribute name="Y" type="xsd:double" use="required"/>
+ <xsd:attribute name="Z" type="xsd:double"/>
+ </xsd:complexType>
+</xsd:element>
+```
+
+to be converted to \93XYZ\94 double array:
+
+```
+PRO.Coordinate <T PRO.XML.Element
+PRO.Coordinate.hasXYZ <R PRO.XML.hasAttribute: L0.FunctionalRelation
+ --> L0.DoubleArray
+```
+
+## ID references
+
+Referencing other XML elements is usually done using element IDs. Using ID Provider and ID Reference rules allows converting these references to statements in Simantics DB.
+ID Provider rule is used for retrieving the ID from referred objects. The rule does not affect the generated ontology.
+
+```xml
+<IDProvider>
+ <ComplexType Name = "PlantItem"/>
+ <Attribute Name="ID" Type ="string"/>
+</IDProvider>
+```
+
+ID Reference rule is used for objects that use ID references. ID Source tells which attribute is used to refer another Element, and Reference defines the name of the relation. With the following rule:
+
+```xml
+<IDReference>
+ <Element Name ="Connection"/>
+ <IDSource Name="ToID" Type ="string"/>
+ <Reference Name="ToIDRef" Type ="ref"/>
+</IDReference>
+```
+
+\93Connection\94 element definition\92s \93ToID\94 reference is converted to ToIDRef relation.
+
+```xml
+<xsd:element name="Connection">
+ <xsd:complexType>
+ <xsd:attribute name="ToID" type="xsd:string"/>
+ \85
+ </xsd:complexType>
+</xsd:element>
+```
+
+The original attribute is kept, so that if ID reference cannot be located, the information about the reference still exists.
+
+```
+PRO.Connection <T PRO.XML.Element
+PRO.Connection.hasToID <R PRO.XML.hasAttribute: L0.FunctionalRelation
+ --> L0.String
+PRO.Connection.ToIDRef <R PRO.XML.hasReference
+```
+
+In imported data, the reference statement will point to referred Element, if the parser is able to locate a Element with the given ID.
+
+| Predicate | Object | Graph |
+|-----------------------|----------------------------------|-------|
+| Basic information | | |
+| InstanceOf | Connection | DB |
+| Is Related To | | |
+| hasToID | V_02_N6 (edit) | DB |
+| ToIDRef | $412442 : (Nozzle) | DB |
+| Other statements | | |
+| hasConnection/Inverse | $416145 : (PipingNetworkSegment) | DB |
+
+## Ordered child
+
+Ordered child rule allows storing the original order of the elements into lists. The rules either force the creating of the lists (used when the schema is interpreted to be indifferent of the order), or disabling the list generation.
+
+Currently the rule hat two types, original and child. An original type rule sets if all the child elements are out into \93OriginalElementList\94. An child rule sets if the child elements are added to type specific lists.
+
+```xml
+<OrderedChild Type="original" Value="disable">
+ <ComplexType Name = "PlantItem"/>
+</OrderedChild>
+
+<OrderedChild Type="child" Value="disable">
+ <ComplexType Name = "PlantItem"/>
+</OrderedChild>
+```
+
+## Unrecognized child elements
+
+Unrecognized child element rule allows processing XML files that do not conform to given schema, and use different element names. In practice, the rule allows injecting Java code to generated parser classes. The code is put into method, which signature is:
+
+```java
+public void configureChild(WriteGraph graph, Deque<Element> parents, Element element, Element child) throws DatabaseException
+```
+
+The method is called with \94element\94 as the element, which conforms to given type in the rule\92s configuration, and \94child\94 is the child element, that could not be recognized. The following example is used for handling incorrect files, which have replaced element name with the contents of attribute \93name\94.
+
+```xml
+<UnrecognizedChildElement>
+ <Element Name ="GenericAttributes"/>
+ <JavaMethod>
+ // Some commercial software do not handle GenericAttribute elements properly:
+ // they use "Name" attribute's value as element's name.
+ GenericAttribute ga = new GenericAttribute();
+ java.util.List<Attribute> attributes = new java.util.ArrayList<Attribute>();
+ attributes.addAll(child.getAttributes());
+ attributes.add(new Attribute("Name", "Name", "", child.getQName()));
+ Element newChild = new Element("", "", "GenericAttribute", attributes);
+ newChild.setParser(ga);
+ Resource res = ga.create(graph, newChild);
+ if (res != null) {
+ newChild.setData(res);
+ parents.push(element);
+ ga.configure(graph, parents, newChild);
+ connectChild(graph, element, newChild);
+ parents.pop();
+ }
+ </JavaMethod>
+</UnrecognizedChildElement>
+```
+
+An example of incorrect file:
+
+```xml
+<GenericAttributes Number="28" Set="Values">
+ <Assembly Format="string" Value="5. Auxiliary Steam System" />
+ <Bendingradiusrtube Format="double" Value="0" Units="mm" ComosUnits="mm M01.15" />
+ <CostCode Format="double" Value="607" />
+```
+
+When the content should be:
+
+```xml
+<GenericAttributes Number="28" Set="Values">
+ <GenericAttribute Name="Assembly" Format="string" Value="5. Auxiliary Steam System" />
+ <GenericAttribute Name="Bendingradiusrtube" Format="double" Value="0" Units="mm\93 />
+ <GenericAttribute Name="CostCode" Format="double" Value="607" />
+```
+
+# References
+
+* W3C XML Schema definition language (XSD) 1.1 Part 1: Structures http://www.w3.org/TR/xmlschema11-1/
+* W3C XML Schema definition language (XSD) 1.1 Part 2: Datatypes http://www.w3.org/TR/xmlschema11-2/
+* [Layer0 specification](Layer0.pdf)
--- /dev/null
+## Simulation Software
+
+* [Apros](http://www.apros.fi/): A system modelling and simulation software for mainly process dynamics simulation; commercial.
+* [Balas](https://info.vttresearch.com/balas): A system modelling and simulation software for mainly process steady state simulation; commercial.
+* [Elmer](https://www.csc.fi/web/elmer): A finite element method (FEM) based multiphysics modelling and simulation software; open source (GPL).
+* [OpenModelica](https://www.openmodelica.org/): A generic system modelling and simulation software based on Modelica modelling language; open source (strict GPL).
+* [OpenFOAM](https://www.openfoam.com/): A fully featured, generic control volume based computational fluid dynamics (CFD) software; open source (GPL).
+* [Code_Aster](https://www.code-aster.org/V2/spip.php?rubrique2): A finite element method (FEM) based structural analysis modelling and simulation software; open source (GPL).
+* [Code_Saturne](https://www.code-saturne.org/cms/): A control volume method (CVM) based computational fluid dynamics (CFD) software; open source (GPL).
+* [Octave](http://www.gnu.org/software/octave/): a high-level language, primarily intended for numerical computations, mostly compatible with Matlab; open source (GPL).
+* [Scilab](https://www.scilab.org/): A scientific software package for numerical computations; open source (CeCILL, <u>Ce</u>a <u>C</u>nrs <u>I</u>nria <u>L</u>ogiciel <u>L</u>ibre).
+
+## Pre-Processing and Mesh Generation
+
+* [SALOME](https://www.salome-platform.org/): A free software that provides a generic platform for Pre and Post-Processing for numerical simulation. It is based on an open and flexible architecture made of reusable components available as free software; open source (LGPL).
+* [Gmsh](http://gmsh.info/): An automatic 3D finite element grid generator with a built-in CAD engine and post-processor; open source (GPL).
+* [Netgen](https://ngsolve.org/): an automatic 3d tetrahedral mesh generator; open source (LGPL)
+* [TetGen](https://www.berlios.de/software/tetgen/): a program to generate tetrahedral meshes of any 3D polyhedral domain; free for research and non-commercial uses, for any commercial use a commercial license is required.
+
+## Scientific Visualisation Software
+
+* [Paraview](https://www.paraview.org/): A multi-platform data analysis and visualization application based on VTK visualisation library; open source (ParaView License Version 1.2).
+* [VisIt](https://wci.llnl.gov/codes/visit/): A multi-platform data analysis and visualization application based on VTK visualisation library; open source (BSD license).
+
+## Eclipse Related
+
+* [Eclipse.org](http://www.eclipse.org/): Eclipse project home page.
+* [Eclipse Corner Articles](http://www.eclipse.org/articles/): An archive of eclipse development tutorials.
+* [A Comparison of Eclipse Extensions and OSGi Services](http://eclipse.dzone.com/articles/comparison-eclipse-extensions-and-osgi-services)
+* Eclipse [SWT](http://www.eclipse.org/swt) widgets:
+ * [Eclipse SWT FAQ](http://www.eclipse.org/swt/faq.php)
+ * [SWT Snippets](http://www.eclipse.org/swt/snippets)
+ * [Highly recommended examples for getting to know how SWT works](https://git.eclipse.org/c/platform/eclipse.platform.swt.git/tree/examples)
+* JFace:
+ * [JFace Wiki](http://wiki.eclipse.org/index.php/JFace)
+ * [JFace Snippets](http://wiki.eclipse.org/JFaceSnippets)
+
+* [Eclipsepedia](http://wiki.eclipse.org/index.php/Main_Page), Eclipse's own Wiki. Also check out the [Eclipsepedia FAQ's](http://wiki.eclipse.org/index.php/Main_Page#Frequently_Asked_Questions)
+
+* Eclipse conferences:
+ * [EclipseCon 2007](http://www.eclipsecon.org/2007/)
+ * [Contributing to Menus with the new API](http://www.eclipsecon.org/2007/index.php?page=sub/&id=3692)
+ * [EclipseCon 2008](http://www.eclipsecon.org/2008/)
+ * [Contributing to Menus](http://www.eclipsecon.org/2008/sub/attachments/Using_Commands_and_Menu_Contributions.ppt)
+
+* Eclipse articles:
+ * [Workbench Selections](http://www.eclipse.org/articles/Article-WorkbenchSelections/article.html)
+ * [Eclipse Jobs API](http://www.eclipse.org/articles/Article-Concurrency/jobs-api.html)
+
+* OSGi articles:
+ * [OSGi and classpath](http://blog.springsource.com/2009/01/19/exposing-the-boot-classpath-in-osgi/)
+
+## Graphics and Geometry Related
+
+* [W3C SVG](http://www.w3.org/Graphics/SVG/)
+* [Batik SVG Toolkit](http://xmlgraphics.apache.org/batik/)
+* [jMonkey Engine](http://www.jmonkeyengine.com/)
+* [Open CASCADE](http://www.opencascade.org/)
+* [VTK](https://vtk.org/)
+* [Silk icon collection](http://www.famfamfam.com/lab/icons/silk/)
--- /dev/null
+# SCL Compiler
+
+## Release notes
+
+### 0.4
+
+* Documentation browser
+* Type checking reimplemented
+ * Properly implemented subsumption solver
+* Improvements in pattern matching
+ * [http://zvon.org/other/haskell/Outputsyntax/As-patterns_reference.html As-patterns]
+ * List pattern matching
+* [http://www.haskell.org/haskellwiki/Section_of_an_infix_operator Sections]
+* Refactoring Prelude
+ * Support for native arrays (Vector type)
+ * Refactored Show class to use StringBuilder
+ * Renamed map -> fmap, mapE -> map
+* Improvements in optimizer
+ * [http://www.haskell.org/haskellwiki/Short_cut_fusion Short-cut fusion]
+ * Bugfixes leading to much more efficient code in some cases
+* Automatic conversion from java method returning a Collection to List
+* Compilation environment parameter that is passed to source loaders
+* Fixing code generation related to Maybe type
+* More unit tests
+* Misc. bugfixes
+
+### 0.3
+
+There was no official release, but the version used in the first SCL training 14.5.2013 is considered 0.3.
--- /dev/null
+## Eight queens puzzle
+
+Copy the following commands to the SCL console:
+
+```haskell
+> n = 8
+> allPositions = [0..n-1]
+> possibleNextPositions l = allPositions \\ (l + lq + uq)
+ where
+ m = length l
+ lq = [l!i - (m-i) | i <- [0..m-1]]
+ uq = [l!i + (m-i) | i <- [0..m-1]]
+> expandSolution l = do
+ x <- possibleNextPositions l
+ return (l + [x])
+> solve k cur = if k == n
+ then return cur
+ else expandSolution cur >>= solve (k+1)
+> solutions = solve 0 []
+> length solutions
+> repeatString k (s :: String) = sum [s | x <- [1..k]]
+> rowText k = repeatString k "." + "X" + repeatString (n-k-1) "."
+> printSolution (l :: [Integer]) = do
+ printString (repeatString n "-")
+ mapM (printString . rowText) l
+> mapM printSolution solutions
+```
\ No newline at end of file
--- /dev/null
+This page documents a mechanism for finding and contributing SCL types and values in Simantics platform. All interfaces and classes mentioned are defined in the plugins `org.simantics.scl.reflection` or `org.simantics.scl.runtime`.
+
+Both types and values are identified by URIs. The last part of the URI is the *name* of the type or value and the prefix before the name is the *namespace*.
+
+## Types
+
+### Grammar and representation
+
+SCL types are written according to the following grammar:
+
+```
+t ::= C // Type constructor
+ | a // Type variable
+ | t1 t2 // Type application
+ | forall a. t // Universal quantification
+ | P t1 ... tn => t // Qualified type
+```
+
+Type constructor is either one capitalized identifier or concatenation of multiple identifiers with period (`.`). In the former case, the last identifier does not have to be capitalized. Type variable is always a one identifier that is not capitalized.
+
+Types are represented in Java using the following subtypes of <code>Type</code> (org.simantics.scl.types)
+
+```
+TCon(String module, String name)
+TVar()
+TApply(Type function, Type parameter)
+TForAll(TVar var, Type type)
+TPred(TFuncApply predicate, Type type)
+```
+
+Some type constructors have special syntax:
+
+```
+a -> b = TApply(TApply(TCon(Types.BUILTIN, "->"), a), b)
+[a] = TApply(TCon(Types.BUILTIN, "[]"), a)
+() = TCon(Types.BUILTIN, "()")
+(a,b) = TApply(TApply(TCon(Types.BUILTIN, "(,)"), a), b)
+(a,b,c) = TApply(TApply(TApply(TCon(Types.BUILTIN, "(,,)"), a), b), c)
+...
+```
+
+A type is converted from a String to Type using Types.parseType.
+
+### Converting types to classes
+
+In order to get a Java class from a type, `TypeBindingScheme` (`org.simantics.scl.reflection`) is needed. It describes which Java class each type constructor corresponds to. With a scheme `s` types are converted to classes with the following rules implemented in `ReflectionUtils.getClass`
+
+```
+c(C) --> s(C)
+c(a) --> Object
+c(t1 t2) --> c(t1)
+c(forall a.t) --> c(t)
+c(P t1 ... tn => t) --> Function
+```
+
+A singleton `MinimalTypeBindingScheme` implements `TypeBindingScheme` that uses extensions to find bindings from type constructors to classes. It must be extended elsewhere in order to get for example the types defined in the database.
+
+The following bindings are defined even when no extensions are defined:
+
+```
+(->) --> Function
+[] --> List
+() --> Tuple0
+(,) --> Tuple2
+(,,) --> Tuple3
+...
+Boolean --> Boolean
+Byte --> Byte
+...
+Long --> Long
+String --> String
+```
+
+## Values
+
+The type conversion rules in the previous section already dictate the Java class of the values of a certain SCL type. Depending on the type constructor, there are additional constraints. For example, values of type `[a]` must implement interface `java.util.List` and additionally elements of the list must be compatible with `a`. Values of type `a -> b` must implement the interface `Function` and additionally when method `appl` is called with a parameter compatible with type `a` the method must return a value compatible with type `b`.
+
+### Finding values
+
+Values are found using `ReflectionUtils.getValue`. The method requires the URI of the value. This method does not cache the values.
+
+## Contributing types and values
+
+Type are contributed putting SCLType-annotations to classes and values with `@SCLValue`-annotations on fields, constructors and methods. Both annotations have an optional name-attribute, which can be used to override the default name that is the name of the class or method annotated. SCLValue -annotation has also a required type-annotation where the SCL type of the value must be declared.
+
+In addition, classes containing these annotations must be declared using the extension point `org.simantics.scl.reflection.binding`. It has the following elements
+
+* **namespace**
+ * **attributes**: path
+ * **possible children**: class, namespace, externalClass, externalMethod, import
+ Represents a library or type in semantic graph. If the element is the root of the extension,
+path is an absolute uri of the resource. Otherwise it is relative path from its parent element.
+* **class**
+ * **attributes**: className
+ Declares a Java class to be searched for annotations.
+* **import**
+ * **attributes**: path, localName (optional)
+ Gives a path a localName that can be used to refer it in type declarations.
+* **externalClass**
+ * **attributes**: className, alternativeName (optional)
+ Contributes a class without annotations.
+* **externalMethod**
+ * **attributes**: className, methodName, alternativeName (optional)<br/>
+ Contributes a method without annotations.
--- /dev/null
+## Getting started
+
+The easiest way of getting started with SCL is to use SCL console that is included in almost all Simantics-based products. You can open the console by pressing ALT-SHIFT-q and then q and choosing "SCL Console" from the list of views.
+
+SCL console works by executing commands you write into the input box in the bottom of the view. After the command has been written, it can be executed by pressing ENTER. However, this works only if the command contains no syntactic errors. Possible errors are highlighted in the input box and a description of the error is shown when you move mouse on top of the highlighted text.
+
+Multiline commands can be written by pressing CTRL-ENTER (or just ENTER when the current command text contains errors). The command history can be browsed with CTRL-UP and CTRL-DOWN.
+
+If the command you write into console results as an ordinary value, it is just printed to the console. Here are couple of examples you can try:
+
+```
+> 13
+13
+> 1+2
+3
+> sin 1
+0.8414709848078965
+> "Hello " + "world!"
+Hello world!
+> [1,3,5]
+[1, 3, 5]
+```
+
+You can also declare local variables to be used in the commands:
+
+```
+> x = 35
+> y = 40
+> x + y
+75
+> x * y
+1400
+```
+
+Also new functions can be defined:
+```
+> f x = x * x
+> f 123
+15129
+```
+
+If you write a command that has side-effects, it is executed in the console:
+
+```
+> print "Hello" ; print "world!"
+Hello
+world!
+```
+
+SCL is a dialect of Haskell and tutorials written for Haskell can be used for learning the details of the language. The main differences between the languages are the strict evaluation strategy used in SCL and somewhat different standard library. Some Haskell tutorials can be found at [https://wiki.haskell.org/Learning_Haskell](https://wiki.haskell.org/Learning_Haskell).
+
+## Extending SCL environment
+
+The SCL values, data types etc. that are available in expressions and commands are defined in SCL modules. Currently all SCL modules must be part of the product plugins (in the future, you can also write modules inside the models). Each module is identified by a URI.
+
+SCL module is a text file ending with extension ".scl". The recommended place for modules is scl/ folder under plugin root, but also other directories can be used:
+
+**scl/Test1.scl**:
+
+```
+fib :: Integer -> Integer
+fib x | x <= 1 = 1
+ | otherwise = fib (x-1) + fib (x-2)
+```
+
+A directory is declared as a SCL package with the following kind of extension points defined in org.simantics.scl.runtime:
+
+```
+ <extension point="org.simantics.scl.runtime.package">
+ <package URI="http://www.simantics.org/Tests"
+ directory="scl"/>
+ </extension>
+```
+
+The module is not automatically available in the console, but you must run an import declaration:
+
+```
+> import "http://www.simantics.org/Tests/Test1" as Test1
+> Test1.fib 13
+377
+```
+
+Import declaration can also be used in modules to refer other modules. Cyclic module dependencies are not allowed.
+
+## Importing functionality from Java
+
+Java interfaces and classes can be imported from Java by declaring them inside importJava block:
+
+```
+importJava "java.util.regex.Pattern" where
+ data Pattern
+
+importJava "java.util.List" where
+ data List a
+```
+
+Java methods, constructors and fields can be similarly imported by giving
+their type annotations in importJava block:
+
+```
+importJava "java.util.regex.Pattern" where
+ @JavaName compile
+ compilePattern :: String -> Pattern
+
+ @JavaName matcher
+ createMatcher :: Pattern -> String -> <Proc> Matcher
+
+importJava "java.util.regex.Matcher" where
+ data Matcher
+
+ @JavaName matches
+ matcherMatches :: Matcher -> <Proc> Boolean
+
+matches : Pattern -> String -> <Proc> Boolean
+matches pattern text = do
+ matcherMatches (createMatcher pattern text)
+```
+
+Another example:
+
+```
+importJava "java.util.ArrayList" where
+ @JavaName "<init>"
+ createArrayList :: () -> <Proc> List a
+
+ @JavaName "<init>"
+ createArrayListWithCapacity :: Integer -> <Proc> List a
+
+ @JavaName size
+ sizeList :: List a -> <Proc> Integer
+
+ @JavaName get
+ getList :: List a -> Integer -> <Proc> a
+
+ @JavaName set
+ setList :: List a -> Integer -> a -> <Proc> ()
+
+ @JavaName add
+ addList :: List a -> a -> <Proc> Boolean
+```
+
+Java constructor is referred with `<init>`. If Java method name and SCL name matches the annotation @JavaName can be left out. Java import mechanism tries to be quite flexible. It provides some arguments based on the effects the function has. It also ignores the return value of the Java method if return type is `()` in SCL.
+
+A major functionality currently still missing is the ability to create new implementations of existing Java interfaces in SCL code or extend an existing class. This can be worked around currently by writing new implementations in Java.
--- /dev/null
+## Basic types
+
+SCL is statically typed language which means that types of the possible values of all variables are known already at compile time. The following types (or more exactly, type constructors) have builtin support:
+* Boolean
+* Byte, Short, Integer, Long
+* Float, Double
+* String
+* BooleanArray, ByteArray, ShortArray, IntegerArray, LongArray, FloatArray, DoubleArray
+* []
+* (), (,), (,,), ...
+* (->)
+* Maybe
+* Array
+
+Other type constructors are either imported from the host language or defined in SCL modules. Except for the couple of special cases in the previous list, the names of all type constructors are capitalized.
+
+Some type constructors are parametric (compare to generics in Java or templates in C++). For example, the list type constructor `[]` has one parameter: the type of the list elements. Thus `[Integer]` is the type of the integer lists and `[String]` is the type of string lists. `[[Integer]]` is the type of the lists of integer lists. Parameters are usually written after the parametric type constructor: for example `Maybe String` or `Array Integer`, but some of the builtin type constructors can be written in a special way in order to make the type expressions more readable:
+
+```
+[a] = [] a
+(a,b) = (,) a b
+(a,b,c) = (,,) a b c
+...
+a -> b = (->) a b
+```
+
+Particularly important type constructor is `(->)` for building function types. For example, the type of the function computing the length of a string is `String -> Integer`: the function takes a string as a parameter and returns an integer.
+
+Types of the functions taking multiple parameters are written by composing function types. For example, the type of a function taking nth element of a string list is `[String] -> Integer -> String`. The function takes a string list and an integer as a parameter and returns a string. Function type operator `->` is right associative thus the previous type is equivalent to `[String] -> (Integer -> String)`. Thus the type expression can be read as well as a type of functions taking a string list and returning another function from integers and strings.
+
+`(a,b)` is the type of pairs where the first component of the pair has type `a` and the second component has type `b`. Tuple types `(a,b,c)`, `(a,b,c,d)` etc. are defined similarly. `Maybe a` is the type of optional values.
+
+## Type variables
+
+Many functions can be defined so that they do not need to know the exact types they are operating with. Such unknown types can be filled in type expressions by type variables: for example the function we discussed earlier that took nth element of a string list does not need the information that list elements are strings in its implementation and so it can be given a more generic type `[a] -> Integer -> a`, i.e a function taking a list of `a`:s and an integer as a parameter and returning a single `a`.
+
+Function types with type variables tell quite much about the function assuming it is total, i.e does not hang or throw a runtime exception with any parameters. For example the type signatures define the following functions uniquely:
+
+```
+id :: a -> a
+swap :: (a,b) -> (b,a)
+const :: a -> b -> a
+```
+
+and there are only two possible total functions satisfying the following signature
+
+```
+choose :: a -> a -> a
+```
+
+Type variables may also refer to parametric types, but all useful examples involve type constraints we describe below.
+
+## Type constraints
+
+SCL does not support function overloading at least in the way Java and C++ support it. This means that every function has a unique type signature. Now consider the addition function (+). We could defined its signature for example as `Integer -> Integer -> Integer`, but then we would need some other name for the sum of doubles `Double -> Double -> Double` or `strings String -> String -> String`. It would seem like the right signature would be `a -> a -> a`, but that is not satisfactory either, because then the function would have to somehow support all possible types.
+
+The solution to the problem is to constrain the set of allowed types for the type variable. Such a constrained type is written in the case of addition function as `Additive a => a -> a -> a`. The constraint `Additive a` is composed of a type class `Additive` followed by parameters of the constraint. The type can be understood in two different ways. A logical reading is
+
+> for any additive type a, the function takes two a:s as parameters and returns a
+
+and operational reading that gives a good intuition what is happening in runtime
+
+> the function takes a parameter Additive a that describes a set of methods that can be used to operate values of a and two a:s and returns a
+
+Constrained type variable can be also parametric. For example, let's say we want to define a function getNth that takes nth element of a list but also works with arrays. The signature would then be
+
+```
+getNth :: Sequence s => s a -> Integer -> a
+```
+
+Type classes form a hierarchy: each class may have any number of superclasses. Only the most specific type class is needed in the constraints. For example, addition and multiplication have the following signatures:
+
+```
+(+) :: Additive a => a -> a -> a
+(*) :: Ring a => a -> a -> a
+```
+
+and `Additive` is a superclass of `Ring a`. A function using both operators need to specify only Ring as a constraint:
+
+```
+doubleAndAddOne :: Ring a => a -> a
+doubleAndAddOne x = 2*x + 1
+```
+
+## Effect types
+
+SCL functions are [referentially transparent](https://en.wikipedia.org/wiki/Referential_transparency) which means that they are like mathematical functions always returning the same value for the same parameters and not causing any observable side-effects. This seems extremely restrictive because most of the programs are written in order to generate some kind of side-effects and even completely mathematical algorithms involve functions that are not referentially transparent such as generation of random numbers.
+
+This policy does not however restrict expressive power of the language because functions can return and manipulate *descriptions of computations*. These computations are then executed by some external means. Two different ways of handling computations in SCL are monads and effect types. The former concept is described [(in)numerable](https://wiki.haskell.org/Monad_tutorials_timeline) times in different Haskell tutorials, and is defined with the machinery already described. Effect types are not applicable to as large a range of different computation concepts as monads are but they are easier to work with.
+
+An effectful computation has type `<effects>` value. The type after angle brackets is the type of the value obtained by the computation. Side-effects that might happen during computation are listed inside of angle brackets. Effect types must always occur as a return type of a function. Here are some examples of functions with side-effects:
+
+```
+randomBetween :: Double -> Double -> <Nondet> Double
+resourceByUri :: String -> <ReadGraph> Resource
+claim :: Resource -> Resource -> Resource -> <WriteGraph> ()
+randomLiteral :: Double -> Double -> <Nondet,WriteGraph> Resource
+```
+
+Effect types are much like type constraints: you can mostly ignore them when using functions. All effects you use are automatically collected and added to the type signature of the defined function (or checked against type annotation if provided).
+
+Like type classes, effects form a hierarchy. For example `WriteGraph` inherits `ReadGraph` and a function both reading and writing to graph is annotated only with `<WriteGraph>` effect.
+
+Like types, effects can also be abstracted with effect variables. This is important when defining generic functions that manipulate possibly effectful functions:
+
+```
+executeTwice :: (() -> <e> ()) -> <e> ()
+executeTwice f = do f () ; f ()
+
+(.) :: (b -> <e2> c) -> (a -> <e1> b) -> (a -> <e1,e2> c)
+(f . g) x = f (g x)
+```
--- /dev/null
+The following dev-wiki pages are still to be converted to Markdown pages:
+
+# Overview
+
+ Introduction to Simantics Architecture
+ Roadmap
+ Move this content to "Archive section"
+ Roadmapping will be continued using Gitlab milestones etc from now on.
+ Data View
+ Component View
+
+
+# Miscellaneous Documents
+
+ Quick Development Environment Setup Guide
+ Target Platform
+ Development Practices
+ Internationalization
+ Update Site
+ Coding Convention
+ Tools
+ Testing
+ FAQ
+ Migration To Git
+
+
+# Database Development
+
+ Tutorial: Quickstart
+ Tutorial: Database Development
+ Team Features
+
+
+# Data management & Experiment Control
+
+ Databoard Specification
+ Databoard Java Manual
+ Experiment Control
+ Dataflows
+
+
+# UI Development
+
+ Browser Manual
+ Browser Component
+ Scene Graph Loader
+ Messages
+ Modelled Views
+ Documents
+ Selection View
+
+
+# Model Development
+
+ Structural Ontology
+ Users and Roles
+ Models
+ Concept Versioning
+ Component Identification
+ Tutorial: Model Development
+
+
+# Issue Development
+
+ Issue subsystem general description
+
+
+# Project Development
+
+ Project Management Conceptual Model
+ Project Development
+ Tutorial: Project Development
+
+
+# Diagram Development
+
+ 2D Ontologies
+ Diagram
+ Scene graph
+ Diagram connections
+ Tutorial: Diagram Development
+
+# List of all pages in the wiki
+
+TODO:
+* [ ] for not-yet-translated pages
+* [X] for translation completed pages
+* [D] for deprecated pages that need to be examined and possibly removed
+* [R] for pages that are to be removed
+
+
+* [ ] 2D Ontologies
+* [X] Binary Container Format
+* [D] Buckminster
+ * Consider moving this to some "Archive section" as old platform material
+* [X] Check list: Model browser contributions
+* [ ] Coding Convention
+* [ ] Command file format
+* [ ] Commands
+* [ ] Component Identification
+* [ ] Component View
+* [ ] Concept Versioning
+* [ ] DB Snippets
+* [ ] Data View
+* [ ] Database Testing
+* [ ] Databoard Developer Manual
+* [ ] Databoard Specification
+* [ ] Databoard Tutorials
+* [ ] Dataflows
+* [D] Deprecated Target Platforms
+* [D] Developer meeting 16.4.2012
+* [D] Developer meeting 2.4.2012
+* [D] Development Environment Setup Guide
+* [D] Development Practices
+* [ ] Diagram connections
+* [D] EventThread Pattern
+* [ ] Experiment Control
+* [D] Extra meeting 10.1.2012
+* [D] Extra meeting 14.2.2012
+* [D] Extra meeting 17.1.2012
+* [D] Extra meeting 26.1.2012
+* [D] Extra meeting 30.1.2012
+* [D] FAQ
+* [ ] Functions
+ * Need to enhance this, this is important for many cases!
+ * Could also combine it with ProceduralValues which has older information on these facilities.
+* [X] Glossary
+* [X] Graph Compiler
+* [X] Graph File Format
+* [ ] Interface summary
+* [D] Internationalization
+ * https://gitlab.simantics.org/simantics/platform/-/wikis/Internationalization
+* [ ] Introduction to Simantics Architecture
+* [X] Inverse Relations
+* [ ] Issue subsystem general description
+* [D] Licensing
+ * https://gitlab.simantics.org/simantics/platform/-/wikis/Internationalization
+* [ ] Logging in Simantics Platform
+* [D] Mapping
+* [D] Migration To Git
+* [ ] Models
+* [D] Models Deprecated
+* [ ] Ontology Development Exercises
+* Org.simantics.browsing.ui
+* Org.simantics.browsing.ui.feature
+* Org.simantics.browsing.ui Manual
+* Org.simantics.charts
+* Org.simantics.databoard
+* Org.simantics.db
+* Org.simantics.db.procore.server
+* Org.simantics.db.tests
+* Org.simantics.diagram
+* Org.simantics.document
+* Org.simantics.fastlz
+* Org.simantics.g2d
+* Org.simantics.g2d.feature
+* Org.simantics.graph
+* Org.simantics.history
+* Org.simantics.message
+* Org.simantics.message.feature
+* [R] Org.simantics.objmap
+* [X] Org.simantics.objmap Manual
+* Org.simantics.project
+* Org.simantics.scenegraph
+* Org.simantics.scenegraph.loader
+* Org.simantics.scenegraph.ui
+* Org.simantics.views
+* Org.simantics.wiki
+* [D] Plugins
+* [X] Procedural Values
+* [ ] Project Development
+* [ ] Project Management Conceptual Model
+* [ ] Project Set Tester
+* [D] Quick Development Environment Setup
+* [D] Regular meeting 9.1.2012
+* [X] Resource Adaptation
+* [X] Resource Serialization
+* [D] Roadmap
+ * Shall be archived
+* [X] SCL Compiler
+* [X] SCL Examples
+* [X] SCL Registry
+* [X] SCL Tutorial
+* [X] SCL Types
+* [D] Scene Graph: Sysdyn-scenario
+* [D] Scene graph node list
+* [ ] Selection View
+* [X] Simantics Generic File Import
+* [R] Simantics Specifications
+* [ ] Structural Ontology
+* [X] Subgraph Extents
+* [ ] Subgraph operations
+* [ ] Target Platform (DEPRECATED, must update if left)
+* [D] Team Features (TODO: consider for deletion)
+* [ ] Testing
+* [ ] Tools
+* [X] Transferable Graph
+* [ ] Tutorial: Database Development
+* [ ] Tutorial: Diagram Development
+* [ ] Tutorial: Model Development
+* [ ] Tutorial: Ontology Development
+* [ ] Tutorial: Project Development
+* [ ] Tutorial: Quickstart
+* [ ] Tutorials
+* [ ] Undo Mechanism
+* [ ] Undo and Redo
+* [ ] Update Site
+* [X] Useful Links
+* [ ] Users and Roles
+* [X] Variable
+* [X] Version Migration
+* [X] Virtual Graphs
+* [D] Workshop 15.2.2012
+* [D] Workshop 16.2.2012
+* [X] XML Schema Conversion
Code Review / simantics / platform.git / commitdiff
