Merge "Add kdoc for immutable data structure classes." into main
diff --git a/services/permission/java/com/android/server/permission/access/immutable/IndexedList.kt b/services/permission/java/com/android/server/permission/access/immutable/IndexedList.kt
index 6108ad2..ce4aa44 100644
--- a/services/permission/java/com/android/server/permission/access/immutable/IndexedList.kt
+++ b/services/permission/java/com/android/server/permission/access/immutable/IndexedList.kt
@@ -16,6 +16,9 @@
package com.android.server.permission.access.immutable
+/**
+ * Immutable list with index-based access.
+ */
sealed class IndexedList<T>(
internal val list: ArrayList<T>
) : Immutable<MutableIndexedList<T>> {
@@ -34,6 +37,9 @@
override fun toString(): String = list.toString()
}
+/**
+ * Mutable list with index-based access.
+ */
class MutableIndexedList<T>(
list: ArrayList<T> = ArrayList()
) : IndexedList<T>(list) {
diff --git a/services/permission/java/com/android/server/permission/access/immutable/IndexedListSet.kt b/services/permission/java/com/android/server/permission/access/immutable/IndexedListSet.kt
index 1202c81..77e71ba 100644
--- a/services/permission/java/com/android/server/permission/access/immutable/IndexedListSet.kt
+++ b/services/permission/java/com/android/server/permission/access/immutable/IndexedListSet.kt
@@ -16,6 +16,9 @@
package com.android.server.permission.access.immutable
+/**
+ * Immutable set with index-based access, implemented using a list.
+ */
sealed class IndexedListSet<T>(
internal val list: ArrayList<T>
) : Immutable<MutableIndexedListSet<T>> {
@@ -36,6 +39,9 @@
override fun toString(): String = list.toString()
}
+/**
+ * Mutable set with index-based access, implemented using a list.
+ */
class MutableIndexedListSet<T>(
list: ArrayList<T> = ArrayList()
) : IndexedListSet<T>(list) {
diff --git a/services/permission/java/com/android/server/permission/access/immutable/IndexedMap.kt b/services/permission/java/com/android/server/permission/access/immutable/IndexedMap.kt
index 5c75de8..299cc89 100644
--- a/services/permission/java/com/android/server/permission/access/immutable/IndexedMap.kt
+++ b/services/permission/java/com/android/server/permission/access/immutable/IndexedMap.kt
@@ -18,6 +18,9 @@
import android.util.ArrayMap
+/**
+ * Immutable map with index-based access.
+ */
sealed class IndexedMap<K, V>(
internal val map: ArrayMap<K, V>
) : Immutable<MutableIndexedMap<K, V>> {
@@ -42,6 +45,9 @@
override fun toString(): String = map.toString()
}
+/**
+ * Mutable map with index-based access.
+ */
class MutableIndexedMap<K, V>(
map: ArrayMap<K, V> = ArrayMap()
) : IndexedMap<K, V>(map) {
diff --git a/services/permission/java/com/android/server/permission/access/immutable/IndexedReferenceMap.kt b/services/permission/java/com/android/server/permission/access/immutable/IndexedReferenceMap.kt
index 8c963aa..ff76a47 100644
--- a/services/permission/java/com/android/server/permission/access/immutable/IndexedReferenceMap.kt
+++ b/services/permission/java/com/android/server/permission/access/immutable/IndexedReferenceMap.kt
@@ -18,6 +18,11 @@
import android.util.ArrayMap
+/**
+ * Immutable map with index-based access and mutable data structure values.
+ *
+ * @see MutableReference
+ */
sealed class IndexedReferenceMap<K, I : Immutable<M>, M : I>(
internal val map: ArrayMap<K, MutableReference<I, M>>
) : Immutable<MutableIndexedReferenceMap<K, I, M>> {
@@ -42,6 +47,11 @@
override fun toString(): String = map.toString()
}
+/**
+ * Mutable map with index-based access and mutable data structure values.
+ *
+ * @see MutableReference
+ */
class MutableIndexedReferenceMap<K, I : Immutable<M>, M : I>(
map: ArrayMap<K, MutableReference<I, M>> = ArrayMap()
) : IndexedReferenceMap<K, I, M>(map) {
diff --git a/services/permission/java/com/android/server/permission/access/immutable/IndexedSet.kt b/services/permission/java/com/android/server/permission/access/immutable/IndexedSet.kt
index 9868616..547e56c 100644
--- a/services/permission/java/com/android/server/permission/access/immutable/IndexedSet.kt
+++ b/services/permission/java/com/android/server/permission/access/immutable/IndexedSet.kt
@@ -18,6 +18,9 @@
import android.util.ArraySet
+/**
+ * Immutable set with index-based access.
+ */
sealed class IndexedSet<T>(
internal val set: ArraySet<T>
) : Immutable<MutableIndexedSet<T>> {
@@ -37,6 +40,9 @@
override fun toString(): String = set.toString()
}
+/**
+ * Mutable set with index-based access.
+ */
class MutableIndexedSet<T>(
set: ArraySet<T> = ArraySet()
) : IndexedSet<T>(set) {
diff --git a/services/permission/java/com/android/server/permission/access/immutable/IntMap.kt b/services/permission/java/com/android/server/permission/access/immutable/IntMap.kt
index b7d8b4c..7ed29e8 100644
--- a/services/permission/java/com/android/server/permission/access/immutable/IntMap.kt
+++ b/services/permission/java/com/android/server/permission/access/immutable/IntMap.kt
@@ -18,6 +18,9 @@
import android.util.SparseArray
+/**
+ * Immutable map with index-based access and [Int] keys.
+ */
sealed class IntMap<T>(
internal val array: SparseArray<T>
) : Immutable<MutableIntMap<T>> {
@@ -41,6 +44,9 @@
override fun toString(): String = array.toString()
}
+/**
+ * Mutable map with index-based access and [Int] keys.
+ */
class MutableIntMap<T>(
array: SparseArray<T> = SparseArray()
) : IntMap<T>(array) {
diff --git a/services/permission/java/com/android/server/permission/access/immutable/IntReferenceMap.kt b/services/permission/java/com/android/server/permission/access/immutable/IntReferenceMap.kt
index 22fa8f2..160b227 100644
--- a/services/permission/java/com/android/server/permission/access/immutable/IntReferenceMap.kt
+++ b/services/permission/java/com/android/server/permission/access/immutable/IntReferenceMap.kt
@@ -18,6 +18,11 @@
import android.util.SparseArray
+/**
+ * Immutable map with index-based access, [Int] keys and mutable data structure values.
+ *
+ * @see MutableReference
+ */
sealed class IntReferenceMap<I : Immutable<M>, M : I>(
internal val array: SparseArray<MutableReference<I, M>>
) : Immutable<MutableIntReferenceMap<I, M>> {
@@ -42,6 +47,11 @@
override fun toString(): String = array.toString()
}
+/**
+ * Mutable map with index-based access, [Int] keys and mutable data structure values.
+ *
+ * @see MutableReference
+ */
class MutableIntReferenceMap<I : Immutable<M>, M : I>(
array: SparseArray<MutableReference<I, M>> = SparseArray()
) : IntReferenceMap<I, M>(array) {
diff --git a/services/permission/java/com/android/server/permission/access/immutable/IntSet.kt b/services/permission/java/com/android/server/permission/access/immutable/IntSet.kt
index 9da3671..21f2af2 100644
--- a/services/permission/java/com/android/server/permission/access/immutable/IntSet.kt
+++ b/services/permission/java/com/android/server/permission/access/immutable/IntSet.kt
@@ -18,6 +18,9 @@
import android.util.SparseBooleanArray
+/**
+ * Immutable set with index-based access and [Int] elements.
+ */
sealed class IntSet(
internal val array: SparseBooleanArray
) : Immutable<MutableIntSet> {
@@ -37,6 +40,9 @@
override fun toString(): String = array.toString()
}
+/**
+ * Mutable set with index-based access and [Int] elements.
+ */
class MutableIntSet(
array: SparseBooleanArray = SparseBooleanArray()
) : IntSet(array) {
diff --git a/services/permission/java/com/android/server/permission/access/immutable/MutableReference.kt b/services/permission/java/com/android/server/permission/access/immutable/MutableReference.kt
index e39a3bb..171cfeb 100644
--- a/services/permission/java/com/android/server/permission/access/immutable/MutableReference.kt
+++ b/services/permission/java/com/android/server/permission/access/immutable/MutableReference.kt
@@ -16,14 +16,39 @@
package com.android.server.permission.access.immutable
+/**
+ * Wrapper class for reference to a mutable data structure instance.
+ *
+ * This class encapsulates the logic to mutate/copy a mutable data structure instance and update the
+ * reference to the new mutated instance. It also remembers the mutated instance so that it can be
+ * reused during further mutations.
+ *
+ * Instances of this class should be kept private within a data structure, with the [get] method
+ * exposed on the immutable interface of the data structure as a `getFoo` method, and the [mutate]
+ * method exposed on the mutable interface of the data structure as a `mutateFoo` method. When the
+ * data structure is mutated/copied, a new instance of this class should be obtained with
+ * [toImmutable], which makes the wrapped reference immutable-only again and thus prevents
+ * further modifications to a data structure accessed with its immutable interface.
+ *
+ * @see MutableIndexedReferenceMap
+ * @see MutableIntReferenceMap
+ */
class MutableReference<I : Immutable<M>, M : I> private constructor(
private var immutable: I,
private var mutable: M?
) {
constructor(mutable: M) : this(mutable, mutable)
+ /**
+ * Return an immutable reference to the wrapped mutable data structure.
+ */
fun get(): I = immutable
+ /**
+ * Make the wrapped mutable data structure mutable, by either calling [Immutable.toMutable] and
+ * replacing the wrapped reference with its result, or reusing the existing reference if it's
+ * already mutable.
+ */
fun mutate(): M {
mutable?.let { return it }
return immutable.toMutable().also {
@@ -32,6 +57,10 @@
}
}
+ /**
+ * Create a new [MutableReference] instance with the wrapped mutable data structure being
+ * immutable-only again.
+ */
fun toImmutable(): MutableReference<I, M> = MutableReference(immutable, null)
override fun equals(other: Any?): Boolean {