Javadoc for Ehcache and memcached cache storage backends. I think we're in
good shape for Javadocs on the caching module now. git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@1057287 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Jonathan Moore
parent
4b29dae09d
commit
6e1d7a0ad3
|
|
@ -41,27 +41,66 @@ import org.apache.http.client.cache.HttpCacheUpdateException;
|
|||
import org.apache.http.impl.client.cache.CacheConfig;
|
||||
import org.apache.http.impl.client.cache.DefaultHttpCacheEntrySerializer;
|
||||
|
||||
/**
|
||||
* <p>This class is a storage backend for cache entries that uses the
|
||||
* popular <a href="http://ehcache.org">Ehcache</a> cache implementation.
|
||||
* In particular, this backend allows for spillover to disk, where the
|
||||
* cache can be effectively larger than memory, and cached responses are
|
||||
* paged into and out of memory from disk as needed.</p>
|
||||
*
|
||||
* <p><b>N.B.</b> Since the Ehcache is configured ahead of time with a
|
||||
* maximum number of cache entries, this effectively ignores the
|
||||
* {@link CacheConfig#setMaxCacheEntries(int) maximum cache entries}
|
||||
* specified by a provided {@link CacheConfig}.</p>
|
||||
*
|
||||
* <p>Please refer to the <a href="http://ehcache.org/documentation/index.html">
|
||||
* Ehcache documentation</a> for details on how to configure the Ehcache
|
||||
* itself.</p>
|
||||
* @since 4.1
|
||||
*/
|
||||
public class EhcacheHttpCacheStorage implements HttpCacheStorage {
|
||||
|
||||
private final Ehcache cache;
|
||||
private final HttpCacheEntrySerializer serializer;
|
||||
private final int maxUpdateRetries;
|
||||
|
||||
/**
|
||||
* Constructs a storage backend using the provided Ehcache
|
||||
* with default configuration options.
|
||||
* @param cache where to store cached origin responses
|
||||
*/
|
||||
public EhcacheHttpCacheStorage(Ehcache cache) {
|
||||
this(cache, new CacheConfig(), new DefaultHttpCacheEntrySerializer());
|
||||
}
|
||||
|
||||
/**
|
||||
* Constructs a storage backend using the provided Ehcache
|
||||
* with the given configuration options.
|
||||
* @param cache where to store cached origin responses
|
||||
* @param config cache storage configuration options - note that
|
||||
* the setting for max object size <b>will be ignored</b> and
|
||||
* should be configured in the Ehcache instead.
|
||||
*/
|
||||
public EhcacheHttpCacheStorage(Ehcache cache, CacheConfig config){
|
||||
this(cache, config, new DefaultHttpCacheEntrySerializer());
|
||||
}
|
||||
|
||||
/**
|
||||
* Constructs a storage backend using the provided Ehcache
|
||||
* with the given configuration options, but using an alternative
|
||||
* cache entry serialization strategy.
|
||||
* @param cache where to store cached origin responses
|
||||
* @param config cache storage configuration options - note that
|
||||
* the setting for max object size <b>will be ignored</b> and
|
||||
* should be configured in the Ehcache instead.
|
||||
* @param serializer alternative serialization mechanism
|
||||
*/
|
||||
public EhcacheHttpCacheStorage(Ehcache cache, CacheConfig config, HttpCacheEntrySerializer serializer){
|
||||
this.cache = cache;
|
||||
this.maxUpdateRetries = config.getMaxUpdateRetries();
|
||||
this.serializer = serializer;
|
||||
}
|
||||
|
||||
|
||||
public synchronized void putEntry(String key, HttpCacheEntry entry) throws IOException {
|
||||
ByteArrayOutputStream bos = new ByteArrayOutputStream();
|
||||
serializer.writeTo(entry, bos);
|
||||
|
|
|
|||
40
httpclient-cache/src/main/java/org/apache/http/impl/client/cache/ehcache/package.html
vendored
Normal file
40
httpclient-cache/src/main/java/org/apache/http/impl/client/cache/ehcache/package.html
vendored
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
||||
<html>
|
||||
<head>
|
||||
<!--
|
||||
====================================================================
|
||||
Licensed to the Apache Software Foundation (ASF) under one
|
||||
or more contributor license agreements. See the NOTICE file
|
||||
distributed with this work for additional information
|
||||
regarding copyright ownership. The ASF licenses this file
|
||||
to you under the Apache License, Version 2.0 (the
|
||||
"License"); you may not use this file except in compliance
|
||||
with the License. You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing,
|
||||
software distributed under the License is distributed on an
|
||||
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
||||
KIND, either express or implied. See the License for the
|
||||
specific language governing permissions and limitations
|
||||
under the License.
|
||||
====================================================================
|
||||
|
||||
This software consists of voluntary contributions made by many
|
||||
individuals on behalf of the Apache Software Foundation. For more
|
||||
information on the Apache Software Foundation, please see
|
||||
<http://www.apache.org/>.
|
||||
-->
|
||||
</head>
|
||||
<body bgcolor="white">
|
||||
|
||||
<p>
|
||||
This package contains a storage backend based on
|
||||
<a href="http://ehcache.org/">Ehcache</a>
|
||||
that can be plugged into
|
||||
a {@link org.apache.http.impl.client.cache.CachingHttpClient} and
|
||||
used for storing cache entries.
|
||||
</p>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -45,20 +45,71 @@ import org.apache.http.client.cache.HttpCacheUpdateCallback;
|
|||
import org.apache.http.impl.client.cache.CacheConfig;
|
||||
import org.apache.http.impl.client.cache.DefaultHttpCacheEntrySerializer;
|
||||
|
||||
/**
|
||||
* <p>This class is a storage backend that uses an external <i>memcached</i>
|
||||
* for storing cached origin responses. This storage option provides a
|
||||
* couple of interesting advantages over the default in-memory storage
|
||||
* backend:
|
||||
* <ol>
|
||||
* <li>in-memory cached objects can survive an application restart since
|
||||
* they are held in a separate process</li>
|
||||
* <li>it becomes possible for several cooperating applications to share
|
||||
* a large <i>memcached</i> farm together, effectively providing cache
|
||||
* peering of a sort</li>
|
||||
* </ol>
|
||||
* 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 <a href="http://dustin.github.com/java-memcached-client/apidocs/net/spy/memcached/KetamaConnectionFactory.html">
|
||||
* KetamaConnectionFactory</a>).
|
||||
* </p>
|
||||
*
|
||||
* <p>Please refer to the <a href="http://code.google.com/p/memcached/wiki/NewStart">
|
||||
* memcached documentation</a> and in particular to the documentation for
|
||||
* the <a href="http://code.google.com/p/spymemcached/">spymemcached
|
||||
* documentation</a> for details about how to set up and configure memcached
|
||||
* and the Java client used here, respectively.</p>
|
||||
*
|
||||
* @since 4.1
|
||||
*/
|
||||
public class MemcachedHttpCacheStorage implements HttpCacheStorage {
|
||||
|
||||
private final MemcachedClientIF client;
|
||||
private final HttpCacheEntrySerializer serializer;
|
||||
private final int maxUpdateRetries;
|
||||
|
||||
/**
|
||||
* Create a storage backend talking to a <i>memcached</i> 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.
|
||||
* @param address where the <i>memcached</i> daemon is running
|
||||
* @throws IOException
|
||||
*/
|
||||
public MemcachedHttpCacheStorage(InetSocketAddress address) throws IOException {
|
||||
this(new MemcachedClient(address));
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a storage backend using the pre-configured given
|
||||
* <i>memcached</i> client.
|
||||
* @param cache client to use for communicating with <i>memcached</i>
|
||||
*/
|
||||
public MemcachedHttpCacheStorage(MemcachedClientIF cache) {
|
||||
this(cache, new CacheConfig(), new DefaultHttpCacheEntrySerializer());
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a storage backend using the given <i>memcached</i> client and
|
||||
* applying the given cache configuration and cache entry serialization
|
||||
* mechanism.
|
||||
* @param client how to talk to <i>memcached</i>
|
||||
* @param config apply HTTP cache-related options
|
||||
* @param serializer how to serialize the cache entries before writing
|
||||
* them out to <i>memcached</i>. The provided {@link
|
||||
* DefaultHttpCacheEntrySerializer} is a fine serialization mechanism
|
||||
* to use here.
|
||||
*/
|
||||
public MemcachedHttpCacheStorage(MemcachedClientIF client, CacheConfig config,
|
||||
HttpCacheEntrySerializer serializer) {
|
||||
this.client = client;
|
||||
|
|
|
|||
40
httpclient-cache/src/main/java/org/apache/http/impl/client/cache/memcached/package.html
vendored
Normal file
40
httpclient-cache/src/main/java/org/apache/http/impl/client/cache/memcached/package.html
vendored
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
||||
<html>
|
||||
<head>
|
||||
<!--
|
||||
====================================================================
|
||||
Licensed to the Apache Software Foundation (ASF) under one
|
||||
or more contributor license agreements. See the NOTICE file
|
||||
distributed with this work for additional information
|
||||
regarding copyright ownership. The ASF licenses this file
|
||||
to you under the Apache License, Version 2.0 (the
|
||||
"License"); you may not use this file except in compliance
|
||||
with the License. You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing,
|
||||
software distributed under the License is distributed on an
|
||||
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
||||
KIND, either express or implied. See the License for the
|
||||
specific language governing permissions and limitations
|
||||
under the License.
|
||||
====================================================================
|
||||
|
||||
This software consists of voluntary contributions made by many
|
||||
individuals on behalf of the Apache Software Foundation. For more
|
||||
information on the Apache Software Foundation, please see
|
||||
<http://www.apache.org/>.
|
||||
-->
|
||||
</head>
|
||||
<body bgcolor="white">
|
||||
|
||||
<p>
|
||||
This package contains a storage backend based on
|
||||
<a href="http://memcached.org/">memcached</a>
|
||||
that can be plugged into
|
||||
a {@link org.apache.http.impl.client.cache.CachingHttpClient} and
|
||||
used for storing cache entries.
|
||||
</p>
|
||||
</body>
|
||||
</html>
|
||||
Loading…
Reference in New Issue