Merge pull request #214 from rosette-api/RLPNC-7350-return-multi-translations

RLPNC-7350: Rosapi returns a list of RNT results

Author: fhasanaj

api/src/test/java/com/basistech/rosette/api/RosetteAPITest.java

@@ -258,11 +258,34 @@ void testTranslateName(String testFilename, String responseStr, int statusCode)
         }
     }
 
+    private static Stream<Arguments> testMultiTranslateNameParameters() throws IOException {
+        return getTestFiles("-multi-name-translation.json");
+    }
+
+    @ParameterizedTest(name = "testFilename: {0}; statusCode: {2}")
+    @MethodSource("testMultiTranslateNameParameters")
+    void testMultiTranslateName(String testFilename, String responseStr, int statusCode) throws IOException {
+        setStatusCodeResponse(responseStr, statusCode);
+        NameTranslationRequest request = readValueNameTranslation(testFilename);
+        try {
+            NameTranslationResponse response = api.perform(AbstractRosetteAPI.NAME_TRANSLATION_SERVICE_PATH, request,
+                    NameTranslationResponse.class);
+            verifyMultiNameTranslations(response, responseStr);
+        } catch (HttpRosetteAPIException e) {
+            verifyException(e, responseStr);
+        }
+    }
+
     private void verifyNameTranslation(NameTranslationResponse response, String responseStr) throws IOException {
         NameTranslationResponse goldResponse = mapper.readValue(responseStr, NameTranslationResponse.class);
         assertEquals(goldResponse.getTranslation(), response.getTranslation());
     }
 
+    private void verifyMultiNameTranslations(NameTranslationResponse response, String responseStr) throws IOException {
+        NameTranslationResponse goldResponse = mapper.readValue(responseStr, NameTranslationResponse.class);
+        assertEquals(goldResponse.getTranslations(), response.getTranslations());
+    }
+
     private NameTranslationRequest readValueNameTranslation(String testFilename) throws IOException {
         File input = new File("src/test/mock-data/request", testFilename);
         return mapper.readValue(input, NameTranslationRequest.class);

api/src/test/mock-data/request/rnt-1-multi-name-translation.json

@@ -0,0 +1,11 @@
+{
+  "entityType": "PERSON",
+  "name": "معمر محمد أبو منيار القذاف", 
+  "sourceLanguageOfOrigin": "ara", 
+  "sourceLanguageOfUse": "ara", 
+  "sourceScript": "Arab", 
+  "targetLanguage": "eng", 
+  "targetScheme": "IC", 
+  "targetScript": "Latn",
+  "maximumResults": 10
+}

api/src/test/mock-data/response/rnt-1-multi-name-translation.json

@@ -0,0 +1,49 @@
+{
+  "sourceScript": "Arab",
+  "sourceLanguageOfUse": "ara",
+  "targetLanguage": "eng",
+  "targetScript": "Latn",
+  "targetScheme": "IC",
+  "translations": [
+    {
+      "translatio": "Mu'ammar Muhammad Abu-Minyar al-Qadhaf",
+      "confidence": 0.10655738
+    },
+    {
+      "translation": "Mu'ammar Muhammad Abu-Minyar al-Qadhaf",
+      "confidence": 0.10382514
+    },
+    {
+      "translation": "Mu'ammar Muhammad Abaw Minyar al-Qadhaf",
+      "confidence": 0.1010929
+    },
+    {
+      "translation": "Mu'ammar Muhammad Abu-Minyar al-Qadhaf",
+      "confidence": 0.10094909
+    },
+    {
+      "translation": "Mu'ammar Mhammad Abu-Minyar al-Qadhaf",
+      "confidence": 0.10094909
+    },
+    {
+      "translation": "Mu'ammar Muhammad Abu-Minyar al-Qadhaf",
+      "confidence": 0.09836066
+    },
+    {
+      "translation": "Mu'ammar Muhammad Abw Minyar al-Qadhaf",
+      "confidence": 0.09836066
+    },
+    {
+      "translation": "Mu'ammar Mhammad Abu-Minyar al-Qadhaf",
+      "confidence": 0.09836066
+    },
+    {
+      "translation": "Mu'ammar Muhammad Abaw Minyar al-Qadhaf",
+      "confidence": 0.09577222
+    },
+    {
+      "translation": "Mu'ammar Mhammad Abaw Minyar al-Qadhaf",
+      "confidence": 0.09577222
+    }
+  ]
+}

api/src/test/mock-data/response/rnt-1-multi-name-translation.status

@@ -0,0 +1 @@
+200

examples/src/main/java/com/basistech/rosette/examples/NameMultipleTranslationsExample.java

@@ -0,0 +1,58 @@
+/*
+* Copyright 2024 Basis Technology Corp.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+package com.basistech.rosette.examples;
+
+import static com.basistech.rosette.api.common.AbstractRosetteAPI.NAME_TRANSLATION_SERVICE_PATH;
+
+import java.io.IOException;
+
+import com.basistech.rosette.api.HttpRosetteAPI;
+import com.basistech.rosette.apimodel.NameTranslationRequest;
+import com.basistech.rosette.apimodel.NameTranslationResponse;
+import com.basistech.util.LanguageCode;
+
+/**
+ * Example which demonstrates the name translation api with maximumResults option set.
+ */
+@SuppressWarnings({"java:S1166", "java:S2221", "java:S106"})
+public final class NameMultipleTranslationsExample extends ExampleBase {
+    public static void main(String[] args) {
+        try {
+            new NameMultipleTranslationsExample().run();
+        } catch (Exception e) {
+            e.printStackTrace();
+            System.exit(1);
+        }
+    }
+
+    private void run() throws IOException {
+        String translatedNameData = "معمر محمد أبو منيار القذاف";
+        NameTranslationRequest request = NameTranslationRequest.builder()
+                .name(translatedNameData)
+                .targetLanguage(LanguageCode.ENGLISH)
+                .maximumResults(10)
+                .build();
+
+        HttpRosetteAPI rosetteApi = new HttpRosetteAPI.Builder()
+                                    .key(getApiKeyFromSystemProperty())
+                                    .url(getAltUrlFromSystemProperty())
+                                    .build();
+        //The api object creates an http client, but to provide your own:
+        //api.httpClient(CloseableHttpClient)
+        NameTranslationResponse response = rosetteApi.perform(NAME_TRANSLATION_SERVICE_PATH, request, NameTranslationResponse.class);
+        System.out.println(responseToJson(response));
+    }
+}

json/src/main/java/com/basistech/rosette/apimodel/jackson/NameTranslationRequestMixin.java

@@ -41,7 +41,8 @@ protected NameTranslationRequestMixin(
             @JsonProperty("sourceLanguageOfUse") LanguageCode sourceLanguageOfUse,
             @JsonProperty("targetLanguage") LanguageCode targetLanguage,
             @JsonProperty("targetScript") ISO15924 targetScript,
-            @JsonProperty("targetScheme") TransliterationScheme targetScheme
+            @JsonProperty("targetScheme") TransliterationScheme targetScheme,
+            @JsonProperty("maximumResults") Integer maximumResults
     ) {
         //
     }

model/src/main/java/com/basistech/rosette/apimodel/NameTranslation.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2024 Basis Technology Corp.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.basistech.rosette.apimodel;
+
+import lombok.Builder;
+import lombok.EqualsAndHashCode;
+import lombok.Getter;
+
+import com.basistech.rosette.annotations.JacksonMixin;
+
+@Getter
+@EqualsAndHashCode
+@Builder
+@JacksonMixin
+public class NameTranslation {
+    String translation;
+    Double confidence;
+
+    public NameTranslation(String translation, Double confidence) {
+        this.translation = translation;
+        this.confidence = confidence;
+    }
+}

model/src/main/java/com/basistech/rosette/apimodel/NameTranslationRequest.java

@@ -72,7 +72,11 @@ public final class NameTranslationRequest extends Request {
      */
     private final TransliterationScheme targetScheme;
 
-    @Builder     // workaround for inheritance https://github.com/rzwitserloot/lombok/issues/853
+    /**
+     * @return the maximum number of translation results to return
+     */
+    private final Integer maximumResults;
+
     public NameTranslationRequest(String profileId,
                                    String name,
                                    String entityType,
@@ -82,6 +86,20 @@ public NameTranslationRequest(String profileId,
                                    LanguageCode targetLanguage,
                                    ISO15924 targetScript,
                                    TransliterationScheme targetScheme) {
+        this(profileId, name, entityType, sourceScript, sourceLanguageOfOrigin, sourceLanguageOfUse, targetLanguage, targetScript, targetScheme, null);
+    }
+
+    @Builder     // workaround for inheritance https://github.com/rzwitserloot/lombok/issues/853
+    public NameTranslationRequest(String profileId,
+                                  String name,
+                                  String entityType,
+                                  ISO15924 sourceScript,
+                                  LanguageCode sourceLanguageOfOrigin,
+                                  LanguageCode sourceLanguageOfUse,
+                                  LanguageCode targetLanguage,
+                                  ISO15924 targetScript,
+                                  TransliterationScheme targetScheme,
+                                  Integer maximumResults) {
         super(profileId);
         this.name = name;
         this.entityType = entityType;
@@ -91,5 +109,6 @@ public NameTranslationRequest(String profileId,
         this.targetLanguage = targetLanguage;
         this.targetScript = targetScript;
         this.targetScheme = targetScheme;
+        this.maximumResults = maximumResults;
     }
 }

model/src/main/java/com/basistech/rosette/apimodel/NameTranslationResponse.java

@@ -16,6 +16,8 @@
 
 package com.basistech.rosette.apimodel;
 
+import java.util.List;
+
 import com.basistech.rosette.annotations.JacksonMixin;
 import com.basistech.util.ISO15924;
 import com.basistech.util.LanguageCode;
@@ -72,4 +74,9 @@ public class NameTranslationResponse extends Response {
      * @return the translation confidence (0.0-1.0)
      */
     private final Double confidence;
+
+    /**
+     * @return the translation
+     */
+    private final List<NameTranslation> translations;
 }