Home | History | Annotate | Download | only in phonenumbers
      1 /*
      2  * Copyright (C) 2013 The Libphonenumber Authors
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  * http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 package com.google.i18n.phonenumbers;
     18 
     19 import com.google.i18n.phonenumbers.PhoneNumberUtil;
     20 import com.google.i18n.phonenumbers.PhoneNumberUtil.PhoneNumberType;
     21 import com.google.i18n.phonenumbers.Phonenumber.PhoneNumber;
     22 import com.google.i18n.phonenumbers.prefixmapper.PrefixFileReader;
     23 
     24 import java.util.Locale;
     25 
     26 /**
     27  * A phone prefix mapper which provides carrier information related to a phone number.
     28  *
     29  * @author Cecilia Roes
     30  */
     31 public class PhoneNumberToCarrierMapper {
     32   private static PhoneNumberToCarrierMapper instance = null;
     33   private static final String MAPPING_DATA_DIRECTORY =
     34       "/com/google/i18n/phonenumbers/carrier/data/";
     35   private PrefixFileReader prefixFileReader = null;
     36 
     37   private final PhoneNumberUtil phoneUtil = PhoneNumberUtil.getInstance();
     38 
     39   // @VisibleForTesting
     40   PhoneNumberToCarrierMapper(String phonePrefixDataDirectory) {
     41     prefixFileReader = new PrefixFileReader(phonePrefixDataDirectory);
     42   }
     43 
     44   /**
     45    * Gets a {@link PhoneNumberToCarrierMapper} instance to carry out international carrier lookup.
     46    *
     47    * <p> The {@link PhoneNumberToCarrierMapper} is implemented as a singleton. Therefore, calling
     48    * this method multiple times will only result in one instance being created.
     49    *
     50    * @return  a {@link PhoneNumberToCarrierMapper} instance
     51    */
     52   public static synchronized PhoneNumberToCarrierMapper getInstance() {
     53     if (instance == null) {
     54       instance = new PhoneNumberToCarrierMapper(MAPPING_DATA_DIRECTORY);
     55     }
     56     return instance;
     57   }
     58 
     59   /**
     60    * Returns a carrier name for the given phone number, in the language provided. The carrier name
     61    * is the one the number was originally allocated to, however if the country supports mobile
     62    * number portability the number might not belong to the returned carrier anymore. If no mapping
     63    * is found an empty string is returned.
     64    *
     65    * <p>This method assumes the validity of the number passed in has already been checked, and that
     66    * the number is suitable for carrier lookup. We consider mobile and pager numbers possible
     67    * candidates for carrier lookup.
     68    *
     69    * @param number  a valid phone number for which we want to get a carrier name
     70    * @param languageCode  the language code in which the name should be written
     71    * @return  a carrier name for the given phone number
     72    */
     73   public String getNameForValidNumber(PhoneNumber number, Locale languageCode) {
     74     String langStr = languageCode.getLanguage();
     75     String scriptStr = "";  // No script is specified
     76     String regionStr = languageCode.getCountry();
     77 
     78     return prefixFileReader.getDescriptionForNumber(number, langStr, scriptStr, regionStr);
     79   }
     80 
     81   /**
     82    * Gets the name of the carrier for the given phone number, in the language provided. As per
     83    * {@link #getNameForValidNumber(PhoneNumber, Locale)} but explicitly checks the validity of
     84    * the number passed in.
     85    *
     86    * @param number  the phone number for which we want to get a carrier name
     87    * @param languageCode  the language code in which the name should be written
     88    * @return  a carrier name for the given phone number, or empty string if the number passed in is
     89    *     invalid
     90    */
     91   public String getNameForNumber(PhoneNumber number, Locale languageCode) {
     92     PhoneNumberType numberType = phoneUtil.getNumberType(number);
     93     if (isMobile(numberType)) {
     94       return getNameForValidNumber(number, languageCode);
     95     }
     96     return "";
     97   }
     98 
     99   /**
    100    * Gets the name of the carrier for the given phone number only when it is 'safe' to display to
    101    * users. A carrier name is considered safe if the number is valid and for a region that doesn't
    102    * support
    103    * <a href="http://en.wikipedia.org/wiki/Mobile_number_portability">mobile number portability</a>.
    104    *
    105    * @param number  the phone number for which we want to get a carrier name
    106    * @param languageCode  the language code in which the name should be written
    107    * @return  a carrier name that is safe to display to users, or the empty string
    108    */
    109   public String getSafeDisplayName(PhoneNumber number, Locale languageCode) {
    110     if (phoneUtil.isMobileNumberPortableRegion(phoneUtil.getRegionCodeForNumber(number))) {
    111       return "";
    112     }
    113     return getNameForNumber(number, languageCode);
    114   }
    115 
    116   /**
    117    * Checks if the supplied number type supports carrier lookup.
    118    */
    119   private boolean isMobile(PhoneNumberType numberType) {
    120     return (numberType == PhoneNumberType.MOBILE
    121         || numberType == PhoneNumberType.FIXED_LINE_OR_MOBILE
    122         || numberType == PhoneNumberType.PAGER);
    123   }
    124 }
    125