Add Translate.translate methods and tests

gcloud-java-translate/src/main/java/com/google/cloud/translate/Translate.java

@@ -51,6 +51,38 @@ public static LanguageListOption targetLanguage(String targetLanguage) {
     }
   }
 
+  /**
+   * Class for specifying translate options.
+   */
+  class TranslateOption extends Option {
+
+    private static final long serialVersionUID = 1347871763933507106L;
+
+    private TranslateOption(TranslateRpc.Option rpcOption, String value) {
+      super(rpcOption, value);
+    }
+
+    /**
+     * Returns an option for setting the source language. If not provided, Google Translate will try
+     * to detect the language of the text to translate.
+     *
+     * @param sourceLanguage the source language code
+     */
+    public static TranslateOption sourceLanguage(String sourceLanguage) {
+      return new TranslateOption(TranslateRpc.Option.SOURCE_LANGUAGE, sourceLanguage);
+    }
+
+    /**
+     * Returns an option for setting the target language. If this option is not provided, the value
+     * returned by {@link TranslateOptions#targetLanguage()} is used.
+     *
+     * @param targetLanguage the target language code
+     */
+    public static TranslateOption targetLanguage(String targetLanguage) {
+      return new TranslateOption(TranslateRpc.Option.TARGET_LANGUAGE, targetLanguage);
+    }
+  }
+
   /**
    * Returns the list of languages supported by Google Translate. If
    * {@link LanguageListOption#targetLanguage(String)} is provided, {@link Language#name()} values
@@ -112,4 +144,48 @@ public static LanguageListOption targetLanguage(String targetLanguage) {
    * }</pre>
    */
   Detection detect(String text);
+
+  /**
+   * Translates the provided texts.
+   *
+   * <p>Example of translating some texts:
+   * <pre> {@code
+   * List<String> texts = new LinkedList<>();
+   * texts.add("Hello, World!");
+   * texts.add("¡Hola Mundo!");
+   * List<Translation> translations = translate.translate(texts);
+   * }</pre>
+   *
+   * <p>Example of translating some texts, specifying source and target language:
+   * <pre> {@code
+   * List<String> texts = new LinkedList<>();
+   * texts.add("¡Hola Mundo!");
+   * List<Translation> translations = translate.translate(texts,
+   *     TranslateOption.sourceLanguage("es"), TranslateOption.targetLanguage("de"));
+   * }</pre>
+   *
+   * @param texts the texts to translate
+   * @return a list of objects containing information on the language translation, one for each
+   *     provided text, in order.
+   */
+  List<Translation> translate(List<String> texts, TranslateOption... options);
+
+  /**
+   * Translates the provided texts.
+   *
+   * <p>Example of translating a text:
+   * <pre> {@code
+   * Translation translation = translate.translate("¡Hola Mundo!");
+   * }</pre>
+   *
+   * <p>Example of translating a text, specifying source and target language:
+   * <pre> {@code
+   * Translation translation = translate.translate("¡Hola Mundo!",
+   *     TranslateOption.sourceLanguage("es"), TranslateOption.targetLanguage("de"));
+   * }</pre>
+   *
+   * @param text the text to translate
+   * @return an object containing information on the language translation
+   */
+  Translation translate(String text, TranslateOption... options);
 }

gcloud-java-translate/src/main/java/com/google/cloud/translate/TranslateImpl.java

@@ -22,6 +22,7 @@
 
 import com.google.api.services.translate.model.DetectionsResourceItems;
 import com.google.api.services.translate.model.LanguagesResource;
+import com.google.api.services.translate.model.TranslationsResource;
 import com.google.cloud.BaseService;
 import com.google.cloud.RetryHelper.RetryHelperException;
 import com.google.cloud.translate.spi.TranslateRpc;
@@ -102,6 +103,26 @@ public Detection detect(String text) {
     return detect(Collections.singletonList(text)).get(0);
   }
 
+  @Override
+  public List<Translation> translate(final List<String> texts, final TranslateOption... options) {
+    try {
+      return Lists.transform(runWithRetries(new Callable<List<TranslationsResource>>() {
+        @Override
+        public List<TranslationsResource> call() {
+          return translateRpc.translate(texts, optionMap(options));
+        }
+      }, options().retryParams(), EXCEPTION_HANDLER, options().clock()),
+          Translation.FROM_PB_FUNCTION);
+    } catch (RetryHelperException e) {
+      throw TranslateException.translateAndThrow(e);
+    }
+  }
+
+  @Override
+  public Translation translate(String text, TranslateOption... options) {
+    return translate(Collections.singletonList(text), options).get(0);
+  }
+
   private Map<TranslateRpc.Option, ?> optionMap(Option... options) {
     Map<TranslateRpc.Option, Object> optionMap = Maps.newEnumMap(TranslateRpc.Option.class);
     for (Option option : options) {

gcloud-java-translate/src/main/java/com/google/cloud/translate/TranslateOptions.java

@@ -20,11 +20,13 @@
 
 import com.google.cloud.AuthCredentials;
 import com.google.cloud.HttpServiceOptions;
+import com.google.cloud.translate.Translate.TranslateOption;
 import com.google.cloud.translate.spi.DefaultTranslateRpc;
 import com.google.cloud.translate.spi.TranslateRpc;
 import com.google.cloud.translate.spi.TranslateRpcFactory;
 import com.google.common.collect.ImmutableSet;
 
+import java.util.List;
 import java.util.Locale;
 import java.util.Set;
 
@@ -96,6 +98,10 @@ public Builder authCredentials(AuthCredentials authCredentials) {
 
     /**
      * Sets the code for the default target language. If not set, english ({@code en}) is used.
+     * {@link Translate#translate(List, TranslateOption...)} and
+     * {@link Translate#translate(String, TranslateOption...)} calls will use this
+     * value unless a {@link TranslateOption#targetLanguage(String)} option is explicitly
+     * provided.
      *
      * @return the builder
      */

gcloud-java-translate/src/test/java/com/google/cloud/translate/TranslateImplTest.java

@@ -21,8 +21,10 @@
 
 import com.google.api.services.translate.model.DetectionsResourceItems;
 import com.google.api.services.translate.model.LanguagesResource;
+import com.google.api.services.translate.model.TranslationsResource;
 import com.google.cloud.RetryParams;
 import com.google.cloud.translate.Translate.LanguageListOption;
+import com.google.cloud.translate.Translate.TranslateOption;
 import com.google.cloud.translate.spi.TranslateRpc;
 import com.google.cloud.translate.spi.TranslateRpcFactory;
 import com.google.common.collect.ImmutableList;
@@ -63,6 +65,12 @@ public class TranslateImplTest {
       new DetectionsResourceItems().setLanguage("en").setConfidence(0.8F);
   private static final Detection DETECTION1 = Detection.fromPb(DETECTION1_PB);
   private static final Detection DETECTION2 = Detection.fromPb(DETECTION2_PB);
+  private static final TranslationsResource TRANSLATION1_PB =
+      new TranslationsResource().setTranslatedText("Hello World!").setDetectedSourceLanguage("es");
+  private static final TranslationsResource TRANSLATION2_PB =
+      new TranslationsResource().setTranslatedText("Hello World!").setDetectedSourceLanguage("de");
+  private static final Translation TRANSLATION1 = Translation.fromPb(TRANSLATION1_PB);
+  private static final Translation TRANSLATION2 = Translation.fromPb(TRANSLATION2_PB);
 
   // Empty TranslateRpc options
   private static final Map<TranslateRpc.Option, ?> EMPTY_RPC_OPTIONS = ImmutableMap.of();
@@ -73,6 +81,15 @@ public class TranslateImplTest {
   private static final Map<TranslateRpc.Option, ?> LANGUAGE_LIST_OPTIONS = ImmutableMap.of(
       TranslateRpc.Option.TARGET_LANGUAGE, LANGUAGE_LIST_OPTION.value());
 
+  // Translate options
+  private static final TranslateOption TARGET_LANGUAGE_OPTION =
+      TranslateOption.targetLanguage("en");
+  private static final TranslateOption SOURCE_LANGUAGE_OPTION =
+      TranslateOption.sourceLanguage("de");
+  private static final Map<TranslateRpc.Option, ?> TRANSLATE_OPTIONS = ImmutableMap.of(
+      TranslateRpc.Option.TARGET_LANGUAGE, TARGET_LANGUAGE_OPTION.value(),
+      TranslateRpc.Option.SOURCE_LANGUAGE, SOURCE_LANGUAGE_OPTION.value());
+
   private TranslateOptions options;
   private TranslateRpcFactory rpcFactoryMock;
   private TranslateRpc translateRpcMock;
@@ -249,6 +266,51 @@ public void testDetectVarargNoDetection() {
     translate.detect(text1, text2);
   }
 
+  @Test
+  public void testTranslate() {
+    String text = "¡Hola Mundo!";
+    EasyMock.expect(translateRpcMock.translate(ImmutableList.of(text), EMPTY_RPC_OPTIONS))
+        .andReturn(ImmutableList.of(TRANSLATION1_PB));
+    EasyMock.replay(translateRpcMock);
+    initializeService();
+    assertEquals(TRANSLATION1, translate.translate(text));
+  }
+
+  @Test
+  public void testTranslateWithOptions() {
+    String text = "Hallo Welt!";
+    EasyMock.expect(translateRpcMock.translate(ImmutableList.of(text), TRANSLATE_OPTIONS))
+        .andReturn(ImmutableList.of(TRANSLATION2_PB));
+    EasyMock.replay(translateRpcMock);
+    initializeService();
+    assertEquals(TRANSLATION2,
+        translate.translate(text, TARGET_LANGUAGE_OPTION, SOURCE_LANGUAGE_OPTION));
+  }
+
+  @Test
+  public void testTranslateList() {
+    String text1 = "¡Hola Mundo!";
+    String text2 = "Hallo Welt!";
+    List<String> texts = ImmutableList.of(text1, text2);
+    EasyMock.expect(translateRpcMock.translate(texts, EMPTY_RPC_OPTIONS))
+        .andReturn(ImmutableList.of(TRANSLATION1_PB, TRANSLATION2_PB));
+    EasyMock.replay(translateRpcMock);
+    initializeService();
+    assertEquals(ImmutableList.of(TRANSLATION1, TRANSLATION2), translate.translate(texts));
+  }
+
+  @Test
+  public void testTranslateListWithOptions() {
+    String text = "Hallo Welt!";
+    List<String> texts = ImmutableList.of(text);
+    EasyMock.expect(translateRpcMock.translate(texts, TRANSLATE_OPTIONS))
+        .andReturn(ImmutableList.of(TRANSLATION2_PB));
+    EasyMock.replay(translateRpcMock);
+    initializeService();
+    assertEquals(ImmutableList.of(TRANSLATION2),
+        translate.translate(texts, TARGET_LANGUAGE_OPTION, SOURCE_LANGUAGE_OPTION));
+  }
+
   @Test
   public void testRetryableException() {
     EasyMock.expect(translateRpcMock.listSupportedLanguages(EMPTY_RPC_OPTIONS))