1 /*
2  * Copyright 2017 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 
17 package android.app.slice;
18 
19 import android.annotation.NonNull;
20 import android.annotation.Nullable;
21 import android.net.Uri;
22 import android.os.Parcel;
23 import android.os.Parcelable;
24 
25 /**
26  * Class describing the structure of the data contained within a slice.
27  * <p>
28  * A data version contains a string which describes the type of structure
29  * and a revision which denotes this specific implementation. Revisions are expected
30  * to be backwards compatible and monotonically increasing. Meaning if a
31  * SliceSpec has the same type and an equal or lesser revision,
32  * it is expected to be compatible.
33  * <p>
34  * Apps rendering slices will provide a list of supported versions to the OS which
35  * will also be given to the app. Apps should only return a {@link Slice} with a
36  * {@link SliceSpec} that one of the supported {@link SliceSpec}s provided
37  * {@link #canRender}.
38  *
39  * @see Slice
40  * @see SliceProvider#onBindSlice(Uri, Set)
41  */
42 public final class SliceSpec implements Parcelable {
43 
44     private final String mType;
45     private final int mRevision;
46 
SliceSpec(@onNull String type, int revision)47     public SliceSpec(@NonNull String type, int revision) {
48         mType = type;
49         mRevision = revision;
50     }
51 
52     /**
53      * @hide
54      */
SliceSpec(Parcel source)55     public SliceSpec(Parcel source) {
56         mType = source.readString();
57         mRevision = source.readInt();
58     }
59 
60     @Override
describeContents()61     public int describeContents() {
62         return 0;
63     }
64 
65     @Override
writeToParcel(Parcel dest, int flags)66     public void writeToParcel(Parcel dest, int flags) {
67         dest.writeString(mType);
68         dest.writeInt(mRevision);
69     }
70 
71     /**
72      * Gets the type of the version.
73      */
getType()74     public String getType() {
75         return mType;
76     }
77 
78     /**
79      * Gets the revision of the version.
80      */
getRevision()81     public int getRevision() {
82         return mRevision;
83     }
84 
85     /**
86      * Indicates that this spec can be used to render the specified spec.
87      * <p>
88      * Rendering support is not bi-directional (e.g. Spec v3 can render
89      * Spec v2, but Spec v2 cannot render Spec v3).
90      *
91      * @param candidate candidate format of data.
92      * @return true if versions are compatible.
93      * @see androidx.slice.widget.SliceView
94      */
canRender(@onNull SliceSpec candidate)95     public boolean canRender(@NonNull SliceSpec candidate) {
96         if (!mType.equals(candidate.mType)) return false;
97         return mRevision >= candidate.mRevision;
98     }
99 
100     @Override
equals(@ullable Object obj)101     public boolean equals(@Nullable Object obj) {
102         if (!(obj instanceof SliceSpec)) return false;
103         SliceSpec other = (SliceSpec) obj;
104         return mType.equals(other.mType) && mRevision == other.mRevision;
105     }
106 
107     @Override
toString()108     public String toString() {
109         return String.format("SliceSpec{%s,%d}", mType, mRevision);
110     }
111 
112     public static final @android.annotation.NonNull Creator<SliceSpec> CREATOR = new Creator<SliceSpec>() {
113         @Override
114         public SliceSpec createFromParcel(Parcel source) {
115             return new SliceSpec(source);
116         }
117 
118         @Override
119         public SliceSpec[] newArray(int size) {
120             return new SliceSpec[size];
121         }
122     };
123 }
124