hc-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From j...@apache.org
Subject svn commit: r1057287 - in /httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache: ehcache/EhcacheHttpCacheStorage.java ehcache/package.html memcached/MemcachedHttpCacheStorage.java memcached/package.html
Date Mon, 10 Jan 2011 17:09:57 GMT
Author: jonm
Date: Mon Jan 10 17:09:56 2011
New Revision: 1057287

URL: http://svn.apache.org/viewvc?rev=1057287&view=rev
Log:
Javadoc for Ehcache and memcached cache storage backends. I think we're in
good shape for Javadocs on the caching module now.

Added:
    httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/ehcache/package.html
  (with props)
    httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/memcached/package.html
  (with props)
Modified:
    httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/ehcache/EhcacheHttpCacheStorage.java
    httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/memcached/MemcachedHttpCacheStorage.java

Modified: httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/ehcache/EhcacheHttpCacheStorage.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/ehcache/EhcacheHttpCacheStorage.java?rev=1057287&r1=1057286&r2=1057287&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/ehcache/EhcacheHttpCacheStorage.java
(original)
+++ httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/ehcache/EhcacheHttpCacheStorage.java
Mon Jan 10 17:09:56 2011
@@ -41,27 +41,66 @@ import org.apache.http.client.cache.Http
 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);

Added: httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/ehcache/package.html
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/ehcache/package.html?rev=1057287&view=auto
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/ehcache/package.html
(added)
+++ httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/ehcache/package.html
Mon Jan 10 17:09:56 2011
@@ -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>

Propchange: httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/ehcache/package.html
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/ehcache/package.html
------------------------------------------------------------------------------
    svn:keywords = Date Author Id Revision HeadURL

Propchange: httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/ehcache/package.html
------------------------------------------------------------------------------
    svn:mime-type = text/html

Modified: httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/memcached/MemcachedHttpCacheStorage.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/memcached/MemcachedHttpCacheStorage.java?rev=1057287&r1=1057286&r2=1057287&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/memcached/MemcachedHttpCacheStorage.java
(original)
+++ httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/memcached/MemcachedHttpCacheStorage.java
Mon Jan 10 17:09:56 2011
@@ -45,20 +45,71 @@ import org.apache.http.client.cache.Http
 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;

Added: httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/memcached/package.html
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/memcached/package.html?rev=1057287&view=auto
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/memcached/package.html
(added)
+++ httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/memcached/package.html
Mon Jan 10 17:09:56 2011
@@ -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>

Propchange: httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/memcached/package.html
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/memcached/package.html
------------------------------------------------------------------------------
    svn:keywords = Date Author Id Revision HeadURL

Propchange: httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/memcached/package.html
------------------------------------------------------------------------------
    svn:mime-type = text/html



Mime
View raw message