BIS Mapping Language Tutorial resources

examples/README.md

@@ -2,4 +2,5 @@ Example resources for different development and operational topics.
 
 ## Directory Structure 
 
-* [`scheduler`](scheduler/) - example resources for the BIS Task Scheduler.
+* [`bismapper`](bismapper/) - example projects for the *BIS Mapping Designer*.
+* [`scheduler`](scheduler/) - example resources for the *BIS Task Scheduler*.

examples/bismapper/BISMappingLanguage/.classpath

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<classpath>
+	<classpathentry kind="src" path="src/main/schemas"/>
+	<classpathentry excluding="**" kind="src" path="src/test/messages"/>
+	<classpathentry kind="src" path="src/main/java"/>
+	<classpathentry kind="src" path="src/main/modules"/>
+	<classpathentry kind="src" path="src/main/mappings"/>
+	<classpathentry kind="src" path="src/test/java"/>
+	<classpathentry kind="src" path="src/test/resources"/>
+	<classpathentry kind="con" path="com.seeburger.bicng.ide.project.classpath.BICNGClasspathContainer"/>
+	<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-1.8"/>
+	<classpathentry kind="output" path="target/classes"/>
+</classpath>

examples/bismapper/BISMappingLanguage/.gitignore

@@ -0,0 +1,2 @@
+/target
+/bin

examples/bismapper/BISMappingLanguage/.project

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>BISMappingLanguage</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+		<buildCommand>
+			<name>org.eclipse.jdt.core.javabuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+		<buildCommand>
+			<name>org.eclipse.xtext.ui.shared.xtextBuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+	</buildSpec>
+	<natures>
+		<nature>org.eclipse.jdt.core.javanature</nature>
+		<nature>org.eclipse.xtext.ui.shared.xtextNature</nature>
+		<nature>com.seeburger.bicng.ide.project.BICNGNature</nature>
+	</natures>
+</projectDescription>

examples/bismapper/BISMappingLanguage/.settings/org.eclipse.core.resources.prefs

@@ -0,0 +1,2 @@
+eclipse.preferences.version=1
+encoding/<project>=UTF-8

examples/bismapper/BISMappingLanguage/.settings/org.eclipse.jdt.core.prefs

@@ -0,0 +1,4 @@
+eclipse.preferences.version=1
+org.eclipse.jdt.core.compiler.codegen.targetPlatform=1.8
+org.eclipse.jdt.core.compiler.compliance=1.8
+org.eclipse.jdt.core.compiler.source=1.8

examples/bismapper/BISMappingLanguage/README.md

@@ -0,0 +1,34 @@
+Example **BIS Mapping Designer** project for the *BIS Mapping Language Tutorial*.
+
+## Files
+
+The following lists only the most important files in this project:
+
+* `pom.xml`- Project Object Model and build script (Maven)
+* `src/test/messages/SalesData/SalesData.xml` - Test message for the more complex path-expression examples
+* `src/main/schemas/SalesData.seexsd` - Sample Data Message Schema
+* `src/main/mappings/16_Grouping.seemap` - (One of the) Sample Map using the SampleData schema.
+
+
+## Using the sample project
+
+You need to import the sample project (directory) into the *BIS Mapping Designer* with the following procedure:
+
+Prerequisite: *BIS Developer Studio* with *BIS Mapping Designer* plugin installed and licensed.
+
+- Start *BIS Developer Studio*, make sure to pick a workspace directory outside of the installation directory.
+- Optional: switch or reset the BIS Mapping Designer perspective: **Window -> Perspective -> Open Perspective -> Mapping -> Open** (if Mapping is not in the list use "Other... -> Mapping**).
+- Check out this `bis-resources` Git repository into a local directory.
+- Use **File -> Import... -> General -> Existing Projects into Workspace** and select the `examples/bismapper/BisMapperLanguage` directory from this check-out as root directory.
+- Check the box near project and choose **Finish**.
+- In the *Project Explorer* view: unfold `BISMappingLanguage` project, `src/main/mappings` and `src/test/messages/SalesData` folders.
+- Open a mapping in the tree by double clicking **src/mappings/16_Grouping.seemap**.
+- On the right side, activate the **Mapping Tester** view.
+- Drag the testfile `messages/SalesData/SalesData.xml` into the (input) **Message Instance** pane.
+- Press **Run** (play button icon) on top of the Mapping Tester to execute this mapping and see the results below in the **Output** pane.
+
+Alternatively, you can also use **File -> Import -> Git -> Projects from Git (with smart import)** and specify `https://github.com/seeburger-ag/bis-resources.git` as your URI.
+
+## See Also
+
+Refer to the **BIS Mapping Designer** (F1) Online-Help and the `BIS_Mapping_Language_Tutorial.pdf` (for example [available](https://community.seeburger.com/t/bis-mapping-designer-short-tutorial-download/1023) on the *SEEBURGER Customer Community*).

examples/bismapper/BISMappingLanguage/pom.xml

@@ -0,0 +1,68 @@
+<?xml version="1.0"?>
+<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>com.seeburger.bicng.projects</groupId>
+  <artifactId>BISMappingLanguage</artifactId>
+  <version>0.0.1-SNAPSHOT</version>
+  <properties>
+    <maven.compiler.target>1.8</maven.compiler.target>
+    <maven.compiler.source>1.8</maven.compiler.source>
+  </properties>
+  <build>
+    <resources>
+      <resource>
+        <directory>src/main/schemas</directory>
+        <excludes>
+          <exclude>**/*.java</exclude>
+        </excludes>
+      </resource>
+      <resource>
+        <directory>src/main/modules</directory>
+        <includes>
+          <include>**/*.seemap</include>
+        </includes>
+      </resource>
+      <resource>
+        <directory>src/main/mappings</directory>
+        <includes>
+          <include>**/*.seemap</include>
+        </includes>
+      </resource>
+      <resource>
+        <directory>src/main/java</directory>
+        <includes>
+          <include>**/*.java</include>
+        </includes>
+      </resource>
+      <resource>
+        <directory>${project.build.sourceDirectory}</directory>
+        <includes>
+          <include>**/*.properties</include>
+        </includes>
+      </resource>
+      <resource>
+        <directory>.</directory>
+        <includes>
+          <include>report_template*.html</include>
+          <include>*.properties</include>
+        </includes>
+      </resource>
+    </resources>
+    <testResources>
+      <testResource>
+        <directory>src/test/resources</directory>
+        <excludes>
+          <exclude>**/*.java</exclude>
+        </excludes>
+      </testResource>
+      <testResource>
+        <directory>src/test/messages</directory>
+        <excludes>
+          <exclude>**/*.java</exclude>
+        </excludes>
+      </testResource>
+    </testResources>
+    <finalName>${project.name}</finalName>
+  </build>
+</project>

examples/bismapper/BISMappingLanguage/src/main/mappings/01_BasicNodeCreation.seemap

@@ -0,0 +1,26 @@
+(:
+BasicNodeCreation.seemap
+created at 2024-04-17 by d.pace, SEEBURGER AG.
+Copyright 2024, SEEBURGER AG. All rights reserved.
+:)
+
+root
+{
+    output := "Hello, World!"
+
+    (:
+        Exercise:
+
+        1. Create another complex child node named "myNode" under root
+        2. Create a value assignment inside "myNode"
+
+        Expected output:
+
+        <root>
+            <output>Hello, World!</output>
+            <myNode>
+                <value>Hi!</value>
+            </myNode>
+        </root>
+    :)
+}

examples/bismapper/BISMappingLanguage/src/main/mappings/02_Literals.seemap

@@ -0,0 +1,59 @@
+(:
+Literals.seemap
+created at 2024-05-07 by d.pace, SEEBURGER AG.
+Copyright 2024, SEEBURGER AG. All rights reserved.
+:)
+
+root
+{
+    (: String literals can be enclosed in single or double quotes :)
+    myString := "Hi!"
+    myString := 'Hi!'
+
+    (: This is especially useful if the string content contains quotation marks :)
+    myString := "Let's go"
+    myString := 'Hamlet: "To be, or not to be, that is the question"'
+
+    (: Quotation marks inside strings must be escaped with backslashes :)
+    myString := 'Bertrand Russell: "Science is what you know. Philosophy is what you don\'t know."'
+
+    (: Integer literals :)
+    myInteger := 42
+    myInteger := - 23
+
+    (: Native support for big integers :)
+    myLargeInteger := 123987418753462384721379456189327645891264
+
+    (: Decimal literals :)
+    myDecimal := 3.1415
+    myDecimal := - 6.8
+
+    (: Native support for big decimals :)
+    myLargeDecimal := 867168719871984687169875637841358713.681738735
+
+    (: Boolean literals :)
+    myBoolean := true()
+    myBoolean := false()
+
+    (:
+        Exercise:
+
+        1. Create another complex child node named "myNode" under root
+        2. Create four value assignments under the new complex node:
+           * A value assignment with a string value
+           * A value assignment with an integer value
+           * A value assignment with a decimal value
+           * A value assignment with a boolean value
+
+        Expected output:
+
+        <root>
+            <myNode>
+                <myString>Hi!</myString>
+                <myInteger>42</myInteger>
+                <myDecimal>3.1415</myDecimal>
+                <myBoolean>true</myBoolean>
+            </myNode>
+        </root>
+    :)
+}

examples/bismapper/BISMappingLanguage/src/main/mappings/03_ArithmeticExpressions.seemap

@@ -0,0 +1,38 @@
+(:
+ArithmeticExpressions.seemap
+created at 2024-05-07 by d.pace, SEEBURGER AG.
+Copyright 2024, SEEBURGER AG. All rights reserved.
+:)
+
+root
+{
+    additionResult := 23 + 42
+    subtractionResult := 42 - 23
+    multiplicationReslt := 23 * 42
+    divisionResult := 42 div 23 (: Note: division operator is div, not / :)
+    integerDivisionResult := 42 idiv 23 (: cuts off all fraction digits :)
+    moduloResult := 8 mod 3 (: remainder after division :)
+
+    result1 := 2 * 3 + 4
+    (: use parentheses to prioritize computations against default operator precedence :)
+    result2 := 2 * (3 + 4)
+
+    (: rounding :)
+    floor := floor(1.9)
+    ceil := ceil(1.1)
+    round := round(1.5)
+    advancedRound := round(1.5, 0, "HALF_DOWN")
+
+    (:
+        Exercise:
+
+        An input message contains 207 items.
+        In the output, the items have to be written in groups of max. 5 items.
+        Compute how many groups are needed.
+        Write the result to a leaf node named "numberOfGroups".
+
+        Expected output:´
+
+        <numberOfGroups>42</numberOfGroups>
+    :)
+}

examples/bismapper/BISMappingLanguage/src/main/mappings/04_Variables.seemap

@@ -0,0 +1,48 @@
+(:
+Variables.seemap
+created at 2024-05-07 by d.pace, SEEBURGER AG.
+Copyright 2024, SEEBURGER AG. All rights reserved.
+:)
+
+root
+{
+    (: Variables are declared using let clauses :)
+    let $x := 42
+    (: we can use $x from now on, but $x is visible inside root{} only :)
+    element
+    {
+        myNumber := $x
+
+        let $y := "test"
+        (: scope of $y starts here :)
+        myString := $y
+        (: scope of $y ends here :)
+    }
+
+    rootLevelNumber := $x
+    (: $y is not visible here :)
+}
+
+(: neither $x nor $y are visible here :)
+
+(:
+    Exercise:
+
+    1. Declare a new variable named $a before the "root" node with the value "my value".
+    2. Add a value assignment before "element" and write out the value of $a.
+    3. Add a value assignment after "myString" and write out the value of $a.
+    4. Add a value assignment after "rootLevelNumber" and write out the value of $a.
+
+    Expected Output:
+
+    <root>
+        <output>my value</output>
+        <element>
+            <myNumber>42</myNumber>
+            <myString>test</myString>
+            <output>my value</output>
+        </element>
+        <rootLevelNumber>42</rootLevelNumber>
+        <output>my value</output>
+    </root>
+:)

examples/bismapper/BISMappingLanguage/src/main/mappings/05_Sequences.seemap

@@ -0,0 +1,59 @@
+(:
+Sequences.seemap
+created at 2024-05-07 by d.pace SEEBURGER AG.
+Copyright 2024, SEEBURGER AG. All rights reserved.
+:)
+
+root
+{
+    (: Sequence of numbers :)
+    let $myNumbers := (1, 2, 3)
+
+    (: count() returns the number of elements in a sequence :)
+    numberCount := count($myNumbers)
+    firstNumber := $myNumbers[1] (: NOTE: all indices are 1-based, not 0-based! :)
+
+    (: when a sequence is assigned to a simple target node, the node is repeated automatically :)
+    numberSequence := $myNumbers
+
+    (: Sequence of strings :)
+    let $myStrings := ("a", "b", "c")
+    stringSequence := $myStrings
+
+    (: Even single elements are sequences with 1 element :)
+    let $myString := "test"
+    literalElementCount := count($myString)
+    accessLiteralSequence := $myString[1]
+
+    (: There is no "null" concept in XPath / XQuery, instead empty sequences are used :)
+    let $emptySequence := ()
+    emptySequenceElementCount := count($emptySequence)
+    emptySequenceOutput := $emptySequence
+
+    (: IMPORTANT TAKEAWAY: every expression results in a sequence :)
+
+    (: some functions take sequences as parameters :)
+    sum := sum($myNumbers)
+    average := avg($myNumbers)
+    minimum := min($myNumbers)
+    maximum := max($myNumbers)
+
+    (:
+        Exercise:
+
+        Create a mixed sequence containing
+        * A string literal
+        * An integer literal
+        * A decimal literal
+        * A boolean literal
+
+        and write all elements of the sequence to the output.
+
+        Expected output:
+
+        <output>string</output>
+        <output>42</output>
+        <output>3.1415</output>
+        <output>true</output>
+    :)
+}