Rename NonGeographicalRegion to NonGeographicalEntity.

This is to be consistent with the naming of non-geographical entities, since region and non-geographical can be contradictory.

Author: KarolJakubKrawiec

java/libphonenumber/src/com/google/i18n/phonenumbers/AsYouTypeFormatter.java

@@ -612,7 +612,7 @@ private boolean attemptToExtractCountryCallingCode() {
     nationalNumber.append(numberWithoutCountryCallingCode);
     String newRegionCode = phoneUtil.getRegionCodeForCountryCode(countryCode);
     if (PhoneNumberUtil.REGION_CODE_FOR_NON_GEO_ENTITY.equals(newRegionCode)) {
-      currentMetadata = phoneUtil.getMetadataForNonGeographicalRegion(countryCode);
+      currentMetadata = phoneUtil.getMetadataForNonGeographicalEntity(countryCode);
     } else if (!newRegionCode.equals(defaultCountry)) {
       currentMetadata = getMetadataForRegion(newRegionCode);
     }

java/libphonenumber/src/com/google/i18n/phonenumbers/PhoneNumberUtil.java

@@ -699,7 +699,7 @@ abstract boolean verify(
 
   // The set of country calling codes that map to the non-geo entity region ("001"). This set
   // currently contains < 12 elements so the default capacity of 16 (load factor=0.75) is fine.
-  private final Set<Integer> countryCodesForNonGeographicalRegion = new HashSet<>();
+  private final Set<Integer> countryCodesForNonGeographicalEntity = new HashSet<>();
 
   /**
    * This class implements a singleton, the constructor is only visible to facilitate testing.
@@ -715,7 +715,7 @@ abstract boolean verify(
       // that's the only region code it maps to.
       if (regionCodes.size() == 1 && REGION_CODE_FOR_NON_GEO_ENTITY.equals(regionCodes.get(0))) {
         // This is the subset of all country codes that map to the non-geo entity region code.
-        countryCodesForNonGeographicalRegion.add(entry.getKey());
+        countryCodesForNonGeographicalEntity.add(entry.getKey());
       } else {
         // The supported regions set does not include the "001" non-geo entity region code.
         supportedRegions.addAll(regionCodes);
@@ -1072,7 +1072,7 @@ public Set<String> getSupportedRegions() {
    *     library supports
    */
   public Set<Integer> getSupportedGlobalNetworkCallingCodes() {
-    return Collections.unmodifiableSet(countryCodesForNonGeographicalRegion);
+    return Collections.unmodifiableSet(countryCodesForNonGeographicalEntity);
   }
 
   /**
@@ -1159,7 +1159,7 @@ public Set<PhoneNumberType> getSupportedTypesForRegion(String regionCode) {
    * entity.
    */
   public Set<PhoneNumberType> getSupportedTypesForNonGeoEntity(int countryCallingCode) {
-    PhoneMetadata metadata = getMetadataForNonGeographicalRegion(countryCallingCode);
+    PhoneMetadata metadata = getMetadataForNonGeographicalEntity(countryCallingCode);
     if (metadata == null) {
       logger.log(Level.WARNING, "Unknown country calling code for a non-geographical entity "
           + "provided: " + countryCallingCode);
@@ -1436,7 +1436,7 @@ public String formatNationalNumberWithCarrierCode(PhoneNumber number, CharSequen
   private PhoneMetadata getMetadataForRegionOrCallingCode(
       int countryCallingCode, String regionCode) {
     return REGION_CODE_FOR_NON_GEO_ENTITY.equals(regionCode)
-        ? getMetadataForNonGeographicalRegion(countryCallingCode)
+        ? getMetadataForNonGeographicalEntity(countryCallingCode)
         : getMetadataForRegion(regionCode);
   }
 
@@ -2149,7 +2149,7 @@ public PhoneNumber getExampleNumberForType(PhoneNumberType type) {
     // If there wasn't an example number for a region, try the non-geographical entities.
     for (int countryCallingCode : getSupportedGlobalNetworkCallingCodes()) {
       PhoneNumberDesc desc = getNumberDescByType(
-          getMetadataForNonGeographicalRegion(countryCallingCode), type);
+          getMetadataForNonGeographicalEntity(countryCallingCode), type);
       try {
         if (desc.hasExampleNumber()) {
           return parse("+" + countryCallingCode + desc.getExampleNumber(), UNKNOWN_REGION);
@@ -2171,7 +2171,7 @@ public PhoneNumber getExampleNumberForType(PhoneNumberType type) {
    *    to a non-geographical entity.
    */
   public PhoneNumber getExampleNumberForNonGeoEntity(int countryCallingCode) {
-    PhoneMetadata metadata = getMetadataForNonGeographicalRegion(countryCallingCode);
+    PhoneMetadata metadata = getMetadataForNonGeographicalEntity(countryCallingCode);
     if (metadata != null) {
       // For geographical entities, fixed-line data is always present. However, for non-geographical
       // entities, this is not the case, so we have to go through different types to find the
@@ -2322,18 +2322,26 @@ PhoneMetadata getMetadataForRegion(String regionCode) {
     return phoneMetadata;
   }
 
+  /**
+   * @deprecated use the following name {@link #getMetadataForNonGeographicalEntity}
+   */
+  @Deprecated
+  PhoneMetadata getMetadataForNonGeographicalRegion(int countryCallingCode) {
+    return getMetadataForNonGeographicalEntity(countryCallingCode);
+  }
+
   /**
    * Returns the metadata for the given country calling code or {@code null} if the country calling
    * code is invalid or unknown.
    *
    * @throws MissingMetadataException if the country calling code is valid, but metadata cannot be
    *     found.
    */
-  PhoneMetadata getMetadataForNonGeographicalRegion(int countryCallingCode) {
-    if (!countryCodesForNonGeographicalRegion.contains(countryCallingCode)) {
+  PhoneMetadata getMetadataForNonGeographicalEntity(int countryCallingCode) {
+    if (!countryCodesForNonGeographicalEntity.contains(countryCallingCode)) {
       return null;
     }
-    PhoneMetadata phoneMetadata = metadataSource.getMetadataForNonGeographicalRegion(
+    PhoneMetadata phoneMetadata = metadataSource.getMetadataForNonGeographicalEntity(
         countryCallingCode);
     ensureMetadataIsNonNull(phoneMetadata,
         "Missing metadata for country code " + countryCallingCode);

java/libphonenumber/src/com/google/i18n/phonenumbers/metadata/source/FormattingMetadataSource.java

@@ -25,7 +25,7 @@ public interface FormattingMetadataSource {
    * Returns formatting phone metadata for provided country calling code.
    *
    * <p>This method is similar to the one in {@link
-   * NonGeographicalEntityMetadataSource#getMetadataForNonGeographicalRegion(int)}, except that it
+   * NonGeographicalEntityMetadataSourceV2#getMetadataForNonGeographicalEntity(int)}, except that it
    * will not fail for geographical regions, it can be used for both geo- and non-geo entities.
    *
    * <p>In case the provided {@code countryCallingCode} maps to several different regions, only one

java/libphonenumber/src/com/google/i18n/phonenumbers/metadata/source/MetadataSource.java

@@ -17,5 +17,5 @@
 package com.google.i18n.phonenumbers.metadata.source;
 
 /** A source of phone metadata split by different regions. */
-public interface MetadataSource extends RegionMetadataSource, NonGeographicalEntityMetadataSource {
+public interface MetadataSource extends RegionMetadataSource, NonGeographicalEntityMetadataSource, NonGeographicalEntityMetadataSourceV2 {
 }

java/libphonenumber/src/com/google/i18n/phonenumbers/metadata/source/MetadataSourceImpl.java

@@ -49,8 +49,17 @@ public MetadataSourceImpl(
             metadataLoader, metadataParser, new CompositeMetadataContainer()));
   }
 
+  /**
+   * @deprecated Use {@link #getMetadataForNonGeographicalEntity(int)}
+   */
+  @Deprecated
   @Override
   public PhoneMetadata getMetadataForNonGeographicalRegion(int countryCallingCode) {
+    return getMetadataForNonGeographicalEntity(countryCallingCode);
+  }
+
+  @Override
+  public PhoneMetadata getMetadataForNonGeographicalEntity(int countryCallingCode) {
     if (GeoEntityUtility.isGeoEntity(countryCallingCode)) {
       throw new IllegalArgumentException(
           countryCallingCode + " calling code belongs to a geo entity");

java/libphonenumber/src/com/google/i18n/phonenumbers/metadata/source/NonGeographicalEntityMetadataSource.java

@@ -19,29 +19,14 @@
 import com.google.i18n.phonenumbers.Phonemetadata.PhoneMetadata;
 
 /**
- * A source of phone metadata for non-geographical entities.
- *
- * <p>Non-geographical entities are phone number ranges that have a country calling code, but either
- * do not belong to an actual country (some international services), or belong to a region which has
- * a different country calling code from the country it is part of. Examples of such ranges are
- * those starting with:
- *
- * <ul>
- *   <li>800 - country code assigned to the Universal International Freephone Service
- *   <li>808 - country code assigned to the International Shared Cost Service
- *   <li>870 - country code assigned to the Pitcairn Islands
- *   <li>...
- * </ul>
+ * @deprecated Use {@link NonGeographicalEntityMetadataSourceV2}
  */
+@Deprecated
 public interface NonGeographicalEntityMetadataSource {
 
   /**
-   * Gets phone metadata for a non-geographical entity.
-   *
-   * @param countryCallingCode the country calling code.
-   * @return the phone metadata for that entity, or null if there is none.
-   * @throws IllegalArgumentException if provided {@code countryCallingCode} does not belong to a
-   *     non-geographical entity
+   * @deprecated use {@link NonGeographicalEntityMetadataSourceV2#getMetadataForNonGeographicalEntity(int)}
    */
+  @Deprecated
   PhoneMetadata getMetadataForNonGeographicalRegion(int countryCallingCode);
-}
+}

java/libphonenumber/src/com/google/i18n/phonenumbers/metadata/source/NonGeographicalEntityMetadataSourceV2.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright (C) 2022 The Libphonenumber Authors
+ *
+ * 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.metadata.source;
+
+import com.google.i18n.phonenumbers.Phonemetadata.PhoneMetadata;
+
+/**
+ * A source of phone metadata for non-geographical entities.
+ *
+ * <p>Non-geographical entities are phone number ranges that have a country calling code, but either
+ * do not belong to an actual country (some international services), or belong to a region which has
+ * a different country calling code from the country it is part of. Examples of such ranges are
+ * those starting with:
+ *
+ * <ul>
+ *   <li>800 - country code assigned to the Universal International Freephone Service
+ *   <li>808 - country code assigned to the International Shared Cost Service
+ *   <li>870 - country code assigned to the Pitcairn Islands
+ *   <li>...
+ * </ul>
+ */
+public interface NonGeographicalEntityMetadataSourceV2 {
+
+  /**
+   * Gets phone metadata for a non-geographical entity.
+   *
+   * @param countryCallingCode the country calling code.
+   * @return the phone metadata for that entity, or null if there is none.
+   * @throws IllegalArgumentException if provided {@code countryCallingCode} does not belong to a
+   *     non-geographical entity
+   */
+  PhoneMetadata getMetadataForNonGeographicalEntity(int countryCallingCode);
+}

java/libphonenumber/test/com/google/i18n/phonenumbers/PhoneNumberUtilTest.java

@@ -161,7 +161,7 @@ public void testGetSupportedCallingCodes() {
 
   public void testGetInstanceLoadBadMetadata() {
     assertNull(phoneUtil.getMetadataForRegion("No Such Region"));
-    assertNull(phoneUtil.getMetadataForNonGeographicalRegion(-1));
+    assertNull(phoneUtil.getMetadataForNonGeographicalEntity(-1));
   }
 
   public void testGetSupportedTypesForRegion() {
@@ -262,7 +262,7 @@ public void testGetInstanceLoadARMetadata() {
   }
 
   public void testGetInstanceLoadInternationalTollFreeMetadata() {
-    PhoneMetadata metadata = phoneUtil.getMetadataForNonGeographicalRegion(800);
+    PhoneMetadata metadata = phoneUtil.getMetadataForNonGeographicalEntity(800);
     assertEquals("001", metadata.getId());
     assertEquals(800, metadata.getCountryCode());
     assertEquals("$1 $2", metadata.getNumberFormat(0).getFormat());
@@ -3247,8 +3247,8 @@ public void testGetMetadataForRegionForUnknownRegion_shouldBeNull() {
     assertNull(phoneUtil.getMetadataForRegion(RegionCode.ZZ));
   }
 
-  public void testGetMetadataForNonGeographicalRegionForGeoRegion_shouldBeNull() {
-    assertNull(phoneUtil.getMetadataForNonGeographicalRegion(/* countryCallingCode = */ 1));
+  public void testGetMetadataForNonGeographicalEntityForGeoRegion_shouldBeNull() {
+    assertNull(phoneUtil.getMetadataForNonGeographicalEntity(/* countryCallingCode = */ 1));
   }
 
   public void testGetMetadataForRegionForMissingMetadata() {
@@ -3262,13 +3262,13 @@ public void run() {
         });
   }
 
-  public void testGetMetadataForNonGeographicalRegionForMissingMetadata() {
+  public void testGetMetadataForNonGeographicalEntityForMissingMetadata() {
     assertThrows(
         MissingMetadataException.class,
         new ThrowingRunnable() {
           @Override
           public void run() {
-            phoneNumberUtilWithMissingMetadata.getMetadataForNonGeographicalRegion(800);
+            phoneNumberUtilWithMissingMetadata.getMetadataForNonGeographicalEntity(800);
           }
         });
   }