java/carrier/src/com/google/i18n/phonenumbers/PhoneNumberToCarrierMapper.java

   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 text description for the given phone number, in the language provided. The
  61    * description consists of the name of the carrier the number was originally allocated to, however
  62    * if the country supports mobile number portability the number might not belong to the returned
  63    * carrier anymore. If no mapping 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 text description
  70    * @param languageCode  the language code for which the description should be written
  71    * @return  a text description for the given language code for the given phone number
  72    */
  73   public String getDescriptionForValidNumber(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    * As per {@link #getDescriptionForValidNumber(PhoneNumber, Locale)} but explicitly checks
  83    * the validity of the number passed in.
  84    *
  85    * @param number  the phone number for which we want to get a text description
  86    * @param languageCode  the language code for which the description should be written
  87    * @return  a text description for the given language code for the given phone number, or empty
  88    *     string if the number passed in is invalid
  89    */
  90   public String getDescriptionForNumber(PhoneNumber number, Locale languageCode) {
  91     PhoneNumberType numberType = phoneUtil.getNumberType(number);
  92     if (isMobile(numberType)) {
  93       return getDescriptionForValidNumber(number, languageCode);
  94     }
  95     return "";
  96   }
  97
  98   /**
  99    * Checks if the supplied number type supports carrier lookup.
 100    */
 101   private boolean isMobile(PhoneNumberType numberType) {
 102     return (numberType == PhoneNumberType.MOBILE ||
 103             numberType == PhoneNumberType.FIXED_LINE_OR_MOBILE ||
 104             numberType == PhoneNumberType.PAGER);
 105   }
 106 }