1 /* 2 * Copyright (C) 2020 The Android Open Source Project 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 package com.android.timezone.location.lookup; 17 18 import com.android.timezone.location.common.PiiLoggable; 19 20 import java.io.Closeable; 21 import java.io.File; 22 import java.io.IOException; 23 import java.util.List; 24 25 /** 26 * A class that performs location-based time zone lookups synchronously without exposing 27 * implementation details. 28 */ 29 public abstract class GeoTimeZonesFinder implements Closeable { 30 31 /** 32 * Returns the default {@link GeoTimeZonesFinder}. This method will open the underlying storage 33 * and may carry some CPU and I/O expense; callers may want to hold the 34 * {@link GeoTimeZonesFinder} object for multiple lookups to amortize that cost but at the cost 35 * of some memory, or close it immediately after a single use. 36 * 37 * @throws IOException in the unlikely event of errors when reading underlying file(s) 38 */ 39 // @NonNull create(File file)40 public static GeoTimeZonesFinder create(File file) throws IOException { 41 return S2RangeFileBasedGeoTimeZonesFinder.create(file); 42 } 43 44 /** 45 * Returns a token for a given location. See {@link LocationToken} for details. 46 * 47 * @throws IOException in the unlikely event of errors when reading the underlying file 48 */ 49 // @NonNull createLocationTokenForLatLng(double latDegrees, double lngDegrees)50 public abstract LocationToken createLocationTokenForLatLng(double latDegrees, double lngDegrees) 51 throws IOException; 52 53 /** 54 * Returns the time zone ID(s) associated with a location. The list returned will never be 55 * {@code null}, but may be empty, contain one time zone ID or several. When there are several 56 * it is typical to treat the first as the preferred, but multiple IDs can be returned, for 57 * example, for border cases in case the caller has other information that may indicate one of 58 * the other candidate zones should be used. 59 * 60 * <p>The IDs returned can be passed to methods like {@link 61 * java.util.TimeZone#getTimeZone(String)}, 62 * 63 * @throws IOException in the unlikely event of errors when reading the underlying file 64 */ 65 // @NonNull findTimeZonesForLatLng(double latDegrees, double lngDegrees)66 public abstract List<String> findTimeZonesForLatLng(double latDegrees, double lngDegrees) 67 throws IOException; 68 69 /** 70 * Returns the time zone ID(s) associated with a location token. The list returned will never be 71 * {@code null}, but may be empty, contain one time zone ID or several. When there are several 72 * it is typical to treat the first as the preferred, but multiple IDs can be returned, for 73 * example, for border cases in case the caller has other information that may indicate one of 74 * the other candidate zones should be used. 75 * 76 * <p>The IDs returned can be passed to methods like {@link 77 * java.util.TimeZone#getTimeZone(String)}, 78 * 79 * @throws IOException in the unlikely event of errors when reading the underlying file 80 */ 81 // @NonNull findTimeZonesForLocationToken(LocationToken locationToken)82 public abstract List<String> findTimeZonesForLocationToken(LocationToken locationToken) 83 throws IOException; 84 85 /** 86 * A class that represents an area with the same time zones. Two locations with tokens that 87 * {@link #equals(Object) equal each other} will definitely return the same time zone IDs. 88 * 89 * <p>Depending on the implementation, it may be cheaper to obtain a {@link LocationToken} than 90 * doing a full lookup. 91 */ 92 public abstract static class LocationToken implements PiiLoggable { 93 @Override equals(Object other)94 public abstract boolean equals(Object other); 95 96 @Override hashCode()97 public abstract int hashCode(); 98 } 99 } 100