Address.java revision 54b6cfa9a9e5b861a9930af873580d6dc20f773c
1/* 2 * Copyright (C) 2007 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 17package android.location; 18 19import java.util.HashMap; 20import java.util.Locale; 21import java.util.Map; 22import java.util.Set; 23 24import android.os.Bundle; 25import android.os.Parcel; 26import android.os.Parcelable; 27 28/** 29 * A class representing an Address, i.e, a set of Strings describing a location. 30 * 31 * The addres format is a simplified version of xAL (eXtensible Address Language) 32 * http://www.oasis-open.org/committees/ciq/ciq.html#6 33 */ 34public class Address implements Parcelable { 35 36 private Locale mLocale; 37 38 private String mFeatureName; 39 private HashMap<Integer, String> mAddressLines; 40 private int mMaxAddressLineIndex = -1; 41 private String mAdminArea; 42 private String mSubAdminArea; 43 private String mLocality; 44 private String mThoroughfare; 45 private String mPostalCode; 46 private String mCountryCode; 47 private String mCountryName; 48 private double mLatitude; 49 private double mLongitude; 50 private boolean mHasLatitude = false; 51 private boolean mHasLongitude = false; 52 private String mPhone; 53 private String mUrl; 54 private Bundle mExtras = null; 55 56 /** 57 * Constructs a new Address object set to the given Locale and with all 58 * other fields initialized to null or false. 59 */ 60 public Address(Locale locale) { 61 mLocale = locale; 62 } 63 64 /** 65 * Returns the Locale associated with this address. 66 */ 67 public Locale getLocale() { 68 return mLocale; 69 } 70 71 /** 72 * Returns the largest index currently in use to specify an address line. 73 * If no address lines are specified, -1 is returned. 74 */ 75 public int getMaxAddressLineIndex() { 76 return mMaxAddressLineIndex; 77 } 78 79 /** 80 * Returns a line of the address numbered by the given index 81 * (starting at 0), or null if no such line is present. 82 * 83 * @throws IllegalArgumentException if index < 0 84 */ 85 public String getAddressLine(int index) { 86 if (index < 0) { 87 throw new IllegalArgumentException("index = " + index + " < 0"); 88 } 89 return mAddressLines == null? null : mAddressLines.get(index); 90 } 91 92 /** 93 * Sets the line of the address numbered by index (starting at 0) to the 94 * given String, which may be null. 95 * 96 * @throws IllegalArgumentException if index < 0 97 */ 98 public void setAddressLine(int index, String line) { 99 if (index < 0) { 100 throw new IllegalArgumentException("index = " + index + " < 0"); 101 } 102 if (mAddressLines == null) { 103 mAddressLines = new HashMap<Integer, String>(); 104 } 105 mAddressLines.put(index, line); 106 107 if (line == null) { 108 // We've eliminated a line, recompute the max index 109 mMaxAddressLineIndex = -1; 110 for (Integer i : mAddressLines.keySet()) { 111 mMaxAddressLineIndex = Math.max(mMaxAddressLineIndex, i); 112 } 113 } else { 114 mMaxAddressLineIndex = Math.max(mMaxAddressLineIndex, index); 115 } 116 } 117 118 /** 119 * Returns the feature name of the address, for example, "Golden Gate Bridge", or null 120 * if it is unknown 121 */ 122 public String getFeatureName() { 123 return mFeatureName; 124 } 125 126 /** 127 * Sets the feature name of the address to the given String, which may be null 128 */ 129 public void setFeatureName(String featureName) { 130 mFeatureName = featureName; 131 } 132 133 /** 134 * Returns the administrative area name of the address, for example, "CA", or null if 135 * it is unknown 136 */ 137 public String getAdminArea() { 138 return mAdminArea; 139 } 140 141 /** 142 * Sets the administrative area name of the address to the given String, which may be null 143 */ 144 public void setAdminArea(String adminArea) { 145 this.mAdminArea = adminArea; 146 } 147 148 /** 149 * Returns the sub-administrative area name of the address, for example, "Santa Clara County", 150 * or null if it is unknown 151 */ 152 public String getSubAdminArea() { 153 return mSubAdminArea; 154 } 155 156 /** 157 * Sets the sub-administrative area name of the address to the given String, which may be null 158 */ 159 public void setSubAdminArea(String subAdminArea) { 160 this.mSubAdminArea = subAdminArea; 161 } 162 163 /** 164 * Returns the locality of the address, for example "Mountain View", or null if it is unknown. 165 */ 166 public String getLocality() { 167 return mLocality; 168 } 169 170 /** 171 * Sets the locality of the address to the given String, which may be null. 172 */ 173 public void setLocality(String locality) { 174 mLocality = locality; 175 } 176 177 /** 178 * Returns the thoroughfare name of the address, for example, "1600 Ampitheater Parkway", 179 * which may be null 180 */ 181 public String getThoroughfare() { 182 return mThoroughfare; 183 } 184 185 /** 186 * Sets the thoroughfare name of the address, which may be null. 187 */ 188 public void setThoroughfare(String thoroughfare) { 189 this.mThoroughfare = thoroughfare; 190 } 191 192 /** 193 * Returns the postal code of the address, for example "94110", 194 * or null if it is unknown. 195 */ 196 public String getPostalCode() { 197 return mPostalCode; 198 } 199 200 /** 201 * Sets the postal code of the address to the given String, which may 202 * be null. 203 */ 204 public void setPostalCode(String postalCode) { 205 mPostalCode = postalCode; 206 } 207 208 /** 209 * Returns the country code of the address, for example "US", 210 * or null if it is unknown. 211 */ 212 public String getCountryCode() { 213 return mCountryCode; 214 } 215 216 /** 217 * Sets the country code of the address to the given String, which may 218 * be null. 219 */ 220 public void setCountryCode(String countryCode) { 221 mCountryCode = countryCode; 222 } 223 224 /** 225 * Returns the localized country name of the address, for example "Iceland", 226 * or null if it is unknown. 227 */ 228 public String getCountryName() { 229 return mCountryName; 230 } 231 232 /** 233 * Sets the country name of the address to the given String, which may 234 * be null. 235 */ 236 public void setCountryName(String countryName) { 237 mCountryName = countryName; 238 } 239 240 /** 241 * Returns true if a latitude has been assigned to this Address, 242 * false otherwise. 243 */ 244 public boolean hasLatitude() { 245 return mHasLatitude; 246 } 247 248 /** 249 * Returns the latitude of the address if known. 250 * 251 * @throws IllegalStateException if this Address has not been assigned 252 * a latitude. 253 */ 254 public double getLatitude() { 255 if (mHasLatitude) { 256 return mLatitude; 257 } else { 258 throw new IllegalStateException(); 259 } 260 } 261 262 /** 263 * Sets the latitude associated with this address. 264 */ 265 public void setLatitude(double latitude) { 266 mLatitude = latitude; 267 mHasLatitude = true; 268 } 269 270 /** 271 * Removes any latitude associated with this address. 272 */ 273 public void clearLatitude() { 274 mHasLatitude = false; 275 } 276 277 /** 278 * Returns true if a longitude has been assigned to this Address, 279 * false otherwise. 280 */ 281 public boolean hasLongitude() { 282 return mHasLongitude; 283 } 284 285 /** 286 * Returns the longitude of the address if known. 287 * 288 * @throws IllegalStateException if this Address has not been assigned 289 * a longitude. 290 */ 291 public double getLongitude() { 292 if (mHasLongitude) { 293 return mLongitude; 294 } else { 295 throw new IllegalStateException(); 296 } 297 } 298 299 /** 300 * Sets the longitude associated with this address. 301 */ 302 public void setLongitude(double longitude) { 303 mLongitude = longitude; 304 mHasLongitude = true; 305 } 306 307 /** 308 * Removes any longitude associated with this address. 309 */ 310 public void clearLongitude() { 311 mHasLongitude = false; 312 } 313 314 /** 315 * Returns the phone number of the address if known, 316 * or null if it is unknown. 317 * 318 * @throws IllegalStateException if this Address has not been assigned 319 * a latitude. 320 */ 321 public String getPhone() { 322 return mPhone; 323 } 324 325 /** 326 * Sets the phone number associated with this address. 327 */ 328 public void setPhone(String phone) { 329 mPhone = phone; 330 } 331 332 /** 333 * Returns the public URL for the address if known, 334 * or null if it is unknown. 335 */ 336 public String getUrl() { 337 return mUrl; 338 } 339 340 /** 341 * Sets the public URL associated with this address. 342 */ 343 public void setUrl(String Url) { 344 mUrl = Url; 345 } 346 347 /** 348 * Returns additional provider-specific information about the 349 * address as a Bundle. The keys and values are determined 350 * by the provider. If no additional information is available, 351 * null is returned. 352 * 353 * <!-- 354 * <p> A number of common key/value pairs are listed 355 * below. Providers that use any of the keys on this list must 356 * provide the corresponding value as described below. 357 * 358 * <ul> 359 * </ul> 360 * --> 361 */ 362 public Bundle getExtras() { 363 return mExtras; 364 } 365 366 /** 367 * Sets the extra information associated with this fix to the 368 * given Bundle. 369 */ 370 public void setExtras(Bundle extras) { 371 mExtras = (extras == null) ? null : new Bundle(extras); 372 } 373 374 @Override 375 public String toString() { 376 StringBuilder sb = new StringBuilder(); 377 sb.append("Address[addressLines=["); 378 for (int i = 0; i <= mMaxAddressLineIndex; i++) { 379 if (i > 0) { 380 sb.append(','); 381 } 382 sb.append(i); 383 sb.append(':'); 384 String line = mAddressLines.get(i); 385 if (line == null) { 386 sb.append("null"); 387 } else { 388 sb.append('\"'); 389 sb.append(line); 390 sb.append('\"'); 391 } 392 } 393 sb.append(']'); 394 sb.append(",feature="); 395 sb.append(mFeatureName); 396 sb.append(",admin="); 397 sb.append(mAdminArea); 398 sb.append(",sub-admin="); 399 sb.append(mSubAdminArea); 400 sb.append(",locality="); 401 sb.append(mLocality); 402 sb.append(",thoroughfare="); 403 sb.append(mThoroughfare); 404 sb.append(",postalCode="); 405 sb.append(mPostalCode); 406 sb.append(",countryCode="); 407 sb.append(mCountryCode); 408 sb.append(",countryName="); 409 sb.append(mCountryName); 410 sb.append(",hasLatitude="); 411 sb.append(mHasLatitude); 412 sb.append(",latitude="); 413 sb.append(mLatitude); 414 sb.append(",hasLongitude="); 415 sb.append(mHasLongitude); 416 sb.append(",longitude="); 417 sb.append(mLongitude); 418 sb.append(",phone="); 419 sb.append(mPhone); 420 sb.append(",url="); 421 sb.append(mUrl); 422 sb.append(",extras="); 423 sb.append(mExtras); 424 sb.append(']'); 425 return sb.toString(); 426 } 427 428 public static final Parcelable.Creator<Address> CREATOR = 429 new Parcelable.Creator<Address>() { 430 public Address createFromParcel(Parcel in) { 431 String language = in.readString(); 432 String country = in.readString(); 433 Locale locale = country.length() > 0 ? 434 new Locale(language, country) : 435 new Locale(language); 436 Address a = new Address(locale); 437 438 int N = in.readInt(); 439 if (N > 0) { 440 a.mAddressLines = new HashMap<Integer, String>(N); 441 for (int i = 0; i < N; i++) { 442 int index = in.readInt(); 443 String line = in.readString(); 444 a.mAddressLines.put(index, line); 445 a.mMaxAddressLineIndex = 446 Math.max(a.mMaxAddressLineIndex, index); 447 } 448 } else { 449 a.mAddressLines = null; 450 a.mMaxAddressLineIndex = -1; 451 } 452 a.mFeatureName = in.readString(); 453 a.mAdminArea = in.readString(); 454 a.mSubAdminArea = in.readString(); 455 a.mLocality = in.readString(); 456 a.mThoroughfare = in.readString(); 457 a.mPostalCode = in.readString(); 458 a.mCountryCode = in.readString(); 459 a.mCountryName = in.readString(); 460 a.mHasLatitude = in.readInt() == 0 ? false : true; 461 if (a.mHasLatitude) { 462 a.mLatitude = in.readDouble(); 463 } 464 a.mHasLongitude = in.readInt() == 0 ? false : true; 465 if (a.mHasLongitude) { 466 a.mLongitude = in.readDouble(); 467 } 468 a.mPhone = in.readString(); 469 a.mUrl = in.readString(); 470 a.mExtras = in.readBundle(); 471 return a; 472 } 473 474 public Address[] newArray(int size) { 475 return new Address[size]; 476 } 477 }; 478 479 public int describeContents() { 480 return (mExtras != null) ? mExtras.describeContents() : 0; 481 } 482 483 public void writeToParcel(Parcel parcel, int flags) { 484 parcel.writeString(mLocale.getLanguage()); 485 parcel.writeString(mLocale.getCountry()); 486 if (mAddressLines == null) { 487 parcel.writeInt(0); 488 } else { 489 Set<Map.Entry<Integer, String>> entries = mAddressLines.entrySet(); 490 parcel.writeInt(entries.size()); 491 for (Map.Entry<Integer, String> e : entries) { 492 parcel.writeInt(e.getKey()); 493 parcel.writeString(e.getValue()); 494 } 495 } 496 parcel.writeString(mFeatureName); 497 parcel.writeString(mAdminArea); 498 parcel.writeString(mSubAdminArea); 499 parcel.writeString(mLocality); 500 parcel.writeString(mThoroughfare); 501 parcel.writeString(mPostalCode); 502 parcel.writeString(mCountryCode); 503 parcel.writeString(mCountryName); 504 parcel.writeInt(mHasLatitude ? 1 : 0); 505 if (mHasLatitude) { 506 parcel.writeDouble(mLatitude); 507 } 508 parcel.writeInt(mHasLongitude ? 1 : 0); 509 if (mHasLongitude){ 510 parcel.writeDouble(mLongitude); 511 } 512 parcel.writeString(mPhone); 513 parcel.writeString(mUrl); 514 parcel.writeBundle(mExtras); 515 } 516} 517