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
