Documentation

You are viewing the documentation for the 3.0.0 release. The latest stable release series is 3.0.x.

§Configuring WS Cache

Play WS allows you to set up HTTP caching from configuration.

§Enabling Cache

You must have a JSR 107 cache implementation (aka JCache) available in your Play application to use Play WS’s cache facility. Play comes with an implementation that uses ehcache, so the easiest implementation is to add the following to build.sbt:

libraryDependencies += ws
libraryDependencies += ehcache

And enable the HTTP cache by adding the following to application.conf

play.ws.cache.enabled=true

If no JCache implementation is found, then Play WS will use an HTTP Cache with a stub cache that does not store anything.

§Enabling Freshness Heuristics

By default, Play WS does not cache HTTP responses when no explicit cache information is passed in. However, HTTP caching does have an option to cache pages based off heuristics so that you can cache responses even without co-operation from the remote server.

To enable heuristics, set the following in application.conf:

play.ws.cache.heuristics.enabled=true

Play WS uses the LM-Factor algorithm to cache HTTP responses.

§Limiting Cache Size

Cache size is limited by the underlying cache implementation. Play WS will create a generic cache if no cache was found, but you should bound the cache explicitly, as JCache does not provide many options.

NOTE: If you do not limit the HTTP cache or expire elements in the cache, then you may cause the JVM to run out of memory.

In ehcache, you can specify an existing cache by specifying CacheManager resource explicitly, which is used in cachingProvider.getCacheManager(uri, environment.classLoader):

play.ws.cache.cacheManagerResource="ehcache-play-ws-cache.xml"

and then adding a cache such as following into the conf directory:

<ehcache
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="http://ehcache.org/ehcache.xsd"
        name="play-ws-cache"
        updateCheck="false"
        >

	<cache name="play-ws-cache" maxEntriesLocalHeap="10000" eternal="false"
		timeToIdleSeconds="360" timeToLiveSeconds="1000" overflowToDisk="false" />

</ehcache>

NOTE: play.ws.cache.cacheManagerURI is deprecated, use play.ws.cache.cacheManagerResource with a path on the classpath instead.

§Debugging the Cache

To see exactly what the HTTP caching layer in Play WS is doing, please add the following to logback.xml:

<logger name="play.api.libs.ws.ahc.cache" level="TRACE" />

§Defining a Caching Provider

You can define a specific CachingProvider for the WS cache, even if you are already using ehcache as a caching provider for Play Cache. For example, you can load the Caffeine library:

// https://mvnrepository.com/artifact/com.github.ben-manes.caffeine/jcache
libraryDependencies += "com.github.ben-manes.caffeine" % "jcache" % "2.4.0"

and then specify Caffeine JCache as the caching provider:

play.ws.cache.cachingProviderName="<jcache caching provider class name>"

§Reference Configuration

The reference configuration shows the default settings for Play WS Caching:

# Copyright (C) from 2022 The Play Framework Contributors <https://github.com/playframework>, 2011-2021 Lightbend Inc. <https://www.lightbend.com>

play {
  modules {
    enabled += "play.api.libs.ws.ahc.AhcWSModule"
    enabled += "play.libs.ws.ahc.AhcWSModule"
  }
}

# Configuration settings for JSR 107 Cache for Play WS.
play.ws.cache {

  # True if caching is enabled for the default WS client, false by default
  enabled = false

  # Calculates heuristic freshness if no explicit freshness is enabled
  # according to https://tools.ietf.org/html/rfc7234#section-4.2.2 with LM-Freshness
  heuristics.enabled = false

  # The name of the cache
  name = "play-ws-cache"

  # A specific caching provider name (e.g. if both ehcache and caffeine are set)
  cachingProviderName = ""

  # The CacheManager resource to use. For example:
  #
  # cacheManagerResource = "ehcache-play-ws-cache.xml"
  #
  # If null, will use the ehcache default URI.
  cacheManagerResource = null

  # The CacheManager URI to use. If non-null, this is used instead of cacheManagerResource.
  cacheManagerURI = null
}

Next: Static assets