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
PhoneNumberToCarrierMapper(String phonePrefixDataDirectory)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    */
getInstance()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    */
getNameForValidNumber(PhoneNumber number, Locale languageCode)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    */
getNameForNumber(PhoneNumber number, Locale languageCode)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    */
getSafeDisplayName(PhoneNumber number, Locale languageCode)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    */
isMobile(PhoneNumberType numberType)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