diff options
Diffstat (limited to 'mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache')
14 files changed, 1092 insertions, 0 deletions
diff --git a/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/CacheResponseStatus.java b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/CacheResponseStatus.java new file mode 100644 index 000000000..d000839af --- /dev/null +++ b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/CacheResponseStatus.java @@ -0,0 +1,55 @@ +/* + * ==================================================================== + * 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/>. + * + */ +package ch.boye.httpclientandroidlib.client.cache; + +/** + * This enumeration represents the various ways a response can be generated + * by the {@link ch.boye.httpclientandroidlib.impl.client.cache.CachingHttpClient}; + * if a request is executed with an {@link ch.boye.httpclientandroidlib.protocol.HttpContext} + * then a parameter with one of these values will be registered in the + * context under the key + * {@link ch.boye.httpclientandroidlib.impl.client.cache.CachingHttpClient#CACHE_RESPONSE_STATUS}. + */ +public enum CacheResponseStatus { + + /** The response was generated directly by the caching module. */ + CACHE_MODULE_RESPONSE, + + /** A response was generated from the cache with no requests sent + * upstream. + */ + CACHE_HIT, + + /** The response came from an upstream server. */ + CACHE_MISS, + + /** The response was generated from the cache after validating the + * entry with the origin server. + */ + VALIDATED; + +} diff --git a/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HeaderConstants.java b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HeaderConstants.java new file mode 100644 index 000000000..22f34dcff --- /dev/null +++ b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HeaderConstants.java @@ -0,0 +1,81 @@ +/* + * ==================================================================== + * 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/>. + * + */ +package ch.boye.httpclientandroidlib.client.cache; + +import ch.boye.httpclientandroidlib.annotation.Immutable; + +/** + * Records static constants for various HTTP header names. + * @since 4.1 + */ +@Immutable +public class HeaderConstants { + + public static final String GET_METHOD = "GET"; + public static final String HEAD_METHOD = "HEAD"; + public static final String OPTIONS_METHOD = "OPTIONS"; + public static final String PUT_METHOD = "PUT"; + public static final String DELETE_METHOD = "DELETE"; + public static final String TRACE_METHOD = "TRACE"; + + public static final String LAST_MODIFIED = "Last-Modified"; + public static final String IF_MATCH = "If-Match"; + public static final String IF_RANGE = "If-Range"; + public static final String IF_UNMODIFIED_SINCE = "If-Unmodified-Since"; + public static final String IF_MODIFIED_SINCE = "If-Modified-Since"; + public static final String IF_NONE_MATCH = "If-None-Match"; + + public static final String PRAGMA = "Pragma"; + public static final String MAX_FORWARDS = "Max-Forwards"; + public static final String ETAG = "ETag"; + public static final String EXPIRES = "Expires"; + public static final String AGE = "Age"; + public static final String VARY = "Vary"; + public static final String ALLOW = "Allow"; + public static final String VIA = "Via"; + public static final String PUBLIC = "public"; + public static final String PRIVATE = "private"; + + public static final String CACHE_CONTROL = "Cache-Control"; + public static final String CACHE_CONTROL_NO_STORE = "no-store"; + public static final String CACHE_CONTROL_NO_CACHE = "no-cache"; + public static final String CACHE_CONTROL_MAX_AGE = "max-age"; + public static final String CACHE_CONTROL_MAX_STALE = "max-stale"; + public static final String CACHE_CONTROL_MIN_FRESH = "min-fresh"; + public static final String CACHE_CONTROL_MUST_REVALIDATE = "must-revalidate"; + public static final String CACHE_CONTROL_PROXY_REVALIDATE = "proxy-revalidate"; + public static final String STALE_IF_ERROR = "stale-if-error"; + public static final String STALE_WHILE_REVALIDATE = "stale-while-revalidate"; + + public static final String WARNING = "Warning"; + public static final String RANGE = "Range"; + public static final String CONTENT_RANGE = "Content-Range"; + public static final String WWW_AUTHENTICATE = "WWW-Authenticate"; + public static final String PROXY_AUTHENTICATE = "Proxy-Authenticate"; + public static final String AUTHORIZATION = "Authorization"; + +} diff --git a/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HttpCacheContext.java b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HttpCacheContext.java new file mode 100644 index 000000000..54edfa12a --- /dev/null +++ b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HttpCacheContext.java @@ -0,0 +1,71 @@ +/* + * ==================================================================== + * 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/>. + * + */ +package ch.boye.httpclientandroidlib.client.cache; + +import ch.boye.httpclientandroidlib.annotation.NotThreadSafe; +import ch.boye.httpclientandroidlib.client.protocol.HttpClientContext; +import ch.boye.httpclientandroidlib.protocol.BasicHttpContext; +import ch.boye.httpclientandroidlib.protocol.HttpContext; + +/** + * @since 4.3 + */ +@NotThreadSafe +public class HttpCacheContext extends HttpClientContext { + + /** + * This is the name under which the {@link CacheResponseStatus} of a request + * (for example, whether it resulted in a cache hit) will be recorded if an + * {@link HttpContext} is provided during execution. + */ + public static final String CACHE_RESPONSE_STATUS = "http.cache.response.status"; + + public static HttpCacheContext adapt(final HttpContext context) { + if (context instanceof HttpCacheContext) { + return (HttpCacheContext) context; + } else { + return new HttpCacheContext(context); + } + } + + public static HttpCacheContext create() { + return new HttpCacheContext(new BasicHttpContext()); + } + + public HttpCacheContext(final HttpContext context) { + super(context); + } + + public HttpCacheContext() { + super(); + } + + public CacheResponseStatus getCacheResponseStatus() { + return getAttribute(CACHE_RESPONSE_STATUS, CacheResponseStatus.class); + } + +} diff --git a/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HttpCacheEntry.java b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HttpCacheEntry.java new file mode 100644 index 000000000..d03786279 --- /dev/null +++ b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HttpCacheEntry.java @@ -0,0 +1,263 @@ +/* + * ==================================================================== + * 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/>. + * + */ +package ch.boye.httpclientandroidlib.client.cache; + +import java.io.Serializable; +import java.util.Collections; +import java.util.Date; +import java.util.HashMap; +import java.util.Map; + +import ch.boye.httpclientandroidlib.Header; +import ch.boye.httpclientandroidlib.ProtocolVersion; +import ch.boye.httpclientandroidlib.StatusLine; +import ch.boye.httpclientandroidlib.annotation.Immutable; +import ch.boye.httpclientandroidlib.client.utils.DateUtils; +import ch.boye.httpclientandroidlib.message.HeaderGroup; +import ch.boye.httpclientandroidlib.protocol.HTTP; +import ch.boye.httpclientandroidlib.util.Args; + +/** + * Structure used to store an {@link ch.boye.httpclientandroidlib.HttpResponse} in a cache. + * Some entries can optionally depend on system resources that may require + * explicit deallocation. In such a case {@link #getResource()} should return + * a non null instance of {@link Resource} that must be deallocated by calling + * {@link Resource#dispose()} method when no longer used. + * + * @since 4.1 + */ +@Immutable +public class HttpCacheEntry implements Serializable { + + private static final long serialVersionUID = -6300496422359477413L; + + private final Date requestDate; + private final Date responseDate; + private final StatusLine statusLine; + private final HeaderGroup responseHeaders; + private final Resource resource; + private final Map<String,String> variantMap; + private final Date date; + + /** + * Create a new {@link HttpCacheEntry} with variants. + * @param requestDate + * Date/time when the request was made (Used for age + * calculations) + * @param responseDate + * Date/time that the response came back (Used for age + * calculations) + * @param statusLine + * HTTP status line from origin response + * @param responseHeaders + * Header[] from original HTTP Response + * @param resource representing origin response body + * @param variantMap describing cache entries that are variants + * of this parent entry; this maps a "variant key" (derived + * from the varying request headers) to a "cache key" (where + * in the cache storage the particular variant is located) + */ + public HttpCacheEntry( + final Date requestDate, + final Date responseDate, + final StatusLine statusLine, + final Header[] responseHeaders, + final Resource resource, + final Map<String,String> variantMap) { + super(); + Args.notNull(requestDate, "Request date"); + Args.notNull(responseDate, "Response date"); + Args.notNull(statusLine, "Status line"); + Args.notNull(responseHeaders, "Response headers"); + this.requestDate = requestDate; + this.responseDate = responseDate; + this.statusLine = statusLine; + this.responseHeaders = new HeaderGroup(); + this.responseHeaders.setHeaders(responseHeaders); + this.resource = resource; + this.variantMap = variantMap != null + ? new HashMap<String,String>(variantMap) + : null; + this.date = parseDate(); + } + + /** + * Create a new {@link HttpCacheEntry}. + * + * @param requestDate + * Date/time when the request was made (Used for age + * calculations) + * @param responseDate + * Date/time that the response came back (Used for age + * calculations) + * @param statusLine + * HTTP status line from origin response + * @param responseHeaders + * Header[] from original HTTP Response + * @param resource representing origin response body + */ + public HttpCacheEntry(final Date requestDate, final Date responseDate, final StatusLine statusLine, + final Header[] responseHeaders, final Resource resource) { + this(requestDate, responseDate, statusLine, responseHeaders, resource, + new HashMap<String,String>()); + } + + /** + * Find the "Date" response header and parse it into a java.util.Date + * @return the Date value of the header or null if the header is not present + */ + private Date parseDate() { + final Header dateHdr = getFirstHeader(HTTP.DATE_HEADER); + if (dateHdr == null) { + return null; + } + return DateUtils.parseDate(dateHdr.getValue()); + } + + /** + * Returns the {@link StatusLine} from the origin + * {@link ch.boye.httpclientandroidlib.HttpResponse}. + */ + public StatusLine getStatusLine() { + return this.statusLine; + } + + /** + * Returns the {@link ProtocolVersion} from the origin + * {@link ch.boye.httpclientandroidlib.HttpResponse}. + */ + public ProtocolVersion getProtocolVersion() { + return this.statusLine.getProtocolVersion(); + } + + /** + * Gets the reason phrase from the origin + * {@link ch.boye.httpclientandroidlib.HttpResponse}, for example, "Not Modified". + */ + public String getReasonPhrase() { + return this.statusLine.getReasonPhrase(); + } + + /** + * Returns the HTTP response code from the origin + * {@link ch.boye.httpclientandroidlib.HttpResponse}. + */ + public int getStatusCode() { + return this.statusLine.getStatusCode(); + } + + /** + * Returns the time the associated origin request was initiated by the + * caching module. + * @return {@link Date} + */ + public Date getRequestDate() { + return requestDate; + } + + /** + * Returns the time the origin response was received by the caching module. + * @return {@link Date} + */ + public Date getResponseDate() { + return responseDate; + } + + /** + * Returns all the headers that were on the origin response. + */ + public Header[] getAllHeaders() { + return responseHeaders.getAllHeaders(); + } + + /** + * Returns the first header from the origin response with the given + * name. + */ + public Header getFirstHeader(final String name) { + return responseHeaders.getFirstHeader(name); + } + + /** + * Gets all the headers with the given name that were on the origin + * response. + */ + public Header[] getHeaders(final String name) { + return responseHeaders.getHeaders(name); + } + + /** + * Gets the Date value of the "Date" header or null if the header is missing or cannot be + * parsed. + * + * @since 4.3 + */ + public Date getDate() { + return date; + } + + /** + * Returns the {@link Resource} containing the origin response body. + */ + public Resource getResource() { + return this.resource; + } + + /** + * Indicates whether the origin response indicated the associated + * resource had variants (i.e. that the Vary header was set on the + * origin response). + * @return {@code true} if this cached response was a variant + */ + public boolean hasVariants() { + return getFirstHeader(HeaderConstants.VARY) != null; + } + + /** + * Returns an index about where in the cache different variants for + * a given resource are stored. This maps "variant keys" to "cache keys", + * where the variant key is derived from the varying request headers, + * and the cache key is the location in the + * {@link ch.boye.httpclientandroidlib.client.cache.HttpCacheStorage} where that + * particular variant is stored. The first variant returned is used as + * the "parent" entry to hold this index of the other variants. + */ + public Map<String, String> getVariantMap() { + return Collections.unmodifiableMap(variantMap); + } + + /** + * Provides a string representation of this instance suitable for + * human consumption. + */ + @Override + public String toString() { + return "[request date=" + this.requestDate + "; response date=" + this.responseDate + + "; statusLine=" + this.statusLine + "]"; + } + +} diff --git a/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HttpCacheEntrySerializationException.java b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HttpCacheEntrySerializationException.java new file mode 100644 index 000000000..e74f64db6 --- /dev/null +++ b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HttpCacheEntrySerializationException.java @@ -0,0 +1,48 @@ +/* + * ==================================================================== + * 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/>. + * + */ +package ch.boye.httpclientandroidlib.client.cache; + +import java.io.IOException; + +/** + * Thrown if serialization or deserialization of an {@link HttpCacheEntry} + * fails. + */ +public class HttpCacheEntrySerializationException extends IOException { + + private static final long serialVersionUID = 9219188365878433519L; + + public HttpCacheEntrySerializationException(final String message) { + super(); + } + + public HttpCacheEntrySerializationException(final String message, final Throwable cause) { + super(message); + initCause(cause); + } + +} diff --git a/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HttpCacheEntrySerializer.java b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HttpCacheEntrySerializer.java new file mode 100644 index 000000000..2903fb74d --- /dev/null +++ b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HttpCacheEntrySerializer.java @@ -0,0 +1,54 @@ +/* + * ==================================================================== + * 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/>. + * + */ +package ch.boye.httpclientandroidlib.client.cache; + +import java.io.IOException; +import java.io.InputStream; +import java.io.OutputStream; + +/** + * Used by some {@link HttpCacheStorage} implementations to serialize + * {@link HttpCacheEntry} instances to a byte representation before + * storage. + */ +public interface HttpCacheEntrySerializer { + + /** + * Serializes the given entry to a byte representation on the + * given {@link OutputStream}. + * @throws IOException + */ + void writeTo(HttpCacheEntry entry, OutputStream os) throws IOException; + + /** + * Deserializes a byte representation of a cache entry by reading + * from the given {@link InputStream}. + * @throws IOException + */ + HttpCacheEntry readFrom(InputStream is) throws IOException; + +} diff --git a/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HttpCacheInvalidator.java b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HttpCacheInvalidator.java new file mode 100644 index 000000000..f8e70968b --- /dev/null +++ b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HttpCacheInvalidator.java @@ -0,0 +1,58 @@ +/* + * ==================================================================== + * 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/>. + * + */ +package ch.boye.httpclientandroidlib.client.cache; + +import ch.boye.httpclientandroidlib.HttpHost; +import ch.boye.httpclientandroidlib.HttpRequest; +import ch.boye.httpclientandroidlib.HttpResponse; + +/** + * Given a particular HttpRequest, flush any cache entries that this request + * would invalidate. + * + * @since 4.3 + */ +public interface HttpCacheInvalidator { + + /** + * Remove cache entries from the cache that are no longer fresh or have been + * invalidated in some way. + * + * @param host + * The backend host we are talking to + * @param req + * The HttpRequest to that host + */ + void flushInvalidatedCacheEntries(HttpHost host, HttpRequest req); + + /** + * Flushes entries that were invalidated by the given response received for + * the given host/request pair. + */ + void flushInvalidatedCacheEntries(HttpHost host, HttpRequest request, HttpResponse response); + +} diff --git a/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HttpCacheStorage.java b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HttpCacheStorage.java new file mode 100644 index 000000000..b0759d195 --- /dev/null +++ b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HttpCacheStorage.java @@ -0,0 +1,81 @@ +/* + * ==================================================================== + * 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/>. + * + */ +package ch.boye.httpclientandroidlib.client.cache; + +import java.io.IOException; + +/** + * New storage backends should implement this {@link HttpCacheStorage} + * interface. They can then be plugged into the existing + * {@link ch.boye.httpclientandroidlib.impl.client.cache.CachingHttpClient} + * implementation. + * + * @since 4.1 + */ +public interface HttpCacheStorage { + + /** + * Store a given cache entry under the given key. + * @param key where in the cache to store the entry + * @param entry cached response to store + * @throws IOException + */ + void putEntry(String key, HttpCacheEntry entry) throws IOException; + + /** + * Retrieves the cache entry stored under the given key + * or null if no entry exists under that key. + * @param key cache key + * @return an {@link HttpCacheEntry} or {@code null} if no + * entry exists + * @throws IOException + */ + HttpCacheEntry getEntry(String key) throws IOException; + + /** + * Deletes/invalidates/removes any cache entries currently + * stored under the given key. + * @param key + * @throws IOException + */ + void removeEntry(String key) throws IOException; + + /** + * Atomically applies the given callback to update an existing cache + * entry under a given key. + * @param key indicates which entry to modify + * @param callback performs the update; see + * {@link HttpCacheUpdateCallback} for details, but roughly the + * callback expects to be handed the current entry and will return + * the new value for the entry. + * @throws IOException + * @throws HttpCacheUpdateException + */ + void updateEntry( + String key, HttpCacheUpdateCallback callback) throws IOException, HttpCacheUpdateException; + +} diff --git a/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HttpCacheUpdateCallback.java b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HttpCacheUpdateCallback.java new file mode 100644 index 000000000..abc810fe8 --- /dev/null +++ b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HttpCacheUpdateCallback.java @@ -0,0 +1,52 @@ +/* + * ==================================================================== + * 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/>. + * + */ +package ch.boye.httpclientandroidlib.client.cache; + +import java.io.IOException; + +/** + * Used for atomically updating entries in a {@link HttpCacheStorage} + * implementation. The current entry (if any) is fed into an implementation + * of this interface, and the new, possibly updated entry (if any) + * should be returned. + */ +public interface HttpCacheUpdateCallback { + + /** + * Returns the new cache entry that should replace an existing one. + * + * @param existing + * the cache entry currently in-place in the cache, possibly + * <code>null</code> if nonexistent + * @return the cache entry that should replace it, again, + * possibly <code>null</code> if the entry should be deleted + * + * @since 4.1 + */ + HttpCacheEntry update(HttpCacheEntry existing) throws IOException; + +} diff --git a/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HttpCacheUpdateException.java b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HttpCacheUpdateException.java new file mode 100644 index 000000000..278fe3afb --- /dev/null +++ b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/HttpCacheUpdateException.java @@ -0,0 +1,48 @@ +/* + * ==================================================================== + * 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/>. + * + */ +package ch.boye.httpclientandroidlib.client.cache; + +/** + * Signals that {@link HttpCacheStorage} encountered an error performing an + * update operation. + * + * @since 4.1 + */ +public class HttpCacheUpdateException extends Exception { + + private static final long serialVersionUID = 823573584868632876L; + + public HttpCacheUpdateException(final String message) { + super(message); + } + + public HttpCacheUpdateException(final String message, final Throwable cause) { + super(message); + initCause(cause); + } + +} diff --git a/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/InputLimit.java b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/InputLimit.java new file mode 100644 index 000000000..45ef3b26d --- /dev/null +++ b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/InputLimit.java @@ -0,0 +1,76 @@ +/* + * ==================================================================== + * 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/>. + * + */ +package ch.boye.httpclientandroidlib.client.cache; + +import ch.boye.httpclientandroidlib.annotation.NotThreadSafe; + +/** + * Used to limiting the size of an incoming response body of + * unknown size that is optimistically being read in anticipation + * of caching it. + * @since 4.1 + */ +@NotThreadSafe // reached +public class InputLimit { + + private final long value; + private boolean reached; + + /** + * Create a limit for how many bytes of a response body to + * read. + * @param value maximum length in bytes + */ + public InputLimit(final long value) { + super(); + this.value = value; + this.reached = false; + } + + /** + * Returns the current maximum limit that was set on + * creation. + */ + public long getValue() { + return this.value; + } + + /** + * Used to report that the limit has been reached. + */ + public void reached() { + this.reached = true; + } + + /** + * Returns {@code true} if the input limit has been reached. + */ + public boolean isReached() { + return this.reached; + } + +} diff --git a/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/Resource.java b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/Resource.java new file mode 100644 index 000000000..86811e85c --- /dev/null +++ b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/Resource.java @@ -0,0 +1,60 @@ +/* + * ==================================================================== + * 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/>. + * + */ +package ch.boye.httpclientandroidlib.client.cache; + +import java.io.IOException; +import java.io.InputStream; +import java.io.Serializable; + +/** + * Represents a disposable system resource used for handling + * cached response bodies. + * + * @since 4.1 + */ +public interface Resource extends Serializable { + + /** + * Returns an {@link InputStream} from which the response + * body can be read. + * @throws IOException + */ + InputStream getInputStream() throws IOException; + + /** + * Returns the length in bytes of the response body. + */ + long length(); + + /** + * Indicates the system no longer needs to keep this + * response body and any system resources associated with + * it may be reclaimed. + */ + void dispose(); + +} diff --git a/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/ResourceFactory.java b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/ResourceFactory.java new file mode 100644 index 000000000..0583d2605 --- /dev/null +++ b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/ResourceFactory.java @@ -0,0 +1,67 @@ +/* + * ==================================================================== + * 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/>. + * + */ +package ch.boye.httpclientandroidlib.client.cache; + +import java.io.IOException; +import java.io.InputStream; + +/** + * Generates {@link Resource} instances for handling cached + * HTTP response bodies. + * + * @since 4.1 + */ +public interface ResourceFactory { + + /** + * Creates a {@link Resource} from a given response body. + * @param requestId a unique identifier for this particular + * response body + * @param instream the original {@link InputStream} + * containing the response body of the origin HTTP response. + * @param limit maximum number of bytes to consume of the + * response body; if this limit is reached before the + * response body is fully consumed, mark the limit has + * having been reached and return a {@code Resource} + * containing the data read to that point. + * @return a {@code Resource} containing however much of + * the response body was successfully read. + * @throws IOException + */ + Resource generate(String requestId, InputStream instream, InputLimit limit) throws IOException; + + /** + * Clones an existing {@link Resource}. + * @param requestId unique identifier provided to associate + * with the cloned response body. + * @param resource the original response body to clone. + * @return the {@code Resource} copy + * @throws IOException + */ + Resource copy(String requestId, Resource resource) throws IOException; + +} diff --git a/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/package.html b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/package.html new file mode 100644 index 000000000..58a1e3ff3 --- /dev/null +++ b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/cache/package.html @@ -0,0 +1,78 @@ +<!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 consists largely of constants and interfaces that are +necessary for building new storage backends for the +{@link org.apache.http.impl.client.cache.CachingHttpClient} or for +those clients wanting to get a little more behavioral information +out of the cache module (for example, whether a particular response +was a cache hit or not). Developers that simply want to instantiate +and make use of the caching module will be better off looking at +the {@code CachingHttpClient} documentation itself. +</p> +<p> +The classes in this package can be divided into two main groups: +reference constants and interfaces needed for storage backends. In +the former group, +{@link org.apache.http.client.cache.HeaderConstants} contains a list +of HTTP header names encoded as static fields, and the +{@link org.apache.http.client.cache.CacheResponseStatus} enumeration +values are set in an {@link org.apache.http.protocol.HttpContext} by +the {@code CachingHttpClient} to indicate how the request was +processed by the caching module itself. +</p> +<p> +New storage backends will need to implement the +{@link org.apache.http.client.cache.HttpCacheStorage} +interface; they can then be passed to one of the {@code CachingHttpClient} +constructors, which will happily make use of the new storage mechanism. +The {@link org.apache.http.client.cache.HttpCacheEntry} class shows the +datastructure for a cache entry that must be stored by the +{@code HttpCacheStorage}. +There is, in addition, the notion of a +{@link org.apache.http.client.cache.Resource} and an associated +{@link org.apache.http.client.cache.ResourceFactory}, which are used for +managing the handling of cached response bodies. The default implementation +used by the {@code CachingHttpClient} stores response bodies in memory; +alternative implementations might involve storing these in a filesystem. A new +{@code ResourceFactory} can be provided along with a {@code HttpCacheStorage} +in one of the constructors to the {@code CachingHttpClient}. Finally, some +of the additional storage backends we provide, like the +{@link org.apache.http.impl.client.cache.ehcache.EhcacheHttpCacheStorage} and +{@link org.apache.http.impl.client.cache.memcached.MemcachedHttpCacheStorage}, +can be provided with different serializers for the cache entry metadata; +developers wanting to experiment with different serialization techniques +should implement the +{@link org.apache.http.client.cache.HttpCacheEntrySerializer} interface. +</p> +</body> +</html> |