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