1 /*
2  * Copyright (C) 2020 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 com.android.car.uxr;
18 
19 import android.content.Context;
20 
21 import androidx.annotation.IdRes;
22 import androidx.annotation.Nullable;
23 import androidx.annotation.StringRes;
24 import androidx.annotation.XmlRes;
25 
26 import java.util.Map;
27 
28 /**
29  * A container class for app specific Car User Experience Restriction override configurations.
30  *
31  * <p>{@link #getInstance(Context, int)} will returned a lazily populated cached reference to the
32  * configurations object that is read using
33  * {@link CarUxRestrictionsAppConfigParser#parseConfig(Context, int)}.
34  *
35  * <p>{@link #getMapping()} can be used to access the mapping of component IDs to configurations
36  * specific to that component.
37  */
38 public class CarUxRestrictionsAppConfig {
39 
40     private final Map<Integer, ListConfig> mMapping;
41     private static CarUxRestrictionsAppConfig sInstance;
42 
CarUxRestrictionsAppConfig(Map<Integer, ListConfig> mapping)43     CarUxRestrictionsAppConfig(Map<Integer, ListConfig> mapping) {
44         mMapping = mapping;
45     }
46 
47     /**
48      * Returns a cached reference to the {@link CarUxRestrictionsAppConfig} object
49      * resulting from parsing the contents of {@code xmlRes} xml resource.
50      *
51      * @param context - the app context
52      * @param xmlRes  - the xml resource that contains the UXR override configs.
53      */
getInstance(Context context, @XmlRes int xmlRes)54     public static CarUxRestrictionsAppConfig getInstance(Context context, @XmlRes int xmlRes) {
55         if (sInstance == null) {
56             sInstance = CarUxRestrictionsAppConfigParser.parseConfig(context, xmlRes);
57         }
58 
59         return sInstance;
60     }
61 
62     /**
63      * Returns a {@link Map} of Resource Ids as ints to {@link ListConfig} objects.
64      */
getMapping()65     public Map<Integer, ListConfig> getMapping() {
66         return mMapping;
67     }
68 
69     /**
70      * A class representing Car User Experience Restriction override configurations for a list UI
71      * component.
72      */
73     public static class ListConfig {
74         @IdRes
75         private final int mId;
76         private final Integer mContentLimit;
77         @StringRes
78         private final Integer mScrollingLimitedMessageResId;
79 
ListConfig(@dRes int id, @Nullable Integer contentLimit, @StringRes Integer scrollingLimitedMessageResId)80         private ListConfig(@IdRes int id, @Nullable Integer contentLimit,
81                 @StringRes Integer scrollingLimitedMessageResId) {
82             mId = id;
83             mContentLimit = contentLimit;
84             mScrollingLimitedMessageResId = scrollingLimitedMessageResId;
85         }
86 
87         /**
88          * Returns a {@code Builder} that can be used to build a {@link ListConfig} object for a
89          * component identified with the provided {@code id}.
90          *
91          * @param id - an identifier for the component whose behavior needs to be overridden with
92          *           the configurations specified in the resulting {@link ListConfig} object.
93          */
builder(@dRes int id)94         public static Builder builder(@IdRes int id) {
95             return new Builder(id);
96         }
97 
98         /**
99          * Returns the identifier for the component whose behavior needs to be overridden by this
100          * config object.
101          */
102         @IdRes
getId()103         public int getId() {
104             return mId;
105         }
106 
107         /**
108          * Returns the item limit to impose on the contents of the corresponding list component.
109          */
110         @Nullable
getContentLimit()111         public Integer getContentLimit() {
112             return mContentLimit;
113         }
114 
115         /**
116          * Returns the string resource ID to use when educating users about why the content in the
117          * list they're browsing has been limited.
118          */
119         @Nullable
120         @StringRes
getScrollingLimitedMessageResId()121         public Integer getScrollingLimitedMessageResId() {
122             return mScrollingLimitedMessageResId;
123         }
124 
125         /**
126          * A Builder for {@link ListConfig}.
127          */
128         public static class Builder {
129             @IdRes
130             private final int mId;
131             private Integer mContentLimit;
132             @StringRes
133             private Integer mScrollingLimitedMessageResId;
134 
135 
136             /**
137              * Constructs a {@code Builder} that can be used to build a {@link ListConfig} object
138              * for a component identified with the provided {@code id}.
139              *
140              * @param id - an identifier for the component whose behavior needs to be overridden
141              *           with the configurations specified in the resulting {@link ListConfig}
142              *           object.
143              */
Builder(@dRes int id)144             private Builder(@IdRes int id) {
145                 mId = id;
146             }
147 
148             /**
149              * Sets the item limit to impose on the contents of the corresponding list component.
150              *
151              * @param contentLimit - the item limit
152              * @return this {@code Builder} object to facilitate chaining.
153              */
setContentLimit(int contentLimit)154             public Builder setContentLimit(int contentLimit) {
155                 mContentLimit = contentLimit;
156                 return this;
157             }
158 
159             /**
160              * Sets the string resource ID to use when educating users about why the content in the
161              * * list they're browsing has been limited.
162              *
163              * @param scrollingLimitedMessageResId - an educational message string resource ID
164              * @return this {@code Builder} object to facilitate chaining.
165              */
setScrollingLimitedMessageResId( @tringRes int scrollingLimitedMessageResId)166             public Builder setScrollingLimitedMessageResId(
167                     @StringRes int scrollingLimitedMessageResId) {
168                 mScrollingLimitedMessageResId = scrollingLimitedMessageResId;
169                 return this;
170             }
171 
172             /**
173              * Build and return a {@link ListConfig} object with the values provided to this
174              * {@code Builder} object.
175              */
build()176             public ListConfig build() {
177                 return new ListConfig(mId, mContentLimit, mScrollingLimitedMessageResId);
178             }
179         }
180     }
181 }
182