[Samples] Add 40.timex-resolution sample

libraries/bot-dialogs/src/main/java/com/microsoft/recognizers/text/datetime/parsers/BaseMergedDateTimeParser.java

@@ -438,7 +438,7 @@ public SortedMap<String, Object> dateTimeResolution(DateTimeParseResult slot) {
         }
 
         List<Map<String, String>> resolutions = new ArrayList<>();
-        Map<String, Object> res = new HashMap<>();
+        LinkedHashMap<String, Object> res = new LinkedHashMap<>();
 
         DateTimeResolutionResult val = (DateTimeResolutionResult)slot.getValue();
         if (val == null) {

libraries/bot-dialogs/src/main/java/com/microsoft/recognizers/text/datetime/utilities/TimexUtility.java

@@ -13,6 +13,7 @@
 import java.time.temporal.ChronoUnit;
 import java.util.ArrayList;
 import java.util.HashMap;
+import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.stream.Collectors;
@@ -281,7 +282,7 @@ public static String mergeTimexAlternatives(String timex1, String timex2) {
         return timex1 + Constants.CompositeTimexDelimiter + timex2;
     }
 
-    public static Map<String, Object> processDoubleTimex(Map<String, Object> resolutionDic, String futureKey, String pastKey, String originTimex) {
+    public static LinkedHashMap<String, Object> processDoubleTimex(LinkedHashMap<String, Object> resolutionDic, String futureKey, String pastKey, String originTimex) {
         String[] timexes = originTimex.split(Constants.CompositeTimexSplit);
 
         if (!resolutionDic.containsKey(futureKey) || !resolutionDic.containsKey(pastKey) || timexes.length != 2) {

samples/40.timex-resolution/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation. All rights reserved.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

samples/40.timex-resolution/pom.xml

@@ -0,0 +1,204 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <groupId>com.microsoft.bot.sample</groupId>
+  <artifactId>bot-timex-resolution</artifactId>
+  <version>sample</version>
+  <packaging>jar</packaging>
+
+  <name>${project.groupId}:${project.artifactId}</name>
+  <description>This package contains a Java Timex Resolution sample.</description>
+  <url>http://maven.apache.org</url>
+
+  <parent>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-parent</artifactId>
+    <version>2.4.0</version>
+    <relativePath/>
+  </parent>
+
+  <licenses>
+    <license>
+      <name>MIT License</name>
+      <url>http://www.opensource.org/licenses/mit-license.php</url>
+    </license>
+  </licenses>
+
+  <developers>
+    <developer>
+      <name>Bot Framework Development</name>
+      <email></email>
+      <organization>Microsoft</organization>
+      <organizationUrl>https://dev.botframework.com/</organizationUrl>
+    </developer>
+  </developers>
+
+  <properties>
+    <java.version>1.8</java.version>
+    <maven.compiler.target>1.8</maven.compiler.target>
+    <maven.compiler.source>1.8</maven.compiler.source>
+    <start-class>com.microsoft.bot.sample.timex.resolution.Application</start-class>
+  </properties>
+
+  <dependencies>
+    <dependency>
+      <groupId>com.microsoft.bot</groupId>
+      <artifactId>bot-dialogs</artifactId>
+      <version>4.6.0-preview9</version>
+    </dependency>
+  </dependencies>
+
+  <profiles>
+    <profile>
+      <id>build</id>
+      <activation>
+        <activeByDefault>true</activeByDefault>
+      </activation>
+      <build>
+        <resources>
+          <resource>
+            <directory>src/main/resources</directory>
+            <filtering>false</filtering>
+          </resource>
+        </resources>
+        <plugins>
+          <plugin>
+            <artifactId>maven-compiler-plugin</artifactId>
+            <version>3.8.1</version>
+          </plugin>
+          <plugin>
+            <artifactId>maven-war-plugin</artifactId>
+            <version>3.2.3</version>
+            <configuration>
+              <warSourceDirectory>src/main/webapp</warSourceDirectory>
+            </configuration>
+          </plugin>
+          <plugin>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-maven-plugin</artifactId>
+            <executions>
+              <execution>
+                <goals>
+                  <goal>repackage</goal>
+                </goals>
+                <configuration>
+                  <mainClass>com.microsoft.bot.sample.timex.resolution.Application</mainClass>
+                </configuration>
+              </execution>
+            </executions>
+          </plugin>
+          <plugin>
+            <groupId>com.microsoft.azure</groupId>
+            <artifactId>azure-webapp-maven-plugin</artifactId>
+            <version>1.12.0</version>
+            <configuration>
+              <schemaVersion>V2</schemaVersion>
+              <resourceGroup>${groupname}</resourceGroup>
+              <appName>${botname}</appName>
+              <appSettings>
+                <property>
+                  <name>JAVA_OPTS</name>
+                  <value>-Dserver.port=80</value>
+                </property>
+              </appSettings>
+              <runtime>
+                <os>linux</os>
+                <javaVersion>Java 8</javaVersion>
+                <webContainer>Java SE</webContainer>
+              </runtime>
+              <deployment>
+                <resources>
+                  <resource>
+                    <directory>${project.basedir}/target</directory>
+                    <includes>
+                      <include>*.jar</include>
+                    </includes>
+                  </resource>
+                </resources>
+              </deployment>
+            </configuration>
+          </plugin>
+        </plugins>
+      </build>
+    </profile>
+
+    <profile>
+      <id>publish</id>
+      <build>
+        <plugins>
+
+          <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-compiler-plugin</artifactId>
+          </plugin>
+          <plugin>
+            <artifactId>maven-war-plugin</artifactId>
+            <version>3.2.3</version>
+            <configuration>
+              <warSourceDirectory>src/main/webapp</warSourceDirectory>
+            </configuration>
+          </plugin>
+
+          <plugin>
+            <groupId>org.sonatype.plugins</groupId>
+            <artifactId>nexus-staging-maven-plugin</artifactId>
+            <version>1.6.8</version>
+            <extensions>true</extensions>
+            <configuration>
+              <skipRemoteStaging>true</skipRemoteStaging>
+              <serverId>ossrh</serverId>
+              <nexusUrl>https://oss.sonatype.org/</nexusUrl>
+              <autoReleaseAfterClose>true</autoReleaseAfterClose>
+            </configuration>
+          </plugin>
+
+          <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-gpg-plugin</artifactId>
+            <executions>
+              <execution>
+                <id>sign-artifacts</id>
+                <phase>verify</phase>
+                <goals>
+                  <goal>sign</goal>
+                </goals>
+              </execution>
+            </executions>
+          </plugin>
+          <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-source-plugin</artifactId>
+            <executions>
+              <execution>
+                <id>attach-sources</id>
+                <goals>
+                  <goal>jar</goal>
+                </goals>
+              </execution>
+            </executions>
+          </plugin>
+          <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-javadoc-plugin</artifactId>
+            <configuration>
+              <source>8</source>
+              <failOnError>false</failOnError>
+            </configuration>
+            <executions>
+              <execution>
+                <id>attach-javadocs</id>
+                <goals>
+                  <goal>jar</goal>
+                </goals>
+              </execution>
+            </executions>
+          </plugin>
+        </plugins>
+      </build>
+    </profile>
+  </profiles>
+</project>

samples/40.timex-resolution/src/main/java/com/microsoft/bot/sample/timex/resolution/Ambiguity.java

@@ -0,0 +1,123 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.bot.sample.timex.resolution;
+
+import com.microsoft.recognizers.text.Culture;
+import com.microsoft.recognizers.text.ModelResult;
+import com.microsoft.recognizers.text.datetime.DateTimeRecognizer;
+
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * TIMEX expressions are designed to represent ambiguous rather than definite dates.
+ * For example:
+ * "Monday" could be any Monday ever.
+ * "May 5th" could be any one of the possible May 5th in the past or the future.
+ * TIMEX does not represent ambiguous times. So if the natural language mentioned 4 o'clock
+ * it could be either 4AM or 4PM. For that the recognizer (and by extension LUIS) would return two TIMEX expressions.
+ * A TIMEX expression can include a date and time parts. So ambiguity of date can be combined with multiple results.
+ * Code that deals with TIMEX expressions is frequently dealing with sets of TIMEX expressions.
+ */
+public final class Ambiguity {
+
+    private Ambiguity() {
+    }
+
+    /**
+     * This method avoid ambiguity obtaining 2 values, backwards and forwards in the calendar.
+     */
+    public static void dateAmbiguity() {
+        // Run the recognizer.
+        List<ModelResult> results = DateTimeRecognizer.recognizeDateTime(
+            "Either Saturday or Sunday would work.",
+            Culture.English);
+
+        // We should find two results in this example.
+        for (ModelResult result : results) {
+            // The resolution includes two example values: going backwards and forwards from NOW in the calendar.
+            LinkedHashSet<String> distinctTimexExpressions = new LinkedHashSet<>();
+            List<Map<String, String>> values = (List<Map<String, String>>) result.resolution.get("values");
+            for (Map<String, String> value : values) {
+                // Each result includes a TIMEX expression that captures the inherent date but not time ambiguity.
+                // We are interested in the distinct set of TIMEX expressions.
+                String timex = value.get("timex");
+                if (timex != null) {
+                    distinctTimexExpressions.add(timex);
+                }
+
+                // There is also either a "value" property on each value or "start" and "end".
+                // If you use ToString() on a TimeProperty object you will get same "value".
+            }
+
+            // The TIMEX expression captures date ambiguity so there will be a single distinct
+            // expression for each result.
+            String output = String.format("%s ( %s )", result.text, String.join(",", distinctTimexExpressions));
+            System.out.println(output);
+
+            // The result also includes a reference to the original string
+            // but note the start and end index are both inclusive.
+        }
+    }
+
+    /**
+     * This method avoid ambiguity obtaining 2 values, one for AM and one for PM.
+     */
+    public static void timeAmbiguity() {
+        // Run the recognizer.
+        List<ModelResult> results = DateTimeRecognizer.recognizeDateTime(
+            "We would like to arrive at 4 o'clock or 5 o'clock.",
+            Culture.English);
+
+        // We should find two results in this example.
+        for (ModelResult result : results) {
+            // The resolution includes two example values: one for AM and one for PM.
+            LinkedHashSet<String> distinctTimexExpressions = new LinkedHashSet<>();
+            List<Map<String, String>> values = (List<Map<String, String>>) result.resolution.get("values");
+            for (Map<String, String> value : values) {
+                // Each result includes a TIMEX expression that captures the inherent date but not time ambiguity.
+                // We are interested in the distinct set of TIMEX expressions.
+                String timex = value.get("timex");
+                if (timex != null) {
+                    distinctTimexExpressions.add(timex);
+                }
+            }
+
+            // TIMEX expressions don't capture time ambiguity so there will be two distinct expressions for each result.
+            String output = String.format("%s ( %s )", result.text, String.join(",", distinctTimexExpressions));
+            System.out.println(output);
+        }
+    }
+
+    /**
+     * This method avoid ambiguity obtaining 4 different values,
+     * backwards and forwards in the calendar and then AM and PM.
+     */
+    public static void dateTimeAmbiguity() {
+        // Run the recognizer.
+        List<ModelResult> results = DateTimeRecognizer.recognizeDateTime(
+            "It will be ready Wednesday at 5 o'clock.",
+            Culture.English);
+
+        // We should find a single result in this example.
+        for (ModelResult result : results) {
+            // The resolution includes four example values: backwards and forward in the calendar and then AM and PM.
+            LinkedHashSet<String> distinctTimexExpressions = new LinkedHashSet<>();
+            List<Map<String, String>> values = (List<Map<String, String>>) result.resolution.get("values");
+            for (Map<String, String> value : values) {
+                // Each result includes a TIMEX expression that captures the inherent date but not time ambiguity.
+                // We are interested in the distinct set of TIMEX expressions.
+                String timex = value.get("timex");
+                if (timex != null) {
+                    distinctTimexExpressions.add(timex);
+                }
+            }
+
+            // TIMEX expressions don't capture time ambiguity so there will be two distinct expressions for each result.
+            String output = String.format("%s ( %s )", result.text, String.join(",", distinctTimexExpressions));
+            System.out.println(output);
+        }
+    }
+}