Merge pull request #23 from googleads/new_address_fields

feat(formatter): add formatting methods for new GA4 address info fields

Author: lindsey-volta

data-manager-util/build.gradle

@@ -21,7 +21,7 @@ plugins {
 
 group = 'com.google.api-ads'
 description = 'Utilities for working with the Data Manager API'
-version = '0.3.0'
+version = '0.4.0'
 
 sourceCompatibility = 1.8
 targetCompatibility = 1.8

data-manager-util/src/main/java/com/google/ads/datamanager/util/UserDataFormatter.java

@@ -90,6 +90,9 @@ public class UserDataFormatter {
   /** Pattern that matches all uppercase characters. */
   private static final Pattern ALL_UPPERCASE_CHARS_PATTERN = Pattern.compile("^[A-Z]+$");
 
+  /** Pattern that matches all non-alphanumeric characters, except spaces. */
+  private static final Pattern SYMBOL_PATTERN = Pattern.compile("[^\\p{L}\\p{N}\\s]");
+
   private UserDataFormatter(MessageDigest sha256Digest) {
     this.sha256Digest = sha256Digest;
   }
@@ -267,6 +270,55 @@ public String formatPostalCode(String postalCode) {
     return postalCode;
   }
 
+  /**
+   * Returns the normalized and formatted location string.
+   *
+   * @param value the string to format
+   * @param label the label used for error messages
+   * @throws IllegalArgumentException if {@code value} is invalid. Examples of an invalid value
+   *     include a {@code null}, blank, or empty string.
+   */
+  private String formatLocationString(String value, String label) {
+    Preconditions.checkArgument(value != null, "Null %s", label);
+    value = value.trim().toLowerCase(LOCALE);
+    value = SYMBOL_PATTERN.matcher(value).replaceAll("");
+    Preconditions.checkArgument(!value.isEmpty(), "Empty or blank %s", label);
+    return value;
+  }
+
+  /**
+   * Returns the provided address line, normalized and formatted.
+   *
+   * @param addressLine the address line to format
+   * @throws IllegalArgumentException if {@code addressLine} is invalid. Examples of an invalid value
+   *     include a {@code null}, blank, or empty string.
+   */
+  public String formatAddressLine(String addressLine) {
+    return formatLocationString(addressLine, "address line");
+  }
+
+  /**
+   * Returns the provided city, normalized and formatted.
+   *
+   * @param city the city to format
+   * @throws IllegalArgumentException if {@code city} is invalid. Examples of an invalid value
+   *     include a {@code null}, blank, or empty string.
+   */
+  public String formatCity(String city) {
+    return formatLocationString(city, "city");
+  }
+
+  /**
+   * Returns the provided administrative area, normalized and formatted.
+   *
+   * @param administrativeArea the administrative area to format
+   * @throws IllegalArgumentException if {@code administrativeArea} is invalid. Examples of an invalid value
+   *     include a {@code null}, blank, or empty string.
+   */
+  public String formatAdministrativeArea(String administrativeArea) {
+    return formatLocationString(administrativeArea, "administrative area");
+  }
+
   /**
    * Returns the SHA-256 hash of the provided string.
    *
@@ -474,6 +526,75 @@ public String processPostalCode(String postalCode) {
     return formatPostalCode(postalCode);
   }
 
+  /**
+   * Formats the address line, hashes, and encodes using the specified encoding.
+   *
+   * <p>This is a convenience method that combines {@link #formatAddressLine(String)}, {@link
+   * #hashString(String)}, and either {@link #hexEncode(byte[])} or {@link #base64Encode(byte[])}
+   * into a single call.
+   *
+   * @return the address line, formatted, hashed, and encoded for the {@code AddressInfo.address_line}
+   *     field in the API.
+   * @throws IllegalArgumentException if the address line is invalid
+   */
+  public String processAddressLine(String addressLine, Encoding encoding) {
+    return hashAndEncode(formatAddressLine(addressLine), encoding);
+  }
+
+  /**
+   * Formats the address line, hashes, base 64-encodes, encrypts, and encodes using the specified
+   * encoding.
+   *
+   * <p>This is a convenience method that combines {@link #formatAddressLine(String)}, {@link
+   * #hashString(String)}, {@link #base64Encode(byte[])}, {@link Encrypter#encrypt(String)}, and
+   * either {@link #hexEncode(byte[])} or {@link #base64Encode(byte[])} into a single call.
+   *
+   * @return the address line, formatted, hashed, encrypted, and encoded for the {@code
+   *     AddressInfo.address_line} field in the API.
+   * @throws IllegalArgumentException if the address line is invalid
+   * @throws NullPointerException if {@code encrypter} is null
+   */
+  public String processAddressLine(String addressLine, Encoding encoding, Encrypter encrypter) {
+    Preconditions.checkNotNull(encrypter, "Null encrypter");
+    return hashEncodeAndEncrypt(formatAddressLine(addressLine), encoding, encrypter);
+  }
+
+  /**
+   * Processes the city.
+   *
+   * <p>This is a convenience method that simply calls {@link #formatCity(String)}. This
+   * method exists for consistency so that all data types have a {@code process...} method.
+   *
+   * <p>Doesn't require an {@link Encoding} since cities shouldn't be encoded or hashed.
+   *
+   * <p>There is no overloaded counterpart that takes an {@link Encrypter} since cities
+   * shouldn't be encrypted.
+   *
+   * @return the city, formatted for the {@code AddressInfo.city} field in the API.
+   * @throws IllegalArgumentException if the city is invalid
+   */
+  public String processCity(String city) {
+    return formatCity(city);
+  }
+
+  /**
+   * Processes the administrative area.
+   *
+   * <p>This is a convenience method that simply calls {@link #formatAdministrativeArea(String)}. This
+   * method exists for consistency so that all data types have a {@code process...} method.
+   *
+   * <p>Doesn't require an {@link Encoding} since administrative areas shouldn't be encoded or hashed.
+   *
+   * <p>There is no overloaded counterpart that takes an {@link Encrypter} since administrative areas
+   * shouldn't be encrypted.
+   *
+   * @return the administrative area, formatted for the {@code AddressInfo.administrative_area} field in the API.
+   * @throws IllegalArgumentException if the administrative area is invalid
+   */
+  public String processAdministrativeArea(String administrativeArea) {
+    return formatAdministrativeArea(administrativeArea);
+  }
+
   /**
    * Hashes the string and then encodes using the specified encoding.
    *

data-manager-util/src/test/java/com/google/ads/datamanager/util/UserDataFormatterTest.java

@@ -238,6 +238,72 @@ public void testFormatPostalCode_invalidInputs() {
         () -> formatter.formatPostalCode("  "));
   }
 
+  @Test
+  public void testFormatAddressLine_validInputs() {
+    assertEquals("1800 amphibious blvd", formatter.formatAddressLine(" 1800 Amphibious Blvd.  "));
+  }
+
+  @Test
+  public void testFormatAddressLine_invalidInputs() {
+    assertThrows(
+        "Null address line",
+        IllegalArgumentException.class,
+        () -> formatter.formatAddressLine(null));
+    assertThrows(
+        "Empty address line",
+        IllegalArgumentException.class,
+        () -> formatter.formatAddressLine(""));
+    assertThrows(
+        "Blank address line",
+        IllegalArgumentException.class,
+        () -> formatter.formatAddressLine("   "));
+  }
+
+  @Test
+  public void testFormatCity_validInputs() {
+    assertEquals("mountain view", formatter.formatCity(" Mountain View  "));
+    assertEquals("mountain view", formatter.formatCity("Mountain View,"));
+  }
+
+  @Test
+  public void testFormatCity_invalidInputs() {
+    assertThrows(
+        "Null city",
+        IllegalArgumentException.class,
+        () -> formatter.formatCity(null));
+    assertThrows(
+        "Empty city",
+        IllegalArgumentException.class,
+        () -> formatter.formatCity(""));
+    assertThrows(
+        "Blank city",
+        IllegalArgumentException.class,
+        () -> formatter.formatCity("   "));
+  }
+
+  @Test
+  public void testFormatAdministrativeArea_validInputs() {
+    assertEquals("ca", formatter.formatAdministrativeArea(" CA  "));
+    assertEquals("california", formatter.formatAdministrativeArea(" California  "));
+    assertEquals("ca", formatter.formatAdministrativeArea("CA,"));
+  }
+
+  @Test
+  public void testFormatAdministrativeArea_invalidInputs() {
+    assertThrows(
+        "Null administrative area",
+        IllegalArgumentException.class,
+        () -> formatter.formatAdministrativeArea(null));
+    assertThrows(
+        "Empty administrative area",
+        IllegalArgumentException.class,
+        () -> formatter.formatAdministrativeArea(""));
+    assertThrows(
+        "Blank administrative area",
+        IllegalArgumentException.class,
+        () -> formatter.formatAdministrativeArea("   "));
+  }
+
   @Test
   public void testHashString_validInputs() {
     Function<String, String> hashAndEncode = s -> hexEncoder.encode(formatter.hashString(s));
@@ -247,6 +313,9 @@ public void testHashString_validInputs() {
     assertEquals(
         "FB4F73A6EC5FDB7077D564CDD22C3554B43CE49168550C3B12C547B78C517B30",
         hashAndEncode.apply("+18005550100"));
+    assertEquals(
+        "FF75E73A0E768CC1FA28A64FAEBBCECCB562D7C05F2FFCDD8D100ABAD73E4579",
+        hashAndEncode.apply("1800 amphibious blvd"));
   }
 
   @Test
@@ -377,4 +446,30 @@ public void testProcessPostalCode_validInputs() {
     assertEquals("1229-076", formatter.formatPostalCode("1229-076"));
     assertEquals("1229-076", formatter.formatPostalCode(" 1229-076  "));
   }
+
+  @Test
+  public void testProcessAddressLine_validInputs_hexEncoding() {
+    final String encodedHash = "FF75E73A0E768CC1FA28A64FAEBBCECCB562D7C05F2FFCDD8D100ABAD73E4579";
+    assertEquals(
+        encodedHash,
+        formatter.processAddressLine(" 1800 Amphibious Blvd.  ", Encoding.HEX));
+  }
+
+  @Test
+  public void testProcessAddressLine_validInputs_base64Encoding() {
+    final String encodedHash = "/3XnOg52jMH6KKZPrrvOzLVi18BfL/zdjRAKutc+RXk=";
+    assertEquals(
+        encodedHash,
+        formatter.processAddressLine(" 1800 Amphibious Blvd.  ", Encoding.BASE64));
+  }
+
+  @Test
+  public void testProcessCity_validInputs() {
+    assertEquals("mountain view", formatter.processCity(" Mountain View  "));
+  }
+
+  @Test
+  public void testProcessAdministrativeArea_validInputs() {
+    assertEquals("ca", formatter.processAdministrativeArea(" CA  "));
+  }
 }