From 0881f77a70fe505767ad77fe3068f3d3a009f373 Mon Sep 17 00:00:00 2001 From: Hai Zhang Date: Wed, 26 Jul 2023 18:08:49 -0700 Subject: [PATCH] Add kdoc for immutable data structure classes. In addition to the existing Immutable.md. Bug: 285432076 Test: presubmit Change-Id: I77529bb4782db6cbe7b8a8f96890a78661aa9fc0 --- .../access/immutable/IndexedList.kt | 6 ++++ .../access/immutable/IndexedListSet.kt | 6 ++++ .../permission/access/immutable/IndexedMap.kt | 6 ++++ .../access/immutable/IndexedReferenceMap.kt | 10 +++++++ .../permission/access/immutable/IndexedSet.kt | 6 ++++ .../permission/access/immutable/IntMap.kt | 6 ++++ .../access/immutable/IntReferenceMap.kt | 10 +++++++ .../permission/access/immutable/IntSet.kt | 6 ++++ .../access/immutable/MutableReference.kt | 29 +++++++++++++++++++ 9 files changed, 85 insertions(+) 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 6108ad2988001..ce4aa4446698b 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( internal val list: ArrayList ) : Immutable> { @@ -34,6 +37,9 @@ sealed class IndexedList( override fun toString(): String = list.toString() } +/** + * Mutable list with index-based access. + */ class MutableIndexedList( list: ArrayList = ArrayList() ) : IndexedList(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 1202c817d97b2..77e71baf0ab77 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( internal val list: ArrayList ) : Immutable> { @@ -36,6 +39,9 @@ sealed class IndexedListSet( override fun toString(): String = list.toString() } +/** + * Mutable set with index-based access, implemented using a list. + */ class MutableIndexedListSet( list: ArrayList = ArrayList() ) : IndexedListSet(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 5c75de83792f3..299cc89d9a07d 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 @@ package com.android.server.permission.access.immutable import android.util.ArrayMap +/** + * Immutable map with index-based access. + */ sealed class IndexedMap( internal val map: ArrayMap ) : Immutable> { @@ -42,6 +45,9 @@ sealed class IndexedMap( override fun toString(): String = map.toString() } +/** + * Mutable map with index-based access. + */ class MutableIndexedMap( map: ArrayMap = ArrayMap() ) : IndexedMap(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 8c963aae1967d..ff76a4745c8b7 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 @@ package com.android.server.permission.access.immutable import android.util.ArrayMap +/** + * Immutable map with index-based access and mutable data structure values. + * + * @see MutableReference + */ sealed class IndexedReferenceMap, M : I>( internal val map: ArrayMap> ) : Immutable> { @@ -42,6 +47,11 @@ sealed class IndexedReferenceMap, M : I>( override fun toString(): String = map.toString() } +/** + * Mutable map with index-based access and mutable data structure values. + * + * @see MutableReference + */ class MutableIndexedReferenceMap, M : I>( map: ArrayMap> = ArrayMap() ) : IndexedReferenceMap(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 986861624e4b6..547e56cef62a9 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 @@ package com.android.server.permission.access.immutable import android.util.ArraySet +/** + * Immutable set with index-based access. + */ sealed class IndexedSet( internal val set: ArraySet ) : Immutable> { @@ -37,6 +40,9 @@ sealed class IndexedSet( override fun toString(): String = set.toString() } +/** + * Mutable set with index-based access. + */ class MutableIndexedSet( set: ArraySet = ArraySet() ) : IndexedSet(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 b7d8b4ccddd04..7ed29e8813acf 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 @@ package com.android.server.permission.access.immutable import android.util.SparseArray +/** + * Immutable map with index-based access and [Int] keys. + */ sealed class IntMap( internal val array: SparseArray ) : Immutable> { @@ -41,6 +44,9 @@ sealed class IntMap( override fun toString(): String = array.toString() } +/** + * Mutable map with index-based access and [Int] keys. + */ class MutableIntMap( array: SparseArray = SparseArray() ) : IntMap(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 22fa8f2a7c7e6..160b2279a0ba6 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 @@ package com.android.server.permission.access.immutable import android.util.SparseArray +/** + * Immutable map with index-based access, [Int] keys and mutable data structure values. + * + * @see MutableReference + */ sealed class IntReferenceMap, M : I>( internal val array: SparseArray> ) : Immutable> { @@ -42,6 +47,11 @@ sealed class IntReferenceMap, M : I>( override fun toString(): String = array.toString() } +/** + * Mutable map with index-based access, [Int] keys and mutable data structure values. + * + * @see MutableReference + */ class MutableIntReferenceMap, M : I>( array: SparseArray> = SparseArray() ) : IntReferenceMap(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 9da36717db7ed..21f2af20c3a91 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 @@ package com.android.server.permission.access.immutable import android.util.SparseBooleanArray +/** + * Immutable set with index-based access and [Int] elements. + */ sealed class IntSet( internal val array: SparseBooleanArray ) : Immutable { @@ -37,6 +40,9 @@ sealed class IntSet( 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 e39a3bbc89423..171cfeb4379d8 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, 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 @@ class MutableReference, M : I> private constructor( } } + /** + * Create a new [MutableReference] instance with the wrapped mutable data structure being + * immutable-only again. + */ fun toImmutable(): MutableReference = MutableReference(immutable, null) override fun equals(other: Any?): Boolean {