1 /* 2 * Copyright (C) 2019 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 package android.content; 17 18 import android.annotation.NonNull; 19 import android.os.Parcel; 20 import android.os.Parcelable; 21 import android.view.contentcapture.ContentCaptureManager; 22 23 import com.android.internal.util.Preconditions; 24 25 import java.io.PrintWriter; 26 27 /** 28 * An identifier for an unique state (locus) in the application. Should be stable across reboots and 29 * backup / restore. 30 * 31 * <p>Locus is a new concept introduced on 32 * {@link android.os.Build.VERSION_CODES#Q Android Q} and it lets the Android system correlate 33 * state between different subsystems such as content capture, shortcuts, and notifications. 34 * 35 * <p>For example, if your app provides an activiy representing a chat between 2 users 36 * (say {@code A} and {@code B}, this chat state could be represented by: 37 * 38 * <pre><code> 39 * LocusId chatId = new LocusId("Chat_A_B"); 40 * </code></pre> 41 * 42 * <p>And then you should use that {@code chatId} by: 43 * 44 * <ul> 45 * <li>Setting it in the chat notification (through 46 * {@link android.app.Notification.Builder#setLocusId(LocusId) 47 * Notification.Builder.setLocusId(chatId)}). 48 * <li>Setting it into the {@link android.content.pm.ShortcutInfo} (through 49 * {@link android.content.pm.ShortcutInfo.Builder#setLocusId(LocusId) 50 * ShortcutInfo.Builder.setLocusId(chatId)}), if you provide a launcher shortcut for that chat 51 * conversation. 52 * <li>Associating it with the {@link android.view.contentcapture.ContentCaptureContext} of the 53 * root view of the chat conversation activity (through 54 * {@link android.view.View#getContentCaptureSession()}, then 55 * {@link android.view.contentcapture.ContentCaptureContext.Builder 56 * new ContentCaptureContext.Builder(chatId).build()} and 57 * {@link android.view.contentcapture.ContentCaptureSession#setContentCaptureContext( 58 * android.view.contentcapture.ContentCaptureContext)} - see {@link ContentCaptureManager} 59 * for more info about content capture). 60 * <li>Configuring your app to launch the chat conversation through the 61 * {@link Intent#ACTION_VIEW_LOCUS} intent. 62 * </ul> 63 */ 64 public final class LocusId implements Parcelable { 65 66 private final String mId; 67 68 /** 69 * Default constructor. 70 * 71 * @throws IllegalArgumentException if {@code id} is empty or {@code null}. 72 */ LocusId(@onNull String id)73 public LocusId(@NonNull String id) { 74 mId = Preconditions.checkStringNotEmpty(id, "id cannot be empty"); 75 } 76 77 /** 78 * Gets the canonical {@code id} associated with the locus. 79 */ 80 @NonNull getId()81 public String getId() { 82 return mId; 83 } 84 85 @Override hashCode()86 public int hashCode() { 87 final int prime = 31; 88 int result = 1; 89 result = prime * result + ((mId == null) ? 0 : mId.hashCode()); 90 return result; 91 } 92 93 @Override equals(Object obj)94 public boolean equals(Object obj) { 95 if (this == obj) return true; 96 if (obj == null) return false; 97 if (getClass() != obj.getClass()) return false; 98 final LocusId other = (LocusId) obj; 99 if (mId == null) { 100 if (other.mId != null) return false; 101 } else { 102 if (!mId.equals(other.mId)) return false; 103 } 104 return true; 105 } 106 107 @Override toString()108 public String toString() { 109 return "LocusId[" + getSanitizedId() + "]"; 110 } 111 112 /** @hide */ dump(@onNull PrintWriter pw)113 public void dump(@NonNull PrintWriter pw) { 114 pw.print("id:"); pw.println(getSanitizedId()); 115 } 116 117 @NonNull getSanitizedId()118 private String getSanitizedId() { 119 final int size = mId.length(); 120 return size + "_chars"; 121 } 122 123 @Override describeContents()124 public int describeContents() { 125 return 0; 126 } 127 128 @Override writeToParcel(Parcel parcel, int flags)129 public void writeToParcel(Parcel parcel, int flags) { 130 parcel.writeString(mId); 131 } 132 133 public static final @NonNull Parcelable.Creator<LocusId> CREATOR = 134 new Parcelable.Creator<LocusId>() { 135 136 @NonNull 137 @Override 138 public LocusId createFromParcel(Parcel parcel) { 139 return new LocusId(parcel.readString()); 140 } 141 142 @NonNull 143 @Override 144 public LocusId[] newArray(int size) { 145 return new LocusId[size]; 146 } 147 }; 148 } 149