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 android.media;
18 
19 import android.annotation.IntRange;
20 import android.annotation.NonNull;
21 import android.annotation.Nullable;
22 
23 import java.util.Set;
24 
25 /**
26  * A read only {@code Map}-style interface of {@link AudioMetadata.Key} value pairs used
27  * for {@link AudioMetadata}.
28  *
29  * <p>Using a {@link AudioMetadata.Key} interface,
30  * this map looks up the corresponding value.
31  * Read-only maps are thread-safe for lookup, but the underlying object
32  * values may need their own thread protection if mutable.</p>
33  *
34  * {@see AudioMetadataMap}
35  */
36 public interface AudioMetadataReadMap {
37     /**
38      * Returns true if the key exists in the map.
39      *
40      * @param key interface for requesting the value.
41      * @param <T> type of value.
42      * @return true if key exists in the Map.
43      */
containsKey(@onNull AudioMetadata.Key<T> key)44     <T> boolean containsKey(@NonNull AudioMetadata.Key<T> key);
45 
46     /**
47      * Returns a copy of the map.
48      *
49      * This is intended for safe conversion between a {@link AudioMetadataReadMap}
50      * interface and a {@link AudioMetadataMap} interface.
51      * Currently only simple objects are used for key values which
52      * means a shallow copy is sufficient.
53      *
54      * @return a Map copied from the existing map.
55      */
56     @NonNull
dup()57     AudioMetadataMap dup(); // lint checker doesn't like clone().
58 
59     /**
60      * Returns the value associated with the key.
61      *
62      * @param key interface for requesting the value.
63      * @param <T> type of value.
64      * @return returns the value of associated with key or null if it doesn't exist.
65      */
66     @Nullable
get(@onNull AudioMetadata.Key<T> key)67     <T> T get(@NonNull AudioMetadata.Key<T> key);
68 
69     /**
70      * Returns a {@code Set} of keys associated with the map.
71      * @hide
72      */
73     @NonNull
keySet()74     Set<AudioMetadata.Key<?>> keySet();
75 
76     /**
77      * Returns the number of elements in the map.
78      */
79     @IntRange(from = 0)
size()80     int size();
81 }
82