Introduce EventListener.

coil-base/src/androidTest/java/coil/RealImageLoaderIntegrationTest.kt

@@ -1,3 +1,5 @@
+@file:OptIn(ExperimentalCoilApi::class)
+
 package coil
 
 import android.content.ContentResolver.SCHEME_ANDROID_RESOURCE
@@ -10,6 +12,7 @@ import android.graphics.drawable.ColorDrawable
 import android.widget.ImageView
 import androidx.core.net.toUri
 import androidx.test.core.app.ApplicationProvider
+import coil.annotation.ExperimentalCoilApi
 import coil.api.get
 import coil.api.getAny
 import coil.api.load
@@ -23,8 +26,10 @@ import coil.decode.Decoder
 import coil.decode.Options
 import coil.fetch.AssetUriFetcher.Companion.ASSET_FILE_PATH_ROOT
 import coil.fetch.DrawableResult
+import coil.fetch.Fetcher
 import coil.request.CachePolicy
 import coil.request.NullRequestDataException
+import coil.request.Request
 import coil.size.PixelSize
 import coil.size.Size
 import coil.transform.CircleCropTransformation
@@ -46,6 +51,7 @@ import org.junit.After
 import org.junit.Before
 import org.junit.Test
 import java.io.File
+import java.util.concurrent.atomic.AtomicBoolean
 import kotlin.coroutines.resume
 import kotlin.coroutines.resumeWithException
 import kotlin.test.assertEquals
@@ -366,7 +372,89 @@ class RealImageLoaderIntegrationTest {
  }
  }
 
- private fun testLoad(data: Any, expectedSize: PixelSize = PixelSize(80, 100)) {
+ @Test
+ fun eventListenerMethodsAreCalled() {
+ class MethodChecker(private val eventName: String) {
+
+ private val isCalled = AtomicBoolean(false)
+
+ fun markCalled() {
+ require(!isCalled.getAndSet(true)) { "$eventName was called more than once." }
+ }
+
+ fun requireCalled() {
+ require(isCalled.get()) { "$eventName was NOT called at least once." }
+ }
+
+ fun requireNotCalled() {
+ require(!isCalled.get()) { "$eventName was called once." }
+ }
+ }
+
+ val eventListener = object : EventListener {
+
+ val onStart = MethodChecker("onStart")
+ val mapStart = MethodChecker("mapStart")
+ val mapEnd = MethodChecker("mapEnd")
+ val resolveSizeStart = MethodChecker("resolveSizeStart")
+ val resolveSizeEnd = MethodChecker("resolveSizeEnd")
+ val fetchStart = MethodChecker("fetchStart")
+ val fetchEnd = MethodChecker("fetchEnd")
+ val decodeStart = MethodChecker("decodeStart")
+ val decodeEnd = MethodChecker("decodeEnd")
+ val transformStart = MethodChecker("transformStart")
+ val transformEnd = MethodChecker("transformEnd")
+ val onSuccess = MethodChecker("transformEnd")
+ val onCancel = MethodChecker("transformEnd")
+ val onError = MethodChecker("transformEnd")
+
+ override fun onStart(request: Request) = onStart.markCalled()
+ override fun mapStart(request: Request) = mapStart.markCalled()
+ override fun mapEnd(request: Request, mappedData: Any) = mapEnd.markCalled()
+ override fun resolveSizeStart(request: Request) = resolveSizeStart.markCalled()
+ override fun resolveSizeEnd(request: Request, size: Size) = resolveSizeEnd.markCalled()
+ override fun fetchStart(request: Request, fetcher: Fetcher<*>, options: Options) = fetchStart.markCalled()
+ override fun fetchEnd(request: Request, fetcher: Fetcher<*>, options: Options) = fetchEnd.markCalled()
+ override fun decodeStart(request: Request, decoder: Decoder, options: Options) = decodeStart.markCalled()
+ override fun decodeEnd(request: Request, decoder: Decoder, options: Options) = decodeEnd.markCalled()
+ override fun transformStart(request: Request) = transformStart.markCalled()
+ override fun transformEnd(request: Request) = transformEnd.markCalled()
+ override fun onSuccess(request: Request, source: DataSource) = onSuccess.markCalled()
+ override fun onCancel(request: Request) = onCancel.markCalled()
+ override fun onError(request: Request, throwable: Throwable) = onError.markCalled()
+ }
+
+ runBlocking {
+ val imageLoader = ImageLoader.Builder(context)
+ .eventListener(eventListener)
+ .build()
+
+ testLoad(copyNormalImageAssetToCacheDir(), imageLoader = imageLoader)
+ }
+
+ eventListener.apply {
+ onStart.requireCalled()
+ mapStart.requireCalled()
+ mapEnd.requireCalled()
+ resolveSizeStart.requireCalled()
+ resolveSizeEnd.requireCalled()
+ fetchStart.requireCalled()
+ fetchEnd.requireCalled()
+ decodeStart.requireCalled()
+ decodeEnd.requireCalled()
+ transformStart.requireCalled()
+ transformEnd.requireCalled()
+ onSuccess.requireCalled()
+ onCancel.requireNotCalled()
+ onError.requireNotCalled()
+ }
+ }
+
+ private fun testLoad(
+ data: Any,
+ expectedSize: PixelSize = PixelSize(80, 100),
+ imageLoader: ImageLoader = this.imageLoader
+ ) {
  val imageView = ImageView(context)
  imageView.scaleType = ImageView.ScaleType.FIT_CENTER
 

coil-base/src/main/java/coil/EventListener.kt

@@ -0,0 +1,147 @@
+package coil
+
+import androidx.annotation.MainThread
+import androidx.annotation.WorkerThread
+import coil.annotation.ExperimentalCoilApi
+import coil.decode.DataSource
+import coil.decode.Decoder
+import coil.decode.Options
+import coil.fetch.Fetcher
+import coil.map.Mapper
+import coil.map.MeasuredMapper
+import coil.request.Request
+import coil.size.Size
+import coil.size.SizeResolver
+import coil.transform.Transformation
+
+/**
+ * An [ImageLoader]-scoped listener for tracking the progress of an image request.
+ * This class is useful for measuring analytics, performance, or other metrics tracking.
+ *
+ * @see ImageLoaderBuilder.eventListener
+ */
+@ExperimentalCoilApi
+interface EventListener : Request.Listener {
+
+ companion object {
+ @JvmField
+ val EMPTY = object : EventListener {}
+ }
+
+ /**
+ * Called when the request is started.
+ */
+ @MainThread
+ override fun onStart(request: Request) {}
+
+ /**
+ * Called before any [Mapper]s or [MeasuredMapper]s are called to convert the request's data.
+ */
+ @MainThread
+ fun mapStart(request: Request) {}
+
+ /**
+ * Called after the request's data has been converted.
+ */
+ @MainThread
+ fun mapEnd(request: Request, mappedData: Any) {}
+
+ /**
+ * Called before [SizeResolver.size] to await the request's size.
+ */
+ @MainThread
+ fun resolveSizeStart(request: Request) {}
+
+ /**
+ * Called after the request's size has been resolved.
+ */
+ @MainThread
+ fun resolveSizeEnd(request: Request, size: Size) {}
+
+ /**
+ * Called before [Fetcher.fetch].
+ *
+ * @param fetcher The [Fetcher] that will be used to handle the request.
+ * @param options The [Options] that will be passed to [Fetcher.fetch].
+ */
+ @WorkerThread
+ fun fetchStart(request: Request, fetcher: Fetcher<*>, options: Options) {}
+
+ /**
+ * Called after [Fetcher.fetch].
+ *
+ * @param fetcher The [Fetcher] that was used to handle the request.
+ * @param options The [Options] that were passed to [Fetcher.fetch].
+ */
+ @WorkerThread
+ fun fetchEnd(request: Request, fetcher: Fetcher<*>, options: Options) {}
+
+ /**
+ * Called before [Decoder.decode].
+ *
+ * @param decoder The [Decoder] that will be used to handle the request.
+ * @param options The [Options] that will be passed to [Decoder.decode].
+ */
+ @WorkerThread
+ fun decodeStart(request: Request, decoder: Decoder, options: Options) {}
+
+ /**
+ * Called after [Decoder.decode].
+ *
+ * @param decoder The [Decoder] that was used to handle the request.
+ * @param options The [Options] that were passed to [Decoder.decode].
+ */
+ @WorkerThread
+ fun decodeEnd(request: Request, decoder: Decoder, options: Options) {}
+
+ /**
+ * Called before any [Transformation]s are applied.
+ */
+ @WorkerThread
+ fun transformStart(request: Request) {}
+
+ /**
+ * Called after any [Transformation]s are applied.
+ */
+ @WorkerThread
+ fun transformEnd(request: Request) {}
+
+ /**
+ * Called when the request is successful.
+ */
+ @MainThread
+ override fun onSuccess(request: Request, source: DataSource) {}
+
+ /**
+ * Called when the request is cancelled.
+ */
+ @MainThread
+ override fun onCancel(request: Request) {}
+
+ /**
+ * Called when the request fails.
+ */
+ @MainThread
+ override fun onError(request: Request, throwable: Throwable) {}
+
+ /** A factory that creates new [EventListener] instances. */
+ interface Factory {
+
+ companion object {
+ @JvmField
+ val EMPTY = Factory(EventListener.EMPTY)
+
+ /** Create an [EventListener.Factory] that returns the same [listener]. */
+ @JvmStatic
+ @JvmName("create")
+ operator fun invoke(listener: EventListener): Factory {
+ return object : Factory {
+ override fun newListener(request: Request) = listener
+ }
+ }
+ }
+
+ /** Return a new [EventListener]. */
+ fun newListener(request: Request): EventListener
+ }
+}

coil-base/src/main/java/coil/ImageLoaderBuilder.kt

@@ -38,6 +38,7 @@ class ImageLoaderBuilder(context: Context) {
  private val applicationContext = context.applicationContext
 
  private var callFactory: Call.Factory? = null
+ private var eventListenerFactory: EventListener.Factory? = null
  private var registry: ComponentRegistry? = null
  private var logger: Logger? = null
  private var defaults = DefaultRequestOptions()
@@ -98,6 +99,7 @@ class ImageLoaderBuilder(context: Context) {
  /**
  * Build and set the [ComponentRegistry].
  */
+ @JvmSynthetic
  inline fun componentRegistry(
  builder: ComponentRegistry.Builder.() -> Unit
  ) = componentRegistry(ComponentRegistry.Builder().apply(builder).build())
@@ -183,6 +185,22 @@ class ImageLoaderBuilder(context: Context) {
  this.trackWeakReferences = enable
  }
 
+ /**
+ * Set a single [EventListener] that will receive all callbacks for requests launched by this image loader.
+ */
+ @ExperimentalCoilApi
+ fun eventListener(listener: EventListener) = eventListener(EventListener.Factory(listener))
+
+ /**
+ * Set the [EventListener.Factory] to create per-request [EventListener]s.
+ *
+ * @see eventListener
+ */
+ @ExperimentalCoilApi
+ fun eventListener(factory: EventListener.Factory) = apply {
+ this.eventListenerFactory = factory
+ }
+
  /**
  * Enable a crossfade animation with duration [CrossfadeDrawable.DEFAULT_DURATION] milliseconds
  * when a request completes successfully.
@@ -314,6 +332,7 @@ class ImageLoaderBuilder(context: Context) {
  memoryCache = memoryCache,
  weakMemoryCache = weakMemoryCache,
  callFactory = callFactory ?: buildDefaultCallFactory(),
+ eventListenerFactory = eventListenerFactory ?: EventListener.Factory.EMPTY,
  registry = registry ?: ComponentRegistry(),
  logger = logger
  )