1 /* 2 * Copyright (C) 2010 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 17 package android.location; 18 19 import android.compat.annotation.UnsupportedAppUsage; 20 import android.os.Parcel; 21 import android.os.Parcelable; 22 import android.os.SystemClock; 23 24 import java.util.Locale; 25 26 /** 27 * This class wraps the country information. 28 * 29 * @hide 30 */ 31 public class Country implements Parcelable { 32 /** 33 * The country code came from the mobile network 34 */ 35 public static final int COUNTRY_SOURCE_NETWORK = 0; 36 37 /** 38 * The country code came from the location service 39 */ 40 public static final int COUNTRY_SOURCE_LOCATION = 1; 41 42 /** 43 * The country code was read from the SIM card 44 */ 45 public static final int COUNTRY_SOURCE_SIM = 2; 46 47 /** 48 * The country code came from the system locale setting 49 */ 50 public static final int COUNTRY_SOURCE_LOCALE = 3; 51 52 /** 53 * The ISO 3166-1 two letters country code. 54 */ 55 private final String mCountryIso; 56 57 /** 58 * Where the country code came from. 59 */ 60 private final int mSource; 61 62 private int mHashCode; 63 64 /** 65 * Time that this object was created (which we assume to be the time that the source was 66 * consulted). This time is in milliseconds since boot up. 67 */ 68 private final long mTimestamp; 69 70 /** 71 * @param countryIso the ISO 3166-1 two letters country code. 72 * @param source where the countryIso came from, could be one of below 73 * values 74 * <p> 75 * <ul> 76 * <li>{@link #COUNTRY_SOURCE_NETWORK}</li> 77 * <li>{@link #COUNTRY_SOURCE_LOCATION}</li> 78 * <li>{@link #COUNTRY_SOURCE_SIM}</li> 79 * <li>{@link #COUNTRY_SOURCE_LOCALE}</li> 80 * </ul> 81 */ 82 @UnsupportedAppUsage Country(final String countryIso, final int source)83 public Country(final String countryIso, final int source) { 84 if (countryIso == null || source < COUNTRY_SOURCE_NETWORK 85 || source > COUNTRY_SOURCE_LOCALE) { 86 throw new IllegalArgumentException(); 87 } 88 mCountryIso = countryIso.toUpperCase(Locale.US); 89 mSource = source; 90 mTimestamp = SystemClock.elapsedRealtime(); 91 } 92 Country(final String countryIso, final int source, long timestamp)93 private Country(final String countryIso, final int source, long timestamp) { 94 if (countryIso == null || source < COUNTRY_SOURCE_NETWORK 95 || source > COUNTRY_SOURCE_LOCALE) { 96 throw new IllegalArgumentException(); 97 } 98 mCountryIso = countryIso.toUpperCase(Locale.US); 99 mSource = source; 100 mTimestamp = timestamp; 101 } 102 Country(Country country)103 public Country(Country country) { 104 mCountryIso = country.mCountryIso; 105 mSource = country.mSource; 106 mTimestamp = country.mTimestamp; 107 } 108 109 /** 110 * @return the ISO 3166-1 two letters country code 111 */ 112 @UnsupportedAppUsage getCountryIso()113 public final String getCountryIso() { 114 return mCountryIso; 115 } 116 117 /** 118 * @return where the country code came from, could be one of below values 119 * <p> 120 * <ul> 121 * <li>{@link #COUNTRY_SOURCE_NETWORK}</li> 122 * <li>{@link #COUNTRY_SOURCE_LOCATION}</li> 123 * <li>{@link #COUNTRY_SOURCE_SIM}</li> 124 * <li>{@link #COUNTRY_SOURCE_LOCALE}</li> 125 * </ul> 126 */ 127 @UnsupportedAppUsage getSource()128 public final int getSource() { 129 return mSource; 130 } 131 132 /** 133 * Returns the time that this object was created (which we assume to be the time that the source 134 * was consulted). 135 */ getTimestamp()136 public final long getTimestamp() { 137 return mTimestamp; 138 } 139 140 public static final @android.annotation.NonNull Parcelable.Creator<Country> CREATOR = new Parcelable.Creator<Country>() { 141 public Country createFromParcel(Parcel in) { 142 return new Country(in.readString(), in.readInt(), in.readLong()); 143 } 144 145 public Country[] newArray(int size) { 146 return new Country[size]; 147 } 148 }; 149 describeContents()150 public int describeContents() { 151 return 0; 152 } 153 writeToParcel(Parcel parcel, int flags)154 public void writeToParcel(Parcel parcel, int flags) { 155 parcel.writeString(mCountryIso); 156 parcel.writeInt(mSource); 157 parcel.writeLong(mTimestamp); 158 } 159 160 /** 161 * Returns true if this {@link Country} is equivalent to the given object. This ignores 162 * the timestamp value and just checks for equivalence of countryIso and source values. 163 * Returns false otherwise. 164 */ 165 @Override equals(Object object)166 public boolean equals(Object object) { 167 if (object == this) { 168 return true; 169 } 170 if (object instanceof Country) { 171 Country c = (Country) object; 172 // No need to check the equivalence of the timestamp 173 return mCountryIso.equals(c.getCountryIso()) && mSource == c.getSource(); 174 } 175 return false; 176 } 177 178 @Override hashCode()179 public int hashCode() { 180 int hash = mHashCode; 181 if (hash == 0) { 182 hash = 17; 183 hash = hash * 13 + mCountryIso.hashCode(); 184 hash = hash * 13 + mSource; 185 mHashCode = hash; 186 } 187 return mHashCode; 188 } 189 190 /** 191 * Compare the specified country to this country object ignoring the source 192 * and timestamp fields, return true if the countryIso fields are equal 193 * 194 * @param country the country to compare 195 * @return true if the specified country's countryIso field is equal to this 196 * country's, false otherwise. 197 */ equalsIgnoreSource(Country country)198 public boolean equalsIgnoreSource(Country country) { 199 return country != null && mCountryIso.equals(country.getCountryIso()); 200 } 201 202 @Override toString()203 public String toString() { 204 return "Country {ISO=" + mCountryIso + ", source=" + mSource + ", time=" + mTimestamp + "}"; 205 } 206 } 207