Home | History | Annotate | Download | only in content 
      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      */
     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
     81     public String getId() {
     82         return mId;
     83     }
     84 
     85     @Override
     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
     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
    108     public String toString() {
    109         return "LocusId[" + getSanitizedId() + "]";
    110     }
    111 
    112     /** @hide */
    113     public void dump(@NonNull PrintWriter pw) {
    114         pw.print("id:"); pw.println(getSanitizedId());
    115     }
    116 
    117     @NonNull
    118     private String getSanitizedId() {
    119         final int size = mId.length();
    120         return size + "_chars";
    121     }
    122 
    123     @Override
    124     public int describeContents() {
    125         return 0;
    126     }
    127 
    128     @Override
    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