ImageCache and ImageProvider changes

Contents

Summary

ImageCache now has a method called containsKey. ImageProvider subclasses should not override resolve, but instead should implement new methods on ImageProvider. These changes were submitted as a single commit to the framework.

Description of change

The sections below describe the changes to containsKey and ImageProvider.

containsKey change

Clients of the ImageCache, such as a custom ImageProvider, may want to know if the cache is already tracking an image. Adding the containsKey method allows callers to discover this without calling a method like putIfAbsent, which can trigger an undesired call to ImageProvider.load.

The default implementation checks both pending and cached image buckets.

  bool containsKey(Object key) {
    return _pendingImages[key] != null || _cache[key] != null;
  }

ImageProvider changes

The ImageProvider.resolve method does some complicated error handling work that should not normally be overridden. It also previously did work to load the image into the image cache, by way of ImageProvider.obtainKey and ImageProvider.load. Subclasses had no opportunity to override this behavior without overriding resolve, and the ability to compose ImageProviders is limited if multiple ImageProviders expect to override resolve.

To solve this issue, resolve is now marked as non-virtual, and two new protected methods have been added: createStream() and resolveStreamForKey(). These methods allow subclasses to control most of the behavior of resolve, without having to duplicate all the error handling work. It also allows subclasses that compose ImageProviders to be more confident that there is only one public entrypoint to the various chained providers.

Migration guide

ImageCache change

Before migration, the code would not have an override of containsKey.

Code after migration:

class MyImageCache implements ImageCache {
  @override
  bool containsKey(Object key) {
    // Check if your custom cache is tracking this key.
  }

  ...
}

ImageProvider change

Code before the migration:

class MyImageProvider extends ImageProvider<Object> {
  @override
  ImageStream resolve(ImageConfiguration configuration) {
    // create stream
    // set up error handling
    // interact with ImageCache
    // call obtainKey/load, etc.
  }
  ...
}

Code after the migration:

class MyImageProvider extends ImageProvider<Object> {
  @override
  ImageStream createStream(ImageConfiguration configuration) {
    // Return stream, or use super.createStream(),
    // which returns a new ImageStream.
  }

  @override
  void resolveStreamForKey(
    ImageConfiguration configuration,
    ImageStream stream,
    Object key,
    ImageErrorListener handleError,
  ) {
    // Interact with the cache, use the key, potentially call `load`,
    // and report any errors back through `handleError`.
  }
  ...
}

Timeline

Landed in version: 1.16.3
In stable release: 1.17

References

API documentation:

Relevant issues:

Relevant PRs: