1 /*
2  * Copyright (C) 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 package com.android.wallpaper.model;
17 
18 import android.content.Context;
19 
20 import androidx.annotation.Nullable;
21 
22 /**
23  * Fetches and provides wallpaper categories to any registered {@link CategoryReceiver}s.
24  */
25 public interface CategoryProvider {
26 
27     /**
28      * Fetches the categories asynchronously; once ready, provides results to the given
29      * {@link CategoryReceiver}.
30      *
31      * @param receiver     The receiver of categories.
32      * @param forceRefresh Whether to force the CategoryProvider to refresh the categories
33      *                     (as opposed to returning cached values from a prior fetch).
34      */
fetchCategories(CategoryReceiver receiver, boolean forceRefresh)35     void fetchCategories(CategoryReceiver receiver, boolean forceRefresh);
36 
getSize()37     int getSize();
38 
39     /**
40      * Returns the Category at the given index position.
41      * <p>
42      * Note that this method is expected to be called after the categories have been fetched.
43      * @param index index of the Category to return.
44      *
45      * @throws IllegalStateException if this method is called before fetching happened.
46      * @throws IndexOutOfBoundsException if the given index is either negative or larger than
47      * {@link #getSize()}
48      */
getCategory(int index)49     Category getCategory(int index);
50 
51     /**
52      * Returns the Category having the given collection ID. If not found, returns null.
53      * <p>
54      * This method should only be called for collection IDs for which the corresponding Category was
55      * already fetched, so the null return case should be treated as an error by callers.
56      */
57     @Nullable
getCategory(String collectionId)58     Category getCategory(String collectionId);
59 
60     /**
61      * Checks if the categories are fetched.
62      */
isCategoriesFetched()63     boolean isCategoriesFetched();
64 
65     /**
66      * Resets the fetched categories if needed.
67      *
68      * @return {@code true} if the fetched categories are reset; {@code false} otherwise.
69      */
resetIfNeeded()70     boolean resetIfNeeded();
71 
72     /**
73      * Checks if creative category collection is available or not.
74      */
isCreativeCategoryAvailable()75     boolean isCreativeCategoryAvailable();
76 
77     /**
78      * Checks if featured collection available.
79      */
isFeaturedCollectionAvailable()80     boolean isFeaturedCollectionAvailable();
81 
82     /**
83      * Checks if should force reload.
84      */
shouldForceReload(Context context)85     default boolean shouldForceReload(Context context) {
86         return false;
87     }
88 }
89