PersistableBundle.java revision 719e6b167041ffaffc2245f692714c8de191863f
1/* 2 * Copyright (C) 2014 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.os; 18 19import android.util.ArrayMap; 20 21import java.util.Set; 22 23/** 24 * A mapping from String values to various types that can be saved to persistent and later 25 * restored. 26 * 27 */ 28public final class PersistableBundle extends CommonBundle { 29 public static final PersistableBundle EMPTY; 30 static final Parcel EMPTY_PARCEL; 31 32 static { 33 EMPTY = new PersistableBundle(); 34 EMPTY.mMap = ArrayMap.EMPTY; 35 EMPTY_PARCEL = CommonBundle.EMPTY_PARCEL; 36 } 37 38 /** 39 * Constructs a new, empty PersistableBundle. 40 */ 41 public PersistableBundle() { 42 super(); 43 } 44 45 /** 46 * Constructs a PersistableBundle whose data is stored as a Parcel. The data 47 * will be unparcelled on first contact, using the assigned ClassLoader. 48 * 49 * @param parcelledData a Parcel containing a PersistableBundle 50 */ 51 PersistableBundle(Parcel parcelledData) { 52 super(parcelledData); 53 } 54 55 /* package */ PersistableBundle(Parcel parcelledData, int length) { 56 super(parcelledData, length); 57 } 58 59 /** 60 * Constructs a new, empty PersistableBundle that uses a specific ClassLoader for 61 * instantiating Parcelable and Serializable objects. 62 * 63 * @param loader An explicit ClassLoader to use when instantiating objects 64 * inside of the PersistableBundle. 65 */ 66 public PersistableBundle(ClassLoader loader) { 67 super(loader); 68 } 69 70 /** 71 * Constructs a new, empty PersistableBundle sized to hold the given number of 72 * elements. The PersistableBundle will grow as needed. 73 * 74 * @param capacity the initial capacity of the PersistableBundle 75 */ 76 public PersistableBundle(int capacity) { 77 super(capacity); 78 } 79 80 /** 81 * Constructs a PersistableBundle containing a copy of the mappings from the given 82 * PersistableBundle. 83 * 84 * @param b a PersistableBundle to be copied. 85 */ 86 public PersistableBundle(PersistableBundle b) { 87 super(b); 88 } 89 90 /** 91 * Make a PersistableBundle for a single key/value pair. 92 * 93 * @hide 94 */ 95 public static PersistableBundle forPair(String key, String value) { 96 PersistableBundle b = new PersistableBundle(1); 97 b.putString(key, value); 98 return b; 99 } 100 101 /** 102 * @hide 103 */ 104 @Override 105 public String getPairValue() { 106 return super.getPairValue(); 107 } 108 109 /** 110 * Changes the ClassLoader this PersistableBundle uses when instantiating objects. 111 * 112 * @param loader An explicit ClassLoader to use when instantiating objects 113 * inside of the PersistableBundle. 114 */ 115 @Override 116 public void setClassLoader(ClassLoader loader) { 117 super.setClassLoader(loader); 118 } 119 120 /** 121 * Return the ClassLoader currently associated with this PersistableBundle. 122 */ 123 @Override 124 public ClassLoader getClassLoader() { 125 return super.getClassLoader(); 126 } 127 128 /** 129 * Clones the current PersistableBundle. The internal map is cloned, but the keys and 130 * values to which it refers are copied by reference. 131 */ 132 @Override 133 public Object clone() { 134 return new PersistableBundle(this); 135 } 136 137 /** 138 * @hide 139 */ 140 @Override 141 public boolean isParcelled() { 142 return super.isParcelled(); 143 } 144 145 /** 146 * Returns the number of mappings contained in this PersistableBundle. 147 * 148 * @return the number of mappings as an int. 149 */ 150 @Override 151 public int size() { 152 return super.size(); 153 } 154 155 /** 156 * Returns true if the mapping of this PersistableBundle is empty, false otherwise. 157 */ 158 @Override 159 public boolean isEmpty() { 160 return super.isEmpty(); 161 } 162 163 /** 164 * Removes all elements from the mapping of this PersistableBundle. 165 */ 166 @Override 167 public void clear() { 168 super.clear(); 169 } 170 171 /** 172 * Returns true if the given key is contained in the mapping 173 * of this PersistableBundle. 174 * 175 * @param key a String key 176 * @return true if the key is part of the mapping, false otherwise 177 */ 178 @Override 179 public boolean containsKey(String key) { 180 return super.containsKey(key); 181 } 182 183 /** 184 * Returns the entry with the given key as an object. 185 * 186 * @param key a String key 187 * @return an Object, or null 188 */ 189 @Override 190 public Object get(String key) { 191 return super.get(key); 192 } 193 194 /** 195 * Removes any entry with the given key from the mapping of this PersistableBundle. 196 * 197 * @param key a String key 198 */ 199 @Override 200 public void remove(String key) { 201 super.remove(key); 202 } 203 204 /** 205 * Inserts all mappings from the given PersistableBundle into this Bundle. 206 * 207 * @param bundle a PersistableBundle 208 */ 209 public void putAll(PersistableBundle bundle) { 210 super.putAll(bundle); 211 } 212 213 /** 214 * Returns a Set containing the Strings used as keys in this PersistableBundle. 215 * 216 * @return a Set of String keys 217 */ 218 @Override 219 public Set<String> keySet() { 220 return super.keySet(); 221 } 222 223 /** 224 * Inserts an int value into the mapping of this PersistableBundle, replacing 225 * any existing value for the given key. 226 * 227 * @param key a String, or null 228 * @param value an int, or null 229 */ 230 @Override 231 public void putInt(String key, int value) { 232 super.putInt(key, value); 233 } 234 235 /** 236 * Inserts a long value into the mapping of this PersistableBundle, replacing 237 * any existing value for the given key. 238 * 239 * @param key a String, or null 240 * @param value a long 241 */ 242 @Override 243 public void putLong(String key, long value) { 244 super.putLong(key, value); 245 } 246 247 /** 248 * Inserts a double value into the mapping of this PersistableBundle, replacing 249 * any existing value for the given key. 250 * 251 * @param key a String, or null 252 * @param value a double 253 */ 254 @Override 255 public void putDouble(String key, double value) { 256 super.putDouble(key, value); 257 } 258 259 /** 260 * Inserts a String value into the mapping of this PersistableBundle, replacing 261 * any existing value for the given key. Either key or value may be null. 262 * 263 * @param key a String, or null 264 * @param value a String, or null 265 */ 266 @Override 267 public void putString(String key, String value) { 268 super.putString(key, value); 269 } 270 271 /** 272 * Inserts an int array value into the mapping of this PersistableBundle, replacing 273 * any existing value for the given key. Either key or value may be null. 274 * 275 * @param key a String, or null 276 * @param value an int array object, or null 277 */ 278 @Override 279 public void putIntArray(String key, int[] value) { 280 super.putIntArray(key, value); 281 } 282 283 /** 284 * Inserts a long array value into the mapping of this PersistableBundle, replacing 285 * any existing value for the given key. Either key or value may be null. 286 * 287 * @param key a String, or null 288 * @param value a long array object, or null 289 */ 290 @Override 291 public void putLongArray(String key, long[] value) { 292 super.putLongArray(key, value); 293 } 294 295 /** 296 * Inserts a double array value into the mapping of this PersistableBundle, replacing 297 * any existing value for the given key. Either key or value may be null. 298 * 299 * @param key a String, or null 300 * @param value a double array object, or null 301 */ 302 @Override 303 public void putDoubleArray(String key, double[] value) { 304 super.putDoubleArray(key, value); 305 } 306 307 /** 308 * Inserts a String array value into the mapping of this PersistableBundle, replacing 309 * any existing value for the given key. Either key or value may be null. 310 * 311 * @param key a String, or null 312 * @param value a String array object, or null 313 */ 314 @Override 315 public void putStringArray(String key, String[] value) { 316 super.putStringArray(key, value); 317 } 318 319 /** 320 * Inserts a PersistableBundle value into the mapping of this Bundle, replacing 321 * any existing value for the given key. Either key or value may be null. 322 * 323 * @param key a String, or null 324 * @param value a Bundle object, or null 325 */ 326 public void putPersistableBundle(String key, PersistableBundle value) { 327 super.putPersistableBundle(key, value); 328 } 329 330 /** 331 * Returns the value associated with the given key, or 0 if 332 * no mapping of the desired type exists for the given key. 333 * 334 * @param key a String 335 * @return an int value 336 */ 337 @Override 338 public int getInt(String key) { 339 return super.getInt(key); 340 } 341 342 /** 343 * Returns the value associated with the given key, or defaultValue if 344 * no mapping of the desired type exists for the given key. 345 * 346 * @param key a String 347 * @param defaultValue Value to return if key does not exist 348 * @return an int value 349 */ 350 @Override 351 public int getInt(String key, int defaultValue) { 352 return super.getInt(key, defaultValue); 353 } 354 355 /** 356 * Returns the value associated with the given key, or 0L if 357 * no mapping of the desired type exists for the given key. 358 * 359 * @param key a String 360 * @return a long value 361 */ 362 @Override 363 public long getLong(String key) { 364 return super.getLong(key); 365 } 366 367 /** 368 * Returns the value associated with the given key, or defaultValue if 369 * no mapping of the desired type exists for the given key. 370 * 371 * @param key a String 372 * @param defaultValue Value to return if key does not exist 373 * @return a long value 374 */ 375 @Override 376 public long getLong(String key, long defaultValue) { 377 return super.getLong(key, defaultValue); 378 } 379 380 /** 381 * Returns the value associated with the given key, or 0.0 if 382 * no mapping of the desired type exists for the given key. 383 * 384 * @param key a String 385 * @return a double value 386 */ 387 @Override 388 public double getDouble(String key) { 389 return super.getDouble(key); 390 } 391 392 /** 393 * Returns the value associated with the given key, or defaultValue if 394 * no mapping of the desired type exists for the given key. 395 * 396 * @param key a String 397 * @param defaultValue Value to return if key does not exist 398 * @return a double value 399 */ 400 @Override 401 public double getDouble(String key, double defaultValue) { 402 return super.getDouble(key, defaultValue); 403 } 404 405 /** 406 * Returns the value associated with the given key, or null if 407 * no mapping of the desired type exists for the given key or a null 408 * value is explicitly associated with the key. 409 * 410 * @param key a String, or null 411 * @return a String value, or null 412 */ 413 @Override 414 public String getString(String key) { 415 return super.getString(key); 416 } 417 418 /** 419 * Returns the value associated with the given key, or defaultValue if 420 * no mapping of the desired type exists for the given key. 421 * 422 * @param key a String, or null 423 * @param defaultValue Value to return if key does not exist 424 * @return the String value associated with the given key, or defaultValue 425 * if no valid String object is currently mapped to that key. 426 */ 427 @Override 428 public String getString(String key, String defaultValue) { 429 return super.getString(key, defaultValue); 430 } 431 432 /** 433 * Returns the value associated with the given key, or null if 434 * no mapping of the desired type exists for the given key or a null 435 * value is explicitly associated with the key. 436 * 437 * @param key a String, or null 438 * @return a Bundle value, or null 439 */ 440 @Override 441 public PersistableBundle getPersistableBundle(String key) { 442 return super.getPersistableBundle(key); 443 } 444 445 /** 446 * Returns the value associated with the given key, or null if 447 * no mapping of the desired type exists for the given key or a null 448 * value is explicitly associated with the key. 449 * 450 * @param key a String, or null 451 * @return an int[] value, or null 452 */ 453 @Override 454 public int[] getIntArray(String key) { 455 return super.getIntArray(key); 456 } 457 458 /** 459 * Returns the value associated with the given key, or null if 460 * no mapping of the desired type exists for the given key or a null 461 * value is explicitly associated with the key. 462 * 463 * @param key a String, or null 464 * @return a long[] value, or null 465 */ 466 @Override 467 public long[] getLongArray(String key) { 468 return super.getLongArray(key); 469 } 470 471 /** 472 * Returns the value associated with the given key, or null if 473 * no mapping of the desired type exists for the given key or a null 474 * value is explicitly associated with the key. 475 * 476 * @param key a String, or null 477 * @return a double[] value, or null 478 */ 479 @Override 480 public double[] getDoubleArray(String key) { 481 return super.getDoubleArray(key); 482 } 483 484 /** 485 * Returns the value associated with the given key, or null if 486 * no mapping of the desired type exists for the given key or a null 487 * value is explicitly associated with the key. 488 * 489 * @param key a String, or null 490 * @return a String[] value, or null 491 */ 492 @Override 493 public String[] getStringArray(String key) { 494 return super.getStringArray(key); 495 } 496 497 public static final Parcelable.Creator<PersistableBundle> CREATOR = 498 new Parcelable.Creator<PersistableBundle>() { 499 @Override 500 public PersistableBundle createFromParcel(Parcel in) { 501 return in.readPersistableBundle(); 502 } 503 504 @Override 505 public PersistableBundle[] newArray(int size) { 506 return new PersistableBundle[size]; 507 } 508 }; 509 510 /** 511 * Report the nature of this Parcelable's contents 512 */ 513 @Override 514 public int describeContents() { 515 return 0; 516 } 517 518 /** 519 * Writes the PersistableBundle contents to a Parcel, typically in order for 520 * it to be passed through an IBinder connection. 521 * @param parcel The parcel to copy this bundle to. 522 */ 523 @Override 524 public void writeToParcel(Parcel parcel, int flags) { 525 final boolean oldAllowFds = parcel.pushAllowFds(false); 526 try { 527 super.writeToParcelInner(parcel, flags); 528 } finally { 529 parcel.restoreAllowFds(oldAllowFds); 530 } 531 } 532 533 /** 534 * Reads the Parcel contents into this PersistableBundle, typically in order for 535 * it to be passed through an IBinder connection. 536 * @param parcel The parcel to overwrite this bundle from. 537 */ 538 public void readFromParcel(Parcel parcel) { 539 super.readFromParcelInner(parcel); 540 } 541 542 @Override 543 synchronized public String toString() { 544 if (mParcelledData != null) { 545 if (mParcelledData == EMPTY_PARCEL) { 546 return "PersistableBundle[EMPTY_PARCEL]"; 547 } else { 548 return "PersistableBundle[mParcelledData.dataSize=" + 549 mParcelledData.dataSize() + "]"; 550 } 551 } 552 return "PersistableBundle[" + mMap.toString() + "]"; 553 } 554 555} 556