*Note for these schemas, the path portion of the URI must exist in the contacts + * database in their appropriate column, otherwise the reference should be discarded. + */ + @Nullable + public String getUri() { + return mUri; + } + + /** + * Returns the key for this {@link Person} or {@code null} if no key was provided. This is + * provided as a unique identifier between other {@link Person}s. + */ + @Nullable + public String getKey() { + return mKey; + } + + /** + * Returns whether or not this {@link Person} is a machine rather than a human. Used primarily + * to identify automated tooling. + */ + public boolean isBot() { + return mIsBot; + } + + /** + * Returns whether or not this {@link Person} is important to the user of this device with + * regards to how frequently they interact. + */ + public boolean isImportant() { + return mIsImportant; + } + + /** + * @return the URI associated with this person, or "name:mName" otherwise + */ + @NonNull + @RestrictTo(LIBRARY_GROUP_PREFIX) + public String resolveToLegacyUri() { + if (mUri != null) { + return mUri; + } + if (mName != null) { + return "name:" + mName; + } + return ""; + } + + @Override + public boolean equals(@Nullable Object otherObject) { + if (otherObject == null) { + return false; + } + + if (!(otherObject instanceof Person)) { + return false; + } + + Person otherPerson = (Person) otherObject; + + // If a unique ID was provided, use it + String key1 = getKey(); + String key2 = otherPerson.getKey(); + if (key1 != null || key2 != null) { + return Objects.equals(key1, key2); + } + + // CharSequence doesn't have well-defined "equals" behavior -- convert to String instead + String name1 = Objects.toString(getName()); + String name2 = Objects.toString(otherPerson.getName()); + + // Fallback: Compare field-by-field + return + Objects.equals(name1, name2) + && Objects.equals(getUri(), otherPerson.getUri()) + && Objects.equals(isBot(), otherPerson.isBot()) + && Objects.equals(isImportant(), otherPerson.isImportant()); + } + + @Override + public int hashCode() { + // If a unique ID was provided, use it + String key = getKey(); + if (key != null) { + return key.hashCode(); + } + + // Fallback: Use hash code for individual fields + return Objects.hash(getName(), getUri(), isBot(), isImportant()); + } + + /** Builder for the immutable {@link Person} class. */ + public static class Builder { + @Nullable CharSequence mName; + @Nullable IconCompat mIcon; + @Nullable String mUri; + @Nullable String mKey; + boolean mIsBot; + boolean mIsImportant; + + /** Creates a new, empty {@link Builder}. */ + public Builder() { } + + Builder(Person person) { + mName = person.mName; + mIcon = person.mIcon; + mUri = person.mUri; + mKey = person.mKey; + mIsBot = person.mIsBot; + mIsImportant = person.mIsImportant; + } + + /** + * Give this {@link Person} a name to use for display. This can be, for example, a full + * name, nickname, username, etc. + */ + @NonNull + public Builder setName(@Nullable CharSequence name) { + mName = name; + return this; + } + + /** + * Set an icon for this {@link Person}. + * + *
The system will prefer this icon over any images that are resolved from + * {@link #setUri(String)}. + */ + @NonNull + public Builder setIcon(@Nullable IconCompat icon) { + mIcon = icon; + return this; + } + + /** + * Set a URI for this {@link Person} which can be any of the following: + *
*Note for these schemas, the path portion of the URI must exist in the contacts + * database in their appropriate column, otherwise the reference will be discarded. + */ + @NonNull + public Builder setUri(@Nullable String uri) { + mUri = uri; + return this; + } + + /** + * Set a unique identifier for this {@link Person}. This is especially useful if the + * {@link #setName(CharSequence)} value isn't unique. This value is preferred for + * identification, but if it's not provided, the person's name will be used in its place. + */ + @NonNull + public Builder setKey(@Nullable String key) { + mKey = key; + return this; + } + + /** + * Sets whether or not this {@link Person} represents a machine rather than a human. This is + * used primarily for testing and automated tooling. + */ + @NonNull + public Builder setBot(boolean bot) { + mIsBot = bot; + return this; + } + + /** + * Sets whether this is an important person. Use this method to denote users who frequently + * interact with the user of this device when {@link #setUri(String)} isn't provided with + * {@link android.provider.ContactsContract.Contacts#CONTENT_LOOKUP_URI}, and instead with + * the {@code mailto:} or {@code tel:} schemas. + */ + @NonNull + public Builder setImportant(boolean important) { + mIsImportant = important; + return this; + } + + /** Creates and returns the {@link Person} this builder represents. */ + @NonNull + public Person build() { + return new Person(this); + } + } + + @RequiresApi(22) + static class Api22Impl { + private Api22Impl() { + // This class is not instantiable. + } + + @DoNotInline + static Person fromPersistableBundle(PersistableBundle bundle) { + return new Builder() + .setName(bundle.getString(NAME_KEY)) + .setUri(bundle.getString(URI_KEY)) + .setKey(bundle.getString(KEY_KEY)) + .setBot(bundle.getBoolean(IS_BOT_KEY)) + .setImportant(bundle.getBoolean(IS_IMPORTANT_KEY)) + .build(); + } + + @DoNotInline + static PersistableBundle toPersistableBundle(Person person) { + PersistableBundle result = new PersistableBundle(); + result.putString(NAME_KEY, person.mName != null ? person.mName.toString() : null); + result.putString(URI_KEY, person.mUri); + result.putString(KEY_KEY, person.mKey); + result.putBoolean(IS_BOT_KEY, person.mIsBot); + result.putBoolean(IS_IMPORTANT_KEY, person.mIsImportant); + return result; + } + } + + @RequiresApi(28) + static class Api28Impl { + private Api28Impl() { + // This class is not instantiable. + } + + @DoNotInline + static Person fromAndroidPerson(android.app.Person person) { + return new Builder() + .setName(person.getName()) + .setIcon( + (person.getIcon() != null) + ? IconCompat.createFromIcon(person.getIcon()) + : null) + .setUri(person.getUri()) + .setKey(person.getKey()) + .setBot(person.isBot()) + .setImportant(person.isImportant()) + .build(); + } + + @SuppressWarnings("deprecation") + @DoNotInline + static android.app.Person toAndroidPerson(Person person) { + return new android.app.Person.Builder() + .setName(person.getName()) + .setIcon((person.getIcon() != null) ? person.getIcon().toIcon() : null) + .setUri(person.getUri()) + .setKey(person.getKey()) + .setBot(person.isBot()) + .setImportant(person.isImportant()) + .build(); + } + } +}