org.apache.http.impl.client.cache.memcached
Class MemcachedHttpCacheStorage

java.lang.Object
  extended by org.apache.http.impl.client.cache.memcached.MemcachedHttpCacheStorage
All Implemented Interfaces:
HttpCacheStorage

public class MemcachedHttpCacheStorage
extends Object
implements HttpCacheStorage

This class is a storage backend that uses an external memcached for storing cached origin responses. This storage option provides a couple of interesting advantages over the default in-memory storage backend:

  1. in-memory cached objects can survive an application restart since they are held in a separate process
  2. it becomes possible for several cooperating applications to share a large memcached farm together

Note that in a shared memcached pool setting you may wish to make use of the Ketama consistent hashing algorithm to reduce the number of cache misses that might result if one of the memcached cluster members fails (see the KetamaConnectionFactory).

Because memcached places limits on the size of its keys, we need to introduce a key hashing scheme to map the annotated URLs the higher-level caching HTTP client wants to use as keys onto ones that are suitable for use with memcached. Please see KeyHashingScheme if you would like to use something other than the provided SHA256KeyHashingScheme.

Because this hashing scheme can potentially result in key collisions (though highly unlikely), we need to store the higher-level logical storage key along with the HttpCacheEntry so that we can re-check it on retrieval. There is a default serialization scheme provided for this, although you can provide your own implementations of MemcachedCacheEntry and MemcachedCacheEntryFactory to customize this serialization.

Please refer to the memcached documentation and in particular to the documentation for the spymemcached documentation for details about how to set up and configure memcached and the Java client used here, respectively.

Since:
4.1

Constructor Summary
MemcachedHttpCacheStorage(InetSocketAddress address)
          Create a storage backend talking to a memcached instance listening on the specified host and port.
MemcachedHttpCacheStorage(net.spy.memcached.MemcachedClientIF cache)
          Create a storage backend using the pre-configured given memcached client.
MemcachedHttpCacheStorage(net.spy.memcached.MemcachedClientIF client, CacheConfig config, HttpCacheEntrySerializer serializer)
          Deprecated. (4.2) do not use
MemcachedHttpCacheStorage(net.spy.memcached.MemcachedClientIF client, CacheConfig config, MemcachedCacheEntryFactory memcachedCacheEntryFactory, KeyHashingScheme keyHashingScheme)
          Create a storage backend using the given memcached client and applying the given cache configuration, serialization, and hashing mechanisms.
 
Method Summary
 HttpCacheEntry getEntry(String url)
          Retrieves the cache entry stored under the given key or null if no entry exists under that key.
 void putEntry(String url, HttpCacheEntry entry)
          Store a given cache entry under the given key.
 void removeEntry(String url)
          Deletes/invalidates/removes any cache entries currently stored under the given key.
 void updateEntry(String url, HttpCacheUpdateCallback callback)
          Atomically applies the given callback to update an existing cache entry under a given key.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MemcachedHttpCacheStorage

public MemcachedHttpCacheStorage(InetSocketAddress address)
                          throws IOException
Create a storage backend talking to a memcached instance listening on the specified host and port. This is useful if you just have a single local memcached instance running on the same machine as your application, for example.

Parameters:
address - where the memcached daemon is running
Throws:
IOException - in case of an error

MemcachedHttpCacheStorage

public MemcachedHttpCacheStorage(net.spy.memcached.MemcachedClientIF cache)
Create a storage backend using the pre-configured given memcached client.

Parameters:
cache - client to use for communicating with memcached

MemcachedHttpCacheStorage

@Deprecated
public MemcachedHttpCacheStorage(net.spy.memcached.MemcachedClientIF client,
                                            CacheConfig config,
                                            HttpCacheEntrySerializer serializer)
Deprecated. (4.2) do not use

Create a storage backend using the given memcached client and applying the given cache configuration and cache entry serialization mechanism. Deprecation note: In the process of fixing a bug based on the need to hash logical storage keys onto memcached cache keys, the serialization process was revamped. This constructor still works, but the serializer argument will be ignored and default implementations of the new framework will be used. You can still provide custom serialization by using the MemcachedHttpCacheStorage(MemcachedClientIF, CacheConfig, MemcachedCacheEntryFactory, KeyHashingScheme) constructor.

Parameters:
client - how to talk to memcached
config - apply HTTP cache-related options
serializer - ignored

MemcachedHttpCacheStorage

public MemcachedHttpCacheStorage(net.spy.memcached.MemcachedClientIF client,
                                 CacheConfig config,
                                 MemcachedCacheEntryFactory memcachedCacheEntryFactory,
                                 KeyHashingScheme keyHashingScheme)
Create a storage backend using the given memcached client and applying the given cache configuration, serialization, and hashing mechanisms.

Parameters:
client - how to talk to memcached
config - apply HTTP cache-related options
memcachedCacheEntryFactory - Factory pattern used for obtaining instances of alternative cache entry serialization mechanisms
keyHashingScheme - how to map higher-level logical "storage keys" onto "cache keys" suitable for use with memcached
Method Detail

putEntry

public void putEntry(String url,
                     HttpCacheEntry entry)
              throws IOException
Description copied from interface: HttpCacheStorage
Store a given cache entry under the given key.

Specified by:
putEntry in interface HttpCacheStorage
Parameters:
url - where in the cache to store the entry
entry - cached response to store
Throws:
IOException

getEntry

public HttpCacheEntry getEntry(String url)
                        throws IOException
Description copied from interface: HttpCacheStorage
Retrieves the cache entry stored under the given key or null if no entry exists under that key.

Specified by:
getEntry in interface HttpCacheStorage
Parameters:
url - cache key
Returns:
an HttpCacheEntry or null if no entry exists
Throws:
IOException

removeEntry

public void removeEntry(String url)
                 throws IOException
Description copied from interface: HttpCacheStorage
Deletes/invalidates/removes any cache entries currently stored under the given key.

Specified by:
removeEntry in interface HttpCacheStorage
Throws:
IOException

updateEntry

public void updateEntry(String url,
                        HttpCacheUpdateCallback callback)
                 throws HttpCacheUpdateException,
                        IOException
Description copied from interface: HttpCacheStorage
Atomically applies the given callback to update an existing cache entry under a given key.

Specified by:
updateEntry in interface HttpCacheStorage
Parameters:
url - indicates which entry to modify
callback - performs the update; see HttpCacheUpdateCallback for details, but roughly the callback expects to be handed the current entry and will return the new value for the entry.
Throws:
HttpCacheUpdateException
IOException


Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.