2 * Copyright (C) 2012 The Libphonenumber Authors
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 package com.google.i18n.phonenumbers;
19 import com.google.i18n.phonenumbers.PhoneNumberUtil.PhoneNumberType;
20 import com.google.i18n.phonenumbers.Phonenumber.PhoneNumber;
21 import com.google.i18n.phonenumbers.prefixmapper.PrefixTimeZonesMap;
23 import java.io.IOException;
24 import java.io.InputStream;
25 import java.io.ObjectInputStream;
26 import java.util.ArrayList;
27 import java.util.Collections;
28 import java.util.List;
29 import java.util.logging.Level;
30 import java.util.logging.Logger;
33 * An offline mapper from phone numbers to time zones.
35 public class PhoneNumberToTimeZonesMapper {
36 private static PhoneNumberToTimeZonesMapper instance = null;
37 private static final String MAPPING_DATA_DIRECTORY =
38 "/com/google/i18n/phonenumbers/timezones/data/";
39 private static final String MAPPING_DATA_FILE_NAME = "map_data";
40 // This is defined by ICU as the unknown time zone.
41 private static final String UNKNOWN_TIMEZONE = "Etc/Unknown";
42 // A list with the ICU unknown time zone as single element.
44 static final List<String> UNKNOWN_TIME_ZONE_LIST = new ArrayList<String>(1);
46 UNKNOWN_TIME_ZONE_LIST.add(UNKNOWN_TIMEZONE);
49 private static final Logger LOGGER =
50 Logger.getLogger(PhoneNumberToTimeZonesMapper.class.getName());
52 private PrefixTimeZonesMap prefixTimeZonesMap = null;
55 PhoneNumberToTimeZonesMapper(String prefixTimeZonesMapDataDirectory) {
56 this.prefixTimeZonesMap = loadPrefixTimeZonesMapFromFile(
57 prefixTimeZonesMapDataDirectory + MAPPING_DATA_FILE_NAME);
60 private PhoneNumberToTimeZonesMapper(PrefixTimeZonesMap prefixTimeZonesMap) {
61 this.prefixTimeZonesMap = prefixTimeZonesMap;
64 private static PrefixTimeZonesMap loadPrefixTimeZonesMapFromFile(String path) {
65 InputStream source = PhoneNumberToTimeZonesMapper.class.getResourceAsStream(path);
66 ObjectInputStream in = null;
67 PrefixTimeZonesMap map = new PrefixTimeZonesMap();
69 in = new ObjectInputStream(source);
71 } catch (IOException e) {
72 LOGGER.log(Level.WARNING, e.toString());
79 private static void close(InputStream in) {
83 } catch (IOException e) {
84 LOGGER.log(Level.WARNING, e.toString());
90 * Helper class used for lazy instantiation of a PhoneNumberToTimeZonesMapper. This also loads the
91 * map data in a thread-safe way.
93 private static class LazyHolder {
94 private static final PhoneNumberToTimeZonesMapper INSTANCE;
96 PrefixTimeZonesMap map =
97 loadPrefixTimeZonesMapFromFile(MAPPING_DATA_DIRECTORY + MAPPING_DATA_FILE_NAME);
98 INSTANCE = new PhoneNumberToTimeZonesMapper(map);
103 * Gets a {@link PhoneNumberToTimeZonesMapper} instance.
105 * <p> The {@link PhoneNumberToTimeZonesMapper} is implemented as a singleton. Therefore, calling
106 * this method multiple times will only result in one instance being created.
108 * @return a {@link PhoneNumberToTimeZonesMapper} instance
110 public static synchronized PhoneNumberToTimeZonesMapper getInstance() {
111 return LazyHolder.INSTANCE;
115 * Returns a list of time zones to which a phone number belongs.
117 * <p>This method assumes the validity of the number passed in has already been checked, and that
118 * the number is geo-localizable. We consider fixed-line and mobile numbers possible candidates
119 * for geo-localization.
121 * @param number a valid phone number for which we want to get the time zones to which it belongs
122 * @return a list of the corresponding time zones or a single element list with the default
123 * unknown time zone if no other time zone was found or if the number was invalid
125 public List<String> getTimeZonesForGeographicalNumber(PhoneNumber number) {
126 return getTimeZonesForGeocodableNumber(number);
130 * As per {@link #getTimeZonesForGeographicalNumber(PhoneNumber)} but explicitly checks
131 * the validity of the number passed in.
133 * @param number the phone number for which we want to get the time zones to which it belongs
134 * @return a list of the corresponding time zones or a single element list with the default
135 * unknown time zone if no other time zone was found or if the number was invalid
137 public List<String> getTimeZonesForNumber(PhoneNumber number) {
138 PhoneNumberType numberType = PhoneNumberUtil.getInstance().getNumberType(number);
139 if (numberType == PhoneNumberType.UNKNOWN) {
140 return UNKNOWN_TIME_ZONE_LIST;
141 } else if (!canBeGeocoded(numberType)) {
142 return getCountryLevelTimeZonesforNumber(number);
144 return getTimeZonesForGeographicalNumber(number);
148 * A similar method is implemented as PhoneNumberUtil.isNumberGeographical, which performs a
149 * stricter check, as it determines if a number has a geographical association. Also, if new
150 * phone number types were added, we should check if this other method should be updated too.
151 * TODO: Remove duplication by completing the logic in the method in PhoneNumberUtil.
152 * For more information, see the comments in that method.
154 private boolean canBeGeocoded(PhoneNumberType numberType) {
155 return (numberType == PhoneNumberType.FIXED_LINE ||
156 numberType == PhoneNumberType.MOBILE ||
157 numberType == PhoneNumberType.FIXED_LINE_OR_MOBILE);
161 * Returns a String with the ICU unknown time zone.
163 public static String getUnknownTimeZone() {
164 return UNKNOWN_TIMEZONE;
168 * Returns a list of time zones to which a geocodable phone number belongs.
170 * @param number the phone number for which we want to get the time zones to which it belongs
171 * @return the list of corresponding time zones or a single element list with the default
172 * unknown time zone if no other time zone was found or if the number was invalid
174 private List<String> getTimeZonesForGeocodableNumber(PhoneNumber number) {
175 List<String> timezones = prefixTimeZonesMap.lookupTimeZonesForNumber(number);
176 return Collections.unmodifiableList(timezones.isEmpty() ? UNKNOWN_TIME_ZONE_LIST
181 * Returns the list of time zones corresponding to the country calling code of {@code number}.
183 * @param number the phone number to look up
184 * @return the list of corresponding time zones or a single element list with the default
185 * unknown time zone if no other time zone was found
187 private List<String> getCountryLevelTimeZonesforNumber(PhoneNumber number) {
188 List<String> timezones = prefixTimeZonesMap.lookupCountryLevelTimeZonesForNumber(number);
189 return Collections.unmodifiableList(timezones.isEmpty() ? UNKNOWN_TIME_ZONE_LIST