Feat: Support for Distributions in Templated Workloads (#385)

PR adds support for various Numerical Distributions in templated
benchmarks

- Uniform
- Binomial
- Zipfian
- Scrambled

The distributions work not only for integers, but also different types
such as timestamps, long, float
A table of supported combinations can be found in the templated
benchmarks readme.

| Type | uniform | binomial | zipfian | scrambled (zipfian) |
|---|:---:|:---:|:---:|:---:|
| INTEGER | X | X | X | X |
| FLOAT / REAL | X | X|- | - |
| BIGINT | X | X | X | X |
| VARCHAR / STRING | X | -| -| -|
| TIMESTAMP | X | X |X |X |
| DATE | X | X| X| X|
| TIME | X |X | X| X|

Usage example:

```xml
<templates>
    <template name="MyTemplate">
        <query><![CDATA[SELECT * FROM MyTable WHERE id = ?]]></query>
        <types>
            <type>INTEGER</type>
        </types>
        <values>
            <value dist="uniform" min="0" max="1000" seed="1"/>
        </values>
         <values>
            <value dist="zipf" min="1" max="1000" seed="2"/>
        </values>
    </template>
    <!-- ... -->
<templates>
```
This PR is not a breaking change - One can still use a static value in
the templated queries.
`<value>10</value>`

In the future, I could see a breaking change that adds the datatype
directly to the values so the TemplatedValue can do the type handling
directly. `<value dist="uniform" type="integer">`. This would make type
checking easier and remove the need to store the original min/max values
as strings for all datatypes.

---------

Co-authored-by: Brian Kroth <bpkroth@users.noreply.github.com>

Author: ETHenzlere

data/templated/example.xml

@@ -9,12 +9,12 @@
          <type>INTEGER</type>
       </types>
       <values>
-         <value>3</value>
-         <value>4</value>
+         <value dist="uniform" min="1" max="3"/>
+         <value dist="zipfian" min="1" max="2"/>
       </values>
        <values>
-         <value>5</value>
-         <value>6</value>
+         <value dist="scrambled" min="0" max="4" seed="999"/>
+         <value dist="normal" min="1" max="3" seed="1"/>
       </values>
    </template>
    <template name="GetCust">
@@ -33,8 +33,8 @@
          <type>INTEGER</type>
       </types>
       <values>
+        <value>1</value>
         <value />
-        <value>8</value>
       </values>
    </template>
    <template name="GetWarehouse">
@@ -53,8 +53,8 @@
          <type>FLOAT</type>
       </types>
       <values>
-         <value>10</value>
-         <value>10.49</value>
+         <value dist="normal" min="10" max="12.5"/>
+         <value dist="uniform" min="15.1" max="100.22"/>
       </values>
       <values>
          <value>10.50</value>
@@ -64,19 +64,28 @@
     <template name="UpdateItemPrice">
       <query><![CDATA[UPDATE item SET i_price = i_price + 1 WHERE i_price < ?]]></query>
       <types>
-         <type>FLOAT</type>
+         <type>INTEGER</type>
       </types>
       <values>
-         <value>2.1</value>
+         <value dist="zipfian" min="10" max="40">2</value>
       </values>
    </template>
    <template name="DeleteItem">
-      <query><![CDATA[DELETE FROM item WHERE i_price > ?]]></query>
+      <query><![CDATA[DELETE FROM oorder WHERE o_entry_d < ?]]></query>
       <types>
-         <type>FLOAT</type>
+         <type>TIMESTAMP</type>
       </types>
       <values>
-         <value>255.0</value>
+         <value dist="uniform" min="1000" max="300000"></value>
+      </values>
+       <values>
+         <value dist="normal" min="1000" max="300000"></value>
+      </values>
+       <values>
+         <value dist="zipfian" min="1000" max="300000"></value>
+      </values>
+       <values>
+         <value dist="scrambled" min="1000" max="300000"></value>
       </values>
    </template>
    <template name="InsertItem">
@@ -97,9 +106,9 @@
          <value>1</value>
          <value>1</value>
          <value>1</value>
-         <value>2022-10-10 11:30:30</value>
-         <value>1.0</value>
-         <value>Test</value>
+         <value dist="uniform" min="1999-12-12 01:01:55" max="2000-12-12 04:04:44"/>
+         <value dist="normal" min="0.5" max="12.5"/>
+         <value dist="uniform" min="0" max="23"/>
       </values>
    </template>
 </templates>

src/main/java/com/oltpbenchmark/api/templates/ObjectFactory.java

@@ -17,10 +17,10 @@
 
 //
 // This file was generated by the JavaTM Architecture for XML Binding(JAXB) Reference
-// Implementation, vJAXB 2.1.10
-// See <a href="http://java.sun.com/xml/jaxb">http://java.sun.com/xml/jaxb</a>
+// Implementation, v2.3.0.1
+// See <a href="https://javaee.github.io/jaxb-v2/">https://javaee.github.io/jaxb-v2/</a>
 // Any modifications to this file will be lost upon recompilation of the source schema.
-// Generated on: 2011.12.28 at 11:42:38 PM EST
+// Generated on: 2023.11.16 at 08:29:59 AM UTC
 //
 
 package com.oltpbenchmark.api.templates;
@@ -32,7 +32,7 @@
 
 /**
  * This object contains factory methods for each Java content interface and Java element interface
- * generated in the com.oltpbenchmark.api.templates package.
+ * generated in the main.java.com.oltpbenchmark.api.templates package.
  *
  * <p>An ObjectFactory allows you to programatically construct new instances of the Java
  * representation for XML content. The Java representation of XML content can consist of schema
@@ -46,10 +46,15 @@ public class ObjectFactory {
 
   /**
    * Create a new ObjectFactory that can be used to create new instances of schema derived classes
-   * for package: com.oltpbenchmark.api.templates
+   * for package: main.java.com.oltpbenchmark.api.templates
    */
   public ObjectFactory() {}
 
+  /** Create an instance of {@link TemplatesType } */
+  public TemplatesType createTemplatesType() {
+    return new TemplatesType();
+  }
+
   /** Create an instance of {@link TemplateType } */
   public TemplateType createTemplateType() {
     return new TemplateType();
@@ -65,9 +70,19 @@ public ValuesType createValuesType() {
     return new ValuesType();
   }
 
-  /** Create an instance of {@link JAXBElement }{@code <}{@link TemplatesType }{@code >}} */
+  /** Create an instance of {@link ValueType } */
+  public ValueType createValueType() {
+    return new ValueType();
+  }
+
+  /**
+   * Create an instance of {@link JAXBElement }{@code <}{@link TemplatesType }{@code >}
+   *
+   * @param value Java instance representing xml element's value.
+   * @return the new instance of {@link JAXBElement }{@code <}{@link TemplatesType }{@code >}
+   */
   @XmlElementDecl(namespace = "", name = "templates")
-  public JAXBElement<TemplatesType> createDialects(TemplatesType value) {
-    return new JAXBElement<>(_Templates_QNAME, TemplatesType.class, null, value);
+  public JAXBElement<TemplatesType> createTemplates(TemplatesType value) {
+    return new JAXBElement<TemplatesType>(_Templates_QNAME, TemplatesType.class, null, value);
   }
 }

src/main/java/com/oltpbenchmark/api/templates/TemplateType.java

@@ -17,10 +17,10 @@
 
 //
 // This file was generated by the JavaTM Architecture for XML Binding(JAXB) Reference
-// Implementation, vJAXB 2.1.10
-// See <a href="http://java.sun.com/xml/jaxb">http://java.sun.com/xml/jaxb</a>
+// Implementation, v2.3.0.1
+// See <a href="https://javaee.github.io/jaxb-v2/">https://javaee.github.io/jaxb-v2/</a>
 // Any modifications to this file will be lost upon recompilation of the source schema.
-// Generated on: 2011.12.28 at 11:42:38 PM EST
+// Generated on: 2023.11.16 at 08:29:59 AM UTC
 //
 
 package com.oltpbenchmark.api.templates;
@@ -30,21 +30,23 @@
 import java.util.List;
 
 /**
- * Java class for dialectType complex type.
+ * Java class for templateType complex type.
  *
  * <p>The following schema fragment specifies the expected content contained within this class.
  *
  * <pre>
- * &lt;complexType name="dialectType">
- *   &lt;complexContent>
- *     &lt;restriction base="{http://www.w3.org/2001/XMLSchema}anyType">
- *       &lt;sequence>
- *         &lt;element name="procedure" type="{}procedureType" maxOccurs="unbounded"/>
- *       &lt;/sequence>
- *       &lt;attribute name="type" use="required" type="{http://www.w3.org/2001/XMLSchema}string" />
- *     &lt;/restriction>
- *   &lt;/complexContent>
- * &lt;/complexType>
+ * &lt;complexType name="templateType"&gt;
+ *   &lt;complexContent&gt;
+ *     &lt;restriction base="{http://www.w3.org/2001/XMLSchema}anyType"&gt;
+ *       &lt;sequence&gt;
+ *         &lt;element name="query" type="{http://www.w3.org/2001/XMLSchema}string"/&gt;
+ *         &lt;element name="types" type="{}typesType"/&gt;
+ *         &lt;element name="values" type="{}valuesType" maxOccurs="unbounded"/&gt;
+ *       &lt;/sequence&gt;
+ *       &lt;attribute name="name" use="required" type="{http://www.w3.org/2001/XMLSchema}string" /&gt;
+ *     &lt;/restriction&gt;
+ *   &lt;/complexContent&gt;
+ * &lt;/complexType&gt;
  * </pre>
  */
 @XmlAccessorType(XmlAccessType.FIELD)
@@ -53,9 +55,6 @@
     propOrder = {"query", "types", "values"})
 public class TemplateType {
 
-  @XmlAttribute(required = true)
-  protected String name;
-
   @XmlElement(required = true)
   protected String query;
 
@@ -65,24 +64,63 @@ public class TemplateType {
   @XmlElement(required = true)
   protected List<ValuesType> values;
 
-  /** Gets the value of the query property. */
+  @XmlAttribute(name = "name", required = true)
+  protected String name;
+
+  /**
+   * Gets the value of the query property.
+   *
+   * @return possible object is {@link String }
+   */
   public String getQuery() {
     return this.query;
   }
 
-  /** Gets the value of the types property. */
+  /**
+   * Sets the value of the query property.
+   *
+   * @param value allowed object is {@link String }
+   */
+  public void setQuery(String value) {
+    this.query = value;
+  }
+
+  /**
+   * Gets the value of the types property.
+   *
+   * @return possible object is {@link TypesType }
+   */
   public TypesType getTypes() {
     return this.types;
   }
 
   /**
-   * Gets the value of the types property.
+   * Sets the value of the types property.
+   *
+   * @param value allowed object is {@link TypesType }
+   */
+  public void setTypes(TypesType value) {
+    this.types = value;
+  }
+
+  /**
+   * Gets the value of the values property.
+   *
+   * <p>This accessor method returns a reference to the live list, not a snapshot. Therefore any
+   * modification you make to the returned list will be present inside the JAXB object. This is why
+   * there is not a <CODE>set</CODE> method for the values property.
+   *
+   * <p>For example, to add a new item, do as follows:
+   *
+   * <pre>
+   * getValues().add(newItem);
+   * </pre>
    *
    * <p>Objects of the following type(s) are allowed in the list {@link ValuesType }
    */
-  public List<ValuesType> getValues() {
+  public List<ValuesType> getValuesList() {
     if (this.values == null) {
-      this.values = new ArrayList<>();
+      this.values = new ArrayList<ValuesType>();
     }
     return this.values;
   }
@@ -93,6 +131,15 @@ public List<ValuesType> getValues() {
    * @return possible object is {@link String }
    */
   public String getName() {
-    return name;
+    return this.name;
+  }
+
+  /**
+   * Sets the value of the name property.
+   *
+   * @param value allowed object is {@link String }
+   */
+  public void setName(String value) {
+    this.name = value;
   }
 }

src/main/java/com/oltpbenchmark/api/templates/TemplatesType.java

@@ -17,36 +17,33 @@
 
 //
 // This file was generated by the JavaTM Architecture for XML Binding(JAXB) Reference
-// Implementation, vJAXB 2.1.10
-// See <a href="http://java.sun.com/xml/jaxb">http://java.sun.com/xml/jaxb</a>
+// Implementation, v2.3.0.1
+// See <a href="https://javaee.github.io/jaxb-v2/">https://javaee.github.io/jaxb-v2/</a>
 // Any modifications to this file will be lost upon recompilation of the source schema.
-// Generated on: 2011.12.28 at 11:42:38 PM EST
+// Generated on: 2023.11.16 at 08:29:59 AM UTC
 //
 
 package com.oltpbenchmark.api.templates;
 
-import jakarta.xml.bind.annotation.XmlAccessType;
-import jakarta.xml.bind.annotation.XmlAccessorType;
-import jakarta.xml.bind.annotation.XmlElement;
-import jakarta.xml.bind.annotation.XmlType;
+import jakarta.xml.bind.annotation.*;
 import java.util.ArrayList;
 import java.util.List;
 
 /**
- * Java class for dialectsType complex type.
+ * Java class for templatesType complex type.
  *
  * <p>The following schema fragment specifies the expected content contained within this class.
  *
  * <pre>
- * &lt;complexType name="dialectsType">
- *   &lt;complexContent>
- *     &lt;restriction base="{http://www.w3.org/2001/XMLSchema}anyType">
- *       &lt;sequence>
- *         &lt;element name="dialect" type="{}dialectType" maxOccurs="unbounded"/>
- *       &lt;/sequence>
- *     &lt;/restriction>
- *   &lt;/complexContent>
- * &lt;/complexType>
+ * &lt;complexType name="templatesType"&gt;
+ *   &lt;complexContent&gt;
+ *     &lt;restriction base="{http://www.w3.org/2001/XMLSchema}anyType"&gt;
+ *       &lt;sequence&gt;
+ *         &lt;element name="template" type="{}templateType" maxOccurs="unbounded"/&gt;
+ *       &lt;/sequence&gt;
+ *     &lt;/restriction&gt;
+ *   &lt;/complexContent&gt;
+ * &lt;/complexType&gt;
  * </pre>
  */
 @XmlAccessorType(XmlAccessType.FIELD)
@@ -59,13 +56,23 @@ public class TemplatesType {
   protected List<TemplateType> template;
 
   /**
-   * Gets the value of the dialect property.
+   * Gets the value of the template property.
+   *
+   * <p>This accessor method returns a reference to the live list, not a snapshot. Therefore any
+   * modification you make to the returned list will be present inside the JAXB object. This is why
+   * there is not a <CODE>set</CODE> method for the template property.
+   *
+   * <p>For example, to add a new item, do as follows:
+   *
+   * <pre>
+   * getTemplate().add(newItem);
+   * </pre>
    *
    * <p>Objects of the following type(s) are allowed in the list {@link TemplateType }
    */
   public List<TemplateType> getTemplateList() {
     if (this.template == null) {
-      this.template = new ArrayList<>();
+      this.template = new ArrayList<TemplateType>();
     }
     return this.template;
   }