JAVA: Metadata changes, introduction of PhoneNumberOfflineGeocoder class and small fixes.

java/release_notes.txt

@@ -1,3 +1,13 @@
+May 24th, 2011
+* Code changes:
+ - Phonenumber now implements Serializable.
+ - findNumbers doesn't accept numbers with mis-matched brackets as phone-numbers
+ - An offline phone number geocoder has been added. The current implementation just returns the
+   region name for the phone number; more detailed geocoding will be added later.
+* Metadata changes:
+ - New countries: GF, KP, NC, PA, PF, PW, PY, SB, SR, TO, UY, VU
+ - Updates: CY, CZ, ES, GB, GQ, JM, MQ, TN, VI
+
 May 9th, 2011
 * Code changes:
  - Fixed potential for a null-ptr exception in getExampleNumber

java/src/com/google/i18n/phonenumbers/PhoneNumberMatcher.java

@@ -69,6 +69,13 @@ final class PhoneNumberMatcher implements Iterator<PhoneNumberMatch> {
   private static final Pattern SLASH_SEPARATED_DATES =
       Pattern.compile("(?:(?:[0-3]?\\d/[01]?\\d)|(?:[01]?\\d/[0-3]?\\d))/(?:[12]\\d)?\\d{2}");
 
+  /**
+   * Pattern to check that brackets match. Opening brackets should be closed within a phone number.
+   * This also checks that there is something inside the brackets. Having no brackets at all is also
+   * fine.
+   */
+  private static final Pattern MATCHING_BRACKETS;
+
   /**
    * Matches white-space, which may indicate the end of a phone number and the start of something
    * else (such as a neighbouring zip-code).
@@ -76,8 +83,25 @@ final class PhoneNumberMatcher implements Iterator<PhoneNumberMatch> {
   private static final Pattern GROUP_SEPARATOR = Pattern.compile("\\p{Z}+");
 
   static {
-    /* Builds the PATTERN regular expression. The building blocks below exist to make the pattern
-     * more easily understood. */
+    /* Builds the MATCHING_BRACKETS and PATTERN regular expressions. The building blocks below exist
+     * to make the pattern more easily understood. */
+
+    String openingParens = "(\\[\uFF08\uFF3B";
+    String closingParens = ")\\]\uFF09\uFF3D";
+    String nonParens = "[^" + openingParens + closingParens + "]";
+
+    /* Limit on the number of pairs of brackets in a phone number. */
+    String bracketPairLimit = limit(0, 3);
+    /*
+     * An opening bracket at the beginning may not be closed, but subsequent ones should be.  It's
+     * also possible that the leading bracket was dropped, so we shouldn't be surprised if we see a
+     * closing bracket first. We limit the sets of brackets in a phone number to four.
+     */
+    MATCHING_BRACKETS = Pattern.compile(
+        "(?:[" + openingParens + "])?" + "(?:" + nonParens + "+" + "[" + closingParens + "])?" +
+        nonParens + "+" +
+        "(?:[" + openingParens + "]" + nonParens + "+[" + closingParens + "])" + bracketPairLimit +
+        nonParens + "*");
 
     /* Limit on the number of leading (plus) characters. */
     String leadLimit = limit(0, 2);
@@ -97,7 +121,7 @@ final class PhoneNumberMatcher implements Iterator<PhoneNumberMatch> {
     /* A digits block without punctuation. */
     String digitSequence = "\\p{Nd}" + limit(1, digitBlockLimit);
     /* Punctuation that may be at the start of a phone number - brackets and plus signs. */
-    String leadClass = "[(\\[" + PhoneNumberUtil.PLUS_CHARS + "]";
+    String leadClass = "[" + openingParens + PhoneNumberUtil.PLUS_CHARS + "]";
 
     /* Phone number pattern allowing optional punctuation. */
     PATTERN = Pattern.compile(
@@ -321,6 +345,11 @@ final class PhoneNumberMatcher implements Iterator<PhoneNumberMatch> {
    */
   private PhoneNumberMatch parseAndVerify(String candidate, int offset) {
     try {
+      // Check the candidate doesn't contain any formatting which would indicate that it really
+      // isn't a phone number.
+      if (!MATCHING_BRACKETS.matcher(candidate).matches()) {
+        return null;
+      }
       PhoneNumber number = util.parse(candidate, preferredRegion);
       if (leniency.verify(number, util)) {
         return new PhoneNumberMatch(offset, candidate, number);

java/src/com/google/i18n/phonenumbers/PhoneNumberOfflineGeocoder.java

@@ -0,0 +1,78 @@
+/*
+ * Copyright (C) 2011 Google Inc.
+ *
+ * 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.google.i18n.phonenumbers;
+
+import com.google.i18n.phonenumbers.Phonenumber.PhoneNumber;
+
+import java.util.Locale;
+
+/**
+ * A offline geocoder which provides geographical information related to a phone number.
+ *
+ * @author Shaopeng Jia
+ */
+public class PhoneNumberOfflineGeocoder {
+  private static PhoneNumberOfflineGeocoder instance = null;
+  private PhoneNumberUtil phoneUtil;
+
+  /**
+   * For testing purposes, we allow the phone number util variable to be injected.
+   */
+  PhoneNumberOfflineGeocoder(PhoneNumberUtil phoneUtil) {
+    this.phoneUtil = phoneUtil;
+  }
+
+  /**
+   * Gets a {@link PhoneNumberOfflineGeocoder} instance to carry out international phone number
+   * geocoding.
+   *
+   * <p> The {@link PhoneNumberOfflineGeocoder} is implemented as a singleton. Therefore, calling
+   * this method multiple times will only result in one instance being created.
+   * 
+   * @return  a {@link PhoneNumberOfflineGeocoder} instance
+   */
+  public static synchronized PhoneNumberOfflineGeocoder getInstance() {
+    if (instance == null) {
+      instance = new PhoneNumberOfflineGeocoder(PhoneNumberUtil.getInstance());
+    }
+    return instance;
+  }
+
+  /**
+   * Returns the customary display name in the given language for the given territory the phone
+   * number is from.
+   */
+  private String getCountryNameForNumber(PhoneNumber number, Locale language) {
+    String regionCode = phoneUtil.getRegionCodeForNumber(number);
+    return (regionCode == null || regionCode.equals("ZZ"))
+        ? "" : new Locale("", regionCode).getDisplayCountry(language);
+  }
+
+  /**
+   * Returns a text description in the given language for the given phone number. The
+   * description might consist of the name of the country where the phone number is from and/or the
+   * name of the geographical area the phone number is from.
+   *
+   * @param number  the phone number for which we want to get a text description
+   * @param language  the language in which the description should be written
+   * @return  a text description in the given language for the given phone number
+   */
+  public String getDescriptionForNumber(PhoneNumber number, Locale language) {
+    // TODO: Implement logic to figure out fine-grained geographical information based
+    // on area code here.
+    return getCountryNameForNumber(number, language);
+  }
+}

java/src/com/google/i18n/phonenumbers/Phonenumber.java

@@ -22,9 +22,12 @@
 
 package com.google.i18n.phonenumbers;
 
+import java.io.Serializable;
+
 public final class Phonenumber {
   private Phonenumber() {}
-  public static class PhoneNumber {
+  public static class PhoneNumber implements Serializable {
+    private static final long serialVersionUID = 1L;
     public enum CountryCodeSource {
       FROM_NUMBER_WITH_PLUS_SIGN,
       FROM_NUMBER_WITH_IDD,

java/test/com/google/i18n/phonenumbers/PhoneNumberMatcherTest.java

@@ -221,6 +221,25 @@ public class PhoneNumberMatcherTest extends TestCase {
     assertEquals(number, matchWithSpaces.rawString());
   }
 
+  public void testNonMatchingBracketsAreInvalid() throws Exception {
+    // The digits up to the ", " form a valid US number, but it shouldn't be matched as one since
+    // there was a non-matching bracket present.
+    assertTrue(hasNoMatches(phoneUtil.findNumbers(
+        "80.585 [79.964, 81.191]", "US")));
+
+    // The trailing "]" is thrown away before parsing, so the resultant number, while a valid US
+    // number, does not have matching brackets.
+    assertTrue(hasNoMatches(phoneUtil.findNumbers(
+        "80.585 [79.964]", "US")));
+
+    assertTrue(hasNoMatches(phoneUtil.findNumbers(
+        "80.585 ((79.964)", "US")));
+
+    // This case has too many sets of brackets to be valid.
+    assertTrue(hasNoMatches(phoneUtil.findNumbers(
+        "(80).(585) (79).(9)64", "US")));
+  }
+
   public void testNoMatchIfRegionIsNull() throws Exception {
     // Fail on non-international prefix if region code is null.
     assertTrue(hasNoMatches(phoneUtil.findNumbers(

java/test/com/google/i18n/phonenumbers/PhoneNumberOfflineGeocoderTest.java

@@ -0,0 +1,64 @@
+/*
+ * Copyright (C) 2011 Google Inc.
+ *
+ * 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.google.i18n.phonenumbers;
+
+import com.google.i18n.phonenumbers.Phonenumber.PhoneNumber;
+import junit.framework.TestCase;
+
+import java.util.Locale;
+
+/**
+ * Unit tests for PhoneNumberOfflineGeocoder.java
+ *
+ * @author Shaopeng Jia
+ */
+public class PhoneNumberOfflineGeocoderTest extends TestCase {
+  private PhoneNumberOfflineGeocoder geocoder;
+  static final String TEST_META_DATA_FILE_PREFIX =
+      "/com/google/i18n/phonenumbers/data/PhoneNumberMetadataProtoForTesting";
+
+  // Set up some test numbers to re-use.
+  private static final PhoneNumber US_NUMBER1 =
+      new PhoneNumber().setCountryCode(1).setNationalNumber(6502530000L);
+  private static final PhoneNumber BS_NUMBER1 =
+      new PhoneNumber().setCountryCode(1).setNationalNumber(2423651234L);
+  private static final PhoneNumber AU_NUMBER =
+      new PhoneNumber().setCountryCode(61).setNationalNumber(236618300L);
+  private static final PhoneNumber NUMBER_WITH_INVALID_COUNTRY_CODE =
+      new PhoneNumber().setCountryCode(999).setNationalNumber(2423651234L);
+
+  public PhoneNumberOfflineGeocoderTest() {
+    PhoneNumberUtil.resetInstance();
+    PhoneNumberUtil phoneUtil = PhoneNumberUtil.getInstance(
+        TEST_META_DATA_FILE_PREFIX,
+        CountryCodeToRegionCodeMapForTesting.getCountryCodeToRegionCodeMap());
+    geocoder = new PhoneNumberOfflineGeocoder(phoneUtil);
+  }
+
+  public void testGetCompactDescriptionForNumber() {
+    assertEquals("United States",
+        geocoder.getDescriptionForNumber(US_NUMBER1, Locale.ENGLISH));
+    assertEquals("Stati Uniti",
+        geocoder.getDescriptionForNumber(US_NUMBER1, Locale.ITALIAN));
+    assertEquals("Bahamas",
+        geocoder.getDescriptionForNumber(BS_NUMBER1, Locale.ENGLISH));
+    assertEquals("Australia",
+        geocoder.getDescriptionForNumber(AU_NUMBER, Locale.ENGLISH));
+    assertEquals("", geocoder.getDescriptionForNumber(NUMBER_WITH_INVALID_COUNTRY_CODE,
+                                                      Locale.ENGLISH));
+  }
+}