diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HeaderConstants.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HeaderConstants.java index 1dbaaf33f..e2c6cdb77 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HeaderConstants.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HeaderConstants.java @@ -26,14 +26,11 @@ */ package org.apache.hc.client5.http.cache; -import org.apache.hc.core5.annotation.Contract; -import org.apache.hc.core5.annotation.ThreadingBehavior; - /** * Records static constants for various HTTP header names. + * * @since 4.1 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) public class HeaderConstants { public static final String GET_METHOD = "GET"; diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpAsyncCacheStorage.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpAsyncCacheStorage.java index 6fdf1f850..447af80d5 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpAsyncCacheStorage.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpAsyncCacheStorage.java @@ -29,6 +29,8 @@ package org.apache.hc.client5.http.cache; import java.util.Collection; import java.util.Map; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.concurrent.Cancellable; import org.apache.hc.core5.concurrent.FutureCallback; @@ -37,9 +39,13 @@ import org.apache.hc.core5.concurrent.FutureCallback; * storage backend that can then be plugged into the asynchronous * (non-blocking ) request execution * pipeline. + *

+ * Implementations of this interface are expected to be threading-safe. + *

* * @since 5.0 */ +@Contract(threading = ThreadingBehavior.SAFE) public interface HttpAsyncCacheStorage { /** diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpAsyncCacheStorageAdaptor.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpAsyncCacheStorageAdaptor.java index baa849768..7f1e525b3 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpAsyncCacheStorageAdaptor.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpAsyncCacheStorageAdaptor.java @@ -30,6 +30,8 @@ import java.util.Collection; import java.util.Map; import org.apache.hc.client5.http.impl.Operations; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.concurrent.Cancellable; import org.apache.hc.core5.concurrent.FutureCallback; import org.apache.hc.core5.util.Args; @@ -40,6 +42,7 @@ import org.apache.hc.core5.util.Args; * * @since 5.0 */ +@Contract(threading = ThreadingBehavior.SAFE_CONDITIONAL) public final class HttpAsyncCacheStorageAdaptor implements HttpAsyncCacheStorage { private final HttpCacheStorage cacheStorage; diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheCASOperation.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheCASOperation.java index 722b11689..4b59bb37f 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheCASOperation.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheCASOperation.java @@ -26,11 +26,15 @@ */ package org.apache.hc.client5.http.cache; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; + /** * Atomic Compare-And-Swap (CAS) cache operation. * * @since 5.0 */ +@Contract(threading = ThreadingBehavior.STATELESS) public interface HttpCacheCASOperation { /** diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheContext.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheContext.java index f1e4e8f32..435bc8618 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheContext.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheContext.java @@ -31,6 +31,9 @@ import org.apache.hc.core5.http.protocol.BasicHttpContext; import org.apache.hc.core5.http.protocol.HttpContext; /** + * Adaptor class that provides convenience type safe setters and getters + * for caching {@link HttpContext} attributes. + * * @since 4.3 */ public class HttpCacheContext extends HttpClientContext { diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheEntrySerializer.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheEntrySerializer.java index 70f57c6bd..e08a08dfc 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheEntrySerializer.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheEntrySerializer.java @@ -26,11 +26,15 @@ */ package org.apache.hc.client5.http.cache; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; + /** * Serializer / deserializer for {@link HttpCacheStorageEntry} entries. * * @since 5.0 */ +@Contract(threading = ThreadingBehavior.STATELESS) public interface HttpCacheEntrySerializer { /** diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheInvalidator.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheInvalidator.java index e373d2230..df80379ad 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheInvalidator.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheInvalidator.java @@ -28,7 +28,9 @@ package org.apache.hc.client5.http.cache; import java.net.URI; +import org.apache.hc.core5.annotation.Contract; import org.apache.hc.core5.annotation.Internal; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.function.Resolver; import org.apache.hc.core5.http.HttpHost; import org.apache.hc.core5.http.HttpRequest; @@ -40,6 +42,7 @@ import org.apache.hc.core5.http.HttpResponse; * * @since 4.3 */ +@Contract(threading = ThreadingBehavior.STATELESS) @Internal public interface HttpCacheInvalidator { diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheResponse.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheResponse.java deleted file mode 100644 index 68a6dbaa7..000000000 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheResponse.java +++ /dev/null @@ -1,140 +0,0 @@ -/* - * ==================================================================== - * 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 - * . - * - */ - -package org.apache.hc.client5.http.cache; - -import java.nio.charset.Charset; -import java.nio.charset.StandardCharsets; -import java.util.Set; - -import org.apache.hc.core5.http.ContentType; -import org.apache.hc.core5.http.EntityDetails; -import org.apache.hc.core5.util.Args; - -public final class HttpCacheResponse implements EntityDetails { - - private final int code; - private final String reasonPhrase; - private final byte[] body; - private final ContentType contentType; - - public static HttpCacheResponse create( - final int code, - final String reasonPhrase, - final byte[] body, - final ContentType contentType) { - return new HttpCacheResponse(code, reasonPhrase, body, contentType); - } - - public static HttpCacheResponse create( - final int code, - final byte[] body, - final ContentType contentType) { - return new HttpCacheResponse(code, null, body, contentType); - } - - public static HttpCacheResponse create( - final int code, - final String reasonPhrase) { - return new HttpCacheResponse(code, reasonPhrase, null, null); - } - - public static HttpCacheResponse create(final int code) { - return new HttpCacheResponse(code, null, null, null); - } - - public static HttpCacheResponse create( - final int code, - final String reasonPhrase, - final String body, - final ContentType contentType) { - if (body != null) { - final Charset charset = contentType != null ? contentType.getCharset() : null; - final byte[] b = body.getBytes(charset != null ? charset : StandardCharsets.US_ASCII); - return new HttpCacheResponse(code, reasonPhrase, b, contentType); - } else { - return create(code, reasonPhrase); - } - } - - public static HttpCacheResponse create( - final int code, - final String body, - final ContentType contentType) { - return create(code, null, body, contentType); - } - - private HttpCacheResponse( - final int code, - final String reasonPhrase, - final byte[] body, - final ContentType contentType) { - this.code = Args.checkRange(code, 200, 599, "HTTP status"); - this.reasonPhrase = reasonPhrase; - this.body = body; - this.contentType = contentType; - } - - public int getCode() { - return code; - } - - public String getReasonPhrase() { - return reasonPhrase; - } - - public byte[] getBody() { - return body; - } - - @Override - public long getContentLength() { - return body != null ? body.length : 0; - } - - @Override - public String getContentType() { - return contentType != null ? contentType.toString() : null; - } - - @Override - public String getContentEncoding() { - return null; - } - - @Override - public boolean isChunked() { - return false; - } - - @Override - public Set getTrailerNames() { - return null; - } - -} - diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheStorage.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheStorage.java index b4a459ef9..0e0ac720a 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheStorage.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheStorage.java @@ -29,13 +29,20 @@ package org.apache.hc.client5.http.cache; import java.util.Collection; import java.util.Map; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; + /** * {@literal HttpCacheStorage} represents an abstract HTTP cache * storage backend that can then be plugged into the classic * (blocking) request execution pipeline. + *

+ * Implementations of this interface are expected to be threading-safe. + *

* * @since 4.1 */ +@Contract(threading = ThreadingBehavior.SAFE) public interface HttpCacheStorage { /** diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheStorageEntry.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheStorageEntry.java index 5e3cb7a20..1031d019a 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheStorageEntry.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheStorageEntry.java @@ -28,8 +28,16 @@ package org.apache.hc.client5.http.cache; import java.io.Serializable; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.util.Args; +/** + * This class contains a {@link HttpCacheEntry} along with its key. + * + * @since 5.0 + */ +@Contract(threading = ThreadingBehavior.IMMUTABLE) public final class HttpCacheStorageEntry implements Serializable { private static final long serialVersionUID = 1L; diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/Resource.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/Resource.java index 1a986e22f..b2cf02892 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/Resource.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/Resource.java @@ -30,12 +30,19 @@ import java.io.ByteArrayInputStream; import java.io.InputStream; import java.io.Serializable; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; + /** * Represents a disposable system resource used for handling * cached response bodies. + *

+ * Implementations of this interface are expected to be threading-safe. + *

* * @since 4.1 */ +@Contract(threading = ThreadingBehavior.SAFE) public abstract class Resource implements Serializable { private static final long serialVersionUID = 1L; diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/ResourceFactory.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/ResourceFactory.java index e94a82bbd..2ef204a6f 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/ResourceFactory.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/ResourceFactory.java @@ -26,12 +26,16 @@ */ package org.apache.hc.client5.http.cache; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; + /** * Generates {@link Resource} instances for handling cached * HTTP response bodies. * * @since 4.1 */ +@Contract(threading = ThreadingBehavior.STATELESS) public interface ResourceFactory { /** diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/package-info.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/package-info.java new file mode 100644 index 000000000..9e9b2a505 --- /dev/null +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/package-info.java @@ -0,0 +1,32 @@ +/* + * ==================================================================== + * 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 + * . + * + */ + +/** + * Caching APIs for both the classic and the asynchronous + * HTTP transports. + */ +package org.apache.hc.client5.http.cache; diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/package.html b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/package.html deleted file mode 100644 index 3ef03e264..000000000 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/package.html +++ /dev/null @@ -1,78 +0,0 @@ - - - - - - - -

- This package consists largely of constants and interfaces that are - necessary for building new storage backends for the - {@link org.apache.hc.client5.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. -

-

- 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.hc.client5.http.client.cache.HeaderConstants} contains a list - of HTTP header names encoded as static fields, and the - {@link org.apache.hc.client5.http.client.cache.CacheResponseStatus} enumeration - values are set in an {@link org.apache.hc.client5.http.protocol.HttpContext} by - the {@code CachingHttpClient} to indicate how the request was - processed by the caching module itself. -

-

- New storage backends will need to implement the - {@link org.apache.hc.client5.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.hc.client5.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.hc.client5.http.client.cache.Resource} and an associated - {@link org.apache.hc.client5.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.hc.client5.http.impl.client.cache.ehcache.EhcacheHttpCacheStorage} and - {@link org.apache.hc.client5.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.hc.client5.http.client.cache.HttpCacheEntrySerializer} interface. -

- - diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/AsyncCachingExec.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/AsyncCachingExec.java index 2cb66f1a8..beecb4dee 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/AsyncCachingExec.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/AsyncCachingExec.java @@ -88,7 +88,7 @@ import org.apache.hc.core5.util.ByteArrayBuffer; * @since 5.0 */ @Contract(threading = ThreadingBehavior.SAFE) // So long as the responseCache implementation is threadsafe -public class AsyncCachingExec extends CachingExecBase implements AsyncExecChainHandler { +class AsyncCachingExec extends CachingExecBase implements AsyncExecChainHandler { private final HttpAsyncCache responseCache; private final DefaultAsyncCacheRevalidator cacheRevalidator; @@ -120,7 +120,7 @@ public class AsyncCachingExec extends CachingExecBase implements AsyncExecChainH this.conditionalRequestBuilder = conditionalRequestBuilder; } - public AsyncCachingExec( + AsyncCachingExec( final HttpAsyncCache cache, final ScheduledExecutorService executorService, final SchedulingStrategy schedulingStrategy, @@ -130,7 +130,7 @@ public class AsyncCachingExec extends CachingExecBase implements AsyncExecChainH config); } - public AsyncCachingExec( + AsyncCachingExec( final ResourceFactory resourceFactory, final HttpAsyncCacheStorage storage, final ScheduledExecutorService executorService, @@ -144,7 +144,7 @@ public class AsyncCachingExec extends CachingExecBase implements AsyncExecChainH final AsyncExecChain.Scope scope, final AsyncExecCallback asyncExecCallback) { scope.clientContext.setAttribute(HttpCoreContext.HTTP_RESPONSE, cacheResponse); - scope.execRuntime.releaseConnection(); + scope.execRuntime.releaseEndpoint(); final SimpleBody body = cacheResponse.getBody(); final byte[] content = body != null ? body.getBodyBytes() : null; diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/BasicIdGenerator.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/BasicIdGenerator.java index 5c48ed719..cfa28aca7 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/BasicIdGenerator.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/BasicIdGenerator.java @@ -33,13 +33,9 @@ import java.security.SecureRandom; import java.util.Formatter; import java.util.Locale; -import org.apache.hc.core5.annotation.Contract; -import org.apache.hc.core5.annotation.ThreadingBehavior; - /** * Should produce reasonably unique tokens. */ -@Contract(threading = ThreadingBehavior.SAFE) class BasicIdGenerator { private final String hostname; diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ByteArrayCacheEntrySerializer.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ByteArrayCacheEntrySerializer.java index e5f653c75..7b7f45732 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ByteArrayCacheEntrySerializer.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ByteArrayCacheEntrySerializer.java @@ -46,7 +46,7 @@ import org.apache.hc.core5.annotation.ThreadingBehavior; * * @since 4.1 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public final class ByteArrayCacheEntrySerializer implements HttpCacheEntrySerializer { public static final ByteArrayCacheEntrySerializer INSTANCE = new ByteArrayCacheEntrySerializer(); diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CacheKeyGenerator.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CacheKeyGenerator.java index 2ea3e1f3f..bb84aee7f 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CacheKeyGenerator.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CacheKeyGenerator.java @@ -50,7 +50,7 @@ import org.apache.hc.core5.http.message.MessageSupport; /** * @since 4.1 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class CacheKeyGenerator implements Resolver { public static final CacheKeyGenerator INSTANCE = new CacheKeyGenerator(); diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CacheUpdateHandler.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CacheUpdateHandler.java index 2db7beab6..3ee2fe941 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CacheUpdateHandler.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CacheUpdateHandler.java @@ -37,8 +37,6 @@ import org.apache.hc.client5.http.cache.Resource; import org.apache.hc.client5.http.cache.ResourceFactory; import org.apache.hc.client5.http.cache.ResourceIOException; import org.apache.hc.client5.http.utils.DateUtils; -import org.apache.hc.core5.annotation.Contract; -import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.Header; import org.apache.hc.core5.http.HttpHeaders; import org.apache.hc.core5.http.HttpRequest; @@ -51,10 +49,7 @@ import org.apache.hc.core5.util.ByteArrayBuffer; /** * Creates new {@link HttpCacheEntry}s and updates existing ones with new or updated information * based on the response from the origin server. - * - * @since 5.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) class CacheUpdateHandler { private final ResourceFactory resourceFactory; diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CacheValidityPolicy.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CacheValidityPolicy.java index 7930d4336..2d469cada 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CacheValidityPolicy.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CacheValidityPolicy.java @@ -33,8 +33,6 @@ import org.apache.hc.client5.http.cache.HeaderConstants; import org.apache.hc.client5.http.cache.HttpCacheEntry; import org.apache.hc.client5.http.cache.Resource; import org.apache.hc.client5.http.utils.DateUtils; -import org.apache.hc.core5.annotation.Contract; -import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.Header; import org.apache.hc.core5.http.HeaderElement; import org.apache.hc.core5.http.HttpHeaders; @@ -42,10 +40,6 @@ import org.apache.hc.core5.http.HttpRequest; import org.apache.hc.core5.http.MessageHeaders; import org.apache.hc.core5.http.message.MessageSupport; -/** - * @since 4.1 - */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) class CacheValidityPolicy { public static final long MAX_AGE = 2147483648L; diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CacheableRequestPolicy.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CacheableRequestPolicy.java index 620ad9b26..45f818014 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CacheableRequestPolicy.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CacheableRequestPolicy.java @@ -29,8 +29,6 @@ package org.apache.hc.client5.http.impl.cache; import java.util.Iterator; import org.apache.hc.client5.http.cache.HeaderConstants; -import org.apache.hc.core5.annotation.Contract; -import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.HeaderElement; import org.apache.hc.core5.http.HttpRequest; import org.apache.hc.core5.http.HttpVersion; @@ -41,10 +39,7 @@ import org.slf4j.LoggerFactory; /** * Determines if an HttpRequest is allowed to be served from the cache. - * - * @since 4.1 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) class CacheableRequestPolicy { private final Logger log = LoggerFactory.getLogger(getClass()); diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CachedHttpResponseGenerator.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CachedHttpResponseGenerator.java index d55883789..f3a0002d7 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CachedHttpResponseGenerator.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CachedHttpResponseGenerator.java @@ -34,8 +34,6 @@ import org.apache.hc.client5.http.cache.HttpCacheEntry; import org.apache.hc.client5.http.cache.Resource; import org.apache.hc.client5.http.cache.ResourceIOException; import org.apache.hc.client5.http.utils.DateUtils; -import org.apache.hc.core5.annotation.Contract; -import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.ContentType; import org.apache.hc.core5.http.Header; import org.apache.hc.core5.http.HttpHeaders; @@ -47,10 +45,7 @@ import org.apache.hc.core5.http.message.BasicHeader; /** * Rebuilds an {@link HttpResponse} from a {@link HttpCacheEntry} - * - * @since 4.1 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) class CachedHttpResponseGenerator { private final CacheValidityPolicy validityStrategy; diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CachedResponseSuitabilityChecker.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CachedResponseSuitabilityChecker.java index f191778cb..dc6b4d179 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CachedResponseSuitabilityChecker.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CachedResponseSuitabilityChecker.java @@ -32,8 +32,6 @@ import java.util.Iterator; import org.apache.hc.client5.http.cache.HeaderConstants; import org.apache.hc.client5.http.cache.HttpCacheEntry; import org.apache.hc.client5.http.utils.DateUtils; -import org.apache.hc.core5.annotation.Contract; -import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.Header; import org.apache.hc.core5.http.HeaderElement; import org.apache.hc.core5.http.HttpHost; @@ -46,10 +44,7 @@ import org.slf4j.LoggerFactory; /** * Determines whether a given {@link HttpCacheEntry} is suitable to be * used as a response for a given {@link HttpRequest}. - * - * @since 4.1 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) class CachedResponseSuitabilityChecker { private final Logger log = LoggerFactory.getLogger(getClass()); diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CachingExec.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CachingExec.java index a5150944a..10a0f8db1 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CachingExec.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CachingExec.java @@ -49,8 +49,6 @@ import org.apache.hc.client5.http.impl.classic.ClassicRequestCopier; import org.apache.hc.client5.http.protocol.HttpClientContext; import org.apache.hc.client5.http.schedule.SchedulingStrategy; import org.apache.hc.client5.http.utils.DateUtils; -import org.apache.hc.core5.annotation.Contract; -import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.ClassicHttpRequest; import org.apache.hc.core5.http.ClassicHttpResponse; import org.apache.hc.core5.http.Header; @@ -100,8 +98,7 @@ import org.slf4j.LoggerFactory; * * @since 4.3 */ -@Contract(threading = ThreadingBehavior.SAFE) // So long as the responseCache implementation is threadsafe -public class CachingExec extends CachingExecBase implements ExecChainHandler { +class CachingExec extends CachingExecBase implements ExecChainHandler { private final HttpCache responseCache; private final DefaultCacheRevalidator cacheRevalidator; @@ -135,7 +132,7 @@ public class CachingExec extends CachingExecBase implements ExecChainHandler { this.conditionalRequestBuilder = conditionalRequestBuilder; } - public CachingExec( + CachingExec( final HttpCache cache, final ScheduledExecutorService executorService, final SchedulingStrategy schedulingStrategy, @@ -145,7 +142,7 @@ public class CachingExec extends CachingExecBase implements ExecChainHandler { config); } - public CachingExec( + CachingExec( final ResourceFactory resourceFactory, final HttpCacheStorage storage, final ScheduledExecutorService executorService, diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CachingHttpAsyncClients.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CachingHttpAsyncClients.java index 230791b28..4742b00d0 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CachingHttpAsyncClients.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CachingHttpAsyncClients.java @@ -30,8 +30,6 @@ package org.apache.hc.client5.http.impl.cache; import java.io.File; import org.apache.hc.client5.http.impl.async.CloseableHttpAsyncClient; -import org.apache.hc.core5.annotation.Contract; -import org.apache.hc.core5.annotation.ThreadingBehavior; /** * Factory methods for {@link CloseableHttpAsyncClient} instances @@ -39,8 +37,7 @@ import org.apache.hc.core5.annotation.ThreadingBehavior; * * @since 5.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) -public class CachingHttpAsyncClients { +public final class CachingHttpAsyncClients { private CachingHttpAsyncClients() { super(); diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CachingHttpClients.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CachingHttpClients.java index 0ea8eede5..c8cf99a34 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CachingHttpClients.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/CachingHttpClients.java @@ -30,8 +30,6 @@ package org.apache.hc.client5.http.impl.cache; import java.io.File; import org.apache.hc.client5.http.impl.classic.CloseableHttpClient; -import org.apache.hc.core5.annotation.Contract; -import org.apache.hc.core5.annotation.ThreadingBehavior; /** * Factory methods for {@link CloseableHttpClient} instances @@ -39,8 +37,7 @@ import org.apache.hc.core5.annotation.ThreadingBehavior; * * @since 4.3 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) -public class CachingHttpClients { +public final class CachingHttpClients { private CachingHttpClients() { super(); diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ConditionalRequestBuilder.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ConditionalRequestBuilder.java index b6eeb9e35..b5cc5fe43 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ConditionalRequestBuilder.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ConditionalRequestBuilder.java @@ -32,17 +32,11 @@ import java.util.Map; import org.apache.hc.client5.http.cache.HeaderConstants; import org.apache.hc.client5.http.cache.HttpCacheEntry; import org.apache.hc.client5.http.impl.MessageCopier; -import org.apache.hc.core5.annotation.Contract; -import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.Header; import org.apache.hc.core5.http.HeaderElement; import org.apache.hc.core5.http.HttpRequest; import org.apache.hc.core5.http.message.MessageSupport; -/** - * @since 4.1 - */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) class ConditionalRequestBuilder { private final MessageCopier messageCopier; diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/DefaultAsyncCacheInvalidator.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/DefaultAsyncCacheInvalidator.java index 246a11a7f..91aab395e 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/DefaultAsyncCacheInvalidator.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/DefaultAsyncCacheInvalidator.java @@ -56,7 +56,7 @@ import org.slf4j.LoggerFactory; * * @since 5.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) @Internal public class DefaultAsyncCacheInvalidator extends CacheInvalidatorBase implements HttpAsyncCacheInvalidator { diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/DefaultCacheInvalidator.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/DefaultCacheInvalidator.java index c305b91e8..12bd68ae7 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/DefaultCacheInvalidator.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/DefaultCacheInvalidator.java @@ -50,7 +50,7 @@ import org.slf4j.LoggerFactory; * * @since 4.1 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) @Internal public class DefaultCacheInvalidator extends CacheInvalidatorBase implements HttpCacheInvalidator { diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/FileResourceFactory.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/FileResourceFactory.java index 99f1ddb68..4b5c67187 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/FileResourceFactory.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/FileResourceFactory.java @@ -45,7 +45,7 @@ import org.apache.hc.core5.util.Args; * * @since 4.1 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class FileResourceFactory implements ResourceFactory { private final File cacheDir; diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/HeapResourceFactory.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/HeapResourceFactory.java index bb656e014..78e965b03 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/HeapResourceFactory.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/HeapResourceFactory.java @@ -38,7 +38,7 @@ import org.apache.hc.core5.util.Args; * * @since 4.1 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class HeapResourceFactory implements ResourceFactory { public static final HeapResourceFactory INSTANCE = new HeapResourceFactory(); diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/HttpAsyncCache.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/HttpAsyncCache.java index dc4b2e6f2..6ba926283 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/HttpAsyncCache.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/HttpAsyncCache.java @@ -30,7 +30,6 @@ import java.util.Date; import java.util.Map; import org.apache.hc.client5.http.cache.HttpCacheEntry; -import org.apache.hc.core5.annotation.Internal; import org.apache.hc.core5.concurrent.Cancellable; import org.apache.hc.core5.concurrent.FutureCallback; import org.apache.hc.core5.http.HttpHost; @@ -38,10 +37,6 @@ import org.apache.hc.core5.http.HttpRequest; import org.apache.hc.core5.http.HttpResponse; import org.apache.hc.core5.util.ByteArrayBuffer; -/** - * @since 5.0 - */ -@Internal interface HttpAsyncCache { String generateKey (HttpHost host, HttpRequest request, HttpCacheEntry cacheEntry); diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/HttpCache.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/HttpCache.java index d2c6e6613..66f4af959 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/HttpCache.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/HttpCache.java @@ -35,9 +35,6 @@ import org.apache.hc.core5.http.HttpRequest; import org.apache.hc.core5.http.HttpResponse; import org.apache.hc.core5.util.ByteArrayBuffer; -/** - * @since 4.1 - */ interface HttpCache { String generateKey (HttpHost host, HttpRequest request, HttpCacheEntry cacheEntry); diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ManagedHttpCacheStorage.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ManagedHttpCacheStorage.java index a89c66748..0623171ce 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ManagedHttpCacheStorage.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ManagedHttpCacheStorage.java @@ -35,9 +35,9 @@ import java.util.Map; import java.util.Set; import java.util.concurrent.atomic.AtomicBoolean; +import org.apache.hc.client5.http.cache.HttpCacheCASOperation; import org.apache.hc.client5.http.cache.HttpCacheEntry; import org.apache.hc.client5.http.cache.HttpCacheStorage; -import org.apache.hc.client5.http.cache.HttpCacheCASOperation; import org.apache.hc.client5.http.cache.Resource; import org.apache.hc.client5.http.cache.ResourceIOException; import org.apache.hc.core5.annotation.Contract; diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/NoopCacheEntrySerializer.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/NoopCacheEntrySerializer.java index 76f17162a..a3f555bf2 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/NoopCacheEntrySerializer.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/NoopCacheEntrySerializer.java @@ -33,9 +33,12 @@ import org.apache.hc.core5.annotation.Contract; import org.apache.hc.core5.annotation.ThreadingBehavior; /** + * {@link HttpCacheEntrySerializer} that uses {@link HttpCacheStorageEntry} + * as its cache content representation. + * * @since 5.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class NoopCacheEntrySerializer implements HttpCacheEntrySerializer { public static final NoopCacheEntrySerializer INSTANCE = new NoopCacheEntrySerializer(); diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/RequestProtocolCompliance.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/RequestProtocolCompliance.java index 99affcb3b..89674e467 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/RequestProtocolCompliance.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/RequestProtocolCompliance.java @@ -32,8 +32,6 @@ import java.util.Iterator; import java.util.List; import org.apache.hc.client5.http.cache.HeaderConstants; -import org.apache.hc.core5.annotation.Contract; -import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.Header; import org.apache.hc.core5.http.HeaderElement; import org.apache.hc.core5.http.HttpRequest; @@ -41,10 +39,6 @@ import org.apache.hc.core5.http.HttpVersion; import org.apache.hc.core5.http.ProtocolVersion; import org.apache.hc.core5.http.message.MessageSupport; -/** - * @since 4.1 - */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) class RequestProtocolCompliance { private final boolean weakETagOnPutDeleteAllowed; diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/RequestProtocolError.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/RequestProtocolError.java index 38ffa7ad2..9e8829e42 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/RequestProtocolError.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/RequestProtocolError.java @@ -26,9 +26,6 @@ */ package org.apache.hc.client5.http.impl.cache; -/** - * @since 4.1 - */ enum RequestProtocolError { UNKNOWN, diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ResourceReference.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ResourceReference.java index 502e13e90..7ada578ba 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ResourceReference.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ResourceReference.java @@ -31,11 +31,8 @@ import java.lang.ref.ReferenceQueue; import org.apache.hc.client5.http.cache.HttpCacheEntry; import org.apache.hc.client5.http.cache.Resource; -import org.apache.hc.core5.annotation.Contract; -import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.util.Args; -@Contract(threading = ThreadingBehavior.IMMUTABLE) class ResourceReference extends PhantomReference { private final Resource resource; diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ResponseCachingPolicy.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ResponseCachingPolicy.java index e8622747e..9564645ec 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ResponseCachingPolicy.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ResponseCachingPolicy.java @@ -34,8 +34,6 @@ import java.util.Set; import org.apache.hc.client5.http.cache.HeaderConstants; import org.apache.hc.client5.http.utils.DateUtils; -import org.apache.hc.core5.annotation.Contract; -import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.Header; import org.apache.hc.core5.http.HeaderElement; import org.apache.hc.core5.http.HttpHeaders; @@ -49,12 +47,6 @@ import org.apache.hc.core5.http.message.MessageSupport; import org.slf4j.Logger; import org.slf4j.LoggerFactory; -/** - * Determines if an HttpResponse can be cached. - * - * @since 4.1 - */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) class ResponseCachingPolicy { private static final String[] AUTH_CACHEABLE_PARAMS = { diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ResponseProtocolCompliance.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ResponseProtocolCompliance.java index ff5f0ccd1..f0e714e0d 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ResponseProtocolCompliance.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ResponseProtocolCompliance.java @@ -34,8 +34,6 @@ import java.util.List; import org.apache.hc.client5.http.ClientProtocolException; import org.apache.hc.client5.http.cache.HeaderConstants; import org.apache.hc.client5.http.utils.DateUtils; -import org.apache.hc.core5.annotation.Contract; -import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.Header; import org.apache.hc.core5.http.HeaderElement; import org.apache.hc.core5.http.HeaderElements; @@ -48,10 +46,6 @@ import org.apache.hc.core5.http.ProtocolVersion; import org.apache.hc.core5.http.message.BasicHeader; import org.apache.hc.core5.http.message.MessageSupport; -/** - * @since 4.1 - */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) class ResponseProtocolCompliance { private static final String UNEXPECTED_100_CONTINUE = "The incoming request did not contain a " diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ehcache/package-info.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ehcache/package-info.java new file mode 100644 index 000000000..818b710b7 --- /dev/null +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ehcache/package-info.java @@ -0,0 +1,31 @@ +/* + * ==================================================================== + * 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 + * . + * + */ + +/** + * Ehcache based caching backend implementation. + */ +package org.apache.hc.client5.http.impl.cache.ehcache; diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ehcache/package.html b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ehcache/package.html deleted file mode 100644 index 9a2736092..000000000 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/ehcache/package.html +++ /dev/null @@ -1,40 +0,0 @@ - - - - - - - -

-This package contains a storage backend based on -Ehcache -that can be plugged into -a {@link org.apache.http.impl.client.cache.CachingHttpClient} and -used for storing cache entries. -

- - diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/memcached/KeyHashingScheme.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/memcached/KeyHashingScheme.java index d24faab08..a087b897b 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/memcached/KeyHashingScheme.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/memcached/KeyHashingScheme.java @@ -58,6 +58,8 @@ * keys. Clients can implement this interface to change the way the mapping * is done (for example, to add a prefix to all cache keys to provide a form * of memcached namespacing). + * + * @since 4.1 */ public interface KeyHashingScheme { diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/memcached/MemcachedKeyHashingException.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/memcached/MemcachedKeyHashingException.java index 8b2fd1439..4499d9834 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/memcached/MemcachedKeyHashingException.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/memcached/MemcachedKeyHashingException.java @@ -27,9 +27,11 @@ package org.apache.hc.client5.http.impl.cache.memcached; /** - * Indicates a problem encountered when trying to map a + * Signals a problem encountered when trying to map a * logical "storage key" to a "cache key" suitable for use with * memcached. + * + * @since 4.1 */ public class MemcachedKeyHashingException extends RuntimeException { diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/memcached/MemcachedOperationTimeoutException.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/memcached/MemcachedOperationTimeoutException.java index 054753cbe..d221d3ee1 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/memcached/MemcachedOperationTimeoutException.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/memcached/MemcachedOperationTimeoutException.java @@ -29,9 +29,11 @@ package org.apache.hc.client5.http.impl.cache.memcached; import org.apache.hc.client5.http.cache.ResourceIOException; /** - * Raised when memcached times out on us. + * Signals memcached operation timeout. + * + * @since 4.1 */ -class MemcachedOperationTimeoutException extends ResourceIOException { +public class MemcachedOperationTimeoutException extends ResourceIOException { private static final long serialVersionUID = 1L; diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/memcached/PrefixKeyHashingScheme.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/memcached/PrefixKeyHashingScheme.java index b7a1fd41b..ad2dfe252 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/memcached/PrefixKeyHashingScheme.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/memcached/PrefixKeyHashingScheme.java @@ -32,6 +32,8 @@ package org.apache.hc.client5.http.impl.cache.memcached; * a known prefix to the results of another {@code KeyHashingScheme}. * Primarily useful for namespacing a shared memcached cluster, for * example. + * + * @since 4.1 */ public final class PrefixKeyHashingScheme implements KeyHashingScheme { diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/memcached/SHA256KeyHashingScheme.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/memcached/SHA256KeyHashingScheme.java index dd23b3c42..c54938df4 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/memcached/SHA256KeyHashingScheme.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/memcached/SHA256KeyHashingScheme.java @@ -39,6 +39,8 @@ import org.slf4j.LoggerFactory; * algorithm. The hashes produced are hex-encoded SHA-256 * digests and hence are always 64-character hexadecimal * strings. + * + * @since 4.1 */ public final class SHA256KeyHashingScheme implements KeyHashingScheme { diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/memcached/package-info.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/memcached/package-info.java new file mode 100644 index 000000000..87618b2b8 --- /dev/null +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/memcached/package-info.java @@ -0,0 +1,32 @@ +/* + * ==================================================================== + * 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 + * . + * + */ + +/** + * Memcached based caching backend + * implementation. + */ +package org.apache.hc.client5.http.impl.cache.memcached; diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/memcached/package.html b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/memcached/package.html deleted file mode 100644 index 72c328533..000000000 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/memcached/package.html +++ /dev/null @@ -1,40 +0,0 @@ - - - - - - - -

-This package contains a storage backend based on -memcached -that can be plugged into -a {@link org.apache.http.impl.client.cache.CachingHttpClient} and -used for storing cache entries. -

- - diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/package-info.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/package-info.java new file mode 100644 index 000000000..be63ef919 --- /dev/null +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/package-info.java @@ -0,0 +1,32 @@ +/* + * ==================================================================== + * 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 + * . + * + */ + +/** + * Caching API implementation for both the classic and + * the asynchronous HTTP transports. + */ +package org.apache.hc.client5.http.impl.cache; diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/package.html b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/package.html deleted file mode 100644 index 486aded29..000000000 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/package.html +++ /dev/null @@ -1,42 +0,0 @@ - - - - - - - -

- This package contains a cache module that can be used for HTTP/1.1 - client-side caching. The primary classes in this package are the - {@link org.apache.hc.client5.http.impl.client.cache.CachingHttpClient}, - which is a drop-in replacement for - a {@link org.apache.hc.client5.http.impl.client.DefaultHttpClient} that adds - caching, and the {@link org.apache.hc.client5.http.impl.client.cache.CacheConfig} - class that can be used for configuring it. -

- - diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/schedule/ExponentialBackOffSchedulingStrategy.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/schedule/ExponentialBackOffSchedulingStrategy.java index ee17f1fec..92e550931 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/schedule/ExponentialBackOffSchedulingStrategy.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/schedule/ExponentialBackOffSchedulingStrategy.java @@ -52,9 +52,9 @@ import org.apache.hc.core5.util.TimeValue; * * The resulting delay won't exceed {@link #getMaxExpiry()}. * - * @since 4.3 + * @since 5.0 */ -@Contract(threading = ThreadingBehavior.SAFE) +@Contract(threading = ThreadingBehavior.STATELESS) public class ExponentialBackOffSchedulingStrategy implements SchedulingStrategy { public static final long DEFAULT_BACK_OFF_RATE = 10; diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/schedule/package-info.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/schedule/package-info.java new file mode 100644 index 000000000..33186ec4b --- /dev/null +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/schedule/package-info.java @@ -0,0 +1,31 @@ +/* + * ==================================================================== + * 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 + * . + * + */ + +/** + * Commons scheduling strategy implementations. + */ +package org.apache.hc.client5.http.impl.schedule; diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/schedule/ConcurrentCountMap.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/schedule/ConcurrentCountMap.java index 60eb84e80..a81ab26e6 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/schedule/ConcurrentCountMap.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/schedule/ConcurrentCountMap.java @@ -34,6 +34,13 @@ import org.apache.hc.core5.annotation.Contract; import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.util.Args; +/** + * Concurrent map of integer counts. + * + * @since 5.0 + * + * @param identifier used as a map key + */ @Contract(threading = ThreadingBehavior.SAFE) public final class ConcurrentCountMap { diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/schedule/SchedulingStrategy.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/schedule/SchedulingStrategy.java index bffed1dc3..3e5464f68 100644 --- a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/schedule/SchedulingStrategy.java +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/schedule/SchedulingStrategy.java @@ -26,6 +26,8 @@ */ package org.apache.hc.client5.http.schedule; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.util.TimeValue; /** @@ -33,6 +35,7 @@ import org.apache.hc.core5.util.TimeValue; * * @since 5.0 */ +@Contract(threading = ThreadingBehavior.STATELESS) public interface SchedulingStrategy { /** diff --git a/httpclient5-cache/src/main/java/org/apache/hc/client5/http/schedule/package-info.java b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/schedule/package-info.java new file mode 100644 index 000000000..6ad5d7b33 --- /dev/null +++ b/httpclient5-cache/src/main/java/org/apache/hc/client5/http/schedule/package-info.java @@ -0,0 +1,31 @@ +/* + * ==================================================================== + * 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 + * . + * + */ + +/** + * Scheduling strategies used by HTTP cache implementations. + */ +package org.apache.hc.client5.http.schedule; diff --git a/httpclient5-fluent/src/main/java/org/apache/hc/client5/http/fluent/Async.java b/httpclient5-fluent/src/main/java/org/apache/hc/client5/http/fluent/Async.java index beb710bb9..a6e13eb23 100644 --- a/httpclient5-fluent/src/main/java/org/apache/hc/client5/http/fluent/Async.java +++ b/httpclient5-fluent/src/main/java/org/apache/hc/client5/http/fluent/Async.java @@ -32,6 +32,11 @@ import org.apache.hc.core5.concurrent.BasicFuture; import org.apache.hc.core5.concurrent.FutureCallback; import org.apache.hc.core5.http.io.HttpClientResponseHandler; +/** + * Asynchronous executor for {@link Request}s. + * + * @since 4.3 + */ public class Async { private Executor executor; diff --git a/httpclient5-fluent/src/main/java/org/apache/hc/client5/http/fluent/Content.java b/httpclient5-fluent/src/main/java/org/apache/hc/client5/http/fluent/Content.java index 1ef83c897..802f40c3b 100644 --- a/httpclient5-fluent/src/main/java/org/apache/hc/client5/http/fluent/Content.java +++ b/httpclient5-fluent/src/main/java/org/apache/hc/client5/http/fluent/Content.java @@ -35,7 +35,9 @@ import org.apache.hc.core5.http.ContentType; /** * This class represents arbitrary content of a specific type that can be consumed - * multiple times and requires no explicit deallocation. + * multiple times and requires no explicit deallocation used by the fluent facade. + * + * @since 4.2 */ public class Content { diff --git a/httpclient5-fluent/src/main/java/org/apache/hc/client5/http/fluent/Executor.java b/httpclient5-fluent/src/main/java/org/apache/hc/client5/http/fluent/Executor.java index bf0e4a1fb..28fef8617 100644 --- a/httpclient5-fluent/src/main/java/org/apache/hc/client5/http/fluent/Executor.java +++ b/httpclient5-fluent/src/main/java/org/apache/hc/client5/http/fluent/Executor.java @@ -47,10 +47,12 @@ import org.apache.hc.core5.http.HttpHost; import org.apache.hc.core5.util.TimeValue; /** - * An Executor for fluent requests. + * Executor for {@link Request}s. *

* A connection pool with maximum 100 connections per route and * a total maximum of 200 connections is used internally. + * + * @since 4.2 */ public class Executor { diff --git a/httpclient5-fluent/src/main/java/org/apache/hc/client5/http/fluent/Form.java b/httpclient5-fluent/src/main/java/org/apache/hc/client5/http/fluent/Form.java index 1d578cae9..194b69eff 100644 --- a/httpclient5-fluent/src/main/java/org/apache/hc/client5/http/fluent/Form.java +++ b/httpclient5-fluent/src/main/java/org/apache/hc/client5/http/fluent/Form.java @@ -32,6 +32,11 @@ import java.util.List; import org.apache.hc.core5.http.NameValuePair; import org.apache.hc.core5.http.message.BasicNameValuePair; +/** + * HTTP form used by the fluent facade. + * + * @since 4.2 + */ public class Form { private final List params; diff --git a/httpclient5-fluent/src/main/java/org/apache/hc/client5/http/fluent/Request.java b/httpclient5-fluent/src/main/java/org/apache/hc/client5/http/fluent/Request.java index 72bcf983c..0494461d1 100644 --- a/httpclient5-fluent/src/main/java/org/apache/hc/client5/http/fluent/Request.java +++ b/httpclient5-fluent/src/main/java/org/apache/hc/client5/http/fluent/Request.java @@ -63,6 +63,11 @@ import org.apache.hc.core5.http.io.entity.InputStreamEntity; import org.apache.hc.core5.net.URLEncodedUtils; import org.apache.hc.core5.util.Timeout; +/** + * HTTP request used by the fluent facade. + * + * @since 4.2 + */ public class Request { public static final String DATE_FORMAT = "EEE, dd MMM yyyy HH:mm:ss zzz"; diff --git a/httpclient5-fluent/src/main/java/org/apache/hc/client5/http/fluent/Response.java b/httpclient5-fluent/src/main/java/org/apache/hc/client5/http/fluent/Response.java index df4d42fbd..ea40c256d 100644 --- a/httpclient5-fluent/src/main/java/org/apache/hc/client5/http/fluent/Response.java +++ b/httpclient5-fluent/src/main/java/org/apache/hc/client5/http/fluent/Response.java @@ -43,6 +43,11 @@ import org.apache.hc.core5.http.io.HttpClientResponseHandler; import org.apache.hc.core5.http.io.entity.ByteArrayEntity; import org.apache.hc.core5.http.io.entity.EntityUtils; +/** + * HTTP response used by the fluent facade. + * + * @since 4.2 + */ public class Response { private final ClassicHttpResponse response; diff --git a/httpclient5-win/src/main/java/org/apache/hc/client5/http/impl/win/WindowsNTLMSchemeFactory.java b/httpclient5-win/src/main/java/org/apache/hc/client5/http/impl/win/WindowsNTLMSchemeFactory.java index 0f6d997ac..2639e0adb 100644 --- a/httpclient5-win/src/main/java/org/apache/hc/client5/http/impl/win/WindowsNTLMSchemeFactory.java +++ b/httpclient5-win/src/main/java/org/apache/hc/client5/http/impl/win/WindowsNTLMSchemeFactory.java @@ -31,19 +31,18 @@ import org.apache.hc.client5.http.auth.AuthScheme; import org.apache.hc.client5.http.auth.AuthSchemeProvider; import org.apache.hc.client5.http.auth.AuthSchemes; import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.Experimental; import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.protocol.HttpContext; /** * {@link AuthSchemeProvider} implementation that creates and initializes * {@link WindowsNegotiateScheme} using JNA to implement NTLM - *

- * EXPERIMENTAL - *

* * @since 4.4 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) +@Experimental public class WindowsNTLMSchemeFactory implements AuthSchemeProvider { private final String servicePrincipalName; diff --git a/httpclient5-win/src/main/java/org/apache/hc/client5/http/impl/win/WindowsNegotiateScheme.java b/httpclient5-win/src/main/java/org/apache/hc/client5/http/impl/win/WindowsNegotiateScheme.java index 34a8936a7..dd9c39bb5 100644 --- a/httpclient5-win/src/main/java/org/apache/hc/client5/http/impl/win/WindowsNegotiateScheme.java +++ b/httpclient5-win/src/main/java/org/apache/hc/client5/http/impl/win/WindowsNegotiateScheme.java @@ -32,13 +32,14 @@ import org.apache.commons.codec.binary.Base64; import org.apache.hc.client5.http.RouteInfo; import org.apache.hc.client5.http.auth.AuthChallenge; import org.apache.hc.client5.http.auth.AuthScheme; +import org.apache.hc.client5.http.auth.AuthSchemes; import org.apache.hc.client5.http.auth.AuthenticationException; import org.apache.hc.client5.http.auth.BasicUserPrincipal; import org.apache.hc.client5.http.auth.ChallengeType; import org.apache.hc.client5.http.auth.CredentialsProvider; import org.apache.hc.client5.http.auth.MalformedChallengeException; -import org.apache.hc.client5.http.auth.AuthSchemes; import org.apache.hc.client5.http.protocol.HttpClientContext; +import org.apache.hc.core5.annotation.Experimental; import org.apache.hc.core5.http.HttpHost; import org.apache.hc.core5.http.HttpRequest; import org.apache.hc.core5.http.protocol.HttpContext; @@ -63,12 +64,10 @@ import com.sun.jna.ptr.IntByReference; *

* This will delegate negotiation to the windows machine. *

- *

- * EXPERIMENTAL - *

* * @since 4.4 */ +@Experimental public class WindowsNegotiateScheme implements AuthScheme { private final Logger log = LoggerFactory.getLogger(getClass()); diff --git a/httpclient5-win/src/main/java/org/apache/hc/client5/http/impl/win/WindowsNegotiateSchemeFactory.java b/httpclient5-win/src/main/java/org/apache/hc/client5/http/impl/win/WindowsNegotiateSchemeFactory.java index d43c99469..b6e9ef02c 100644 --- a/httpclient5-win/src/main/java/org/apache/hc/client5/http/impl/win/WindowsNegotiateSchemeFactory.java +++ b/httpclient5-win/src/main/java/org/apache/hc/client5/http/impl/win/WindowsNegotiateSchemeFactory.java @@ -31,19 +31,18 @@ import org.apache.hc.client5.http.auth.AuthScheme; import org.apache.hc.client5.http.auth.AuthSchemeProvider; import org.apache.hc.client5.http.auth.AuthSchemes; import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.Experimental; import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.protocol.HttpContext; /** * {@link AuthSchemeProvider} implementation that creates and initializes * {@link WindowsNegotiateScheme} using JNA to Negotiate credentials - *

- * EXPERIMENTAL - *

* * @since 4.4 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) +@Experimental public class WindowsNegotiateSchemeFactory implements AuthSchemeProvider { private final String servicePrincipalName; diff --git a/httpclient5/src/examples/org/apache/hc/client5/http/examples/ClientWithRequestFuture.java b/httpclient5/src/examples/org/apache/hc/client5/http/examples/ClientWithRequestFuture.java index d0458b66d..daff64642 100644 --- a/httpclient5/src/examples/org/apache/hc/client5/http/examples/ClientWithRequestFuture.java +++ b/httpclient5/src/examples/org/apache/hc/client5/http/examples/ClientWithRequestFuture.java @@ -30,13 +30,13 @@ import java.io.IOException; import java.util.concurrent.CancellationException; import java.util.concurrent.ExecutorService; import java.util.concurrent.Executors; +import java.util.concurrent.FutureTask; import java.util.concurrent.TimeUnit; import org.apache.hc.client5.http.classic.methods.HttpGet; import org.apache.hc.client5.http.impl.classic.CloseableHttpClient; import org.apache.hc.client5.http.impl.classic.FutureRequestExecutionService; import org.apache.hc.client5.http.impl.classic.HttpClientBuilder; -import org.apache.hc.client5.http.impl.classic.HttpRequestFutureTask; import org.apache.hc.client5.http.impl.io.PoolingHttpClientConnectionManagerBuilder; import org.apache.hc.client5.http.io.HttpClientConnectionManager; import org.apache.hc.client5.http.protocol.HttpClientContext; @@ -70,7 +70,7 @@ public class ClientWithRequestFuture { // Simple request ... final HttpGet request1 = new HttpGet("http://httpbin.org/get"); - final HttpRequestFutureTask futureTask1 = requestExecService.execute(request1, + final FutureTask futureTask1 = requestExecService.execute(request1, HttpClientContext.create(), handler); final Boolean wasItOk1 = futureTask1.get(); System.out.println("It was ok? " + wasItOk1); @@ -78,7 +78,7 @@ public class ClientWithRequestFuture { // Cancel a request try { final HttpGet request2 = new HttpGet("http://httpbin.org/get"); - final HttpRequestFutureTask futureTask2 = requestExecService.execute(request2, + final FutureTask futureTask2 = requestExecService.execute(request2, HttpClientContext.create(), handler); futureTask2.cancel(true); final Boolean wasItOk2 = futureTask2.get(); @@ -89,7 +89,7 @@ public class ClientWithRequestFuture { // Request with a timeout final HttpGet request3 = new HttpGet("http://httpbin.org/get"); - final HttpRequestFutureTask futureTask3 = requestExecService.execute(request3, + final FutureTask futureTask3 = requestExecService.execute(request3, HttpClientContext.create(), handler); final Boolean wasItOk3 = futureTask3.get(10, TimeUnit.SECONDS); System.out.println("It was ok? " + wasItOk3); @@ -115,7 +115,7 @@ public class ClientWithRequestFuture { final HttpGet request4 = new HttpGet("http://httpbin.org/get"); // using a null HttpContext here since it is optional // the callback will be called when the task completes, fails, or is cancelled - final HttpRequestFutureTask futureTask4 = requestExecService.execute(request4, + final FutureTask futureTask4 = requestExecService.execute(request4, HttpClientContext.create(), handler, callback); final Boolean wasItOk4 = futureTask4.get(10, TimeUnit.SECONDS); System.out.println("It was ok? " + wasItOk4); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/AuthenticationStrategy.java b/httpclient5/src/main/java/org/apache/hc/client5/http/AuthenticationStrategy.java index e5371caa0..1e534a5f2 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/AuthenticationStrategy.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/AuthenticationStrategy.java @@ -33,6 +33,8 @@ import java.util.Map; import org.apache.hc.client5.http.auth.AuthChallenge; import org.apache.hc.client5.http.auth.AuthScheme; import org.apache.hc.client5.http.auth.ChallengeType; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.protocol.HttpContext; /** @@ -44,6 +46,7 @@ import org.apache.hc.core5.http.protocol.HttpContext; * * @since 4.2 */ +@Contract(threading = ThreadingBehavior.STATELESS) public interface AuthenticationStrategy { /** diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/CircularRedirectException.java b/httpclient5/src/main/java/org/apache/hc/client5/http/CircularRedirectException.java index 91508de2c..92d03c9c2 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/CircularRedirectException.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/CircularRedirectException.java @@ -29,7 +29,6 @@ package org.apache.hc.client5.http; /** * Signals a circular redirect * - * * @since 4.0 */ public class CircularRedirectException extends RedirectException { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/ConnectTimeoutException.java b/httpclient5/src/main/java/org/apache/hc/client5/http/ConnectTimeoutException.java index c9019acc1..9b7437718 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/ConnectTimeoutException.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/ConnectTimeoutException.java @@ -38,7 +38,6 @@ import org.apache.hc.core5.net.NamedEndpoint; * A timeout while connecting to an HTTP server or waiting for an * available connection from an HttpConnectionManager. * - * * @since 4.0 */ public class ConnectTimeoutException extends InterruptedIOException { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/ConnectionKeepAliveStrategy.java b/httpclient5/src/main/java/org/apache/hc/client5/http/ConnectionKeepAliveStrategy.java index d58ce2cbd..90ebde363 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/ConnectionKeepAliveStrategy.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/ConnectionKeepAliveStrategy.java @@ -26,6 +26,8 @@ */ package org.apache.hc.client5.http; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.HttpResponse; import org.apache.hc.core5.http.protocol.HttpContext; import org.apache.hc.core5.util.TimeValue; @@ -40,6 +42,7 @@ import org.apache.hc.core5.util.TimeValue; * * @since 4.0 */ +@Contract(threading = ThreadingBehavior.STATELESS) public interface ConnectionKeepAliveStrategy { /** diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/DnsResolver.java b/httpclient5/src/main/java/org/apache/hc/client5/http/DnsResolver.java index 4d304c65c..bf9b85e6e 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/DnsResolver.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/DnsResolver.java @@ -29,12 +29,16 @@ package org.apache.hc.client5.http; import java.net.InetAddress; import java.net.UnknownHostException; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; + /** * Users may implement this interface to override the normal DNS lookup offered * by the OS. * * @since 4.2 */ +@Contract(threading = ThreadingBehavior.STATELESS) public interface DnsResolver { /** diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/HttpRequestRetryHandler.java b/httpclient5/src/main/java/org/apache/hc/client5/http/HttpRequestRetryHandler.java index 85371b048..e1573b4c8 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/HttpRequestRetryHandler.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/HttpRequestRetryHandler.java @@ -29,6 +29,8 @@ package org.apache.hc.client5.http; import java.io.IOException; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.HttpRequest; import org.apache.hc.core5.http.protocol.HttpContext; @@ -42,6 +44,7 @@ import org.apache.hc.core5.http.protocol.HttpContext; * * @since 4.0 */ +@Contract(threading = ThreadingBehavior.STATELESS) public interface HttpRequestRetryHandler { /** diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/HttpRoute.java b/httpclient5/src/main/java/org/apache/hc/client5/http/HttpRoute.java index 98c0784a3..ce3a6be55 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/HttpRoute.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/HttpRoute.java @@ -41,7 +41,7 @@ import org.apache.hc.core5.util.Args; import org.apache.hc.core5.util.LangUtils; /** - * The route for a request. + * Connection route definition for HTTP requests. * * @since 4.0 */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/RedirectException.java b/httpclient5/src/main/java/org/apache/hc/client5/http/RedirectException.java index 2e7b825be..507be67bf 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/RedirectException.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/RedirectException.java @@ -31,7 +31,6 @@ import org.apache.hc.core5.http.ProtocolException; /** * Signals violation of HTTP specification caused by an invalid redirect * - * * @since 4.0 */ public class RedirectException extends ProtocolException { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/RouteInfo.java b/httpclient5/src/main/java/org/apache/hc/client5/http/RouteInfo.java index f090034a6..5b6749011 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/RouteInfo.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/RouteInfo.java @@ -32,7 +32,7 @@ import java.net.InetAddress; import org.apache.hc.core5.http.HttpHost; /** - * Read-only interface for route information. + * Connection route information. * * @since 4.0 */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/SchemePortResolver.java b/httpclient5/src/main/java/org/apache/hc/client5/http/SchemePortResolver.java index c3caa83a5..26ddb4225 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/SchemePortResolver.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/SchemePortResolver.java @@ -26,6 +26,8 @@ */ package org.apache.hc.client5.http; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.HttpHost; /** @@ -33,6 +35,7 @@ import org.apache.hc.core5.http.HttpHost; * * @since 4.3 */ +@Contract(threading = ThreadingBehavior.STATELESS) public interface SchemePortResolver { /** diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/ServiceUnavailableRetryStrategy.java b/httpclient5/src/main/java/org/apache/hc/client5/http/ServiceUnavailableRetryStrategy.java index c6aa96821..95753307e 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/ServiceUnavailableRetryStrategy.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/ServiceUnavailableRetryStrategy.java @@ -27,6 +27,8 @@ package org.apache.hc.client5.http; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.HttpResponse; import org.apache.hc.core5.http.protocol.HttpContext; @@ -37,6 +39,7 @@ import org.apache.hc.core5.http.protocol.HttpContext; * * @since 4.2 */ +@Contract(threading = ThreadingBehavior.STATELESS) public interface ServiceUnavailableRetryStrategy { /** diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/StandardMethods.java b/httpclient5/src/main/java/org/apache/hc/client5/http/StandardMethods.java index 3ac56821a..305dc7373 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/StandardMethods.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/StandardMethods.java @@ -29,6 +29,11 @@ package org.apache.hc.client5.http; import java.util.Locale; +/** + * Common HTTP methods defined by the HTTP spec. + * + * @since 5.0 + */ public enum StandardMethods { GET(true, true), diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/UserTokenHandler.java b/httpclient5/src/main/java/org/apache/hc/client5/http/UserTokenHandler.java index 32781a72c..deb094420 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/UserTokenHandler.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/UserTokenHandler.java @@ -27,6 +27,8 @@ package org.apache.hc.client5.http; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.protocol.HttpContext; /** @@ -42,6 +44,7 @@ import org.apache.hc.core5.http.protocol.HttpContext; * * @since 4.0 */ +@Contract(threading = ThreadingBehavior.STATELESS) public interface UserTokenHandler { /** diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/async/AsyncExecCallback.java b/httpclient5/src/main/java/org/apache/hc/client5/http/async/AsyncExecCallback.java index dc75d6e4a..c09d2c1d1 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/async/AsyncExecCallback.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/async/AsyncExecCallback.java @@ -33,14 +33,43 @@ import org.apache.hc.core5.http.HttpException; import org.apache.hc.core5.http.HttpResponse; import org.apache.hc.core5.http.nio.AsyncDataConsumer; +/** + * AsyncExecCallback methods represent response processing events + * in the client side request execution chain. + * + * @since 5.0 + */ public interface AsyncExecCallback { + /** + * Triggered to signal receipt of a response message head sent by the server + * in response to the request being executed. + * + * @param response the response message head. + * @param entityDetails the response entity details or {@code null} if the response + * does not enclose an entity. + * @return the data consumer to be used for processing of incoming response message body. + */ AsyncDataConsumer handleResponse( HttpResponse response, EntityDetails entityDetails) throws HttpException, IOException; + /** + * Triggered to signal completion of the message exchange. + *

+ * Implementations of this message are expected to perform resource deallocation + * allocated in the course of the request execution and response processing. + *

+ */ void completed(); + /** + * Triggered to signal a failure occurred during the message exchange. + *

+ * Implementations of this message are expected to perform resource deallocation + * allocated in the course of the request execution and response processing. + *

+ */ void failed(Exception cause); } diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/async/AsyncExecChain.java b/httpclient5/src/main/java/org/apache/hc/client5/http/async/AsyncExecChain.java index 201e12b4f..b2cff0bd3 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/async/AsyncExecChain.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/async/AsyncExecChain.java @@ -30,14 +30,27 @@ import java.io.IOException; import org.apache.hc.client5.http.HttpRoute; import org.apache.hc.client5.http.protocol.HttpClientContext; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.concurrent.CancellableDependency; import org.apache.hc.core5.http.HttpException; import org.apache.hc.core5.http.HttpRequest; import org.apache.hc.core5.http.nio.AsyncEntityProducer; import org.apache.hc.core5.util.Args; +/** + * Represents a single element in the client side asynchronous request execution chain. + * + * @since 5.0 + */ +@Contract(threading = ThreadingBehavior.STATELESS) public interface AsyncExecChain { + /** + * Request execution scope that includes the unique message exchange ID, + * the connection route, the original request message, the execution + * context and the internal execution runtime. + */ final class Scope { public final String exchangeId; @@ -64,6 +77,15 @@ public interface AsyncExecChain { } + /** + * Proceeds to the next element in the request execution chain. + * + * @param request the actual request. + * @param entityProducer the request entity producer or {@code null} if the request + * does not enclose an entity. + * @param scope the execution scope . + * @param asyncExecCallback the execution callback. + */ void proceed( HttpRequest request, AsyncEntityProducer entityProducer, diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/async/AsyncExecChainHandler.java b/httpclient5/src/main/java/org/apache/hc/client5/http/async/AsyncExecChainHandler.java index f0cbccdeb..3888617fc 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/async/AsyncExecChainHandler.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/async/AsyncExecChainHandler.java @@ -28,12 +28,36 @@ package org.apache.hc.client5.http.async; import java.io.IOException; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.HttpException; import org.apache.hc.core5.http.HttpRequest; import org.apache.hc.core5.http.nio.AsyncEntityProducer; +/** + * Abstract request execution handler in an asynchronous client side request execution + * chain. Handlers can either be a decorator around another element that implements + * a cross cutting aspect or a self-contained executor capable of producing a response + * for the given request. + * + * @since 5.0 + */ +@Contract(threading = ThreadingBehavior.STATELESS) public interface AsyncExecChainHandler { + /** + * Executes the actual HTTP request. The handler can choose to return + * a response message immediately inside the call or asynchronously + * at some later point or delegate request execution to the next + * element in the execution chain. + * + * @param request the actual request. + * @param entityProducer the request entity producer or {@code null} if the request + * does not enclose an entity. + * @param scope the execution scope . + * @param chain the next element in the request execution chain. + * @param asyncExecCallback the execution callback. + */ void execute( HttpRequest request, AsyncEntityProducer entityProducer, diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/async/AsyncExecRuntime.java b/httpclient5/src/main/java/org/apache/hc/client5/http/async/AsyncExecRuntime.java index 7c0b027c6..39e7dff95 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/async/AsyncExecRuntime.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/async/AsyncExecRuntime.java @@ -41,45 +41,111 @@ import org.apache.hc.core5.util.TimeValue; *

* This interface is considered internal and generally ought not be used or accessed * by custom request exec handlers. + *

* * @since 5.0 */ @Internal public interface AsyncExecRuntime { - boolean isConnectionAcquired(); + /** + * Determines of a connection endpoint has been acquired. + * + * @return {@code true} if an endpoint has been acquired, {@code false} otherwise. + */ + boolean isEndpointAcquired(); - Cancellable acquireConnection( + /** + * Initiates operation to acquire a connection endpoint. Endpoints can leased from a pool + * or unconnected new endpoint can be created. + * + * @param route the connection route. + * @param state the expected connection state. May be {@code null} if connection + * can be state-less or its state is irrelevant. + * @param context the execution context. + * @param callback the result callback. + * @return handle that can be used to cancel the operation. + */ + Cancellable acquireEndpoint( HttpRoute route, Object state, - HttpClientContext clientContext, + HttpClientContext context, FutureCallback callback); - void releaseConnection(); + /** + * Releases the acquired endpoint potentially making it available for re-use. + */ + void releaseEndpoint(); - void discardConnection(); + /** + * Shuts down and discards the acquired endpoint. + */ + void discardEndpoint(); - boolean validateConnection(); + /** + * Determines of there the endpoint is connected to the initial hop (connection target + * in case of a direct route or to the first proxy hop in case of a route via a proxy + * or multiple proxies). + * + * @return {@code true} if the endpoint is connected, {@code false} otherwise. + */ + boolean isEndpointConnected(); - boolean isConnected(); - - Cancellable connect( - HttpClientContext clientContext, + /** + * Initiates operation to connect the local endpoint to the initial hop (connection + * target in case of a direct route or to the first proxy hop in case of a route + * via a proxy or multiple proxies). + * + * @param context the execution context. + * @param callback the result callback. + * @return handle that can be used to cancel the operation. + */ + Cancellable connectEndpoint( + HttpClientContext context, FutureCallback callback); + /** + * Upgrades transport security of the active connection by using the TLS security protocol. + * + * @param context the execution context. + */ void upgradeTls(HttpClientContext context); + /** + * Validates the connection making sure it can be used to execute requests. + * + * @return {@code true} if the connection is valid, {@code false}. + */ + boolean validateConnection(); + /** * Initiates a message exchange using the given handler. + * + * @param exchangeHandler the client message handler. + * @param context the execution context. */ Cancellable execute( AsyncClientExchangeHandler exchangeHandler, HttpClientContext context); - void markConnectionReusable(Object state, TimeValue duration); + /** + * Marks the connection as potentially re-usable for the given period of time + * and also marks it as stateful if the state representation is given. + * @param state the connection state representation or {@code null} if stateless. + * @param validityTime the period of time this connection is valid for. + */ + void markConnectionReusable(Object state, TimeValue validityTime); + /** + * Marks the connection as non re-usable. + */ void markConnectionNonReusable(); + /** + * Forks this runtime for parallel execution. + * + * @return another runtime with the same configuration. + */ AsyncExecRuntime fork(); } diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/AbstractBinPushConsumer.java b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/AbstractBinPushConsumer.java index 7f79fd942..04c0f7c41 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/AbstractBinPushConsumer.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/AbstractBinPushConsumer.java @@ -39,8 +39,20 @@ import org.apache.hc.core5.http.nio.AsyncPushConsumer; import org.apache.hc.core5.http.nio.entity.AbstractBinDataConsumer; import org.apache.hc.core5.http.protocol.HttpContext; +/** + * Abstract push response consumer that processes response body data as an octet stream. + * + * @since 5.0 + */ public abstract class AbstractBinPushConsumer extends AbstractBinDataConsumer implements AsyncPushConsumer { + /** + * Triggered to signal the beginning of response processing. + * + * @param response the response message head + * @param contentType the content type of the response body, + * or {@code null} if the response does not enclose a response entity. + */ protected abstract void start(HttpRequest promise, HttpResponse response, ContentType contentType) throws HttpException, IOException; @Override @@ -56,7 +68,7 @@ public abstract class AbstractBinPushConsumer extends AbstractBinDataConsumer im } catch (final UnsupportedCharsetException ex) { throw new UnsupportedEncodingException(ex.getMessage()); } - start(promise, response, contentType); + start(promise, response, contentType != null ? contentType : ContentType.DEFAULT_BINARY); } else { start(promise, response, null); completed(); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/AbstractBinResponseConsumer.java b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/AbstractBinResponseConsumer.java index b165c4f82..f35b55e76 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/AbstractBinResponseConsumer.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/AbstractBinResponseConsumer.java @@ -39,12 +39,31 @@ import org.apache.hc.core5.http.nio.AsyncResponseConsumer; import org.apache.hc.core5.http.nio.entity.AbstractBinDataConsumer; import org.apache.hc.core5.http.protocol.HttpContext; +/** + * Abstract response consumer that processes response body data as an octet stream. + * + * @since 5.0 + * + * @param response message representation. + */ public abstract class AbstractBinResponseConsumer extends AbstractBinDataConsumer implements AsyncResponseConsumer { private volatile FutureCallback resultCallback; + /** + * Triggered to signal the beginning of response processing. + * + * @param response the response message head + * @param contentType the content type of the response body, + * or {@code null} if the response does not enclose a response entity. + */ protected abstract void start(HttpResponse response, ContentType contentType) throws HttpException, IOException; + /** + * Triggered to generate object that represents a result of response message processing. + * + * @return the result of response processing. + */ protected abstract T buildResult(); @Override @@ -63,7 +82,7 @@ public abstract class AbstractBinResponseConsumer extends AbstractBinDataCons if (entityDetails != null) { try { final ContentType contentType = ContentType.parse(entityDetails.getContentType()); - start(response, contentType); + start(response, contentType != null ? contentType : ContentType.DEFAULT_BINARY); } catch (final UnsupportedCharsetException ex) { throw new UnsupportedEncodingException(ex.getMessage()); } diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/AbstractCharPushConsumer.java b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/AbstractCharPushConsumer.java index 899d5a855..fccf509c6 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/AbstractCharPushConsumer.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/AbstractCharPushConsumer.java @@ -41,8 +41,20 @@ import org.apache.hc.core5.http.nio.AsyncPushConsumer; import org.apache.hc.core5.http.nio.entity.AbstractCharDataConsumer; import org.apache.hc.core5.http.protocol.HttpContext; +/** + * Abstract push response consumer that processes response body data as a character stream. + * + * @since 5.0 + */ public abstract class AbstractCharPushConsumer extends AbstractCharDataConsumer implements AsyncPushConsumer { + /** + * Triggered to signal the beginning of data processing. + * + * @param response the response message head + * @param contentType the content type of the response body, + * or {@code null} if the response does not enclose a response entity. + */ protected abstract void start(HttpRequest promise, HttpResponse response, ContentType contentType) throws HttpException, IOException; @Override @@ -63,7 +75,7 @@ public abstract class AbstractCharPushConsumer extends AbstractCharDataConsumer charset = StandardCharsets.US_ASCII; } setCharset(charset); - start(promise, response, contentType); + start(promise, response, contentType != null ? contentType : ContentType.DEFAULT_TEXT); } else { start(promise, response, null); completed(); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/AbstractCharResponseConsumer.java b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/AbstractCharResponseConsumer.java index 9dd5bfedc..825f93f72 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/AbstractCharResponseConsumer.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/AbstractCharResponseConsumer.java @@ -41,12 +41,31 @@ import org.apache.hc.core5.http.nio.AsyncResponseConsumer; import org.apache.hc.core5.http.nio.entity.AbstractCharDataConsumer; import org.apache.hc.core5.http.protocol.HttpContext; +/** + * Abstract response consumer that processes response body data as a character stream. + * + * @since 5.0 + * + * @param response message representation. + */ public abstract class AbstractCharResponseConsumer extends AbstractCharDataConsumer implements AsyncResponseConsumer { private volatile FutureCallback resultCallback; + /** + * Triggered to signal the beginning of data processing. + * + * @param response the response message head + * @param contentType the content type of the response body, + * or {@code null} if the response does not enclose a response entity. + */ protected abstract void start(HttpResponse response, ContentType contentType) throws HttpException, IOException; + /** + * Triggered to generate object that represents a result of response message processing. + * + * @return the result of response processing. + */ protected abstract T buildResult() throws IOException; @Override @@ -74,7 +93,7 @@ public abstract class AbstractCharResponseConsumer extends AbstractCharDataCo charset = StandardCharsets.US_ASCII; } setCharset(charset); - start(response, contentType); + start(response, contentType != null ? contentType : ContentType.DEFAULT_TEXT); } else { start(response, null); completed(); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/AsyncRequestBuilder.java b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/AsyncRequestBuilder.java index c07a42e8f..a0956b4ff 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/AsyncRequestBuilder.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/AsyncRequestBuilder.java @@ -63,6 +63,7 @@ import org.apache.hc.core5.util.TextUtils; * {@link #setEntity(AsyncEntityProducer)} or it is not an entity enclosing method * (such as POST or PUT), parameters will be added to the query component of the request URI. * Otherwise, parameters will be added as a URL encoded entity. + *

* * @since 5.0 */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/ConfigurableHttpRequest.java b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/ConfigurableHttpRequest.java index 23c4bc986..d92dd7ed9 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/ConfigurableHttpRequest.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/ConfigurableHttpRequest.java @@ -34,6 +34,11 @@ import org.apache.hc.client5.http.config.RequestConfig; import org.apache.hc.core5.http.HttpHost; import org.apache.hc.core5.http.message.BasicHttpRequest; +/** + * HTTP request message with a custom configuration. + * + * @since 5.0 + */ public class ConfigurableHttpRequest extends BasicHttpRequest implements Configurable { private static final long serialVersionUID = 1L; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/HttpRequests.java b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/HttpRequests.java index b82dee3fe..056b80b03 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/HttpRequests.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/HttpRequests.java @@ -34,9 +34,9 @@ import org.apache.hc.core5.http.HttpHost; import org.apache.hc.core5.http.message.BasicHttpRequest; /** - * HTTP methods defined in RFC2616. + * Common HTTP methods using {@link BasicHttpRequest} as a HTTP request message representation. * - * @since 5.0-beta2 + * @since 5.0 */ public enum HttpRequests { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/SimpleBody.java b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/SimpleBody.java index 0583f1679..926fef8a5 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/SimpleBody.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/SimpleBody.java @@ -33,6 +33,11 @@ import java.nio.charset.StandardCharsets; import org.apache.hc.core5.http.ContentType; import org.apache.hc.core5.util.Args; +/** + * Message body representation as a simple text string or an array of bytes. + * + * @since 5.0 + */ public final class SimpleBody { private final byte[] bodyAsBytes; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/SimpleHttpRequest.java b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/SimpleHttpRequest.java index 6ef253da9..51306e514 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/SimpleHttpRequest.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/SimpleHttpRequest.java @@ -37,6 +37,13 @@ import org.apache.hc.core5.http.HttpHost; import org.apache.hc.core5.http.HttpRequest; import org.apache.hc.core5.util.Args; +/** + * HTTP request that can enclose a body represented as a simple text string or an array of bytes. + * + * @since 5.0 + * + * @see SimpleBody + */ public final class SimpleHttpRequest extends ConfigurableHttpRequest { private static final long serialVersionUID = 1L; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/SimpleHttpRequests.java b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/SimpleHttpRequests.java index d4380e2b0..f5dd6c801 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/SimpleHttpRequests.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/SimpleHttpRequests.java @@ -33,9 +33,9 @@ import org.apache.hc.client5.http.StandardMethods; import org.apache.hc.core5.http.HttpHost; /** - * HTTP methods defined in RFC2616. + * Common HTTP methods using {@link SimpleHttpRequest} as a HTTP request message representation. * - * @since 5.0-beta2 + * @since 5.0 */ public enum SimpleHttpRequests { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/SimpleHttpResponse.java b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/SimpleHttpResponse.java index c5a9f45e2..e323a2aea 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/SimpleHttpResponse.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/SimpleHttpResponse.java @@ -35,6 +35,13 @@ import org.apache.hc.core5.http.HttpResponse; import org.apache.hc.core5.http.message.BasicHttpResponse; import org.apache.hc.core5.util.Args; +/** + * HTTP response that can enclose a body represented as a simple text string or an array of bytes. + * + * @since 5.0 + * + * @see SimpleBody + */ public final class SimpleHttpResponse extends BasicHttpResponse { private static final long serialVersionUID = 1L; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/SimpleRequestProducer.java b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/SimpleRequestProducer.java index 823959ce0..4e5dc9273 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/SimpleRequestProducer.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/SimpleRequestProducer.java @@ -32,6 +32,14 @@ import org.apache.hc.core5.http.nio.entity.BasicAsyncEntityProducer; import org.apache.hc.core5.http.nio.entity.StringAsyncEntityProducer; import org.apache.hc.core5.util.Args; +/** + * HTTP request producer that generates message data stream events based + * on content of a {@link SimpleHttpRequest} instance. + * + * @since 5.0 + * + * @see SimpleBody + */ public final class SimpleRequestProducer extends BasicRequestProducer { SimpleRequestProducer(final SimpleHttpRequest request, final AsyncEntityProducer entityProducer) { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/SimpleResponseConsumer.java b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/SimpleResponseConsumer.java index 0b6aeede5..4af8defcf 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/SimpleResponseConsumer.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/SimpleResponseConsumer.java @@ -36,6 +36,14 @@ import org.apache.hc.core5.http.nio.entity.BasicAsyncEntityConsumer; import org.apache.hc.core5.http.nio.support.AbstractAsyncResponseConsumer; import org.apache.hc.core5.http.protocol.HttpContext; +/** + * HTTP response consumer that generates a {@link SimpleHttpResponse} instance based on events + * of an incoming data stream. + * + * @since 5.0 + * + * @see SimpleBody + */ public final class SimpleResponseConsumer extends AbstractAsyncResponseConsumer { SimpleResponseConsumer(final AsyncEntityConsumer entityConsumer) { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/package-info.java b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/package-info.java new file mode 100644 index 000000000..939b31622 --- /dev/null +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/package-info.java @@ -0,0 +1,31 @@ +/* + * ==================================================================== + * 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 + * . + * + */ + +/** + * Common HTTP methods and message handlers for the asynchronous I/O model. + */ +package org.apache.hc.client5.http.async.methods; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/async/package-info.java b/httpclient5/src/main/java/org/apache/hc/client5/http/async/package-info.java new file mode 100644 index 000000000..648e8a858 --- /dev/null +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/async/package-info.java @@ -0,0 +1,31 @@ +/* + * ==================================================================== + * 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 client APIs based on the asynchronous, event driven I/O model. + */ +package org.apache.hc.client5.http.async; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/auth/AuthCache.java b/httpclient5/src/main/java/org/apache/hc/client5/http/auth/AuthCache.java index 49d28ecf7..f566b392c 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/auth/AuthCache.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/auth/AuthCache.java @@ -29,9 +29,8 @@ package org.apache.hc.client5.http.auth; import org.apache.hc.core5.http.HttpHost; /** - * Abstract {@link AuthScheme} cache. Initialized {@link AuthScheme} objects - * from this cache can be used to preemptively authenticate against known - * hosts. + * This interface represents an cache of {@link AuthScheme} state information + * that can be re-used for preemptive authentication by subsequent requests. * * @since 4.1 */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/auth/AuthScheme.java b/httpclient5/src/main/java/org/apache/hc/client5/http/auth/AuthScheme.java index 1cb6d55ac..22d884a97 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/auth/AuthScheme.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/auth/AuthScheme.java @@ -42,11 +42,14 @@ import org.apache.hc.core5.http.protocol.HttpContext; * authentication scheme and they may carry a particular security context and be authorized * for a particular user identity. It is important that such schemes always provide * the user identity they represent through the {@link #getPrincipal()} method. + *

*

* Authentication scheme are expected to transition through a series of standard phases or * states. + *

*

* Authentication scheme starts off its life cycle with no context and no specific state. + *

*

* The {@link #processChallenge(AuthChallenge, HttpContext)} method is called to * process an authentication challenge received either from the target server or a proxy. @@ -55,6 +58,7 @@ import org.apache.hc.core5.http.protocol.HttpContext; * challenge details. Standard authentication schemes are expected to provide a realm * attribute in the challenge. {@link #getRealm()} can be called to obtain an identifier * of the realm that requires authorization. + *

*

* Once the challenge has been fully processed the {@link #isResponseReady(HttpHost, * CredentialsProvider, HttpContext)} method to determine whether the scheme is capable of @@ -62,15 +66,18 @@ import org.apache.hc.core5.http.protocol.HttpContext; * required to do so. If this method returns {@code false} the authentication is considered * to be in FAILED state and no authorization response. Otherwise the scheme is considered * to be in RESPONSE_READY state. + *

*

* Once the scheme is ready to respond to the challenge the {@link #generateAuthResponse( * HttpHost, HttpRequest, HttpContext)} method to generate a response token, which will * be sent to the opposite endpoint in the subsequent request message. + *

*

* Certain non-standard schemes may involve multiple challenge / response exchanges to * fully establish a shared context and complete the authentication process. Authentication * schemes are required to return {@code true} {@link #isChallengeComplete()} once the * handshake is considered complete. + *

*

* The authentication scheme is considered successfully completed and in SUCCESS state * if the opposite endpoint accepts the request message containing the authorization @@ -78,6 +85,7 @@ import org.apache.hc.core5.http.protocol.HttpContext; * If the opposite endpoint sends status code 401 or 407 in response to a request message * containing the terminal authorization response, the scheme is considered unsuccessful * and in FAILED state. + *

* * @since 4.0 */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/auth/AuthScope.java b/httpclient5/src/main/java/org/apache/hc/client5/http/auth/AuthScope.java index 2bc4a29e6..46fb78717 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/auth/AuthScope.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/auth/AuthScope.java @@ -38,7 +38,7 @@ import org.apache.hc.core5.util.LangUtils; * {@code AuthScope} represents an authentication scope consisting of * an application protocol, a host name, a port number, a realm name * and an authentication scheme name. - *

+ * * @since 4.0 */ @Contract(threading = ThreadingBehavior.IMMUTABLE) diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/auth/AuthStateCacheable.java b/httpclient5/src/main/java/org/apache/hc/client5/http/auth/AuthStateCacheable.java index 60435cdad..1c1cb8f6a 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/auth/AuthStateCacheable.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/auth/AuthStateCacheable.java @@ -32,6 +32,12 @@ import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +/** + * Indicates that the state of an {@link AuthScheme} can be cached + * and re-used for preemptive authentication by subsequent requests. + * + * @since 5.0 + */ @Documented @Target({ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/auth/AuthenticationException.java b/httpclient5/src/main/java/org/apache/hc/client5/http/auth/AuthenticationException.java index 80d208a71..9fa3d6eb2 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/auth/AuthenticationException.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/auth/AuthenticationException.java @@ -31,7 +31,6 @@ import org.apache.hc.core5.http.ProtocolException; /** * Signals a failure in authentication process * - * * @since 4.0 */ public class AuthenticationException extends ProtocolException { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/auth/BasicUserPrincipal.java b/httpclient5/src/main/java/org/apache/hc/client5/http/auth/BasicUserPrincipal.java index b062675ea..66bac25a5 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/auth/BasicUserPrincipal.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/auth/BasicUserPrincipal.java @@ -35,7 +35,7 @@ import org.apache.hc.core5.util.Args; import org.apache.hc.core5.util.LangUtils; /** - * Basic user principal used for HTTP authentication + * Basic username based principal representation. * * @since 4.0 */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/auth/CredentialsProvider.java b/httpclient5/src/main/java/org/apache/hc/client5/http/auth/CredentialsProvider.java index 13a595b5f..103fc060f 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/auth/CredentialsProvider.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/auth/CredentialsProvider.java @@ -34,6 +34,7 @@ import org.apache.hc.core5.http.protocol.HttpContext; * Implementations of this interface must be thread-safe. Access to shared * data must be synchronized as methods of this interface may be executed * from multiple threads. + *

* * @since 4.0 */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/auth/CredentialsStore.java b/httpclient5/src/main/java/org/apache/hc/client5/http/auth/CredentialsStore.java index 49d1e3b98..a7578830e 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/auth/CredentialsStore.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/auth/CredentialsStore.java @@ -32,6 +32,7 @@ package org.apache.hc.client5.http.auth; * Implementations of this interface must be thread-safe. Access to shared * data must be synchronized as methods of this interface may be executed * from multiple threads. + *

* * @since 4.0 */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/auth/InvalidCredentialsException.java b/httpclient5/src/main/java/org/apache/hc/client5/http/auth/InvalidCredentialsException.java index 74631a531..530a3e64a 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/auth/InvalidCredentialsException.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/auth/InvalidCredentialsException.java @@ -26,17 +26,12 @@ */ package org.apache.hc.client5.http.auth; -import org.apache.hc.core5.annotation.Contract; -import org.apache.hc.core5.annotation.ThreadingBehavior; - /** * Authentication credentials required to respond to a authentication * challenge are invalid * - * * @since 4.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) public class InvalidCredentialsException extends AuthenticationException { private static final long serialVersionUID = -4834003835215460648L; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/auth/KerberosCredentials.java b/httpclient5/src/main/java/org/apache/hc/client5/http/auth/KerberosCredentials.java index fc49bcb34..e40963b2a 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/auth/KerberosCredentials.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/auth/KerberosCredentials.java @@ -34,7 +34,7 @@ import org.apache.hc.core5.annotation.ThreadingBehavior; import org.ietf.jgss.GSSCredential; /** - * {@link Credentials} implementation based on GSSCredential for Kerberos Authentication. + * Kerberos specific {@link Credentials} representation based on {@link GSSCredential}. * * @since 4.4 */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/auth/MalformedChallengeException.java b/httpclient5/src/main/java/org/apache/hc/client5/http/auth/MalformedChallengeException.java index d2ba02e9d..de3590c02 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/auth/MalformedChallengeException.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/auth/MalformedChallengeException.java @@ -32,7 +32,6 @@ import org.apache.hc.core5.http.ProtocolException; * Signals that authentication challenge is in some way invalid or * illegal in the given context * - * * @since 4.0 */ public class MalformedChallengeException extends ProtocolException { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/auth/NTCredentials.java b/httpclient5/src/main/java/org/apache/hc/client5/http/auth/NTCredentials.java index 7c56c80ad..1ee470d80 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/auth/NTCredentials.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/auth/NTCredentials.java @@ -36,7 +36,7 @@ import org.apache.hc.core5.util.Args; import org.apache.hc.core5.util.LangUtils; /** - * {@link Credentials} implementation for Microsoft Windows platforms that includes + * Microsoft Windows specific {@link Credentials} representation that includes * Windows specific attributes such as name of the domain the user belongs to. * * @since 4.0 diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/auth/UsernamePasswordCredentials.java b/httpclient5/src/main/java/org/apache/hc/client5/http/auth/UsernamePasswordCredentials.java index ca49b694c..46b22cc0d 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/auth/UsernamePasswordCredentials.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/auth/UsernamePasswordCredentials.java @@ -35,7 +35,7 @@ import org.apache.hc.core5.util.Args; import org.apache.hc.core5.util.LangUtils; /** - * Simple {@link Credentials} implementation based on a user name / password + * Simple {@link Credentials} representation based on a user name / password * pair. * * @since 4.0 diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/BackoffManager.java b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/BackoffManager.java index 2e4b8bf9f..48ca4f5c7 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/BackoffManager.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/BackoffManager.java @@ -34,7 +34,6 @@ import org.apache.hc.client5.http.HttpRoute; * using the connections. * * @since 4.2 - * */ public interface BackoffManager { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/ExecChain.java b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/ExecChain.java index fd1e92e27..d79c14b94 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/ExecChain.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/ExecChain.java @@ -31,11 +31,19 @@ import java.io.IOException; import org.apache.hc.client5.http.HttpRoute; import org.apache.hc.client5.http.protocol.HttpClientContext; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.ClassicHttpRequest; import org.apache.hc.core5.http.ClassicHttpResponse; import org.apache.hc.core5.http.HttpException; import org.apache.hc.core5.util.Args; +/** + * Represents a single element in the client side classic request execution chain. + * + * @since 5.0 + */ +@Contract(threading = ThreadingBehavior.STATELESS) public interface ExecChain { final class Scope { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/ExecChainHandler.java b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/ExecChainHandler.java index b4f1a6163..035c1000d 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/ExecChainHandler.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/ExecChainHandler.java @@ -29,14 +29,17 @@ package org.apache.hc.client5.http.classic; import java.io.IOException; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.ClassicHttpRequest; import org.apache.hc.core5.http.ClassicHttpResponse; import org.apache.hc.core5.http.HttpException; /** - * This interface represents an element in the HTTP request execution chain. Each element can - * either be a decorator around another element that implements a cross cutting aspect or - * a self-contained executor capable of producing a response for the given request. + * Abstract request execution handler in a classic client side request execution chain. + * Handlers can either be a decorator around another element that implements a cross + * cutting aspect or a self-contained executor capable of producing a response + * for the given request. *

* Important: please note it is required for decorators that implement post execution aspects * or response post-processing of any sort to release resources associated with the response @@ -46,8 +49,18 @@ import org.apache.hc.core5.http.HttpException; * * @since 4.3 */ +@Contract(threading = ThreadingBehavior.STATELESS) public interface ExecChainHandler { + /** + * Executes the actual HTTP request. The handler can choose to return + * a response message or delegate request execution to the next element + * in the execution chain. + * + * @param request the actual request. + * @param scope the execution scope . + * @param chain the next element in the request execution chain. + */ ClassicHttpResponse execute( ClassicHttpRequest request, ExecChain.Scope scope, diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/ExecRuntime.java b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/ExecRuntime.java index bbefe28fb..734197a41 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/ExecRuntime.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/ExecRuntime.java @@ -50,37 +50,110 @@ import org.apache.hc.core5.util.TimeValue; @Internal public interface ExecRuntime { + /** + * Determines of the request execution has been aborted. + * + * @return {@code true} if the request execution has been acquired, + * {@code false} otherwise. + */ boolean isExecutionAborted(); - boolean isConnectionAcquired(); + /** + * Determines of a connection endpoint has been acquired. + * + * @return {@code true} if an endpoint has been acquired, {@code false} otherwise. + */ + boolean isEndpointAcquired(); - void acquireConnection( + /** + * Acquires a connection endpoint. Endpoints can leased from a pool + * or unconnected new endpoint can be created. + * + * @param route the connection route. + * @param state the expected connection state. May be {@code null} if connection + * can be state-less or its state is irrelevant. + * @param context the execution context. + */ + void acquireEndpoint( HttpRoute route, Object state, HttpClientContext context) throws IOException; - void releaseConnection(); + /** + * Releases the acquired endpoint potentially making it available for re-use. + */ + void releaseEndpoint(); - void discardConnection(); + /** + * Shuts down and discards the acquired endpoint. + */ + void discardEndpoint(); - boolean isConnected(); + /** + * Determines of there the endpoint is connected to the initial hop (connection + * target in case of a direct route or to the first proxy hop in case of a route + * via a proxy or multiple proxies). + * + * @return {@code true} if the endpoint is connected, {@code false} otherwise. + */ + boolean isEndpointConnected(); - void disconnect() throws IOException; + /** + * Disconnects the local endpoint from the initial hop in the connection route. + */ + void disconnectEndpoint() throws IOException; - void connect(HttpClientContext context) throws IOException; + /** + * Connect the local endpoint to the initial hop (connection target in case + * of a direct route or to the first proxy hop in case of a route via a proxy + * or multiple proxies). + * + * @param context the execution context. + */ + void connectEndpoint(HttpClientContext context) throws IOException; + /** + * Upgrades transport security of the active connection by using the TLS security protocol. + * + * @param context the execution context. + */ void upgradeTls(HttpClientContext context) throws IOException; + /** + * Executes HTTP request using the given context. + * + * @param request the request message. + * @param context the execution context. + */ ClassicHttpResponse execute( ClassicHttpRequest request, HttpClientContext context) throws IOException, HttpException; + /** + * Determines of the connection is considered re-usable. + * + * @return {@code true} if the connection is re-usable, {@code false} otherwise. + */ boolean isConnectionReusable(); - void markConnectionReusable(Object state, TimeValue duration); + /** + * Marks the connection as potentially re-usable for the given period of time + * and also marks it as stateful if the state representation is given. + * @param state the connection state representation or {@code null} if stateless. + * @param validityTime the period of time this connection is valid for. + */ + void markConnectionReusable(Object state, TimeValue validityTime); + /** + * Marks the connection as non re-usable. + */ void markConnectionNonReusable(); + /** + * Forks this runtime for parallel execution. + * + * @return another runtime with the same configuration. + */ ExecRuntime fork(CancellableDependency cancellableAware); } diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/HttpClient.java b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/HttpClient.java index a63818b4f..7dcda6565 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/HttpClient.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/HttpClient.java @@ -126,12 +126,12 @@ public interface HttpClient { *

* * @param request the request to execute - * @param HttpClientResponseHandler the response handler + * @param responseHandler the response handler * * @return the response object as generated by the response handler. * @throws IOException in case of a problem or the connection was aborted */ - T execute(ClassicHttpRequest request, HttpClientResponseHandler HttpClientResponseHandler) throws IOException; + T execute(ClassicHttpRequest request, HttpClientResponseHandler responseHandler) throws IOException; /** * Executes HTTP request using the given context and processes the @@ -145,14 +145,17 @@ public interface HttpClient { *

* * @param request the request to execute - * @param HttpClientResponseHandler the response handler * @param context the context to use for the execution, or * {@code null} to use the default context + * @param responseHandler the response handler * * @return the response object as generated by the response handler. * @throws IOException in case of a problem or the connection was aborted */ - T execute(ClassicHttpRequest request, HttpClientResponseHandler HttpClientResponseHandler, HttpContext context) throws IOException; + T execute( + ClassicHttpRequest request, + HttpContext context, + HttpClientResponseHandler responseHandler) throws IOException; /** * Executes HTTP request to the target using the default context and @@ -170,12 +173,15 @@ public interface HttpClient { * if they can still determine a route, for example * to a default target or by inspecting the request. * @param request the request to execute - * @param HttpClientResponseHandler the response handler + * @param responseHandler the response handler * * @return the response object as generated by the response handler. * @throws IOException in case of a problem or the connection was aborted */ - T execute(HttpHost target, ClassicHttpRequest request, HttpClientResponseHandler HttpClientResponseHandler) throws IOException; + T execute( + HttpHost target, + ClassicHttpRequest request, + HttpClientResponseHandler responseHandler) throws IOException; /** * Executes HTTP request to the target using the given context and @@ -193,9 +199,9 @@ public interface HttpClient { * if they can still determine a route, for example * to a default target or by inspecting the request. * @param request the request to execute - * @param HttpClientResponseHandler the response handler * @param context the context to use for the execution, or * {@code null} to use the default context + * @param responseHandler the response handler * * @return the response object as generated by the response handler. * @throws IOException in case of a problem or the connection was aborted @@ -203,7 +209,7 @@ public interface HttpClient { T execute( HttpHost target, ClassicHttpRequest request, - HttpClientResponseHandler HttpClientResponseHandler, - HttpContext context) throws IOException; + HttpContext context, + HttpClientResponseHandler responseHandler) throws IOException; } diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/ClassicHttpRequests.java b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/ClassicHttpRequests.java index fec640a69..0d25a64a2 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/ClassicHttpRequests.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/ClassicHttpRequests.java @@ -31,9 +31,9 @@ import java.net.URI; /** - * HTTP methods defined in RFC2616. + * Common HTTP methods using {@link HttpUriRequest} as a HTTP request message representation. * - * @since 5.0-beta2 + * @since 5.0 */ public enum ClassicHttpRequests { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpDelete.java b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpDelete.java index c4418b3f9..98a2e43b5 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpDelete.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpDelete.java @@ -30,17 +30,7 @@ package org.apache.hc.client5.http.classic.methods; import java.net.URI; /** - * HTTP DELETE method - *

- * The HTTP DELETE method is defined in section 9.7 of - * RFC2616: - *

- * The DELETE method requests that the origin server delete the resource - * identified by the Request-URI. [...] The client cannot - * be guaranteed that the operation has been carried out, even if the - * status code returned from the origin server indicates that the action - * has been completed successfully. - *
+ * HTTP DELETE method. * * @since 4.0 */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpGet.java b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpGet.java index e3e469349..8c30166c9 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpGet.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpGet.java @@ -31,17 +31,6 @@ import java.net.URI; /** * HTTP GET method. - *

- * The HTTP GET method is defined in section 9.3 of - * RFC2616: - *

- *
- * The GET method means retrieve whatever information (in the form of an - * entity) is identified by the Request-URI. If the Request-URI refers - * to a data-producing process, it is the produced data which shall be - * returned as the entity in the response and not the source text of the - * process, unless that text happens to be the output of the process. - *
* * @since 4.0 */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpHead.java b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpHead.java index 5fb140de3..c18835fd5 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpHead.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpHead.java @@ -31,20 +31,6 @@ import java.net.URI; /** * HTTP HEAD method. - *

- * The HTTP HEAD method is defined in section 9.4 of - * RFC2616: - *

- *
- * The HEAD method is identical to GET except that the server MUST NOT - * return a message-body in the response. The metainformation contained - * in the HTTP headers in response to a HEAD request SHOULD be identical - * to the information sent in response to a GET request. This method can - * be used for obtaining metainformation about the entity implied by the - * request without transferring the entity-body itself. This method is - * often used for testing hypertext links for validity, accessibility, - * and recent modification. - *
* * @since 4.0 */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpOptions.java b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpOptions.java index ca1241261..7a1e41b6b 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpOptions.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpOptions.java @@ -39,18 +39,6 @@ import org.apache.hc.core5.util.Args; /** * HTTP OPTIONS method. - *

- * The HTTP OPTIONS method is defined in section 9.2 of - * RFC2616: - *

- *
- * The OPTIONS method represents a request for information about the - * communication options available on the request/response chain - * identified by the Request-URI. This method allows the client to - * determine the options and/or requirements associated with a resource, - * or the capabilities of a server, without implying a resource action - * or initiating a resource retrieval. - *
* * @since 4.0 */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpPatch.java b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpPatch.java index 99c50c4f7..c1ee0fc2a 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpPatch.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpPatch.java @@ -31,20 +31,6 @@ import java.net.URI; /** * HTTP PATCH method. - *

- * The HTTP PATCH method is defined in RF5789: - *

- *
The PATCH - * method requests that a set of changes described in the request entity be - * applied to the resource identified by the Request- URI. Differs from the PUT - * method in the way the server processes the enclosed entity to modify the - * resource identified by the Request-URI. In a PUT request, the enclosed entity - * origin server, and the client is requesting that the stored version be - * replaced. With PATCH, however, the enclosed entity contains a set of - * instructions describing how a resource currently residing on the origin - * server should be modified to produce a new version. - *
* * @since 4.2 */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpPost.java b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpPost.java index fd102a34e..41c14531f 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpPost.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpPost.java @@ -31,24 +31,6 @@ import java.net.URI; /** * HTTP POST method. - *

- * The HTTP POST method is defined in section 9.5 of - * RFC2616: - *

- *
- * The POST method is used to request that the origin server accept the entity - * enclosed in the request as a new subordinate of the resource identified by - * the Request-URI in the Request-Line. POST is designed to allow a uniform - * method to cover the following functions: - *
    - *
  • Annotation of existing resources
    • - *
  • Posting a message to a bulletin board, newsgroup, mailing list, or - * similar group of articles
    • - *
  • Providing a block of data, such as the result of submitting a form, - * to a data-handling process
    • - *
  • Extending a database through an append operation
    • - *
- *
* * @since 4.0 */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpPut.java b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpPut.java index fabe2b22e..68e70b3ba 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpPut.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpPut.java @@ -31,16 +31,6 @@ import java.net.URI; /** * HTTP PUT method. - *

- * The HTTP PUT method is defined in section 9.6 of - * RFC2616: - *

- *
- * The PUT method requests that the enclosed entity be stored under the - * supplied Request-URI. If the Request-URI refers to an already - * existing resource, the enclosed entity SHOULD be considered as a - * modified version of the one residing on the origin server. - *
* * @since 4.0 */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpTrace.java b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpTrace.java index 8bd12931f..17092a129 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpTrace.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/HttpTrace.java @@ -31,19 +31,6 @@ import java.net.URI; /** * HTTP TRACE method. - *

- * The HTTP TRACE method is defined in section 9.6 of - * RFC2616: - *

- *
- * The TRACE method is used to invoke a remote, application-layer loop- - * back of the request message. The final recipient of the request - * SHOULD reflect the message received back to the client as the - * entity-body of a 200 (OK) response. The final recipient is either the - * origin server or the first proxy or gateway to receive a Max-Forwards - * value of zero (0) in the request (see section 14.31). A TRACE request - * MUST NOT include an entity. - *
* * @since 4.0 */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/RequestBuilder.java b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/RequestBuilder.java index 4264be15d..1c330ea12 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/RequestBuilder.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/RequestBuilder.java @@ -60,9 +60,10 @@ import org.apache.hc.core5.util.Args; *

* Please note that this class treats parameters differently depending on composition * of the request: if the request has a content entity explicitly set with - * {@link #setEntity(org.apache.hc.core5.http.HttpEntity)} or it is not an entity enclosing method - * (such as POST or PUT), parameters will be added to the query component of the request URI. - * Otherwise, parameters will be added as a URL encoded {@link UrlEncodedFormEntity entity}. + * {@link #setEntity(org.apache.hc.core5.http.HttpEntity)} or it is not an entity enclosing + * method (such as POST or PUT), parameters will be added to the query component + * of the request URI. Otherwise, parameters will be added as a URL encoded + * {@link UrlEncodedFormEntity entity}. *

* * @since 4.3 diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/package-info.java b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/package-info.java index e0c25d2d3..b110daed1 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/package-info.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/methods/package-info.java @@ -26,6 +26,6 @@ */ /** - * Standard HTTP method implementations. + * Common HTTP methods and message handlers for the classic I/O model. */ package org.apache.hc.client5.http.classic.methods; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/package-info.java b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/package-info.java index 53fc06904..c7207cd1b 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/package-info.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/package-info.java @@ -26,6 +26,6 @@ */ /** - * Client HTTP communication APIs. + * HTTP client APIs based on the classic (blocking) I/O model. */ package org.apache.hc.client5.http.classic; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/config/package-info.java b/httpclient5/src/main/java/org/apache/hc/client5/http/config/package-info.java index 32e6e19a2..4c6896f84 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/config/package-info.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/config/package-info.java @@ -26,6 +26,6 @@ */ /** - * Client configuration APIs. + * HTTP client configuration APIs. */ package org.apache.hc.client5.http.config; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/BasicCookieStore.java b/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/BasicCookieStore.java index 6e1cea44c..a3d6e2b96 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/BasicCookieStore.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/BasicCookieStore.java @@ -43,7 +43,6 @@ import org.apache.hc.core5.annotation.ThreadingBehavior; /** * Default implementation of {@link CookieStore} * - * * @since 4.0 */ @Contract(threading = ThreadingBehavior.SAFE) diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/Cookie.java b/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/Cookie.java index 677af5c88..4a8ac10c7 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/Cookie.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/Cookie.java @@ -34,9 +34,6 @@ import java.util.Date; * (also referred to as "magic-cookie") that the HTTP agent and the target * server can exchange to maintain a session. In its simples form an HTTP * cookie is merely a name / value pair. - *

- * Please do not use attributes marked as @Obsolete. They have been rendered - * obsolete by RFC 6265. * * @since 4.0 */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/CookieAttributeHandler.java b/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/CookieAttributeHandler.java index 676d71c3f..b19e8472d 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/CookieAttributeHandler.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/CookieAttributeHandler.java @@ -26,18 +26,22 @@ */ package org.apache.hc.client5.http.cookie; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; + /** * This interface represents a cookie attribute handler responsible * for parsing, validating, and matching a specific cookie attribute, * such as path, domain, port, etc. - * + *

* Different cookie specifications can provide a specific * implementation for this class based on their cookie handling * rules. - * + *

* * @since 4.0 */ +@Contract(threading = ThreadingBehavior.STATELESS) public interface CookieAttributeHandler { /** diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/CookieIdentityComparator.java b/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/CookieIdentityComparator.java index fb17ec14e..098788a15 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/CookieIdentityComparator.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/CookieIdentityComparator.java @@ -36,12 +36,13 @@ import org.apache.hc.core5.annotation.ThreadingBehavior; /** * This cookie comparator can be used to compare identity of cookies. *

- * Cookies are considered identical if their names are equal and - * their domain attributes match ignoring case. + * Cookies are considered identical if their names are equal and + * their domain attributes match ignoring case. + *

* * @since 4.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class CookieIdentityComparator implements Serializable, Comparator { private static final long serialVersionUID = 4466565437490631532L; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/CookiePathComparator.java b/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/CookiePathComparator.java index 6401ba356..e3749c46e 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/CookiePathComparator.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/CookiePathComparator.java @@ -35,7 +35,7 @@ import org.apache.hc.core5.annotation.ThreadingBehavior; /** * This cookie comparator ensures that multiple cookies satisfying - * a common criteria are ordered in the {@code Cookie} header such + * a common criteria are ordered in the {@link Cookie} header such * that those with more specific Path attributes precede those with * less specific. * @@ -48,7 +48,7 @@ import org.apache.hc.core5.annotation.ThreadingBehavior; * * @since 4.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class CookiePathComparator implements Serializable, Comparator { public static final CookiePathComparator INSTANCE = new CookiePathComparator(); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/CookiePriorityComparator.java b/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/CookiePriorityComparator.java index f0ff1ac82..384af70a2 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/CookiePriorityComparator.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/CookiePriorityComparator.java @@ -40,7 +40,7 @@ import org.apache.hc.core5.annotation.ThreadingBehavior; * * @since 4.4 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class CookiePriorityComparator implements Comparator { public static final CookiePriorityComparator INSTANCE = new CookiePriorityComparator(); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/CookieSpec.java b/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/CookieSpec.java index 6899ca197..ddf68bcbe 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/CookieSpec.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/CookieSpec.java @@ -40,9 +40,6 @@ import org.apache.hc.core5.http.Header; *
  • formatting of "Cookie" header * * for a given host, port and path of origin - *

    - * Please do not use methods marked as @Obsolete. They have been rendered - * obsolete by RFC 6265. * * @since 4.0 */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/CookieSpecProvider.java b/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/CookieSpecProvider.java index f6ddc47a5..55a3f5807 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/CookieSpecProvider.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/CookieSpecProvider.java @@ -27,6 +27,8 @@ package org.apache.hc.client5.http.cookie; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.protocol.HttpContext; /** @@ -34,6 +36,7 @@ import org.apache.hc.core5.http.protocol.HttpContext; * * @since 4.3 */ +@Contract(threading = ThreadingBehavior.STATELESS) public interface CookieSpecProvider { /** diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/MalformedCookieException.java b/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/MalformedCookieException.java index a24768abf..ddca9329b 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/MalformedCookieException.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/MalformedCookieException.java @@ -33,7 +33,6 @@ import org.apache.hc.core5.http.ProtocolException; * Signals that a cookie is in some way invalid or illegal in a given * context * - * * @since 4.0 */ public class MalformedCookieException extends ProtocolException { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/SetCookie.java b/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/SetCookie.java index 72da3766d..620006aae 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/SetCookie.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/cookie/SetCookie.java @@ -32,9 +32,6 @@ import java.util.Date; /** * This interface represents a {@code Set-Cookie} response header sent by the * origin server to the HTTP agent in order to maintain a conversational state. - *

    - * Please do not use methods marked as @Obsolete. They have been rendered - * obsolete by RFC 6265 * * @since 4.0 */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/entity/DeflateInputStreamFactory.java b/httpclient5/src/main/java/org/apache/hc/client5/http/entity/DeflateInputStreamFactory.java index 3fa666ae3..8ddefe8c9 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/entity/DeflateInputStreamFactory.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/entity/DeflateInputStreamFactory.java @@ -38,7 +38,7 @@ import org.apache.hc.core5.annotation.ThreadingBehavior; * * @since 5.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class DeflateInputStreamFactory implements InputStreamFactory { /** diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/entity/GZIPInputStreamFactory.java b/httpclient5/src/main/java/org/apache/hc/client5/http/entity/GZIPInputStreamFactory.java index 37bf6f748..6f599ce43 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/entity/GZIPInputStreamFactory.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/entity/GZIPInputStreamFactory.java @@ -39,7 +39,7 @@ import org.apache.hc.core5.annotation.ThreadingBehavior; * * @since 5.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class GZIPInputStreamFactory implements InputStreamFactory { /** diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/AuthSupport.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/AuthSupport.java index 67d3b3536..823e600d3 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/AuthSupport.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/AuthSupport.java @@ -32,14 +32,18 @@ import org.apache.hc.client5.http.auth.AuthScope; import org.apache.hc.client5.http.auth.CredentialsStore; import org.apache.hc.client5.http.auth.UsernamePasswordCredentials; import org.apache.hc.client5.http.auth.AuthSchemes; +import org.apache.hc.core5.annotation.Internal; import org.apache.hc.core5.http.HttpHost; import org.apache.hc.core5.http.HttpRequest; import org.apache.hc.core5.net.URIAuthority; import org.apache.hc.core5.util.Args; /** + * Authentication support methods. + * * @since 5.0 */ +@Internal public class AuthSupport { public static void extractFromAuthority( diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/ChainElements.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/ChainElements.java index 99d252378..9dd95cdad 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/ChainElements.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/ChainElements.java @@ -27,6 +27,11 @@ package org.apache.hc.client5.http.impl; +/** + * Supported elements of request execution pipeline. + * + * @since 5.0 + */ public enum ChainElements { REDIRECT, BACK_OFF, RETRY_SERVICE_UNAVAILABLE, RETRY_IO_ERROR, CACHING, PROTOCOL, CONNECT, MAIN_TRANSPORT diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/ConnPoolSupport.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/ConnPoolSupport.java index a7d0da8ee..6cc87e47a 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/ConnPoolSupport.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/ConnPoolSupport.java @@ -32,6 +32,11 @@ import org.apache.hc.core5.pool.ConnPoolControl; import org.apache.hc.core5.pool.PoolStats; import org.apache.hc.core5.util.Identifiable; +/** + * Connection pooling support methods. + * + * @since 5.0 + */ @Internal public final class ConnPoolSupport { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/CookieSpecRegistries.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/CookieSpecSupport.java similarity index 94% rename from httpclient5/src/main/java/org/apache/hc/client5/http/impl/CookieSpecRegistries.java rename to httpclient5/src/main/java/org/apache/hc/client5/http/impl/CookieSpecSupport.java index 5d1063e79..0bfe92c60 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/CookieSpecRegistries.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/CookieSpecSupport.java @@ -33,13 +33,17 @@ import org.apache.hc.client5.http.impl.cookie.IgnoreSpecProvider; import org.apache.hc.client5.http.impl.cookie.RFC6265CookieSpecProvider; import org.apache.hc.client5.http.psl.PublicSuffixMatcher; import org.apache.hc.client5.http.psl.PublicSuffixMatcherLoader; +import org.apache.hc.core5.annotation.Internal; import org.apache.hc.core5.http.config.Lookup; import org.apache.hc.core5.http.config.RegistryBuilder; /** - * @since 4.5 + * Cookie support methods. + * + * @since 5.0 */ -public final class CookieSpecRegistries { +@Internal +public final class CookieSpecSupport { /** * Creates a builder containing the default registry entries, using the provided public suffix matcher. @@ -74,6 +78,6 @@ public final class CookieSpecRegistries { return createDefaultBuilder(publicSuffixMatcher).build(); } - private CookieSpecRegistries() {} + private CookieSpecSupport() {} } diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/DefaultAuthenticationStrategy.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/DefaultAuthenticationStrategy.java index 73ad51c23..a5578a30f 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/DefaultAuthenticationStrategy.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/DefaultAuthenticationStrategy.java @@ -39,8 +39,8 @@ import org.apache.hc.client5.http.AuthenticationStrategy; import org.apache.hc.client5.http.auth.AuthChallenge; import org.apache.hc.client5.http.auth.AuthScheme; import org.apache.hc.client5.http.auth.AuthSchemeProvider; -import org.apache.hc.client5.http.auth.ChallengeType; import org.apache.hc.client5.http.auth.AuthSchemes; +import org.apache.hc.client5.http.auth.ChallengeType; import org.apache.hc.client5.http.config.RequestConfig; import org.apache.hc.client5.http.protocol.HttpClientContext; import org.apache.hc.core5.annotation.Contract; @@ -56,7 +56,7 @@ import org.slf4j.LoggerFactory; * * @since 5.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class DefaultAuthenticationStrategy implements AuthenticationStrategy { private final Logger log = LoggerFactory.getLogger(getClass()); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/DefaultConnectionKeepAliveStrategy.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/DefaultConnectionKeepAliveStrategy.java index 046cc42bb..3c4c225b0 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/DefaultConnectionKeepAliveStrategy.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/DefaultConnectionKeepAliveStrategy.java @@ -42,13 +42,14 @@ import org.apache.hc.core5.util.TimeValue; /** * Default implementation of a strategy deciding duration * that a connection can remain idle. - * + *

    * The default implementation looks solely at the 'Keep-Alive' * header's timeout token. + *

    * * @since 4.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class DefaultConnectionKeepAliveStrategy implements ConnectionKeepAliveStrategy { public static final DefaultConnectionKeepAliveStrategy INSTANCE = new DefaultConnectionKeepAliveStrategy(); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/DefaultHttpRequestRetryHandler.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/DefaultHttpRequestRetryHandler.java index 06d522f18..1c8bd5e60 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/DefaultHttpRequestRetryHandler.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/DefaultHttpRequestRetryHandler.java @@ -54,7 +54,7 @@ import org.apache.hc.core5.util.Args; * * @since 4.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class DefaultHttpRequestRetryHandler implements HttpRequestRetryHandler { public static final DefaultHttpRequestRetryHandler INSTANCE = new DefaultHttpRequestRetryHandler(); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/DefaultSchemePortResolver.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/DefaultSchemePortResolver.java index 9f74e1f47..144ae5f7f 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/DefaultSchemePortResolver.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/DefaultSchemePortResolver.java @@ -38,7 +38,7 @@ import org.apache.hc.core5.util.Args; * * @since 4.3 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class DefaultSchemePortResolver implements SchemePortResolver { public static final DefaultSchemePortResolver INSTANCE = new DefaultSchemePortResolver(); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/DefaultServiceUnavailableRetryStrategy.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/DefaultServiceUnavailableRetryStrategy.java index b5b0cc238..6c05c6093 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/DefaultServiceUnavailableRetryStrategy.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/DefaultServiceUnavailableRetryStrategy.java @@ -47,7 +47,7 @@ import org.apache.hc.core5.util.Args; * * @since 4.2 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class DefaultServiceUnavailableRetryStrategy implements ServiceUnavailableRetryStrategy { /** diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/DefaultUserTokenHandler.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/DefaultUserTokenHandler.java index 481d91582..87809b81c 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/DefaultUserTokenHandler.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/DefaultUserTokenHandler.java @@ -50,10 +50,11 @@ import org.apache.hc.core5.http.protocol.HttpContext; * based authentication schemes such as NTLM or that of the SSL session * with the client authentication turned on. If both are unavailable, * {@code null} token will be returned. + *

    * * @since 4.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class DefaultUserTokenHandler implements UserTokenHandler { public static final DefaultUserTokenHandler INSTANCE = new DefaultUserTokenHandler(); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/ExecSupport.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/ExecSupport.java index 235d61c8c..c9e42baa4 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/ExecSupport.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/ExecSupport.java @@ -28,6 +28,14 @@ package org.apache.hc.client5.http.impl; import java.util.concurrent.atomic.AtomicLong; +import org.apache.hc.core5.annotation.Internal; + +/** + * Request execution support methods. + * + * @since 5.0 + */ +@Internal public final class ExecSupport { private static final AtomicLong COUNT = new AtomicLong(0); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/IdleConnectionEvictor.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/IdleConnectionEvictor.java index d9b5364ae..56da800f7 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/IdleConnectionEvictor.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/IdleConnectionEvictor.java @@ -30,6 +30,8 @@ package org.apache.hc.client5.http.impl; import java.util.concurrent.ThreadFactory; import java.util.concurrent.TimeUnit; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.concurrent.DefaultThreadFactory; import org.apache.hc.core5.pool.ConnPoolControl; import org.apache.hc.core5.util.Args; @@ -41,6 +43,7 @@ import org.apache.hc.core5.util.TimeValue; * * @since 4.4 */ +@Contract(threading = ThreadingBehavior.SAFE_CONDITIONAL) public final class IdleConnectionEvictor { private final ThreadFactory threadFactory; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/InMemoryDnsResolver.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/InMemoryDnsResolver.java index f915b8c8b..2adf51b01 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/InMemoryDnsResolver.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/InMemoryDnsResolver.java @@ -33,6 +33,8 @@ import java.util.Map; import java.util.concurrent.ConcurrentHashMap; import org.apache.hc.client5.http.DnsResolver; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.util.Args; import org.slf4j.Logger; import org.slf4j.LoggerFactory; @@ -42,6 +44,7 @@ import org.slf4j.LoggerFactory; * * @since 4.2 */ +@Contract(threading = ThreadingBehavior.STATELESS) public class InMemoryDnsResolver implements DnsResolver { /** Logger associated to this class. */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/MessageCopier.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/MessageCopier.java index cd152ea40..39220e7db 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/MessageCopier.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/MessageCopier.java @@ -30,7 +30,7 @@ package org.apache.hc.client5.http.impl; import org.apache.hc.core5.http.HttpMessage; /** - * Abstract HTTP message cloner. + * Abstract HTTP message copier. * * @since 5.0 */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/NoopUserTokenHandler.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/NoopUserTokenHandler.java index 332796e85..300b20f41 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/NoopUserTokenHandler.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/NoopUserTokenHandler.java @@ -37,7 +37,7 @@ import org.apache.hc.core5.http.protocol.HttpContext; * * @since 4.3 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class NoopUserTokenHandler implements UserTokenHandler { public static final NoopUserTokenHandler INSTANCE = new NoopUserTokenHandler(); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/Operations.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/Operations.java index 94e5df96c..da15e56e5 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/Operations.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/Operations.java @@ -34,6 +34,11 @@ import java.util.concurrent.TimeoutException; import org.apache.hc.core5.concurrent.Cancellable; +/** + * Common cancellable operations. + * + * @since 5.0 + */ public final class Operations { private final static Cancellable NOOP_CANCELLABLE = new Cancellable() { @@ -45,6 +50,12 @@ public final class Operations { }; + /** + * This class represents a {@link Future} in the completed state with a fixed result. + * The outcome of the future cannot be altered and it cannot be cancelled. + * + * @param operation result representation. + */ public static class CompletedFuture implements Future { private final T result; @@ -79,10 +90,24 @@ public final class Operations { } + /** + * Creates a {@link Cancellable} operation handle for an ongoing process + * or operation that cannot be cancelled. Attempts to cancel the operation + * with this handle will have no effect. + * + * @return the no-op cancellable operation handle. + */ public static Cancellable nonCancellable() { return NOOP_CANCELLABLE; } + /** + * Creates a {@link Cancellable} operation handle for an ongoing process + * or operation represented by a {@link Future}. + * + * @param future the result future + * @return the cancellable operation handle. + */ public static Cancellable cancellable(final Future future) { if (future == null) { return NOOP_CANCELLABLE; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/RequestCopier.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/RequestCopier.java index 9572d5c34..bb80d9fbd 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/RequestCopier.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/RequestCopier.java @@ -32,6 +32,11 @@ import org.apache.hc.core5.http.Header; import org.apache.hc.core5.http.HttpRequest; import org.apache.hc.core5.http.message.BasicHttpRequest; +/** + * {@link HttpRequest} copier. + * + * @since 5.0 + */ public final class RequestCopier implements MessageCopier { public static final RequestCopier INSTANCE = new RequestCopier(); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/AsyncConnectExec.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/AsyncConnectExec.java index acf31914e..5aad68da6 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/AsyncConnectExec.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/AsyncConnectExec.java @@ -46,6 +46,7 @@ import org.apache.hc.client5.http.impl.routing.BasicRouteDirector; import org.apache.hc.client5.http.protocol.HttpClientContext; import org.apache.hc.client5.http.routing.HttpRouteDirector; import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.Internal; import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.concurrent.CancellableDependency; import org.apache.hc.core5.concurrent.FutureCallback; @@ -67,13 +68,14 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** - * Request executor in the HTTP request execution chain + * Request execution handler in the asynchronous request execution chain * that is responsible for establishing connection to the target - * origin server as specified by the current route. + * origin server as specified by the current connection route. * * @since 5.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE_CONDITIONAL) +@Contract(threading = ThreadingBehavior.STATELESS) +@Internal public final class AsyncConnectExec implements AsyncExecChainHandler { private final Logger log = LoggerFactory.getLogger(getClass()); @@ -131,7 +133,7 @@ public final class AsyncConnectExec implements AsyncExecChainHandler { if (log.isDebugEnabled()) { log.debug(exchangeId + ": connection acquired"); } - if (execRuntime.isConnected()) { + if (execRuntime.isEndpointConnected()) { try { chain.proceed(request, entityProducer, scope, asyncExecCallback); } catch (final HttpException | IOException ex) { @@ -144,12 +146,12 @@ public final class AsyncConnectExec implements AsyncExecChainHandler { }; - if (!execRuntime.isConnectionAcquired()) { + if (!execRuntime.isEndpointAcquired()) { final Object userToken = clientContext.getUserToken(); if (log.isDebugEnabled()) { log.debug(exchangeId + ": acquiring connection with route " + route); } - cancellableDependency.setDependency(execRuntime.acquireConnection( + cancellableDependency.setDependency(execRuntime.acquireEndpoint( route, userToken, clientContext, new FutureCallback() { @Override @@ -193,7 +195,7 @@ public final class AsyncConnectExec implements AsyncExecChainHandler { step = routeDirector.nextStep(route, fact); switch (step) { case HttpRouteDirector.CONNECT_TARGET: - operation.setDependency(execRuntime.connect(clientContext, new FutureCallback() { + operation.setDependency(execRuntime.connectEndpoint(clientContext, new FutureCallback() { @Override public void completed(final AsyncExecRuntime execRuntime) { @@ -216,7 +218,7 @@ public final class AsyncConnectExec implements AsyncExecChainHandler { return; case HttpRouteDirector.CONNECT_PROXY: - operation.setDependency(execRuntime.connect(clientContext, new FutureCallback() { + operation.setDependency(execRuntime.connectEndpoint(clientContext, new FutureCallback() { @Override public void completed(final AsyncExecRuntime execRuntime) { @@ -352,7 +354,7 @@ public final class AsyncConnectExec implements AsyncExecChainHandler { @Override public void completed() { - if (!execRuntime.isConnected()) { + if (!execRuntime.isEndpointConnected()) { state.tracker.reset(); } if (state.challenged) { @@ -388,7 +390,7 @@ public final class AsyncConnectExec implements AsyncExecChainHandler { if (config.isAuthenticationEnabled()) { final boolean proxyAuthRequested = authenticator.isChallenged(proxy, ChallengeType.PROXY, response, proxyAuthExchange, context); if (proxyAuthRequested) { - return authenticator.prepareAuthResponse(proxy, ChallengeType.PROXY, response, + return authenticator.updateAuthState(proxy, ChallengeType.PROXY, response, proxyAuthStrategy, proxyAuthExchange, context); } } diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/AsyncProtocolExec.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/AsyncProtocolExec.java index f74e81719..fac2d000d 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/AsyncProtocolExec.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/AsyncProtocolExec.java @@ -49,6 +49,7 @@ import org.apache.hc.client5.http.impl.auth.HttpAuthenticator; import org.apache.hc.client5.http.protocol.HttpClientContext; import org.apache.hc.client5.http.utils.URIUtils; import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.Internal; import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.EntityDetails; import org.apache.hc.core5.http.Header; @@ -68,17 +69,19 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** - * Request executor in the request execution chain that is responsible - * for implementation of HTTP specification requirements. + * Request execution handler in the asynchronous request execution chain + * that is responsible for implementation of HTTP specification requirements. *

    * Further responsibilities such as communication with the opposite * endpoint is delegated to the next executor in the request execution * chain. + *

    * * @since 5.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) -class AsyncProtocolExec implements AsyncExecChainHandler { +@Contract(threading = ThreadingBehavior.STATELESS) +@Internal +public final class AsyncProtocolExec implements AsyncExecChainHandler { private final Logger log = LoggerFactory.getLogger(getClass()); @@ -191,7 +194,7 @@ class AsyncProtocolExec implements AsyncExecChainHandler { @Override public void completed() { - if (!execRuntime.isConnected()) { + if (!execRuntime.isEndpointConnected()) { if (proxyAuthExchange.getState() == AuthExchange.State.SUCCESS && proxyAuthExchange.isConnectionBased()) { log.debug("Resetting proxy auth state"); @@ -267,11 +270,11 @@ class AsyncProtocolExec implements AsyncExecChainHandler { proxy, ChallengeType.PROXY, response, proxyAuthExchange, context); if (targetAuthRequested) { - return authenticator.prepareAuthResponse(target, ChallengeType.TARGET, response, + return authenticator.updateAuthState(target, ChallengeType.TARGET, response, targetAuthStrategy, targetAuthExchange, context); } if (proxyAuthRequested) { - return authenticator.prepareAuthResponse(proxy, ChallengeType.PROXY, response, + return authenticator.updateAuthState(proxy, ChallengeType.PROXY, response, proxyAuthStrategy, proxyAuthExchange, context); } } diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/AsyncRedirectExec.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/AsyncRedirectExec.java index 1904efca0..540c03f26 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/AsyncRedirectExec.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/AsyncRedirectExec.java @@ -43,6 +43,9 @@ import org.apache.hc.client5.http.protocol.RedirectLocations; import org.apache.hc.client5.http.protocol.RedirectStrategy; import org.apache.hc.client5.http.routing.HttpRoutePlanner; import org.apache.hc.client5.http.utils.URIUtils; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.Internal; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.EntityDetails; import org.apache.hc.core5.http.HttpException; import org.apache.hc.core5.http.HttpHost; @@ -57,7 +60,20 @@ import org.apache.hc.core5.util.LangUtils; import org.slf4j.Logger; import org.slf4j.LoggerFactory; -class AsyncRedirectExec implements AsyncExecChainHandler { +/** + * Request execution handler in the asynchronous request execution chain + * responsbile for handling of request redirects. + *

    + * Further responsibilities such as communication with the opposite + * endpoint is delegated to the next executor in the request execution + * chain. + *

    + * + * @since 5.0 + */ +@Contract(threading = ThreadingBehavior.STATELESS) +@Internal +public final class AsyncRedirectExec implements AsyncExecChainHandler { private final Logger log = LoggerFactory.getLogger(getClass()); @@ -183,7 +199,7 @@ class AsyncRedirectExec implements AsyncExecChainHandler { } else { try { if (state.reroute) { - scope.execRuntime.releaseConnection(); + scope.execRuntime.releaseEndpoint(); } internalExecute(state, chain, asyncExecCallback); } catch (final IOException | HttpException ex) { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/AsyncRetryExec.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/AsyncRetryExec.java index 1118ed3ab..a484b110c 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/AsyncRetryExec.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/AsyncRetryExec.java @@ -35,6 +35,9 @@ import org.apache.hc.client5.http.async.AsyncExecChain; import org.apache.hc.client5.http.async.AsyncExecChainHandler; import org.apache.hc.client5.http.impl.RequestCopier; import org.apache.hc.client5.http.protocol.HttpClientContext; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.Internal; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.EntityDetails; import org.apache.hc.core5.http.HttpException; import org.apache.hc.core5.http.HttpRequest; @@ -45,7 +48,21 @@ import org.apache.hc.core5.util.Args; import org.slf4j.Logger; import org.slf4j.LoggerFactory; -class AsyncRetryExec implements AsyncExecChainHandler { +/** + * Request execution handler in the asynchronous request execution chain + * responsbile for making a decision whether a request failed due to + * an I/O error should be re-executed. + *

    + * Further responsibilities such as communication with the opposite + * endpoint is delegated to the next executor in the request execution + * chain. + *

    + * + * @since 5.0 + */ +@Contract(threading = ThreadingBehavior.STATELESS) +@Internal +public final class AsyncRetryExec implements AsyncExecChainHandler { private final Logger log = LoggerFactory.getLogger(getClass()); @@ -100,7 +117,7 @@ class AsyncRetryExec implements AsyncExecChainHandler { log.info("Retrying request to " + route); } try { - scope.execRuntime.discardConnection(); + scope.execRuntime.discardEndpoint(); if (entityProducer != null) { entityProducer.releaseResources(); } diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/CloseableHttpAsyncClient.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/CloseableHttpAsyncClient.java index 65dbe51b0..46bbbb83b 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/CloseableHttpAsyncClient.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/CloseableHttpAsyncClient.java @@ -54,9 +54,9 @@ import org.apache.hc.core5.util.TimeValue; /** * Base implementation of {@link HttpAsyncClient} that also implements {@link Closeable}. * - * @since 4.0 + * @since 5.0 */ -@Contract(threading = ThreadingBehavior.SAFE) +@Contract(threading = ThreadingBehavior.STATELESS) public abstract class CloseableHttpAsyncClient implements HttpAsyncClient, Closeable { public abstract void start(); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/Http2AsyncClientBuilder.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/Http2AsyncClientBuilder.java index e1f1cbe34..6e9e17b9a 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/Http2AsyncClientBuilder.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/Http2AsyncClientBuilder.java @@ -53,7 +53,7 @@ import org.apache.hc.client5.http.cookie.BasicCookieStore; import org.apache.hc.client5.http.cookie.CookieSpecProvider; import org.apache.hc.client5.http.cookie.CookieStore; import org.apache.hc.client5.http.impl.ChainElements; -import org.apache.hc.client5.http.impl.CookieSpecRegistries; +import org.apache.hc.client5.http.impl.CookieSpecSupport; import org.apache.hc.client5.http.impl.DefaultAuthenticationStrategy; import org.apache.hc.client5.http.impl.DefaultHttpRequestRetryHandler; import org.apache.hc.client5.http.impl.DefaultRedirectStrategy; @@ -116,10 +116,16 @@ import org.apache.hc.core5.util.TimeValue; import org.apache.hc.core5.util.VersionInfo; /** - * Builder for HTTP/2 {@link CloseableHttpAsyncClient} instances. + * Builder for HTTP/2 only {@link CloseableHttpAsyncClient} instances. + *

    + * Concurrent message exchanges with the same connection route executed + * with these {@link CloseableHttpAsyncClient} instances will get + * automatically multiplexed over a single physical HTTP/2 connection. + *

    *

    * When a particular component is not explicitly set this class will * use its default implementation. + *

    * * @since 5.0 */ @@ -769,7 +775,7 @@ public class Http2AsyncClientBuilder { } Lookup cookieSpecRegistryCopy = this.cookieSpecRegistry; if (cookieSpecRegistryCopy == null) { - cookieSpecRegistryCopy = CookieSpecRegistries.createDefault(); + cookieSpecRegistryCopy = CookieSpecSupport.createDefault(); } CookieStore cookieStoreCopy = this.cookieStore; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/Http2AsyncClientEventHandlerFactory.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/Http2AsyncClientEventHandlerFactory.java index 44c9dcdb5..15b50698e 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/Http2AsyncClientEventHandlerFactory.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/Http2AsyncClientEventHandlerFactory.java @@ -31,8 +31,6 @@ import java.io.IOException; import java.util.List; import org.apache.hc.client5.http.impl.ConnPoolSupport; -import org.apache.hc.core5.annotation.Contract; -import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.Header; import org.apache.hc.core5.http.HttpConnection; import org.apache.hc.core5.http.config.CharCodingConfig; @@ -52,10 +50,6 @@ import org.apache.hc.core5.util.Args; import org.slf4j.Logger; import org.slf4j.LoggerFactory; -/** - * @since 5.0 - */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) class Http2AsyncClientEventHandlerFactory implements IOEventHandlerFactory { private final Logger wireLog = LoggerFactory.getLogger("org.apache.hc.client5.http.wire"); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/Http2AsyncMainClientExec.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/Http2AsyncMainClientExec.java index 1d982e9fe..fcf180bd1 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/Http2AsyncMainClientExec.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/Http2AsyncMainClientExec.java @@ -37,6 +37,9 @@ import org.apache.hc.client5.http.async.AsyncExecChain; import org.apache.hc.client5.http.async.AsyncExecChainHandler; import org.apache.hc.client5.http.async.AsyncExecRuntime; import org.apache.hc.client5.http.protocol.HttpClientContext; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.Internal; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.concurrent.CancellableDependency; import org.apache.hc.core5.http.EntityDetails; import org.apache.hc.core5.http.Header; @@ -54,7 +57,16 @@ import org.apache.hc.core5.http.protocol.HttpContext; import org.slf4j.Logger; import org.slf4j.LoggerFactory; -class Http2AsyncMainClientExec implements AsyncExecChainHandler { +/** + * Usually the last HTTP/2 request execution handler in the asynchronous + * request execution chain that is responsible for execution of + * request / response exchanges with the opposite endpoint. + * + * @since 5.0 + */ +@Contract(threading = ThreadingBehavior.STATELESS) +@Internal +public class Http2AsyncMainClientExec implements AsyncExecChainHandler { private final Logger log = LoggerFactory.getLogger(getClass()); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/HttpAsyncClientBuilder.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/HttpAsyncClientBuilder.java index 7cbb91859..c7d1c6ed6 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/HttpAsyncClientBuilder.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/HttpAsyncClientBuilder.java @@ -54,7 +54,7 @@ import org.apache.hc.client5.http.cookie.BasicCookieStore; import org.apache.hc.client5.http.cookie.CookieSpecProvider; import org.apache.hc.client5.http.cookie.CookieStore; import org.apache.hc.client5.http.impl.ChainElements; -import org.apache.hc.client5.http.impl.CookieSpecRegistries; +import org.apache.hc.client5.http.impl.CookieSpecSupport; import org.apache.hc.client5.http.impl.DefaultAuthenticationStrategy; import org.apache.hc.client5.http.impl.DefaultConnectionKeepAliveStrategy; import org.apache.hc.client5.http.impl.DefaultHttpRequestRetryHandler; @@ -126,7 +126,14 @@ import org.apache.hc.core5.util.TimeValue; import org.apache.hc.core5.util.VersionInfo; /** - * Builder for {@link CloseableHttpAsyncClient} instances. + * Builder for {@link CloseableHttpAsyncClient} instances that can negotiate + * the most optimal HTTP protocol version during the {@code TLS} handshake + * with {@code ALPN} extension if supported by the Java runtime. + *

    + * Concurrent message exchanges executed by {@link CloseableHttpAsyncClient} + * instances created with this builder will get automatically assigned to + * separate connections leased from the connection pool. + *

    *

    * When a particular component is not explicitly set this class will * use its default implementation. System properties will be taken @@ -975,7 +982,7 @@ public class HttpAsyncClientBuilder { } Lookup cookieSpecRegistryCopy = this.cookieSpecRegistry; if (cookieSpecRegistryCopy == null) { - cookieSpecRegistryCopy = CookieSpecRegistries.createDefault(); + cookieSpecRegistryCopy = CookieSpecSupport.createDefault(); } CookieStore cookieStoreCopy = this.cookieStore; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/HttpAsyncClientEventHandlerFactory.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/HttpAsyncClientEventHandlerFactory.java index 67f50863f..51028ca46 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/HttpAsyncClientEventHandlerFactory.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/HttpAsyncClientEventHandlerFactory.java @@ -32,8 +32,6 @@ import java.util.Iterator; import java.util.List; import org.apache.hc.client5.http.impl.ConnPoolSupport; -import org.apache.hc.core5.annotation.Contract; -import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.ConnectionReuseStrategy; import org.apache.hc.core5.http.Header; import org.apache.hc.core5.http.HttpConnection; @@ -67,10 +65,6 @@ import org.apache.hc.core5.util.Args; import org.slf4j.Logger; import org.slf4j.LoggerFactory; -/** - * @since 5.0 - */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) class HttpAsyncClientEventHandlerFactory implements IOEventHandlerFactory { private final Logger streamLog = LoggerFactory.getLogger(InternalHttpAsyncClient.class); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/HttpAsyncClients.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/HttpAsyncClients.java index 025f82944..9d3aee84d 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/HttpAsyncClients.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/HttpAsyncClients.java @@ -61,7 +61,7 @@ import org.apache.hc.core5.util.VersionInfo; * * @since 5.0 */ -public class HttpAsyncClients { +public final class HttpAsyncClients { private HttpAsyncClients() { super(); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/HttpAsyncMainClientExec.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/HttpAsyncMainClientExec.java index ff9556b28..fbc4b89e9 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/HttpAsyncMainClientExec.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/HttpAsyncMainClientExec.java @@ -41,6 +41,9 @@ import org.apache.hc.client5.http.async.AsyncExecChain; import org.apache.hc.client5.http.async.AsyncExecChainHandler; import org.apache.hc.client5.http.async.AsyncExecRuntime; import org.apache.hc.client5.http.protocol.HttpClientContext; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.Internal; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.concurrent.CancellableDependency; import org.apache.hc.core5.http.EntityDetails; import org.apache.hc.core5.http.Header; @@ -60,6 +63,15 @@ import org.apache.hc.core5.util.TimeValue; import org.slf4j.Logger; import org.slf4j.LoggerFactory; +/** + * Usually the last HTTP/1.1 request execution handler in the asynchronous + * request execution chain that is responsible for execution of + * request / response exchanges with the opposite endpoint. + * + * @since 5.0 + */ +@Contract(threading = ThreadingBehavior.STATELESS) +@Internal class HttpAsyncMainClientExec implements AsyncExecChainHandler { private final Logger log = LoggerFactory.getLogger(getClass()); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/InternalAbstractHttpAsyncClient.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/InternalAbstractHttpAsyncClient.java index 3fdbe55e3..d99d3cbde 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/InternalAbstractHttpAsyncClient.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/InternalAbstractHttpAsyncClient.java @@ -269,7 +269,7 @@ abstract class InternalAbstractHttpAsyncClient extends AbstractHttpAsyncClientBa log.debug(exchangeId + ": message exchange successfully completed"); } try { - execRuntime.releaseConnection(); + execRuntime.releaseEndpoint(); } finally { responseConsumer.releaseResources(); requestProducer.releaseResources(); @@ -282,7 +282,7 @@ abstract class InternalAbstractHttpAsyncClient extends AbstractHttpAsyncClientBa log.debug(exchangeId + ": request failed: " + cause.getMessage()); } try { - execRuntime.discardConnection(); + execRuntime.discardEndpoint(); responseConsumer.failed(cause); } finally { try { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/InternalHttp2AsyncClient.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/InternalHttp2AsyncClient.java index af8054254..323ef772a 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/InternalHttp2AsyncClient.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/InternalHttp2AsyncClient.java @@ -40,6 +40,9 @@ import org.apache.hc.client5.http.cookie.CookieStore; import org.apache.hc.client5.http.protocol.HttpClientContext; import org.apache.hc.client5.http.routing.HttpRoutePlanner; import org.apache.hc.client5.http.routing.RoutingSupport; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.Internal; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.HttpException; import org.apache.hc.core5.http.HttpRequest; import org.apache.hc.core5.http.config.Lookup; @@ -48,7 +51,19 @@ import org.apache.hc.core5.http.nio.HandlerFactory; import org.apache.hc.core5.http2.nio.pool.H2ConnPool; import org.apache.hc.core5.reactor.DefaultConnectingIOReactor; -class InternalHttp2AsyncClient extends InternalAbstractHttpAsyncClient { +/** + * Internal implementation of HTTP/2 only {@link CloseableHttpAsyncClient}. + *

    + * Concurrent message exchanges with the same connection route executed by + * this client will get automatically multiplexed over a single physical HTTP/2 + * connection. + *

    + * + * @since 5.0 + */ +@Contract(threading = ThreadingBehavior.SAFE_CONDITIONAL) +@Internal +public final class InternalHttp2AsyncClient extends InternalAbstractHttpAsyncClient { private final HttpRoutePlanner routePlanner; private final H2ConnPool connPool; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/InternalHttp2AsyncExecRuntime.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/InternalHttp2AsyncExecRuntime.java index 715222dd1..fa0545df4 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/InternalHttp2AsyncExecRuntime.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/InternalHttp2AsyncExecRuntime.java @@ -71,12 +71,12 @@ class InternalHttp2AsyncExecRuntime implements AsyncExecRuntime { } @Override - public boolean isConnectionAcquired() { + public boolean isEndpointAcquired() { return sessionRef.get() != null; } @Override - public Cancellable acquireConnection( + public Cancellable acquireEndpoint( final HttpRoute route, final Object object, final HttpClientContext context, @@ -113,7 +113,7 @@ class InternalHttp2AsyncExecRuntime implements AsyncExecRuntime { } @Override - public void releaseConnection() { + public void releaseEndpoint() { final Endpoint endpoint = sessionRef.getAndSet(null); if (endpoint != null && !reusable) { endpoint.session.close(CloseMode.GRACEFUL); @@ -121,7 +121,7 @@ class InternalHttp2AsyncExecRuntime implements AsyncExecRuntime { } @Override - public void discardConnection() { + public void discardEndpoint() { final Endpoint endpoint = sessionRef.getAndSet(null); if (endpoint != null) { endpoint.session.close(CloseMode.GRACEFUL); @@ -142,7 +142,7 @@ class InternalHttp2AsyncExecRuntime implements AsyncExecRuntime { } @Override - public boolean isConnected() { + public boolean isEndpointConnected() { final Endpoint endpoint = sessionRef.get(); return endpoint != null && !endpoint.session.isClosed(); } @@ -157,7 +157,7 @@ class InternalHttp2AsyncExecRuntime implements AsyncExecRuntime { } @Override - public Cancellable connect( + public Cancellable connectEndpoint( final HttpClientContext context, final FutureCallback callback) { final Endpoint endpoint = ensureValid(); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/InternalHttpAsyncClient.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/InternalHttpAsyncClient.java index b0e46d02c..be6be9f16 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/InternalHttpAsyncClient.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/InternalHttpAsyncClient.java @@ -41,6 +41,9 @@ import org.apache.hc.client5.http.nio.AsyncClientConnectionManager; import org.apache.hc.client5.http.protocol.HttpClientContext; import org.apache.hc.client5.http.routing.HttpRoutePlanner; import org.apache.hc.client5.http.routing.RoutingSupport; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.Internal; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.HttpException; import org.apache.hc.core5.http.HttpRequest; import org.apache.hc.core5.http.HttpVersion; @@ -51,7 +54,20 @@ import org.apache.hc.core5.http.nio.HandlerFactory; import org.apache.hc.core5.http2.HttpVersionPolicy; import org.apache.hc.core5.reactor.DefaultConnectingIOReactor; -class InternalHttpAsyncClient extends InternalAbstractHttpAsyncClient { +/** + * Internal implementation of {@link CloseableHttpAsyncClient} that can negotiate + * the most optimal HTTP protocol version during during the {@code TLS} handshake + * with {@code ALPN} extension if supported by the Java runtime. + *

    + * Concurrent message exchanges executed by this client will get assigned to + * separate connections leased from the connection pool. + *

    + * + * @since 5.0 + */ +@Contract(threading = ThreadingBehavior.SAFE_CONDITIONAL) +@Internal +public final class InternalHttpAsyncClient extends InternalAbstractHttpAsyncClient { private final AsyncClientConnectionManager connmgr; private final HttpRoutePlanner routePlanner; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/InternalHttpAsyncExecRuntime.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/InternalHttpAsyncExecRuntime.java index 93340f89d..0b531814b 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/InternalHttpAsyncExecRuntime.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/InternalHttpAsyncExecRuntime.java @@ -78,12 +78,12 @@ class InternalHttpAsyncExecRuntime implements AsyncExecRuntime { } @Override - public boolean isConnectionAcquired() { + public boolean isEndpointAcquired() { return endpointRef.get() != null; } @Override - public Cancellable acquireConnection( + public Cancellable acquireEndpoint( final HttpRoute route, final Object object, final HttpClientContext context, @@ -131,7 +131,7 @@ class InternalHttpAsyncExecRuntime implements AsyncExecRuntime { } @Override - public void releaseConnection() { + public void releaseEndpoint() { final AsyncConnectionEndpoint endpoint = endpointRef.getAndSet(null); if (endpoint != null) { if (reusable) { @@ -146,7 +146,7 @@ class InternalHttpAsyncExecRuntime implements AsyncExecRuntime { } @Override - public void discardConnection() { + public void discardEndpoint() { final AsyncConnectionEndpoint endpoint = endpointRef.getAndSet(null); if (endpoint != null) { discardEndpoint(endpoint); @@ -175,13 +175,13 @@ class InternalHttpAsyncExecRuntime implements AsyncExecRuntime { } @Override - public boolean isConnected() { + public boolean isEndpointConnected() { final AsyncConnectionEndpoint endpoint = endpointRef.get(); return endpoint != null && endpoint.isConnected(); } @Override - public Cancellable connect( + public Cancellable connectEndpoint( final HttpClientContext context, final FutureCallback callback) { final AsyncConnectionEndpoint endpoint = ensureValid(); @@ -245,7 +245,7 @@ class InternalHttpAsyncExecRuntime implements AsyncExecRuntime { }; } } else { - connect(context, new FutureCallback() { + connectEndpoint(context, new FutureCallback() { @Override public void completed(final AsyncExecRuntime runtime) { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/LogAppendable.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/LogAppendable.java index 1a328a6aa..9de70b4bc 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/LogAppendable.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/LogAppendable.java @@ -31,7 +31,7 @@ import java.io.IOException; import org.slf4j.Logger; -public final class LogAppendable implements Appendable { +final class LogAppendable implements Appendable { private final Logger log; private final String prefix; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/MinimalHttp2AsyncClient.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/MinimalHttp2AsyncClient.java index 20b2508c5..3d6c68c15 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/MinimalHttp2AsyncClient.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/MinimalHttp2AsyncClient.java @@ -41,6 +41,8 @@ import org.apache.hc.client5.http.impl.ExecSupport; import org.apache.hc.client5.http.impl.classic.RequestFailedException; import org.apache.hc.client5.http.impl.nio.MultuhomeConnectionInitiator; import org.apache.hc.client5.http.protocol.HttpClientContext; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.concurrent.Cancellable; import org.apache.hc.core5.concurrent.ComplexCancellable; import org.apache.hc.core5.concurrent.FutureCallback; @@ -72,6 +74,20 @@ import org.apache.hc.core5.reactor.IOReactorConfig; import org.apache.hc.core5.reactor.IOSession; import org.apache.hc.core5.util.Timeout; +/** + * Minimal implementation of HTTP/2 only {@link CloseableHttpAsyncClient}. This client + * is optimized for HTTP/2 multiplexing message transport and does not support advanced + * HTTP protocol functionality such as request execution via a proxy, state management, + * authentication and request redirects. + *

    + * Concurrent message exchanges with the same connection route executed by + * this client will get automatically multiplexed over a single physical HTTP/2 + * connection. + *

    + * + * @since 5.0 + */ +@Contract(threading = ThreadingBehavior.SAFE_CONDITIONAL) public final class MinimalHttp2AsyncClient extends AbstractMinimalHttpAsyncClientBase { private final H2ConnPool connPool; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/MinimalHttpAsyncClient.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/MinimalHttpAsyncClient.java index c5c29271e..27996db2b 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/MinimalHttpAsyncClient.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/MinimalHttpAsyncClient.java @@ -46,6 +46,8 @@ import org.apache.hc.client5.http.nio.AsyncClientConnectionManager; import org.apache.hc.client5.http.nio.AsyncConnectionEndpoint; import org.apache.hc.client5.http.protocol.HttpClientContext; import org.apache.hc.client5.http.routing.RoutingSupport; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.concurrent.BasicFuture; import org.apache.hc.core5.concurrent.Cancellable; import org.apache.hc.core5.concurrent.ComplexCancellable; @@ -81,6 +83,19 @@ import org.apache.hc.core5.util.Asserts; import org.apache.hc.core5.util.TimeValue; import org.apache.hc.core5.util.Timeout; +/** + * Minimal implementation of {@link CloseableHttpAsyncClient}. This client is + * optimized for HTTP/1.1 and HTTP/2 message transport and does not support + * advanced HTTP protocol functionality such as request execution via a proxy, + * state management, authentication and request redirects. + *

    + * Concurrent message exchanges executed by this client will get assigned to + * separate connections leased from the connection pool. + *

    + * + * @since 5.0 + */ +@Contract(threading = ThreadingBehavior.SAFE_CONDITIONAL) public final class MinimalHttpAsyncClient extends AbstractMinimalHttpAsyncClientBase { private final AsyncClientConnectionManager connmgr; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/package-info.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/package-info.java new file mode 100644 index 000000000..b638c6a6c --- /dev/null +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/package-info.java @@ -0,0 +1,32 @@ +/* + * ==================================================================== + * 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 + * . + * + */ + +/** + * Asynchronous HTTP client API implementation that supports both + * HTTP/2 and HTTP/1.1 transport. + */ +package org.apache.hc.client5.http.impl.async; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/AuthChallengeParser.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/AuthChallengeParser.java index 2ddc27dae..1675b6d37 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/AuthChallengeParser.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/AuthChallengeParser.java @@ -39,6 +39,11 @@ import org.apache.hc.core5.http.message.BasicNameValuePair; import org.apache.hc.core5.http.message.ParserCursor; import org.apache.hc.core5.http.message.TokenParser; +/** + * Authentication challenge parser. + * + * @since 5.0 + */ public class AuthChallengeParser { public static final AuthChallengeParser INSTANCE = new AuthChallengeParser(); @@ -71,7 +76,16 @@ public class AuthChallengeParser { return new BasicNameValuePair(token, null); } - public List parse(final ChallengeType challengeType, final CharSequence buffer, final ParserCursor cursor) throws ParseException { + /** + * Parses the given sequence of characters into a list of {@link AuthChallenge} elements. + * + * @param challengeType the type of challenge (target or proxy). + * @param buffer the sequence of characters to be parsed. + * @param cursor the parser cursor. + * @return a list of auth challenge elements. + */ + public List parse( + final ChallengeType challengeType, final CharSequence buffer, final ParserCursor cursor) throws ParseException { final List list = new ArrayList<>(); String scheme = null; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/BasicSchemeFactory.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/BasicSchemeFactory.java index 50b588ae0..2f0e796db 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/BasicSchemeFactory.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/BasicSchemeFactory.java @@ -41,7 +41,7 @@ import org.apache.hc.core5.http.protocol.HttpContext; * * @since 4.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class BasicSchemeFactory implements AuthSchemeProvider { private final Charset charset; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/CredSspScheme.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/CredSspScheme.java index 1cb02998f..7763a9c10 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/CredSspScheme.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/CredSspScheme.java @@ -64,9 +64,7 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** - *

    * Client implementation of the CredSSP protocol specified in [MS-CSSP]. - *

    *

    * Note: This is implementation is NOT GSS based. It should be. But there is no Java NTLM * implementation as GSS module. Maybe the NTLMEngine can be converted to GSS and then this @@ -76,6 +74,8 @@ import org.slf4j.LoggerFactory; * Based on [MS-CSSP]: Credential Security Support Provider (CredSSP) Protocol (Revision 13.0, 7/14/2016). * The implementation was inspired by Python CredSSP and NTLM implementation by Jordan Borean. *

    + * + * @since 5.0 */ @Experimental public class CredSspScheme implements AuthScheme diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/CredSspSchemeFactory.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/CredSspSchemeFactory.java index 3abfe5868..6472512e3 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/CredSspSchemeFactory.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/CredSspSchemeFactory.java @@ -36,11 +36,20 @@ import javax.net.ssl.SSLContext; import org.apache.hc.client5.http.auth.AuthScheme; import org.apache.hc.client5.http.auth.AuthSchemeProvider; import org.apache.hc.client5.http.ssl.TrustAllStrategy; +import org.apache.hc.core5.annotation.Contract; import org.apache.hc.core5.annotation.Experimental; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.protocol.HttpContext; import org.apache.hc.core5.ssl.SSLContexts; import org.apache.hc.core5.ssl.SSLInitializationException; +/** + * {@link AuthSchemeProvider} implementation that creates and initializes + * {@link CredSspScheme} instances. + * + * @since 4.0 + */ +@Contract(threading = ThreadingBehavior.STATELESS) @Experimental public class CredSspSchemeFactory implements AuthSchemeProvider { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/DigestSchemeFactory.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/DigestSchemeFactory.java index d073d4ee9..4e74740c8 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/DigestSchemeFactory.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/DigestSchemeFactory.java @@ -39,7 +39,7 @@ import org.apache.hc.core5.http.protocol.HttpContext; * * @since 4.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class DigestSchemeFactory implements AuthSchemeProvider { @Override diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/GGSSchemeBase.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/GGSSchemeBase.java index 9afa26d76..608819a20 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/GGSSchemeBase.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/GGSSchemeBase.java @@ -57,6 +57,8 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** + * Common behavior for {@code GSS} based authentication schemes. + * * @since 4.2 */ public abstract class GGSSchemeBase implements AuthScheme { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/HttpAuthenticator.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/HttpAuthenticator.java index b8968bc85..3d8e94410 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/HttpAuthenticator.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/HttpAuthenticator.java @@ -45,7 +45,9 @@ import org.apache.hc.client5.http.auth.ChallengeType; import org.apache.hc.client5.http.auth.CredentialsProvider; import org.apache.hc.client5.http.auth.MalformedChallengeException; import org.apache.hc.client5.http.protocol.HttpClientContext; +import org.apache.hc.core5.annotation.Contract; import org.apache.hc.core5.annotation.Internal; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.FormattedHeader; import org.apache.hc.core5.http.Header; import org.apache.hc.core5.http.HttpHeaders; @@ -63,9 +65,12 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** + * Utility class that implements commons aspects of the client side HTTP authentication. + * * @since 4.3 */ -public class HttpAuthenticator { +@Contract(threading = ThreadingBehavior.STATELESS) +public final class HttpAuthenticator { private final Logger log; private final AuthChallengeParser parser; @@ -81,6 +86,17 @@ public class HttpAuthenticator { this(null); } + /** + * Determines whether the given response represents an authentication challenge. + * + * @param host the hostname of the opposite endpoint. + * @param challengeType the challenge type (target or proxy). + * @param response the response message head. + * @param authExchange the current authentication exchange state. + * @param context the current execution context. + * @return {@code true} if the response message represents an authentication challenge, + * {@code false} otherwise. + */ public boolean isChallenged( final HttpHost host, final ChallengeType challengeType, @@ -123,7 +139,20 @@ public class HttpAuthenticator { return false; } - public boolean prepareAuthResponse( + /** + * Updates the {@link AuthExchange} state based on the challenge presented in the response message + * using the given {@link AuthenticationStrategy}. + * + * @param host the hostname of the opposite endpoint. + * @param challengeType the challenge type (target or proxy). + * @param response the response message head. + * @param authStrategy the authentication strategy. + * @param authExchange the current authentication exchange state. + * @param context the current execution context. + * @return {@code true} if the authentication state has been updated, + * {@code false} if unchanged. + */ + public boolean updateAuthState( final HttpHost host, final ChallengeType challengeType, final HttpResponse response, @@ -254,6 +283,16 @@ public class HttpAuthenticator { return false; } + /** + * Generates a response to the authentication challenge based on the actual {@link AuthExchange} state + * and adds it to the given {@link HttpRequest} message . + * + * @param host the hostname of the opposite endpoint. + * @param challengeType the challenge type (target or proxy). + * @param request the request message head. + * @param authExchange the current authentication exchange state. + * @param context the current execution context. + */ public void addAuthResponse( final HttpHost host, final ChallengeType challengeType, diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/KerberosScheme.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/KerberosScheme.java index 2a2efc58a..f6399a7c7 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/KerberosScheme.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/KerberosScheme.java @@ -28,14 +28,20 @@ package org.apache.hc.client5.http.impl.auth; import org.apache.hc.client5.http.DnsResolver; import org.apache.hc.client5.http.auth.KerberosConfig; +import org.apache.hc.core5.annotation.Experimental; import org.ietf.jgss.GSSException; import org.ietf.jgss.Oid; /** * KERBEROS authentication scheme. + *

    + * Please note this class is considered experimental and may be discontinued or removed + * in the future. + *

    * * @since 4.2 */ +@Experimental public class KerberosScheme extends GGSSchemeBase { private static final String KERBEROS_OID = "1.2.840.113554.1.2.2"; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/KerberosSchemeFactory.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/KerberosSchemeFactory.java index 7c3e9efbb..c1ee7c0e8 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/KerberosSchemeFactory.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/KerberosSchemeFactory.java @@ -31,16 +31,22 @@ import org.apache.hc.client5.http.auth.AuthScheme; import org.apache.hc.client5.http.auth.AuthSchemeProvider; import org.apache.hc.client5.http.auth.KerberosConfig; import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.Experimental; import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.protocol.HttpContext; /** * {@link AuthSchemeProvider} implementation that creates and initializes * {@link KerberosScheme} instances. + *

    + * Please note this class is considered experimental and may be discontinued or removed + * in the future. + *

    * * @since 4.2 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) +@Experimental public class KerberosSchemeFactory implements AuthSchemeProvider { private final KerberosConfig config; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/NTLMEngineException.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/NTLMEngineException.java index c63bf3409..9e4d906f2 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/NTLMEngineException.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/NTLMEngineException.java @@ -31,7 +31,6 @@ import org.apache.hc.client5.http.auth.AuthenticationException; /** * Signals NTLM protocol failure. * - * * @since 4.0 */ public class NTLMEngineException extends AuthenticationException { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/NTLMScheme.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/NTLMScheme.java index 47ed39841..1de53dbca 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/NTLMScheme.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/NTLMScheme.java @@ -47,7 +47,7 @@ import org.apache.hc.core5.util.Args; * * @since 4.0 */ -public class NTLMScheme implements AuthScheme { +public final class NTLMScheme implements AuthScheme { enum State { UNINITIATED, diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/NTLMSchemeFactory.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/NTLMSchemeFactory.java index 83fd4b179..42cc5d45f 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/NTLMSchemeFactory.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/NTLMSchemeFactory.java @@ -40,7 +40,7 @@ import org.apache.hc.core5.http.protocol.HttpContext; * * @since 4.1 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class NTLMSchemeFactory implements AuthSchemeProvider { @Override diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/SPNegoScheme.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/SPNegoScheme.java index 325d5a88d..5f35d9b2a 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/SPNegoScheme.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/SPNegoScheme.java @@ -28,15 +28,21 @@ package org.apache.hc.client5.http.impl.auth; import org.apache.hc.client5.http.DnsResolver; import org.apache.hc.client5.http.auth.KerberosConfig; +import org.apache.hc.core5.annotation.Experimental; import org.ietf.jgss.GSSException; import org.ietf.jgss.Oid; /** * SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) authentication * scheme. + *

    + * Please note this class is considered experimental and may be discontinued or removed + * in the future. + *

    * * @since 4.2 */ +@Experimental public class SPNegoScheme extends GGSSchemeBase { private static final String SPNEGO_OID = "1.3.6.1.5.5.2"; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/SPNegoSchemeFactory.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/SPNegoSchemeFactory.java index 2152f1a7e..61065d4cb 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/SPNegoSchemeFactory.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/SPNegoSchemeFactory.java @@ -31,16 +31,22 @@ import org.apache.hc.client5.http.auth.AuthScheme; import org.apache.hc.client5.http.auth.AuthSchemeProvider; import org.apache.hc.client5.http.auth.KerberosConfig; import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.Experimental; import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.protocol.HttpContext; /** * {@link AuthSchemeProvider} implementation that creates and initializes * {@link SPNegoScheme} instances. + *

    + * Please note this class is considered experimental and may be discontinued or removed + * in the future. + *

    * * @since 4.2 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) +@Experimental public class SPNegoSchemeFactory implements AuthSchemeProvider { private final KerberosConfig config; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/UnsupportedDigestAlgorithmException.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/UnsupportedDigestAlgorithmException.java index 5307867f1..b03d28f90 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/UnsupportedDigestAlgorithmException.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/UnsupportedDigestAlgorithmException.java @@ -30,7 +30,6 @@ package org.apache.hc.client5.http.impl.auth; * Authentication credentials required to respond to a authentication * challenge are invalid * - * * @since 4.0 */ public class UnsupportedDigestAlgorithmException extends RuntimeException { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/package-info.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/package-info.java index b2ae96cc4..e0cb63051 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/package-info.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/package-info.java @@ -26,7 +26,6 @@ */ /** - * Default implementations of standard and common HTTP authentication - * schemes. + * Standard and common HTTP authentication schemes. */ package org.apache.hc.client5.http.impl.auth; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/AIMDBackoffManager.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/AIMDBackoffManager.java index cec7453f9..c662e130a 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/AIMDBackoffManager.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/AIMDBackoffManager.java @@ -31,6 +31,7 @@ import java.util.Map; import org.apache.hc.client5.http.HttpRoute; import org.apache.hc.client5.http.classic.BackoffManager; +import org.apache.hc.core5.annotation.Experimental; import org.apache.hc.core5.pool.ConnPoolControl; import org.apache.hc.core5.util.Args; @@ -54,6 +55,7 @@ import org.apache.hc.core5.util.Args; * * @since 4.2 */ +@Experimental public class AIMDBackoffManager implements BackoffManager { private final ConnPoolControl connPerRoute; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/AbstractHttpClientResponseHandler.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/AbstractHttpClientResponseHandler.java index 9cec146fa..7076ec2f6 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/AbstractHttpClientResponseHandler.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/AbstractHttpClientResponseHandler.java @@ -51,7 +51,7 @@ import org.apache.hc.core5.http.io.entity.EntityUtils; * * @since 4.4 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public abstract class AbstractHttpClientResponseHandler implements HttpClientResponseHandler { /** diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/BackoffStrategyExec.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/BackoffStrategyExec.java index 9733b4068..c37c25869 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/BackoffStrategyExec.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/BackoffStrategyExec.java @@ -35,6 +35,7 @@ import org.apache.hc.client5.http.classic.ConnectionBackoffStrategy; import org.apache.hc.client5.http.classic.ExecChain; import org.apache.hc.client5.http.classic.ExecChainHandler; import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.Experimental; import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.ClassicHttpRequest; import org.apache.hc.core5.http.ClassicHttpResponse; @@ -42,10 +43,19 @@ import org.apache.hc.core5.http.HttpException; import org.apache.hc.core5.util.Args; /** + * Request execution handler in the classic request execution chain + * that is responsible for execution of an {@link ConnectionBackoffStrategy}. + *

    + * Further responsibilities such as communication with the opposite + * endpoint is delegated to the next executor in the request execution + * chain. + *

    + * * @since 4.3 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) -final class BackoffStrategyExec implements ExecChainHandler { +@Contract(threading = ThreadingBehavior.STATELESS) +@Experimental +public final class BackoffStrategyExec implements ExecChainHandler { private final ConnectionBackoffStrategy connectionBackoffStrategy; private final BackoffManager backoffManager; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/BasicHttpClientResponseHandler.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/BasicHttpClientResponseHandler.java index 189cbcdf1..6269c0758 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/BasicHttpClientResponseHandler.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/BasicHttpClientResponseHandler.java @@ -52,7 +52,7 @@ import org.apache.hc.core5.http.io.entity.EntityUtils; * * @since 4.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class BasicHttpClientResponseHandler extends AbstractHttpClientResponseHandler { /** diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ClassicRequestCopier.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ClassicRequestCopier.java index ab2f7baa1..21e2db336 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ClassicRequestCopier.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ClassicRequestCopier.java @@ -33,6 +33,11 @@ import org.apache.hc.core5.http.ClassicHttpRequest; import org.apache.hc.core5.http.Header; import org.apache.hc.core5.http.message.BasicClassicHttpRequest; +/** + * {@link ClassicHttpRequest} copier. + * + * @since 5.0 + */ public final class ClassicRequestCopier implements MessageCopier { public static final ClassicRequestCopier INSTANCE = new ClassicRequestCopier(); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/Clock.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/Clock.java index 06b7ff452..8fbdd0ebb 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/Clock.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/Clock.java @@ -26,12 +26,6 @@ */ package org.apache.hc.client5.http.impl.classic; -/** - * Interface used to enable easier testing of time-related behavior. - * - * @since 4.2 - * - */ interface Clock { /** diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/CloseableHttpClient.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/CloseableHttpClient.java index de105cab8..fb1d3525f 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/CloseableHttpClient.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/CloseableHttpClient.java @@ -61,9 +61,6 @@ public abstract class CloseableHttpClient implements HttpClient, Closeable { protected abstract CloseableHttpResponse doExecute(HttpHost target, ClassicHttpRequest request, HttpContext context) throws IOException; - /** - * {@inheritDoc} - */ @Override public CloseableHttpResponse execute( final HttpHost target, @@ -72,9 +69,6 @@ public abstract class CloseableHttpClient implements HttpClient, Closeable { return doExecute(target, request, context); } - /** - * {@inheritDoc} - */ @Override public CloseableHttpResponse execute( final ClassicHttpRequest request, @@ -102,18 +96,12 @@ public abstract class CloseableHttpClient implements HttpClient, Closeable { return target; } - /** - * {@inheritDoc} - */ @Override public CloseableHttpResponse execute( final ClassicHttpRequest request) throws IOException { return execute(request, (HttpContext) null); } - /** - * {@inheritDoc} - */ @Override public CloseableHttpResponse execute( final HttpHost target, @@ -130,7 +118,7 @@ public abstract class CloseableHttpClient implements HttpClient, Closeable { * resource deallocation internally. * * @param request the request to execute - * @param HttpClientResponseHandler the response handler + * @param responseHandler the response handler * * @return the response object as generated by the response handler. * @throws IOException in case of a problem or the connection was aborted @@ -138,8 +126,8 @@ public abstract class CloseableHttpClient implements HttpClient, Closeable { */ @Override public T execute(final ClassicHttpRequest request, - final HttpClientResponseHandler HttpClientResponseHandler) throws IOException { - return execute(request, HttpClientResponseHandler, null); + final HttpClientResponseHandler responseHandler) throws IOException { + return execute(request, null, responseHandler); } /** @@ -151,7 +139,7 @@ public abstract class CloseableHttpClient implements HttpClient, Closeable { * resource deallocation internally. * * @param request the request to execute - * @param HttpClientResponseHandler the response handler + * @param responseHandler the response handler * @param context the context to use for the execution, or * {@code null} to use the default context * @@ -160,11 +148,12 @@ public abstract class CloseableHttpClient implements HttpClient, Closeable { * @throws ClientProtocolException in case of an http protocol error */ @Override - public T execute(final ClassicHttpRequest request, - final HttpClientResponseHandler HttpClientResponseHandler, final HttpContext context) - throws IOException { + public T execute( + final ClassicHttpRequest request, + final HttpContext context, + final HttpClientResponseHandler responseHandler) throws IOException { final HttpHost target = determineTarget(request); - return execute(target, request, HttpClientResponseHandler, context); + return execute(target, request, context, responseHandler); } /** @@ -180,7 +169,7 @@ public abstract class CloseableHttpClient implements HttpClient, Closeable { * if they can still determine a route, for example * to a default target or by inspecting the request. * @param request the request to execute - * @param HttpClientResponseHandler the response handler + * @param responseHandler the response handler * * @return the response object as generated by the response handler. * @throws IOException in case of a problem or the connection was aborted @@ -188,8 +177,8 @@ public abstract class CloseableHttpClient implements HttpClient, Closeable { */ @Override public T execute(final HttpHost target, final ClassicHttpRequest request, - final HttpClientResponseHandler HttpClientResponseHandler) throws IOException { - return execute(target, request, HttpClientResponseHandler, null); + final HttpClientResponseHandler responseHandler) throws IOException { + return execute(target, request, null, responseHandler); } /** @@ -205,22 +194,25 @@ public abstract class CloseableHttpClient implements HttpClient, Closeable { * if they can still determine a route, for example * to a default target or by inspecting the request. * @param request the request to execute - * @param HttpClientResponseHandler the response handler * @param context the context to use for the execution, or * {@code null} to use the default context + * @param responseHandler the response handler * * @return the response object as generated by the response handler. * @throws IOException in case of a problem or the connection was aborted * @throws ClientProtocolException in case of an http protocol error */ @Override - public T execute(final HttpHost target, final ClassicHttpRequest request, - final HttpClientResponseHandler HttpClientResponseHandler, final HttpContext context) throws IOException { - Args.notNull(HttpClientResponseHandler, "Response handler"); + public T execute( + final HttpHost target, + final ClassicHttpRequest request, + final HttpContext context, + final HttpClientResponseHandler responseHandler) throws IOException { + Args.notNull(responseHandler, "Response handler"); try (final CloseableHttpResponse response = execute(target, request, context)) { try { - final T result = HttpClientResponseHandler.handleResponse(response); + final T result = responseHandler.handleResponse(response); final HttpEntity entity = response.getEntity(); EntityUtils.consume(entity); return result; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/CloseableHttpResponse.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/CloseableHttpResponse.java index ab1801e62..a412e3768 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/CloseableHttpResponse.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/CloseableHttpResponse.java @@ -40,7 +40,7 @@ import org.apache.hc.core5.http.ProtocolVersion; import org.apache.hc.core5.util.Args; /** - * Backward compatibility with HttpClient 4.x. + * Provided for backward compatibility with HttpClient 4.x. * * @since 4.3 */ @@ -198,9 +198,9 @@ public final class CloseableHttpResponse implements ClassicHttpResponse { if (execRuntime != null) { try { response.close(); - execRuntime.disconnect(); + execRuntime.disconnectEndpoint(); } finally { - execRuntime.discardConnection(); + execRuntime.discardEndpoint(); } } else { response.close(); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ConnectExec.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ConnectExec.java index 410a8da70..abafdadb7 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ConnectExec.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ConnectExec.java @@ -44,6 +44,7 @@ import org.apache.hc.client5.http.impl.routing.BasicRouteDirector; import org.apache.hc.client5.http.protocol.HttpClientContext; import org.apache.hc.client5.http.routing.HttpRouteDirector; import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.Internal; import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.ClassicHttpRequest; import org.apache.hc.core5.http.ClassicHttpResponse; @@ -64,13 +65,14 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** - * Request executor in the HTTP request execution chain + * Request execution handler in the classic request execution chain * that is responsible for establishing connection to the target - * origin server as specified by the current route. + * origin server as specified by the current connection route. * * @since 5.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE_CONDITIONAL) +@Contract(threading = ThreadingBehavior.STATELESS) +@Internal public final class ConnectExec implements ExecChainHandler { private final Logger log = LoggerFactory.getLogger(getClass()); @@ -107,12 +109,12 @@ public final class ConnectExec implements ExecChainHandler { final HttpClientContext context = scope.clientContext; final ExecRuntime execRuntime = scope.execRuntime; - if (!execRuntime.isConnectionAcquired()) { + if (!execRuntime.isEndpointAcquired()) { final Object userToken = context.getUserToken(); - execRuntime.acquireConnection(route, userToken, context); + execRuntime.acquireEndpoint(route, userToken, context); } try { - if (!execRuntime.isConnected()) { + if (!execRuntime.isEndpointConnected()) { this.log.debug("Opening connection " + route); final RouteTracker tracker = new RouteTracker(route); @@ -124,11 +126,11 @@ public final class ConnectExec implements ExecChainHandler { switch (step) { case HttpRouteDirector.CONNECT_TARGET: - execRuntime.connect(context); + execRuntime.connectEndpoint(context); tracker.connectTarget(route.isSecure()); break; case HttpRouteDirector.CONNECT_PROXY: - execRuntime.connect(context); + execRuntime.connectEndpoint(context); final HttpHost proxy = route.getProxyHost(); tracker.connectProxy(proxy, false); break; @@ -169,7 +171,7 @@ public final class ConnectExec implements ExecChainHandler { return chain.proceed(request, scope); } catch (final IOException | HttpException | RuntimeException ex) { - execRuntime.discardConnection(); + execRuntime.discardEndpoint(); throw ex; } } @@ -216,7 +218,7 @@ public final class ConnectExec implements ExecChainHandler { if (config.isAuthenticationEnabled()) { if (this.authenticator.isChallenged(proxy, ChallengeType.PROXY, response, proxyAuthExchange, context)) { - if (this.authenticator.prepareAuthResponse(proxy, ChallengeType.PROXY, response, + if (this.authenticator.updateAuthState(proxy, ChallengeType.PROXY, response, this.proxyAuthStrategy, proxyAuthExchange, context)) { // Retry request if (this.reuseStrategy.keepAlive(request, response, context)) { @@ -225,7 +227,7 @@ public final class ConnectExec implements ExecChainHandler { final HttpEntity entity = response.getEntity(); EntityUtils.consume(entity); } else { - execRuntime.disconnect(); + execRuntime.disconnectEndpoint(); } response = null; } @@ -239,7 +241,7 @@ public final class ConnectExec implements ExecChainHandler { // Buffer response content final HttpEntity entity = response.getEntity(); final String responseMessage = entity != null ? EntityUtils.toString(entity) : null; - execRuntime.disconnect(); + execRuntime.disconnectEndpoint(); throw new TunnelRefusedException("CONNECT refused by proxy: " + new StatusLine(response), responseMessage); } diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ContentCompressionExec.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ContentCompressionExec.java index 6736ff0f1..a9781d5f3 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ContentCompressionExec.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ContentCompressionExec.java @@ -40,6 +40,7 @@ import org.apache.hc.client5.http.entity.GZIPInputStreamFactory; import org.apache.hc.client5.http.entity.InputStreamFactory; import org.apache.hc.client5.http.protocol.HttpClientContext; import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.Internal; import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.ClassicHttpRequest; import org.apache.hc.core5.http.ClassicHttpResponse; @@ -55,8 +56,8 @@ import org.apache.hc.core5.http.message.ParserCursor; import org.apache.hc.core5.util.Args; /** - * Request executor in the request execution chain that is responsible - * for automatic response content decompression. + * Request execution handler in the classic request execution chain + * that is responsible for automatic response content decompression. *

    * Further responsibilities such as communication with the opposite * endpoint is delegated to the next executor in the request execution @@ -65,7 +66,8 @@ import org.apache.hc.core5.util.Args; * * @since 5.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) +@Internal public final class ContentCompressionExec implements ExecChainHandler { private final String[] acceptEncoding; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/DefaultBackoffStrategy.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/DefaultBackoffStrategy.java index 7f2ab149e..c78108a78 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/DefaultBackoffStrategy.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/DefaultBackoffStrategy.java @@ -30,6 +30,7 @@ import java.net.ConnectException; import java.net.SocketTimeoutException; import org.apache.hc.client5.http.classic.ConnectionBackoffStrategy; +import org.apache.hc.core5.annotation.Experimental; import org.apache.hc.core5.http.HttpResponse; import org.apache.hc.core5.http.HttpStatus; @@ -40,6 +41,7 @@ import org.apache.hc.core5.http.HttpStatus; * * @since 4.2 */ +@Experimental public class DefaultBackoffStrategy implements ConnectionBackoffStrategy { @Override diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/FutureRequestExecutionService.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/FutureRequestExecutionService.java index 82b5f7b30..464b5f598 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/FutureRequestExecutionService.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/FutureRequestExecutionService.java @@ -29,6 +29,7 @@ package org.apache.hc.client5.http.impl.classic; import java.io.Closeable; import java.io.IOException; import java.util.concurrent.ExecutorService; +import java.util.concurrent.FutureTask; import java.util.concurrent.atomic.AtomicBoolean; import org.apache.hc.client5.http.classic.HttpClient; @@ -40,8 +41,8 @@ import org.apache.hc.core5.http.io.HttpClientResponseHandler; import org.apache.hc.core5.http.protocol.HttpContext; /** - * HttpAsyncClientWithFuture wraps calls to execute with a {@link HttpRequestFutureTask} - * and schedules them using the provided executor service. Scheduled calls may be cancelled. + * This class schedules message execution execution and processing + * as {@link FutureTask}s with the provided {@link ExecutorService}. */ @Contract(threading = ThreadingBehavior.SAFE_CONDITIONAL) public class FutureRequestExecutionService implements Closeable { @@ -82,7 +83,7 @@ public class FutureRequestExecutionService implements Closeable { * handler that will process the response. * @return HttpAsyncClientFutureTask for the scheduled request. */ - public HttpRequestFutureTask execute( + public FutureTask execute( final ClassicHttpRequest request, final HttpContext context, final HttpClientResponseHandler HttpClientResponseHandler) { @@ -105,7 +106,7 @@ public class FutureRequestExecutionService implements Closeable { * started, completed, failed, or cancelled. * @return HttpAsyncClientFutureTask for the scheduled request. */ - public HttpRequestFutureTask execute( + public FutureTask execute( final ClassicHttpRequest request, final HttpContext context, final HttpClientResponseHandler HttpClientResponseHandler, diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/HttpClientBuilder.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/HttpClientBuilder.java index 4d25d70ed..7199263f2 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/HttpClientBuilder.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/HttpClientBuilder.java @@ -58,7 +58,7 @@ import org.apache.hc.client5.http.cookie.CookieSpecProvider; import org.apache.hc.client5.http.cookie.CookieStore; import org.apache.hc.client5.http.entity.InputStreamFactory; import org.apache.hc.client5.http.impl.ChainElements; -import org.apache.hc.client5.http.impl.CookieSpecRegistries; +import org.apache.hc.client5.http.impl.CookieSpecSupport; import org.apache.hc.client5.http.impl.DefaultAuthenticationStrategy; import org.apache.hc.client5.http.impl.DefaultConnectionKeepAliveStrategy; import org.apache.hc.client5.http.impl.DefaultHttpRequestRetryHandler; @@ -614,7 +614,7 @@ public class HttpClientBuilder { * be used for request execution if not explicitly set in the client execution * context. * - * @see CookieSpecRegistries + * @see CookieSpecSupport * */ public final HttpClientBuilder setDefaultCookieSpecRegistry( @@ -961,7 +961,7 @@ public class HttpClientBuilder { } Lookup cookieSpecRegistryCopy = this.cookieSpecRegistry; if (cookieSpecRegistryCopy == null) { - cookieSpecRegistryCopy = CookieSpecRegistries.createDefault(); + cookieSpecRegistryCopy = CookieSpecSupport.createDefault(); } CookieStore defaultCookieStore = this.cookieStore; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/HttpClients.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/HttpClients.java index a136b47bf..55ccb5830 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/HttpClients.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/HttpClients.java @@ -32,9 +32,10 @@ import org.apache.hc.client5.http.io.HttpClientConnectionManager; /** * Factory methods for {@link CloseableHttpClient} instances. + * * @since 4.3 */ -public class HttpClients { +public final class HttpClients { private HttpClients() { super(); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/HttpRequestFutureTask.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/HttpRequestFutureTask.java index 048593c89..85aabc063 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/HttpRequestFutureTask.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/HttpRequestFutureTask.java @@ -31,18 +31,12 @@ import java.util.concurrent.FutureTask; import org.apache.hc.core5.concurrent.Cancellable; import org.apache.hc.core5.http.ClassicHttpRequest; -/** - * FutureTask implementation that wraps a HttpAsyncClientCallable and exposes various task - * specific metrics. - * - * @param - */ -public class HttpRequestFutureTask extends FutureTask { +final class HttpRequestFutureTask extends FutureTask { private final ClassicHttpRequest request; private final HttpRequestTaskCallable callable; - public HttpRequestFutureTask( + HttpRequestFutureTask( final ClassicHttpRequest request, final HttpRequestTaskCallable httpCallable) { super(httpCallable); @@ -50,10 +44,6 @@ public class HttpRequestFutureTask extends FutureTask { this.callable = httpCallable; } - /* - * (non-Javadoc) - * @see java.util.concurrent.FutureTask#cancel(boolean) - */ @Override public boolean cancel(final boolean mayInterruptIfRunning) { callable.cancel(); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/HttpRequestTaskCallable.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/HttpRequestTaskCallable.java index 1e02b2e38..0d47dcc9a 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/HttpRequestTaskCallable.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/HttpRequestTaskCallable.java @@ -87,7 +87,7 @@ class HttpRequestTaskCallable implements Callable { started = System.currentTimeMillis(); try { metrics.getScheduledConnections().decrementAndGet(); - final V result = httpclient.execute(request, responseHandler, context); + final V result = httpclient.execute(request, context, responseHandler); ended = System.currentTimeMillis(); metrics.getSuccessfulConnections().increment(started); if (callback != null) { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/InternalExecRuntime.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/InternalExecRuntime.java index c1e669bdb..7c53570dd 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/InternalExecRuntime.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/InternalExecRuntime.java @@ -85,12 +85,12 @@ class InternalExecRuntime implements ExecRuntime, Cancellable { } @Override - public boolean isConnectionAcquired() { + public boolean isEndpointAcquired() { return endpointRef.get() != null; } @Override - public void acquireConnection(final HttpRoute route, final Object object, final HttpClientContext context) throws IOException { + public void acquireEndpoint(final HttpRoute route, final Object object, final HttpClientContext context) throws IOException { Args.notNull(route, "Route"); if (endpointRef.get() == null) { final RequestConfig requestConfig = context.getRequestConfig(); @@ -137,7 +137,7 @@ class InternalExecRuntime implements ExecRuntime, Cancellable { } @Override - public boolean isConnected() { + public boolean isEndpointConnected() { final ConnectionEndpoint endpoint = endpointRef.get(); return endpoint != null && endpoint.isConnected(); } @@ -157,7 +157,7 @@ class InternalExecRuntime implements ExecRuntime, Cancellable { } @Override - public void connect(final HttpClientContext context) throws IOException { + public void connectEndpoint(final HttpClientContext context) throws IOException { final ConnectionEndpoint endpoint = ensureValid(); if (!endpoint.isConnected()) { connectEndpoint(endpoint, context); @@ -165,7 +165,7 @@ class InternalExecRuntime implements ExecRuntime, Cancellable { } @Override - public void disconnect() throws IOException { + public void disconnectEndpoint() throws IOException { final ConnectionEndpoint endpoint = endpointRef.get(); if (endpoint != null) { endpoint.close(); @@ -206,7 +206,7 @@ class InternalExecRuntime implements ExecRuntime, Cancellable { } @Override - public void releaseConnection() { + public void releaseEndpoint() { final ConnectionEndpoint endpoint = endpointRef.getAndSet(null); if (endpoint != null) { if (reusable) { @@ -227,7 +227,7 @@ class InternalExecRuntime implements ExecRuntime, Cancellable { } @Override - public void discardConnection() { + public void discardEndpoint() { final ConnectionEndpoint endpoint = endpointRef.getAndSet(null); if (endpoint != null) { try { @@ -243,7 +243,7 @@ class InternalExecRuntime implements ExecRuntime, Cancellable { public boolean cancel() { final boolean alreadyReleased = endpointRef.get() == null; log.debug("Cancelling request execution"); - discardConnection(); + discardEndpoint(); return !alreadyReleased; } diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/InternalHttpClient.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/InternalHttpClient.java index 247685624..c227dcf6d 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/InternalHttpClient.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/InternalHttpClient.java @@ -47,6 +47,7 @@ import org.apache.hc.client5.http.protocol.HttpClientContext; import org.apache.hc.client5.http.routing.HttpRoutePlanner; import org.apache.hc.client5.http.routing.RoutingSupport; import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.Internal; import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.concurrent.CancellableDependency; import org.apache.hc.core5.http.ClassicHttpRequest; @@ -64,11 +65,16 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** - * Internal class. + * Internal implementation of {@link CloseableHttpClient}. + *

    + * Concurrent message exchanges executed by this client will get assigned to + * separate connections leased from the connection pool. + *

    * * @since 4.3 */ @Contract(threading = ThreadingBehavior.SAFE_CONDITIONAL) +@Internal class InternalHttpClient extends CloseableHttpClient implements Configurable { private final Logger log = LoggerFactory.getLogger(getClass()); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/MainClientExec.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/MainClientExec.java index b97bad026..93d3b340e 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/MainClientExec.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/MainClientExec.java @@ -40,6 +40,7 @@ import org.apache.hc.client5.http.impl.ConnectionShutdownException; import org.apache.hc.client5.http.io.HttpClientConnectionManager; import org.apache.hc.client5.http.protocol.HttpClientContext; import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.Internal; import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.ClassicHttpRequest; import org.apache.hc.core5.http.ClassicHttpResponse; @@ -54,14 +55,15 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** - * The last request executor in the HTTP request execution chain - * that is responsible for execution of request / response - * exchanges with the opposite endpoint. + * Usually the last request execution handler in the classic request execution + * chain that is responsible for execution of request / response exchanges with + * the opposite endpoint. * * @since 4.3 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE_CONDITIONAL) -final class MainClientExec implements ExecChainHandler { +@Contract(threading = ThreadingBehavior.STATELESS) +@Internal +public final class MainClientExec implements ExecChainHandler { private final Logger log = LoggerFactory.getLogger(getClass()); @@ -130,7 +132,7 @@ final class MainClientExec implements ExecChainHandler { final HttpEntity entity = response.getEntity(); if (entity == null || !entity.isStreaming()) { // connection not needed and (assumed to be) in re-usable state - execRuntime.releaseConnection(); + execRuntime.releaseEndpoint(); return new CloseableHttpResponse(response, null); } ResponseEntityProxy.enchance(response, execRuntime); @@ -139,10 +141,10 @@ final class MainClientExec implements ExecChainHandler { final InterruptedIOException ioex = new InterruptedIOException( "Connection has been shut down"); ioex.initCause(ex); - execRuntime.discardConnection(); + execRuntime.discardEndpoint(); throw ioex; } catch (final HttpException | RuntimeException | IOException ex) { - execRuntime.discardConnection(); + execRuntime.discardEndpoint(); throw ex; } catch (final Error error) { connectionManager.close(CloseMode.IMMEDIATE); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/MinimalHttpClient.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/MinimalHttpClient.java index 539a1b631..2c76aa90e 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/MinimalHttpClient.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/MinimalHttpClient.java @@ -70,11 +70,18 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** - * Internal class. + * Minimal implementation of {@link CloseableHttpClient}. This client is + * optimized for HTTP/1.1 message transport and does not support advanced + * HTTP protocol functionality such as request execution via a proxy, state + * management, authentication and request redirects. + *

    + * Concurrent message exchanges executed by this client will get assigned to + * separate connections leased from the connection pool. + *

    * * @since 4.3 */ -@Contract(threading = ThreadingBehavior.SAFE) +@Contract(threading = ThreadingBehavior.SAFE_CONDITIONAL) public class MinimalHttpClient extends CloseableHttpClient { private final Logger log = LoggerFactory.getLogger(getClass()); @@ -126,11 +133,11 @@ public class MinimalHttpClient extends CloseableHttpClient { final ExecRuntime execRuntime = new InternalExecRuntime(log, connManager, requestExecutor, request instanceof CancellableDependency ? (CancellableDependency) request : null); try { - if (!execRuntime.isConnectionAcquired()) { - execRuntime.acquireConnection(route, null, clientContext); + if (!execRuntime.isEndpointAcquired()) { + execRuntime.acquireEndpoint(route, null, clientContext); } - if (!execRuntime.isConnected()) { - execRuntime.connect(clientContext); + if (!execRuntime.isEndpointConnected()) { + execRuntime.connectEndpoint(clientContext); } context.setAttribute(HttpCoreContext.HTTP_REQUEST, request); @@ -150,7 +157,7 @@ public class MinimalHttpClient extends CloseableHttpClient { final HttpEntity entity = response.getEntity(); if (entity == null || !entity.isStreaming()) { // connection not needed and (assumed to be) in re-usable state - execRuntime.releaseConnection(); + execRuntime.releaseEndpoint(); return new CloseableHttpResponse(response, null); } ResponseEntityProxy.enchance(response, execRuntime); @@ -158,13 +165,13 @@ public class MinimalHttpClient extends CloseableHttpClient { } catch (final ConnectionShutdownException ex) { final InterruptedIOException ioex = new InterruptedIOException("Connection has been shut down"); ioex.initCause(ex); - execRuntime.discardConnection(); + execRuntime.discardEndpoint(); throw ioex; } catch (final HttpException httpException) { - execRuntime.discardConnection(); + execRuntime.discardEndpoint(); throw new ClientProtocolException(httpException); } catch (final RuntimeException | IOException ex) { - execRuntime.discardConnection(); + execRuntime.discardEndpoint(); throw ex; } catch (final Error error) { connManager.close(CloseMode.IMMEDIATE); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ProtocolExec.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ProtocolExec.java index 10d0c5614..0f351f3b6 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ProtocolExec.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ProtocolExec.java @@ -48,6 +48,7 @@ import org.apache.hc.client5.http.impl.auth.HttpAuthenticator; import org.apache.hc.client5.http.protocol.HttpClientContext; import org.apache.hc.client5.http.utils.URIUtils; import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.Internal; import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.ClassicHttpRequest; import org.apache.hc.core5.http.ClassicHttpResponse; @@ -67,8 +68,8 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** - * Request executor in the request execution chain that is responsible - * for implementation of HTTP specification requirements. + * Request execution handler in the classic request execution chain + * that is responsible for implementation of HTTP specification requirements. *

    * Further responsibilities such as communication with the opposite * endpoint is delegated to the next executor in the request execution @@ -77,8 +78,9 @@ import org.slf4j.LoggerFactory; * * @since 4.3 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) -final class ProtocolExec implements ExecChainHandler { +@Contract(threading = ThreadingBehavior.STATELESS) +@Internal +public final class ProtocolExec implements ExecChainHandler { private final Logger log = LoggerFactory.getLogger(getClass()); @@ -179,7 +181,7 @@ final class ProtocolExec implements ExecChainHandler { if (execRuntime.isConnectionReusable()) { EntityUtils.consume(responseEntity); } else { - execRuntime.disconnect(); + execRuntime.disconnectEndpoint(); if (proxyAuthExchange.getState() == AuthExchange.State.SUCCESS && proxyAuthExchange.isConnectionBased()) { log.debug("Resetting proxy auth state"); @@ -202,10 +204,10 @@ final class ProtocolExec implements ExecChainHandler { } } } catch (final HttpException ex) { - execRuntime.discardConnection(); + execRuntime.discardEndpoint(); throw ex; } catch (final RuntimeException | IOException ex) { - execRuntime.discardConnection(); + execRuntime.discardEndpoint(); if (proxyAuthExchange.isConnectionBased()) { proxyAuthExchange.reset(); } @@ -238,11 +240,11 @@ final class ProtocolExec implements ExecChainHandler { proxy, ChallengeType.PROXY, response, proxyAuthExchange, context); if (targetAuthRequested) { - return authenticator.prepareAuthResponse(target, ChallengeType.TARGET, response, + return authenticator.updateAuthState(target, ChallengeType.TARGET, response, targetAuthStrategy, targetAuthExchange, context); } if (proxyAuthRequested) { - return authenticator.prepareAuthResponse(proxy, ChallengeType.PROXY, response, + return authenticator.updateAuthState(proxy, ChallengeType.PROXY, response, proxyAuthStrategy, proxyAuthExchange, context); } } diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ProxyClient.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ProxyClient.java index 7be98fb46..f47c2dfd0 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ProxyClient.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ProxyClient.java @@ -83,7 +83,7 @@ import org.apache.hc.core5.http.protocol.RequestUserAgent; import org.apache.hc.core5.util.Args; /** - * ProxyClient can be used to establish a tunnel via an HTTP proxy. + * ProxyClient can be used to establish a tunnel via an HTTP/1.1 proxy. */ public class ProxyClient { @@ -186,7 +186,7 @@ public class ProxyClient { throw new HttpException("Unexpected response to CONNECT request: " + response); } if (this.authenticator.isChallenged(proxy, ChallengeType.PROXY, response, this.proxyAuthExchange, context)) { - if (this.authenticator.prepareAuthResponse(proxy, ChallengeType.PROXY, response, + if (this.authenticator.updateAuthState(proxy, ChallengeType.PROXY, response, this.proxyAuthStrategy, this.proxyAuthExchange, context)) { // Retry request if (this.reuseStrategy.keepAlive(connect, response, context)) { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/RedirectExec.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/RedirectExec.java index 848d2eb8a..7ada6b3c1 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/RedirectExec.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/RedirectExec.java @@ -46,6 +46,7 @@ import org.apache.hc.client5.http.protocol.RedirectStrategy; import org.apache.hc.client5.http.routing.HttpRoutePlanner; import org.apache.hc.client5.http.utils.URIUtils; import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.Internal; import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.ClassicHttpRequest; import org.apache.hc.core5.http.ClassicHttpResponse; @@ -61,8 +62,8 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** - * Request executor in the request execution chain that is responsible - * for handling of request redirects. + * Request execution handler in the classic request execution chain + * responsible for handling of request redirects. *

    * Further responsibilities such as communication with the opposite * endpoint is delegated to the next executor in the request execution @@ -71,8 +72,9 @@ import org.slf4j.LoggerFactory; * * @since 4.3 */ -@Contract(threading = ThreadingBehavior.SAFE_CONDITIONAL) -final class RedirectExec implements ExecChainHandler { +@Contract(threading = ThreadingBehavior.STATELESS) +@Internal +public final class RedirectExec implements ExecChainHandler { private final Logger log = LoggerFactory.getLogger(getClass()); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/RequestEntityProxy.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/RequestEntityProxy.java index 4a9b81a82..e7e4835ed 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/RequestEntityProxy.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/RequestEntityProxy.java @@ -37,11 +37,6 @@ import org.apache.hc.core5.http.ClassicHttpRequest; import org.apache.hc.core5.http.Header; import org.apache.hc.core5.http.HttpEntity; -/** - * A Proxy class for {@link org.apache.hc.core5.http.HttpEntity} enclosed in a request message. - * - * @since 4.3 - */ class RequestEntityProxy implements HttpEntity { static void enhance(final ClassicHttpRequest request) { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ResponseEntityProxy.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ResponseEntityProxy.java index 9dc55046b..fb6182b59 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ResponseEntityProxy.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ResponseEntityProxy.java @@ -39,11 +39,6 @@ import org.apache.hc.core5.http.io.EofSensorInputStream; import org.apache.hc.core5.http.io.EofSensorWatcher; import org.apache.hc.core5.http.io.entity.HttpEntityWrapper; -/** - * A wrapper class for {@link HttpEntity} enclosed in a response message. - * - * @since 4.3 - */ class ResponseEntityProxy extends HttpEntityWrapper implements EofSensorWatcher { private final ExecRuntime execRuntime; @@ -62,22 +57,22 @@ class ResponseEntityProxy extends HttpEntityWrapper implements EofSensorWatcher private void cleanup() throws IOException { if (this.execRuntime != null) { - if (this.execRuntime.isConnected()) { - this.execRuntime.disconnect(); + if (this.execRuntime.isEndpointConnected()) { + this.execRuntime.disconnectEndpoint(); } - this.execRuntime.discardConnection(); + this.execRuntime.discardEndpoint(); } } private void discardConnection() { if (this.execRuntime != null) { - this.execRuntime.discardConnection(); + this.execRuntime.discardEndpoint(); } } public void releaseConnection() { if (this.execRuntime != null) { - this.execRuntime.releaseConnection(); + this.execRuntime.releaseEndpoint(); } } @@ -127,7 +122,7 @@ class ResponseEntityProxy extends HttpEntityWrapper implements EofSensorWatcher @Override public boolean streamClosed(final InputStream wrapped) throws IOException { try { - final boolean open = execRuntime != null && execRuntime.isConnectionAcquired(); + final boolean open = execRuntime != null && execRuntime.isEndpointAcquired(); // this assumes that closing the stream will // consume the remainder of the response body: try { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/RetryExec.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/RetryExec.java index 7fa9343c2..1c98ec3d1 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/RetryExec.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/RetryExec.java @@ -35,6 +35,7 @@ import org.apache.hc.client5.http.classic.ExecChain; import org.apache.hc.client5.http.classic.ExecChainHandler; import org.apache.hc.client5.http.protocol.HttpClientContext; import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.Internal; import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.ClassicHttpRequest; import org.apache.hc.core5.http.ClassicHttpResponse; @@ -46,9 +47,9 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** - * Request executor in the request execution chain that is responsible - * for making a decision whether a request failed due to an I/O error - * should be re-executed. + * Request execution handler in the classic request execution chain + * responsible for making a decision whether a request failed due to + * an I/O error should be re-executed. *

    * Further responsibilities such as communication with the opposite * endpoint is delegated to the next executor in the request execution @@ -57,8 +58,9 @@ import org.slf4j.LoggerFactory; * * @since 4.3 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE_CONDITIONAL) -final class RetryExec implements ExecChainHandler { +@Contract(threading = ThreadingBehavior.STATELESS) +@Internal +public final class RetryExec implements ExecChainHandler { private final Logger log = LoggerFactory.getLogger(getClass()); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ServiceUnavailableRetryExec.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ServiceUnavailableRetryExec.java index 285d4d872..28d4a6ceb 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ServiceUnavailableRetryExec.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/ServiceUnavailableRetryExec.java @@ -35,6 +35,7 @@ import org.apache.hc.client5.http.classic.ExecChain; import org.apache.hc.client5.http.classic.ExecChainHandler; import org.apache.hc.client5.http.protocol.HttpClientContext; import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.Internal; import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.ClassicHttpRequest; import org.apache.hc.core5.http.ClassicHttpResponse; @@ -56,8 +57,9 @@ import org.slf4j.LoggerFactory; * * @since 4.3 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE_CONDITIONAL) -final class ServiceUnavailableRetryExec implements ExecChainHandler { +@Contract(threading = ThreadingBehavior.STATELESS) +@Internal +public final class ServiceUnavailableRetryExec implements ExecChainHandler { private final Logger log = LoggerFactory.getLogger(getClass()); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/SystemClock.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/SystemClock.java index 0ec51d776..fffca7ef4 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/SystemClock.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/SystemClock.java @@ -26,11 +26,6 @@ */ package org.apache.hc.client5.http.impl.classic; -/** - * The actual system clock. - * - * @since 4.2 - */ class SystemClock implements Clock { @Override diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/package-info.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/package-info.java index 20c017ddc..2447808d3 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/package-info.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/package-info.java @@ -26,27 +26,8 @@ */ /** - * Default HTTP client implementation. - *

    - * The usual execution flow can be demonstrated by the code snippet below: - *

    - * 
    - * CloseableHttpClient httpclient = HttpClients.createDefault();
- * try {
- *      HttpGet httpGet = new HttpGet("http://targethost/homepage");
- *      CloseableHttpResponse response = httpclient.execute(httpGet);
- *      try {
- *          System.out.println(response.getStatusLine());
- *          HttpEntity entity = response.getEntity();
- *          // do something useful with the response body
- *          // and ensure it is fully consumed
- *          EntityUtils.consume(entity);
- *      } finally {
- *          response.close();
- *      }
- * } finally {
- *      httpclient.close();
- * }
- *
    + * Classic HTTP client API implementation that supports HTTP/1.1 transport + * only. This implementation is mostly API compatible with HttpClient 4.5. + * Please use the asynchronous client API implementation for HTTP/2 transport. */ package org.apache.hc.client5.http.impl.classic; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/AbstractCookieAttributeHandler.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/AbstractCookieAttributeHandler.java index 242392327..fe72c0913 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/AbstractCookieAttributeHandler.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/AbstractCookieAttributeHandler.java @@ -37,7 +37,7 @@ import org.apache.hc.core5.annotation.ThreadingBehavior; * * @since 4.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public abstract class AbstractCookieAttributeHandler implements CookieAttributeHandler { @Override diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/AbstractCookieSpec.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/AbstractCookieSpec.java index d6f8707c4..6a92c4e15 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/AbstractCookieSpec.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/AbstractCookieSpec.java @@ -44,7 +44,6 @@ import org.apache.hc.core5.util.Asserts; * validation or matching cookie attributes to a number of arbitrary * {@link CookieAttributeHandler}s. * - * * @since 4.0 */ @Contract(threading = ThreadingBehavior.SAFE) diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/BasicClientCookie.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/BasicClientCookie.java index 4ded0355f..62fb23348 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/BasicClientCookie.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/BasicClientCookie.java @@ -41,7 +41,7 @@ import org.apache.hc.core5.util.Args; * * @since 4.0 */ -public class BasicClientCookie implements SetCookie, Cloneable, Serializable { +public final class BasicClientCookie implements SetCookie, Cloneable, Serializable { private static final long serialVersionUID = -3869795591041535538L; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/BasicDomainHandler.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/BasicDomainHandler.java index bfed82a00..edbf78e3f 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/BasicDomainHandler.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/BasicDomainHandler.java @@ -41,10 +41,11 @@ import org.apache.hc.core5.util.Args; import org.apache.hc.core5.util.TextUtils; /** + * Cookie {@code domain} attribute handler. * * @since 4.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class BasicDomainHandler implements CommonCookieAttributeHandler { public BasicDomainHandler() { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/BasicExpiresHandler.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/BasicExpiresHandler.java index d90dfafcf..1c01784e0 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/BasicExpiresHandler.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/BasicExpiresHandler.java @@ -38,10 +38,11 @@ import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.util.Args; /** + * Cookie {@code expires} attribute handler. * * @since 4.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class BasicExpiresHandler extends AbstractCookieAttributeHandler implements CommonCookieAttributeHandler { /** Valid date patterns */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/BasicMaxAgeHandler.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/BasicMaxAgeHandler.java index 74cba3375..599ad2c40 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/BasicMaxAgeHandler.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/BasicMaxAgeHandler.java @@ -37,10 +37,11 @@ import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.util.Args; /** + * Cookie {@code max-age} attribute handler. * * @since 4.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class BasicMaxAgeHandler extends AbstractCookieAttributeHandler implements CommonCookieAttributeHandler { public BasicMaxAgeHandler() { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/BasicPathHandler.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/BasicPathHandler.java index 43752d77b..9de0403f9 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/BasicPathHandler.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/BasicPathHandler.java @@ -37,10 +37,11 @@ import org.apache.hc.core5.util.Args; import org.apache.hc.core5.util.TextUtils; /** + * Cookie {@code path} attribute handler. * * @since 4.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class BasicPathHandler implements CommonCookieAttributeHandler { public BasicPathHandler() { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/BasicSecureHandler.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/BasicSecureHandler.java index 99406a7d6..e8a3060b4 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/BasicSecureHandler.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/BasicSecureHandler.java @@ -36,10 +36,11 @@ import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.util.Args; /** + * Cookie {@code secure} attribute handler. * * @since 4.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class BasicSecureHandler extends AbstractCookieAttributeHandler implements CommonCookieAttributeHandler { public BasicSecureHandler() { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/CookieSpecBase.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/CookieSpecBase.java index dd10e2f42..af9782214 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/CookieSpecBase.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/CookieSpecBase.java @@ -48,7 +48,7 @@ import org.apache.hc.core5.util.Args; * * @since 4.0 */ -@Contract(threading = ThreadingBehavior.SAFE_CONDITIONAL) +@Contract(threading = ThreadingBehavior.SAFE) public abstract class CookieSpecBase extends AbstractCookieSpec { public CookieSpecBase() { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/IgnoreSpec.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/IgnoreSpec.java index fee891103..018641c1f 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/IgnoreSpec.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/IgnoreSpec.java @@ -42,7 +42,7 @@ import org.apache.hc.core5.http.Header; * * @since 4.1 */ -@Contract(threading = ThreadingBehavior.SAFE) +@Contract(threading = ThreadingBehavior.STATELESS) public class IgnoreSpec extends CookieSpecBase { @Override diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/IgnoreSpecProvider.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/IgnoreSpecProvider.java index e7bf1fcad..38b0879c7 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/IgnoreSpecProvider.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/IgnoreSpecProvider.java @@ -34,11 +34,11 @@ import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.protocol.HttpContext; /** - * {@link org.apache.hc.client5.http.cookie.CookieSpecProvider} implementation that ignores all cookies. + * {@link CookieSpecProvider} implementation that ignores all cookies. * * @since 4.4 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.SAFE) public class IgnoreSpecProvider implements CookieSpecProvider { private volatile CookieSpec cookieSpec; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/LaxExpiresHandler.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/LaxExpiresHandler.java index c75435d0b..ea4ae56ed 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/LaxExpiresHandler.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/LaxExpiresHandler.java @@ -45,10 +45,12 @@ import org.apache.hc.core5.http.message.ParserCursor; import org.apache.hc.core5.util.Args; /** + * Cookie {@code expires} attribute handler conformant to the more relaxed interpretation + * of HTTP state management. * * @since 4.4 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class LaxExpiresHandler extends AbstractCookieAttributeHandler implements CommonCookieAttributeHandler { static final TimeZone UTC = TimeZone.getTimeZone("UTC"); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/LaxMaxAgeHandler.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/LaxMaxAgeHandler.java index cf3639cfa..a1d2f7fe3 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/LaxMaxAgeHandler.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/LaxMaxAgeHandler.java @@ -40,10 +40,12 @@ import org.apache.hc.core5.util.Args; import org.apache.hc.core5.util.TextUtils; /** + * Cookie {@code max-age} attribute handler conformant to the more relaxed interpretation + * of HTTP state management. * * @since 4.4 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class LaxMaxAgeHandler extends AbstractCookieAttributeHandler implements CommonCookieAttributeHandler { private final static Pattern MAX_AGE_PATTERN = Pattern.compile("^\\-?[0-9]+$"); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/PublicSuffixDomainFilter.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/PublicSuffixDomainFilter.java index 3022f8e05..1ae0c25b0 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/PublicSuffixDomainFilter.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/PublicSuffixDomainFilter.java @@ -41,17 +41,17 @@ import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.util.Args; /** - * Wraps a {@link org.apache.hc.client5.http.cookie.CookieAttributeHandler} and leverages its match method - * to never match a suffix from a black list. May be used to provide additional security for - * cross-site attack types by preventing cookies from apparent domains that are not publicly - * available. + * Wraps a {@link org.apache.hc.client5.http.cookie.CookieAttributeHandler} and leverages + * its match method to never match a suffix from a black list. May be used to provide + * additional security for cross-site attack types by preventing cookies from apparent + * domains that are not publicly available. * * @see PublicSuffixList * @see PublicSuffixMatcher * * @since 4.4 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE_CONDITIONAL) +@Contract(threading = ThreadingBehavior.STATELESS) public class PublicSuffixDomainFilter implements CommonCookieAttributeHandler { private final CommonCookieAttributeHandler handler; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/RFC6265CookieSpec.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/RFC6265CookieSpec.java index 3af14c34c..9ec499edb 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/RFC6265CookieSpec.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/RFC6265CookieSpec.java @@ -60,7 +60,7 @@ import org.apache.hc.core5.util.CharArrayBuffer; * * @since 4.5 */ -@Contract(threading = ThreadingBehavior.SAFE_CONDITIONAL) +@Contract(threading = ThreadingBehavior.SAFE) public class RFC6265CookieSpec implements CookieSpec { private final static char PARAM_DELIMITER = ';'; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/RFC6265CookieSpecProvider.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/RFC6265CookieSpecProvider.java index adaa7ef3d..77339432b 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/RFC6265CookieSpecProvider.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/RFC6265CookieSpecProvider.java @@ -38,13 +38,13 @@ import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.protocol.HttpContext; /** - * {@link org.apache.hc.client5.http.cookie.CookieSpecProvider} implementation that provides an instance of - * RFC 6265 conformant cookie policy. The instance returned by this factory can be shared by - * multiple threads. + * {@link CookieSpecProvider} implementation that provides an instance of + * RFC 6265 conformant cookie policy. The instance returned by this factory + * can be shared by multiple threads. * * @since 4.4 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE_CONDITIONAL) +@Contract(threading = ThreadingBehavior.SAFE) public class RFC6265CookieSpecProvider implements CookieSpecProvider { public enum CompatibilityLevel { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/RFC6265LaxSpec.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/RFC6265LaxSpec.java index 0514df39c..56fed126f 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/RFC6265LaxSpec.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/RFC6265LaxSpec.java @@ -32,8 +32,8 @@ import org.apache.hc.core5.annotation.Contract; import org.apache.hc.core5.annotation.ThreadingBehavior; /** - * Standard {@link org.apache.hc.client5.http.cookie.CookieSpec} implementation that enforces a more relaxed - * interpretation of the HTTP state management specification (RFC 6265, section 5) + * Standard {@link org.apache.hc.client5.http.cookie.CookieSpec} implementation that enforces + * a more relaxed interpretation of the HTTP state management specification (RFC 6265, section 5) * for interoperability with existing servers that do not conform to the well behaved profile * (RFC 6265, section 4). * diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/RFC6265StrictSpec.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/RFC6265StrictSpec.java index 774753c8b..22ec3e02a 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/RFC6265StrictSpec.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/RFC6265StrictSpec.java @@ -33,9 +33,9 @@ import org.apache.hc.core5.annotation.Contract; import org.apache.hc.core5.annotation.ThreadingBehavior; /** - * Standard {@link org.apache.hc.client5.http.cookie.CookieSpec} implementation that enforces syntax - * and semantics of the well-behaved profile of the HTTP state management specification - * (RFC 6265, section 4). + * Standard {@link org.apache.hc.client5.http.cookie.CookieSpec} implementation + * that enforces syntax and semantics of the well-behaved profile of the HTTP + * state management specification (RFC 6265, section 4). * * @since 4.4 */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/package-info.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/package-info.java index adc45f1e4..d76c2ebcb 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/package-info.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/cookie/package-info.java @@ -26,7 +26,6 @@ */ /** - * Default implementations of standard and common HTTP state - * management policies. + * Standard and common HTTP cookie management policies. */ package org.apache.hc.client5.http.impl.cookie; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/DefaultHttpClientConnectionOperator.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/DefaultHttpClientConnectionOperator.java index bf915fded..785aa5c2a 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/DefaultHttpClientConnectionOperator.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/DefaultHttpClientConnectionOperator.java @@ -67,7 +67,7 @@ import org.slf4j.LoggerFactory; * @since 4.4 */ @Internal -@Contract(threading = ThreadingBehavior.IMMUTABLE_CONDITIONAL) +@Contract(threading = ThreadingBehavior.STATELESS) public class DefaultHttpClientConnectionOperator implements HttpClientConnectionOperator { static final String SOCKET_FACTORY_REGISTRY = "http.socket-factory-registry"; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/DefaultHttpResponseParserFactory.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/DefaultHttpResponseParserFactory.java index 6859d28e3..f61eeb721 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/DefaultHttpResponseParserFactory.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/DefaultHttpResponseParserFactory.java @@ -43,7 +43,7 @@ import org.apache.hc.core5.http.message.LineParser; * * @since 4.3 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class DefaultHttpResponseParserFactory implements HttpMessageParserFactory { public static final DefaultHttpResponseParserFactory INSTANCE = new DefaultHttpResponseParserFactory(); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/DefaultManagedHttpClientConnection.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/DefaultManagedHttpClientConnection.java index 0b7d1f5b2..b2290c461 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/DefaultManagedHttpClientConnection.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/DefaultManagedHttpClientConnection.java @@ -54,11 +54,6 @@ import org.apache.hc.core5.util.Identifiable; import org.slf4j.Logger; import org.slf4j.LoggerFactory; -/** - * Default {@link ManagedHttpClientConnection} implementation. - * - * @since 4.3 - */ final class DefaultManagedHttpClientConnection extends DefaultBHttpClientConnection implements ManagedHttpClientConnection, Identifiable { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/LoggingOutputStream.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/LoggingOutputStream.java index 7484ee35f..258b40859 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/LoggingOutputStream.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/LoggingOutputStream.java @@ -32,11 +32,6 @@ import java.io.OutputStream; import org.apache.hc.client5.http.impl.Wire; -/** - * Internal class. - * - * @since 4.3 - */ class LoggingOutputStream extends OutputStream { private final OutputStream out; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/ManagedHttpClientConnectionFactory.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/ManagedHttpClientConnectionFactory.java index c2a19e50a..7dd373f4f 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/ManagedHttpClientConnectionFactory.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/ManagedHttpClientConnectionFactory.java @@ -53,7 +53,7 @@ import org.apache.hc.core5.http.io.HttpMessageWriterFactory; * Factory for {@link ManagedHttpClientConnection} instances. * @since 4.3 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class ManagedHttpClientConnectionFactory implements HttpConnectionFactory { private static final AtomicLong COUNTER = new AtomicLong(); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/package-info.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/package-info.java index 71ab3def3..14fc33017 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/package-info.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/package-info.java @@ -26,7 +26,7 @@ */ /** - * Default implementations of client connection management - * functions. + * Client connection management functions based the classic + * connection management APIs. */ package org.apache.hc.client5.http.impl.io; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/nio/DefaultAsyncClientConnectionOperator.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/nio/DefaultAsyncClientConnectionOperator.java index 33503da83..12ce6c96d 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/nio/DefaultAsyncClientConnectionOperator.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/nio/DefaultAsyncClientConnectionOperator.java @@ -38,7 +38,6 @@ import org.apache.hc.client5.http.impl.DefaultSchemePortResolver; import org.apache.hc.client5.http.nio.AsyncClientConnectionOperator; import org.apache.hc.client5.http.nio.ManagedAsyncClientConnection; import org.apache.hc.client5.http.routing.RoutingSupport; -import org.apache.hc.core5.annotation.Internal; import org.apache.hc.core5.concurrent.ComplexFuture; import org.apache.hc.core5.concurrent.FutureCallback; import org.apache.hc.core5.http.HttpHost; @@ -49,12 +48,6 @@ import org.apache.hc.core5.reactor.IOSession; import org.apache.hc.core5.util.Args; import org.apache.hc.core5.util.TimeValue; -/** - * Default {@link AsyncClientConnectionOperator} implementation. - * - * @since 5.0 - */ -@Internal final class DefaultAsyncClientConnectionOperator implements AsyncClientConnectionOperator { private final SchemePortResolver schemePortResolver; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/nio/DefaultManagedAsyncClientConnection.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/nio/DefaultManagedAsyncClientConnection.java index 26d4a15ab..e2382c06d 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/nio/DefaultManagedAsyncClientConnection.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/nio/DefaultManagedAsyncClientConnection.java @@ -36,7 +36,6 @@ import javax.net.ssl.SSLSession; import org.apache.hc.client5.http.impl.ConnPoolSupport; import org.apache.hc.client5.http.nio.ManagedAsyncClientConnection; -import org.apache.hc.core5.annotation.Internal; import org.apache.hc.core5.http.EndpointDetails; import org.apache.hc.core5.http.HttpConnection; import org.apache.hc.core5.http.HttpVersion; @@ -57,12 +56,6 @@ import org.apache.hc.core5.util.Identifiable; import org.slf4j.Logger; import org.slf4j.LoggerFactory; -/** - * Default {@link ManagedAsyncClientConnection} implementation. - * - * @since 5.0 - */ -@Internal final class DefaultManagedAsyncClientConnection implements ManagedAsyncClientConnection, Identifiable { private final Logger log = LoggerFactory.getLogger(getClass()); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/nio/MultuhomeConnectionInitiator.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/nio/MultuhomeConnectionInitiator.java index 0d96357fb..066d17f52 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/nio/MultuhomeConnectionInitiator.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/nio/MultuhomeConnectionInitiator.java @@ -31,6 +31,8 @@ import java.net.SocketAddress; import java.util.concurrent.Future; import org.apache.hc.client5.http.DnsResolver; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.concurrent.FutureCallback; import org.apache.hc.core5.net.NamedEndpoint; import org.apache.hc.core5.reactor.ConnectionInitiator; @@ -43,6 +45,7 @@ import org.apache.hc.core5.util.TimeValue; * * @since 5.0 */ +@Contract(threading = ThreadingBehavior.SAFE_CONDITIONAL) public final class MultuhomeConnectionInitiator implements ConnectionInitiator { private final ConnectionInitiator connectionInitiator; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/nio/package-info.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/nio/package-info.java new file mode 100644 index 000000000..a6e96e095 --- /dev/null +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/nio/package-info.java @@ -0,0 +1,32 @@ +/* + * ==================================================================== + * 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 + * . + * + */ + +/** + * Client connection management functions based the asynchronous + * connection management APIs. + */ +package org.apache.hc.client5.http.impl.nio; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/routing/BasicRouteDirector.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/routing/BasicRouteDirector.java index 99bf10451..f891e6957 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/routing/BasicRouteDirector.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/routing/BasicRouteDirector.java @@ -38,7 +38,7 @@ import org.apache.hc.core5.util.Args; * * @since 4.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class BasicRouteDirector implements HttpRouteDirector { /** diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/routing/DefaultProxyRoutePlanner.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/routing/DefaultProxyRoutePlanner.java index 2a104b7ba..065f640c8 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/routing/DefaultProxyRoutePlanner.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/routing/DefaultProxyRoutePlanner.java @@ -41,7 +41,7 @@ import org.apache.hc.core5.util.Args; * * @since 4.3 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE_CONDITIONAL) +@Contract(threading = ThreadingBehavior.STATELESS) public class DefaultProxyRoutePlanner extends DefaultRoutePlanner { private final HttpHost proxy; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/routing/DefaultRoutePlanner.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/routing/DefaultRoutePlanner.java index 513d8a178..547147648 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/routing/DefaultRoutePlanner.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/routing/DefaultRoutePlanner.java @@ -49,7 +49,7 @@ import org.apache.hc.core5.http.protocol.HttpContext; * * @since 4.3 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE_CONDITIONAL) +@Contract(threading = ThreadingBehavior.STATELESS) public class DefaultRoutePlanner implements HttpRoutePlanner { private final SchemePortResolver schemePortResolver; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/routing/SystemDefaultRoutePlanner.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/routing/SystemDefaultRoutePlanner.java index 1793b34a5..1b0b957da 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/routing/SystemDefaultRoutePlanner.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/routing/SystemDefaultRoutePlanner.java @@ -49,7 +49,7 @@ import org.apache.hc.core5.http.protocol.HttpContext; * * @since 4.3 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE_CONDITIONAL) +@Contract(threading = ThreadingBehavior.STATELESS) public class SystemDefaultRoutePlanner extends DefaultRoutePlanner { private final ProxySelector proxySelector; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/routing/package-info.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/routing/package-info.java new file mode 100644 index 000000000..a6b20f664 --- /dev/null +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/routing/package-info.java @@ -0,0 +1,31 @@ +/* + * ==================================================================== + * 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 + * . + * + */ + +/** + * Standard client connection routing API implementations. + */ +package org.apache.hc.client5.http.impl.routing; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/io/ConnectionEndpoint.java b/httpclient5/src/main/java/org/apache/hc/client5/http/io/ConnectionEndpoint.java index f62fc8a51..7ee8c7b0a 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/io/ConnectionEndpoint.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/io/ConnectionEndpoint.java @@ -39,20 +39,42 @@ import org.apache.hc.core5.http.protocol.HttpContext; import org.apache.hc.core5.io.ModalCloseable; /** - * Client connection endpoint that can be used to execute message exchanges. + * Client endpoint leased from a connection manager. Client points can be used + * to execute HTTP requests. + *

    + * Once the endpoint is no longer needed it MUST be released with {@link #close(org.apache.hc.core5.io.CloseMode)} )}. + *

    * * @since 5.0 */ @Contract(threading = ThreadingBehavior.SAFE) public abstract class ConnectionEndpoint implements ModalCloseable { + /** + * Executes HTTP request using the provided request executor. + *

    + * Once the endpoint is no longer needed it MUST be released with {@link #close(org.apache.hc.core5.io.CloseMode)}. + *

    + * + * @param request the request message. + * @param executor the request executor. + * @param context the execution context. + */ public abstract ClassicHttpResponse execute( ClassicHttpRequest request, HttpRequestExecutor executor, HttpContext context) throws IOException, HttpException; + /** + * Determines if the connection to the remote endpoint is still open and valid. + */ public abstract boolean isConnected(); + /** + * Sets the socket timeout value. + * + * @param timeout timeout value + */ public abstract void setSocketTimeout(int timeout); } diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/io/HttpClientConnectionManager.java b/httpclient5/src/main/java/org/apache/hc/client5/http/io/HttpClientConnectionManager.java index 2d51feda6..0e8b48573 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/io/HttpClientConnectionManager.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/io/HttpClientConnectionManager.java @@ -41,10 +41,12 @@ import org.apache.hc.core5.util.Timeout; * HTTP connections, manage persistent connections and synchronize access to * persistent connections making sure that only one thread of execution can * have access to a connection at a time. + *

    *

    * Implementations of this interface must be thread-safe. Access to shared * data must be synchronized as methods of this interface may be executed * from multiple threads. + *

    * * @since 4.3 */ @@ -93,16 +95,14 @@ public interface HttpClientConnectionManager extends ModalCloseable { * @param endpoint the managed endpoint. * @param connectTimeout connect timeout. * @param context the actual HTTP context. - * @throws IOException */ void connect(ConnectionEndpoint endpoint, TimeValue connectTimeout, HttpContext context) throws IOException; /** - * Upgrades the endpoint's underlying transport to Transport Layer Security. + * Upgrades transport security of the given endpoint by using the TLS security protocol. * * @param endpoint the managed endpoint. * @param context the actual HTTP context. - * @throws IOException */ void upgrade(ConnectionEndpoint endpoint, HttpContext context) throws IOException; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/io/HttpClientConnectionOperator.java b/httpclient5/src/main/java/org/apache/hc/client5/http/io/HttpClientConnectionOperator.java index e206d4dad..d1bf4fa92 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/io/HttpClientConnectionOperator.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/io/HttpClientConnectionOperator.java @@ -30,24 +30,33 @@ package org.apache.hc.client5.http.io; import java.io.IOException; import java.net.InetSocketAddress; +import org.apache.hc.core5.annotation.Contract; import org.apache.hc.core5.annotation.Internal; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.HttpHost; import org.apache.hc.core5.http.io.SocketConfig; import org.apache.hc.core5.http.protocol.HttpContext; import org.apache.hc.core5.util.TimeValue; /** - * Connection operator that performs connection connect and upgrade operations. Usually, components - * participating in these operations are registry of {@link org.apache.hc.client5.http.socket.ConnectionSocketFactory}, - * {@link org.apache.hc.client5.http.SchemePortResolver} and {@link org.apache.hc.client5.http.DnsResolver}. - * In general, HTTP client user should not provide implementations of this interface, as HttpClient will use the - * default one that covers most of the cases needed for majority of users. + * Connection operator that performs connection connect and upgrade operations. * * @since 4.4 */ +@Contract(threading = ThreadingBehavior.STATELESS) @Internal public interface HttpClientConnectionOperator { + /** + * Connect the given managed connection to the remote endpoint. + * + * @param conn the managed connection. + * @param host the address of the opposite endpoint. + * @param localAddress the address of the local endpoint. + * @param connectTimeout the timeout of the connect operation. + * @param socketConfig the socket configuration. + * @param context the execution context. + */ void connect( ManagedHttpClientConnection conn, HttpHost host, @@ -56,6 +65,14 @@ public interface HttpClientConnectionOperator { SocketConfig socketConfig, HttpContext context) throws IOException; + /** + * Upgrades transport security of the given managed connection + * by using the TLS security protocol. + * + * @param conn the managed connection. + * @param host the address of the opposite endpoint with TLS security. + * @param context the execution context. + */ void upgrade( ManagedHttpClientConnection conn, HttpHost host, diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/io/ManagedHttpClientConnection.java b/httpclient5/src/main/java/org/apache/hc/client5/http/io/ManagedHttpClientConnection.java index 226947e16..48546b963 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/io/ManagedHttpClientConnection.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/io/ManagedHttpClientConnection.java @@ -52,7 +52,6 @@ public interface ManagedHttpClientConnection extends HttpClientConnection { * is connection to a remote host. * * @param socket the socket to bind the connection to. - * @throws IOException */ void bind(Socket socket) throws IOException; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/io/package-info.java b/httpclient5/src/main/java/org/apache/hc/client5/http/io/package-info.java new file mode 100644 index 000000000..1a2982e38 --- /dev/null +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/io/package-info.java @@ -0,0 +1,31 @@ +/* + * ==================================================================== + * 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 + * . + * + */ + +/** + * Connection management APIs based on the classic (blocking) I/O model. + */ +package org.apache.hc.client5.http.io; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/nio/AsyncClientConnectionManager.java b/httpclient5/src/main/java/org/apache/hc/client5/http/nio/AsyncClientConnectionManager.java index b3519deb2..d989e157b 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/nio/AsyncClientConnectionManager.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/nio/AsyncClientConnectionManager.java @@ -29,6 +29,8 @@ package org.apache.hc.client5.http.nio; import java.util.concurrent.Future; import org.apache.hc.client5.http.HttpRoute; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.concurrent.FutureCallback; import org.apache.hc.core5.http.protocol.HttpContext; import org.apache.hc.core5.io.ModalCloseable; @@ -43,13 +45,16 @@ import org.apache.hc.core5.util.Timeout; * HTTP connections, manage persistent connections and synchronize access to * persistent connections making sure that only one thread of execution can * have access to a connection at a time. + *

    *

    * Implementations of this interface must be thread-safe. Access to shared * data must be synchronized as methods of this interface may be executed * from multiple threads. + *

    * * @since 5.0 */ +@Contract(threading = ThreadingBehavior.SAFE) public interface AsyncClientConnectionManager extends ModalCloseable { /** @@ -113,7 +118,7 @@ public interface AsyncClientConnectionManager extends ModalCloseable { FutureCallback callback); /** - * Upgrades the endpoint's underlying transport to Transport Layer Security. + * Upgrades transport security of the given endpoint by using the TLS security protocol. * * @param endpoint the managed endpoint. * @param attachment the attachment the upgrade attachment object. diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/nio/AsyncClientConnectionOperator.java b/httpclient5/src/main/java/org/apache/hc/client5/http/nio/AsyncClientConnectionOperator.java index 4bea69c7d..e9e62fcf1 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/nio/AsyncClientConnectionOperator.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/nio/AsyncClientConnectionOperator.java @@ -30,18 +30,35 @@ package org.apache.hc.client5.http.nio; import java.net.SocketAddress; import java.util.concurrent.Future; +import org.apache.hc.core5.annotation.Contract; import org.apache.hc.core5.annotation.Internal; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.concurrent.FutureCallback; import org.apache.hc.core5.http.HttpHost; import org.apache.hc.core5.reactor.ConnectionInitiator; import org.apache.hc.core5.util.TimeValue; /** + * Connection operator that performs connection connect and upgrade operations. + * * @since 5.0 */ +@Contract(threading = ThreadingBehavior.STATELESS) @Internal public interface AsyncClientConnectionOperator { + /** + * Initiates operation to create a connection to the remote endpoint using + * the provided {@link ConnectionInitiator}. + * + * @param connectionInitiator the connection initiator. + * @param host the address of the opposite endpoint. + * @param localAddress the address of the local endpoint. + * @param connectTimeout the timeout of the connect operation. + * @param attachment the attachment, which can be any object representing custom parameter + * of the operation. + * @param callback the future result callback. + */ Future connect( ConnectionInitiator connectionInitiator, HttpHost host, @@ -50,6 +67,16 @@ public interface AsyncClientConnectionOperator { Object attachment, FutureCallback callback); - void upgrade(ManagedAsyncClientConnection connection, HttpHost host, Object attachment); + + /** + * Upgrades transport security of the given managed connection + * by using the TLS security protocol. + * + * @param conn the managed connection. + * @param host the address of the opposite endpoint with TLS security. + * @param attachment the attachment, which can be any object representing custom parameter + * of the operation. + */ + void upgrade(ManagedAsyncClientConnection conn, HttpHost host, Object attachment); } diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/nio/AsyncConnectionEndpoint.java b/httpclient5/src/main/java/org/apache/hc/client5/http/nio/AsyncConnectionEndpoint.java index 3acf72f44..01ab6035e 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/nio/AsyncConnectionEndpoint.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/nio/AsyncConnectionEndpoint.java @@ -53,13 +53,28 @@ import org.apache.hc.core5.io.ModalCloseable; @Contract(threading = ThreadingBehavior.SAFE) public abstract class AsyncConnectionEndpoint implements ModalCloseable { + /** + * Initiates a message exchange using the given handler. + * + * @param exchangeHandler the message exchange handler. + * @param pushHandlerFactory the push handler factory. + * @param context the execution context. + */ public abstract void execute( AsyncClientExchangeHandler exchangeHandler, HandlerFactory pushHandlerFactory, HttpContext context); + /** + * Determines if the connection to the remote endpoint is still open and valid. + */ public abstract boolean isConnected(); + /** + * Sets socket timeout. + * + * @param timeout the socket timeout. + */ public abstract void setSocketTimeout(int timeout); @Override @@ -67,12 +82,29 @@ public abstract class AsyncConnectionEndpoint implements ModalCloseable { close(CloseMode.GRACEFUL); } - public final void execute( + /** + * Initiates a message exchange using the given handler. + * + * @param exchangeHandler the message exchange handler. + * @param context the execution context. + */ + public void execute( final AsyncClientExchangeHandler exchangeHandler, final HttpContext context) { execute(exchangeHandler, null, context); } + /** + * Initiates message exchange using the given request producer and response consumer. + * + * @param requestProducer the request producer. + * @param responseConsumer the response consumer. + * @param pushHandlerFactory the push handler factory. + * @param context the execution context. + * @param callback the result callback. + * @param the result representation. + * @return the result future. + */ public final Future execute( final AsyncRequestProducer requestProducer, final AsyncResponseConsumer responseConsumer, @@ -104,6 +136,16 @@ public abstract class AsyncConnectionEndpoint implements ModalCloseable { return future; } + /** + * Initiates message exchange using the given request producer and response consumer. + * + * @param requestProducer the request producer. + * @param responseConsumer the response consumer. + * @param context the execution context. + * @param callback the result callback. + * @param the result representation. + * @return the result future. + */ public final Future execute( final AsyncRequestProducer requestProducer, final AsyncResponseConsumer responseConsumer, @@ -112,6 +154,16 @@ public abstract class AsyncConnectionEndpoint implements ModalCloseable { return execute(requestProducer, responseConsumer, null, context, callback); } + /** + * Initiates message exchange using the given request producer and response consumer. + * + * @param requestProducer the request producer. + * @param responseConsumer the response consumer. + * @param pushHandlerFactory the push handler factory. + * @param callback the result callback. + * @param the result representation. + * @return the result future. + */ public final Future execute( final AsyncRequestProducer requestProducer, final AsyncResponseConsumer responseConsumer, @@ -120,6 +172,15 @@ public abstract class AsyncConnectionEndpoint implements ModalCloseable { return execute(requestProducer, responseConsumer, pushHandlerFactory, null, callback); } + /** + * Initiates message exchange using the given request producer and response consumer. + * + * @param requestProducer the request producer. + * @param responseConsumer the response consumer. + * @param callback the result callback. + * @param the result representation. + * @return the result future. + */ public final Future execute( final AsyncRequestProducer requestProducer, final AsyncResponseConsumer responseConsumer, diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/nio/ManagedAsyncClientConnection.java b/httpclient5/src/main/java/org/apache/hc/client5/http/nio/ManagedAsyncClientConnection.java index 4f88f93c6..dad4f4a1b 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/nio/ManagedAsyncClientConnection.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/nio/ManagedAsyncClientConnection.java @@ -32,9 +32,21 @@ import org.apache.hc.core5.http.HttpConnection; import org.apache.hc.core5.reactor.Command; import org.apache.hc.core5.reactor.ssl.TransportSecurityLayer; +/** + * Represents a managed asynchronous connection whose state and life cycle + * is managed by a connection manager. + * + * @since 5.0 + */ @Internal public interface ManagedAsyncClientConnection extends HttpConnection, TransportSecurityLayer { + /** + * Submits the given command for execution. + * + * @param command the command to be executed. + * @param priority the command priority. + */ void submitCommand(Command command, Command.Priority priority); /** diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/nio/package-info.java b/httpclient5/src/main/java/org/apache/hc/client5/http/nio/package-info.java new file mode 100644 index 000000000..293dc09d8 --- /dev/null +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/nio/package-info.java @@ -0,0 +1,31 @@ +/* + * ==================================================================== + * 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 + * . + * + */ + +/** + * Connection management APIs based on the asynchronous I/O model. + */ +package org.apache.hc.client5.http.nio; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/package-info.java b/httpclient5/src/main/java/org/apache/hc/client5/http/package-info.java new file mode 100644 index 000000000..83dcb970c --- /dev/null +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/package-info.java @@ -0,0 +1,34 @@ +/* + * ==================================================================== + * 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 + * . + * + */ + +/** + * Client component APIs common to all client transports + * such as connection route information and resolution + * as well as common HTTP method definitions and + * exception classes. + */ +package org.apache.hc.client5.http; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/RedirectStrategy.java b/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/RedirectStrategy.java index 70cd0a3b7..5fade4960 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/RedirectStrategy.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/RedirectStrategy.java @@ -29,6 +29,8 @@ package org.apache.hc.client5.http.protocol; import java.net.URI; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.HttpException; import org.apache.hc.core5.http.HttpRequest; import org.apache.hc.core5.http.HttpResponse; @@ -42,9 +44,11 @@ import org.apache.hc.core5.http.protocol.HttpContext; * Implementations of this interface must be thread-safe. Access to shared * data must be synchronized as methods of this interface may be executed * from multiple threads. + *

    * * @since 4.1 */ +@Contract(threading = ThreadingBehavior.STATELESS) public interface RedirectStrategy { /** diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/RequestAddCookies.java b/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/RequestAddCookies.java index 7d311035d..6637d0eb3 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/RequestAddCookies.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/RequestAddCookies.java @@ -62,7 +62,7 @@ import org.slf4j.LoggerFactory; * * @since 4.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class RequestAddCookies implements HttpRequestInterceptor { private final Logger log = LoggerFactory.getLogger(getClass()); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/RequestAuthCache.java b/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/RequestAuthCache.java index 562bc2f61..b9b29d200 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/RequestAuthCache.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/RequestAuthCache.java @@ -54,7 +54,7 @@ import org.slf4j.LoggerFactory; * * @since 4.1 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class RequestAuthCache implements HttpRequestInterceptor { private final Logger log = LoggerFactory.getLogger(getClass()); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/RequestClientConnControl.java b/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/RequestClientConnControl.java index e1cebc16f..902cac274 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/RequestClientConnControl.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/RequestClientConnControl.java @@ -50,7 +50,7 @@ import org.slf4j.LoggerFactory; * * @since 4.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class RequestClientConnControl implements HttpRequestInterceptor { private final Logger log = LoggerFactory.getLogger(getClass()); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/RequestDefaultHeaders.java b/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/RequestDefaultHeaders.java index 15ace2e9e..3f4e02c3f 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/RequestDefaultHeaders.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/RequestDefaultHeaders.java @@ -45,7 +45,7 @@ import org.apache.hc.core5.util.Args; * * @since 4.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class RequestDefaultHeaders implements HttpRequestInterceptor { private final Collection defaultHeaders; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/RequestExpectContinue.java b/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/RequestExpectContinue.java index c06fedb95..a60a7ea15 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/RequestExpectContinue.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/RequestExpectContinue.java @@ -53,7 +53,7 @@ import org.apache.hc.core5.util.Args; * * @since 4.3 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class RequestExpectContinue implements HttpRequestInterceptor { public RequestExpectContinue() { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/ResponseProcessCookies.java b/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/ResponseProcessCookies.java index 4dc563aa2..eea47050e 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/ResponseProcessCookies.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/ResponseProcessCookies.java @@ -54,7 +54,7 @@ import org.slf4j.LoggerFactory; * * @since 4.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class ResponseProcessCookies implements HttpResponseInterceptor { private final Logger log = LoggerFactory.getLogger(getClass()); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/package-info.java b/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/package-info.java index 31d7889e5..82118e874 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/package-info.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/package-info.java @@ -26,6 +26,7 @@ */ /** - * Client specific HTTP protocol handlers. + * HTTP protocol interceptors that enable advanced functionality + * such as HTTP state management and authentication state caching. */ package org.apache.hc.client5.http.protocol; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/psl/PublicSuffixList.java b/httpclient5/src/main/java/org/apache/hc/client5/http/psl/PublicSuffixList.java index eabf67ff4..477b99d39 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/psl/PublicSuffixList.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/psl/PublicSuffixList.java @@ -39,6 +39,7 @@ import org.apache.hc.core5.util.Args; *

    * An up-to-date list of suffixes can be obtained from * publicsuffix.org + *

    * * @since 4.4 */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/psl/PublicSuffixListParser.java b/httpclient5/src/main/java/org/apache/hc/client5/http/psl/PublicSuffixListParser.java index 730791a3d..9619d5db2 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/psl/PublicSuffixListParser.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/psl/PublicSuffixListParser.java @@ -41,7 +41,7 @@ import org.apache.hc.core5.annotation.ThreadingBehavior; * * @since 4.4 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public final class PublicSuffixListParser { public PublicSuffixListParser() { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/psl/PublicSuffixMatcher.java b/httpclient5/src/main/java/org/apache/hc/client5/http/psl/PublicSuffixMatcher.java index 5c4c6a1d1..9b7dd5704 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/psl/PublicSuffixMatcher.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/psl/PublicSuffixMatcher.java @@ -42,6 +42,7 @@ import org.apache.hc.core5.util.Args; *

    * An up-to-date list of suffixes can be obtained from * publicsuffix.org + *

    * * @see PublicSuffixList * diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/psl/package-info.java b/httpclient5/src/main/java/org/apache/hc/client5/http/psl/package-info.java new file mode 100644 index 000000000..dc16f42fe --- /dev/null +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/psl/package-info.java @@ -0,0 +1,31 @@ +/* + * ==================================================================== + * 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 + * . + * + */ + +/** + * Public Suffix List support classes. + */ +package org.apache.hc.client5.http.psl; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/routing/HttpRouteDirector.java b/httpclient5/src/main/java/org/apache/hc/client5/http/routing/HttpRouteDirector.java index ea6f419e3..e0d23432b 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/routing/HttpRouteDirector.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/routing/HttpRouteDirector.java @@ -28,6 +28,8 @@ package org.apache.hc.client5.http.routing; import org.apache.hc.client5.http.RouteInfo; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; /** * Provides directions on establishing a route. @@ -36,6 +38,7 @@ import org.apache.hc.client5.http.RouteInfo; * * @since 4.0 */ +@Contract(threading = ThreadingBehavior.STATELESS) public interface HttpRouteDirector { /** Indicates that the route can not be established at all. */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/routing/HttpRoutePlanner.java b/httpclient5/src/main/java/org/apache/hc/client5/http/routing/HttpRoutePlanner.java index 03b65996c..129ba7c83 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/routing/HttpRoutePlanner.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/routing/HttpRoutePlanner.java @@ -28,6 +28,8 @@ package org.apache.hc.client5.http.routing; import org.apache.hc.client5.http.HttpRoute; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.HttpException; import org.apache.hc.core5.http.HttpHost; import org.apache.hc.core5.http.protocol.HttpContext; @@ -44,6 +46,7 @@ import org.apache.hc.core5.http.protocol.HttpContext; * * @since 4.0 */ +@Contract(threading = ThreadingBehavior.STATELESS) public interface HttpRoutePlanner { /** diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/socket/ConnectionSocketFactory.java b/httpclient5/src/main/java/org/apache/hc/client5/http/socket/ConnectionSocketFactory.java index 8764d6de0..edb510b37 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/socket/ConnectionSocketFactory.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/socket/ConnectionSocketFactory.java @@ -31,6 +31,8 @@ import java.io.IOException; import java.net.InetSocketAddress; import java.net.Socket; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.HttpHost; import org.apache.hc.core5.http.protocol.HttpContext; import org.apache.hc.core5.util.TimeValue; @@ -40,6 +42,7 @@ import org.apache.hc.core5.util.TimeValue; * * @since 4.3 */ +@Contract(threading = ThreadingBehavior.STATELESS) public interface ConnectionSocketFactory { /** diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/socket/LayeredConnectionSocketFactory.java b/httpclient5/src/main/java/org/apache/hc/client5/http/socket/LayeredConnectionSocketFactory.java index a4f5c1e6d..d35c296e1 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/socket/LayeredConnectionSocketFactory.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/socket/LayeredConnectionSocketFactory.java @@ -30,6 +30,8 @@ package org.apache.hc.client5.http.socket; import java.io.IOException; import java.net.Socket; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.protocol.HttpContext; /** @@ -37,6 +39,7 @@ import org.apache.hc.core5.http.protocol.HttpContext; * * @since 4.3 */ +@Contract(threading = ThreadingBehavior.STATELESS) public interface LayeredConnectionSocketFactory extends ConnectionSocketFactory { /** diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/socket/PlainConnectionSocketFactory.java b/httpclient5/src/main/java/org/apache/hc/client5/http/socket/PlainConnectionSocketFactory.java index 2da55628c..e5245c6e0 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/socket/PlainConnectionSocketFactory.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/socket/PlainConnectionSocketFactory.java @@ -43,7 +43,7 @@ import org.apache.hc.core5.util.TimeValue; * * @since 4.3 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class PlainConnectionSocketFactory implements ConnectionSocketFactory { public static final PlainConnectionSocketFactory INSTANCE = new PlainConnectionSocketFactory(); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/DefaultHostnameVerifier.java b/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/DefaultHostnameVerifier.java index 53ef852b4..cb88375db 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/DefaultHostnameVerifier.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/DefaultHostnameVerifier.java @@ -58,7 +58,7 @@ import org.slf4j.LoggerFactory; * * @since 4.4 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE_CONDITIONAL) +@Contract(threading = ThreadingBehavior.STATELESS) public final class DefaultHostnameVerifier implements HttpClientHostnameVerifier { enum HostNameType { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/DistinguishedNameParser.java b/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/DistinguishedNameParser.java index 2d030ec71..0053c1c9f 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/DistinguishedNameParser.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/DistinguishedNameParser.java @@ -31,15 +31,12 @@ import java.util.ArrayList; import java.util.BitSet; import java.util.List; -import org.apache.hc.core5.annotation.Contract; -import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.NameValuePair; import org.apache.hc.core5.http.message.BasicNameValuePair; import org.apache.hc.core5.http.message.ParserCursor; import org.apache.hc.core5.http.message.TokenParser; import org.apache.hc.core5.util.CharArrayBuffer; -@Contract(threading = ThreadingBehavior.IMMUTABLE) final class DistinguishedNameParser { public final static DistinguishedNameParser INSTANCE = new DistinguishedNameParser(); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/H2TlsStrategy.java b/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/H2TlsStrategy.java index eb064dc4f..b434eaf91 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/H2TlsStrategy.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/H2TlsStrategy.java @@ -46,6 +46,8 @@ import javax.net.ssl.SSLSession; import javax.security.auth.x500.X500Principal; import org.apache.hc.client5.http.psl.PublicSuffixMatcherLoader; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.HttpHost; import org.apache.hc.core5.http.nio.ssl.TlsStrategy; import org.apache.hc.core5.http2.ssl.H2TlsSupport; @@ -66,6 +68,7 @@ import org.slf4j.LoggerFactory; * * @since 5.0 */ +@Contract(threading = ThreadingBehavior.STATELESS) public class H2TlsStrategy implements TlsStrategy { private static String[] split(final String s) { diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/HttpClientHostnameVerifier.java b/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/HttpClientHostnameVerifier.java index 9ac4f62c5..cd51a34b5 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/HttpClientHostnameVerifier.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/HttpClientHostnameVerifier.java @@ -32,13 +32,24 @@ import java.security.cert.X509Certificate; import javax.net.ssl.HostnameVerifier; import javax.net.ssl.SSLException; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; + /** * Extended {@link HostnameVerifier} interface. * * @since 5.0 */ +@Contract(threading = ThreadingBehavior.STATELESS) public interface HttpClientHostnameVerifier extends HostnameVerifier { + /** + * Verifies the supplied server {@link X509Certificate} and ensures it matches + * the original host name. + * + * @param host the original host name. + * @param cert the server certificate; + */ void verify(String host, X509Certificate cert) throws SSLException; } diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/NoopHostnameVerifier.java b/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/NoopHostnameVerifier.java index abcd1c588..dbaec13de 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/NoopHostnameVerifier.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/NoopHostnameVerifier.java @@ -39,7 +39,7 @@ import org.apache.hc.core5.annotation.ThreadingBehavior; * * @since 4.4 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) +@Contract(threading = ThreadingBehavior.STATELESS) public class NoopHostnameVerifier implements HostnameVerifier { public static final NoopHostnameVerifier INSTANCE = new NoopHostnameVerifier(); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/SSLConnectionSocketFactory.java b/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/SSLConnectionSocketFactory.java index cf88c8522..2e5dfc534 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/SSLConnectionSocketFactory.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/SSLConnectionSocketFactory.java @@ -137,7 +137,7 @@ import org.slf4j.LoggerFactory; * * @since 4.3 */ -@Contract(threading = ThreadingBehavior.SAFE) +@Contract(threading = ThreadingBehavior.STATELESS) public class SSLConnectionSocketFactory implements LayeredConnectionSocketFactory { public static final String TLS = "TLS"; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/TrustAllStrategy.java b/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/TrustAllStrategy.java index b7366eaf8..0f6dbe6cb 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/TrustAllStrategy.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/TrustAllStrategy.java @@ -29,6 +29,8 @@ package org.apache.hc.client5.http.ssl; import java.security.cert.CertificateException; import java.security.cert.X509Certificate; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.ssl.TrustStrategy; /** @@ -37,8 +39,9 @@ import org.apache.hc.core5.ssl.TrustStrategy; * context. * * @since 4.5.4 - * @since 5.0-alpha2 + * @since 5.0 */ +@Contract(threading = ThreadingBehavior.STATELESS) public class TrustAllStrategy implements TrustStrategy { public static final TrustAllStrategy INSTANCE = new TrustAllStrategy(); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/TrustSelfSignedStrategy.java b/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/TrustSelfSignedStrategy.java index d6fac20ac..a77f9f21f 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/TrustSelfSignedStrategy.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/ssl/TrustSelfSignedStrategy.java @@ -29,6 +29,8 @@ package org.apache.hc.client5.http.ssl; import java.security.cert.CertificateException; import java.security.cert.X509Certificate; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.ssl.TrustStrategy; /** @@ -37,6 +39,7 @@ import org.apache.hc.core5.ssl.TrustStrategy; * * @since 4.1 */ +@Contract(threading = ThreadingBehavior.STATELESS) public class TrustSelfSignedStrategy implements TrustStrategy { public static final TrustSelfSignedStrategy INSTANCE = new TrustSelfSignedStrategy(); diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/utils/ByteArrayBuilder.java b/httpclient5/src/main/java/org/apache/hc/client5/http/utils/ByteArrayBuilder.java index 7ebbb0f46..6b78abcb2 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/utils/ByteArrayBuilder.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/utils/ByteArrayBuilder.java @@ -35,15 +35,11 @@ import java.nio.charset.CoderResult; import java.nio.charset.CodingErrorAction; import java.nio.charset.StandardCharsets; -import org.apache.hc.core5.annotation.Contract; -import org.apache.hc.core5.annotation.ThreadingBehavior; - /** * Builder class for sequences of bytes. * * @since 5.0 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) public final class ByteArrayBuilder { private CharsetEncoder charsetEncoder; diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/utils/DateUtils.java b/httpclient5/src/main/java/org/apache/hc/client5/http/utils/DateUtils.java index ed5cb38c1..04167c2d7 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/utils/DateUtils.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/utils/DateUtils.java @@ -37,8 +37,6 @@ import java.util.Locale; import java.util.Map; import java.util.TimeZone; -import org.apache.hc.core5.annotation.Contract; -import org.apache.hc.core5.annotation.ThreadingBehavior; import org.apache.hc.core5.http.Header; import org.apache.hc.core5.http.MessageHeaders; import org.apache.hc.core5.util.Args; @@ -50,7 +48,6 @@ import org.apache.hc.core5.util.Args; * * @since 4.3 */ -@Contract(threading = ThreadingBehavior.IMMUTABLE) public final class DateUtils { /** diff --git a/httpclient5/src/test/java/org/apache/hc/client5/http/impl/auth/TestHttpAuthenticator.java b/httpclient5/src/test/java/org/apache/hc/client5/http/impl/auth/TestHttpAuthenticator.java index 2f510e0d5..ac2986e0c 100644 --- a/httpclient5/src/test/java/org/apache/hc/client5/http/impl/auth/TestHttpAuthenticator.java +++ b/httpclient5/src/test/java/org/apache/hc/client5/http/impl/auth/TestHttpAuthenticator.java @@ -175,7 +175,7 @@ public class TestHttpAuthenticator { final DefaultAuthenticationStrategy authStrategy = new DefaultAuthenticationStrategy(); - Assert.assertTrue(this.httpAuthenticator.prepareAuthResponse(host, ChallengeType.TARGET, response, authStrategy, + Assert.assertTrue(this.httpAuthenticator.updateAuthState(host, ChallengeType.TARGET, response, authStrategy, this.authExchange, this.context)); Assert.assertEquals(AuthExchange.State.CHALLENGED, this.authExchange.getState()); @@ -204,7 +204,7 @@ public class TestHttpAuthenticator { final DefaultAuthenticationStrategy authStrategy = new DefaultAuthenticationStrategy(); - Assert.assertTrue(this.httpAuthenticator.prepareAuthResponse(host, ChallengeType.TARGET, response, authStrategy, + Assert.assertTrue(this.httpAuthenticator.updateAuthState(host, ChallengeType.TARGET, response, authStrategy, this.authExchange, this.context)); Assert.assertEquals(AuthExchange.State.CHALLENGED, this.authExchange.getState()); @@ -223,7 +223,7 @@ public class TestHttpAuthenticator { final DefaultAuthenticationStrategy authStrategy = new DefaultAuthenticationStrategy(); - Assert.assertFalse(this.httpAuthenticator.prepareAuthResponse( + Assert.assertFalse(this.httpAuthenticator.updateAuthState( host, ChallengeType.TARGET, response, authStrategy, this.authExchange, this.context)); } @@ -236,7 +236,7 @@ public class TestHttpAuthenticator { final DefaultAuthenticationStrategy authStrategy = new DefaultAuthenticationStrategy(); - Assert.assertFalse(this.httpAuthenticator.prepareAuthResponse( + Assert.assertFalse(this.httpAuthenticator.updateAuthState( host, ChallengeType.TARGET, response, authStrategy, this.authExchange, this.context)); } @@ -249,7 +249,7 @@ public class TestHttpAuthenticator { final DefaultAuthenticationStrategy authStrategy = new DefaultAuthenticationStrategy(); - Assert.assertFalse(this.httpAuthenticator.prepareAuthResponse( + Assert.assertFalse(this.httpAuthenticator.updateAuthState( host, ChallengeType.TARGET, response, authStrategy, this.authExchange, this.context)); } @@ -265,7 +265,7 @@ public class TestHttpAuthenticator { final DefaultAuthenticationStrategy authStrategy = new DefaultAuthenticationStrategy(); - Assert.assertFalse(this.httpAuthenticator.prepareAuthResponse( + Assert.assertFalse(this.httpAuthenticator.updateAuthState( host, ChallengeType.TARGET, response, authStrategy, this.authExchange, this.context)); Assert.assertEquals(AuthExchange.State.FAILURE, this.authExchange.getState()); @@ -284,7 +284,7 @@ public class TestHttpAuthenticator { final DefaultAuthenticationStrategy authStrategy = new DefaultAuthenticationStrategy(); - Assert.assertFalse(this.httpAuthenticator.prepareAuthResponse( + Assert.assertFalse(this.httpAuthenticator.updateAuthState( host, ChallengeType.TARGET, response, authStrategy, this.authExchange, this.context)); Assert.assertEquals(AuthExchange.State.FAILURE, this.authExchange.getState()); @@ -303,7 +303,7 @@ public class TestHttpAuthenticator { this.authExchange.setState(AuthExchange.State.CHALLENGED); this.authExchange.select(new BasicScheme()); - Assert.assertFalse(this.httpAuthenticator.prepareAuthResponse( + Assert.assertFalse(this.httpAuthenticator.updateAuthState( host, ChallengeType.TARGET, response, authStrategy, this.authExchange, this.context)); Assert.assertEquals(AuthExchange.State.FAILURE, this.authExchange.getState()); } @@ -321,7 +321,7 @@ public class TestHttpAuthenticator { this.authExchange.setState(AuthExchange.State.CHALLENGED); this.authExchange.select(new DigestScheme()); - Assert.assertTrue(this.httpAuthenticator.prepareAuthResponse( + Assert.assertTrue(this.httpAuthenticator.updateAuthState( host, ChallengeType.TARGET, response, authStrategy, this.authExchange, this.context)); Assert.assertEquals(AuthExchange.State.HANDSHAKE, this.authExchange.getState()); @@ -343,7 +343,7 @@ public class TestHttpAuthenticator { this.authExchange.setState(AuthExchange.State.CHALLENGED); this.authExchange.select(new BasicScheme()); - Assert.assertTrue(this.httpAuthenticator.prepareAuthResponse( + Assert.assertTrue(this.httpAuthenticator.updateAuthState( host, ChallengeType.TARGET, response, authStrategy, this.authExchange, this.context)); Assert.assertEquals(AuthExchange.State.CHALLENGED, this.authExchange.getState()); @@ -365,7 +365,7 @@ public class TestHttpAuthenticator { final DefaultAuthenticationStrategy authStrategy = new DefaultAuthenticationStrategy(); - Assert.assertFalse(this.httpAuthenticator.prepareAuthResponse( + Assert.assertFalse(this.httpAuthenticator.updateAuthState( host, ChallengeType.TARGET, response, authStrategy, this.authExchange, this.context)); Assert.assertEquals(AuthExchange.State.UNCHALLENGED, this.authExchange.getState()); diff --git a/httpclient5/src/test/java/org/apache/hc/client5/http/impl/classic/TestConnectExec.java b/httpclient5/src/test/java/org/apache/hc/client5/http/impl/classic/TestConnectExec.java index 744f0a7a4..06dfe9543 100644 --- a/httpclient5/src/test/java/org/apache/hc/client5/http/impl/classic/TestConnectExec.java +++ b/httpclient5/src/test/java/org/apache/hc/client5/http/impl/classic/TestConnectExec.java @@ -106,7 +106,7 @@ public class TestConnectExec { .build()); context.setUserToken("Blah"); - Mockito.when(execRuntime.isConnectionAcquired()).thenReturn(false); + Mockito.when(execRuntime.isEndpointAcquired()).thenReturn(false); Mockito.when(execRuntime.execute( Mockito.same(request), Mockito.any())).thenReturn(response); @@ -116,8 +116,8 @@ public class TestConnectExec { Mockito.any())).thenReturn(false); final ExecChain.Scope scope = new ExecChain.Scope("test", route, request, execRuntime, context); exec.execute(request, scope, execChain); - Mockito.verify(execRuntime).acquireConnection(route, "Blah", context); - Mockito.verify(execRuntime).connect(context); + Mockito.verify(execRuntime).acquireEndpoint(route, "Blah", context); + Mockito.verify(execRuntime).connectEndpoint(context); } @Test @@ -127,13 +127,13 @@ public class TestConnectExec { final ClassicHttpRequest request = new HttpGet("http://bar/test"); final ConnectionState connectionState = new ConnectionState(); - Mockito.doAnswer(connectionState.connectAnswer()).when(execRuntime).connect(Mockito.any()); - Mockito.when(execRuntime.isConnected()).thenAnswer(connectionState.isConnectedAnswer()); + Mockito.doAnswer(connectionState.connectAnswer()).when(execRuntime).connectEndpoint(Mockito.any()); + Mockito.when(execRuntime.isEndpointConnected()).thenAnswer(connectionState.isConnectedAnswer()); final ExecChain.Scope scope = new ExecChain.Scope("test", route, request, execRuntime, context); exec.execute(request, scope, execChain); - Mockito.verify(execRuntime).connect(context); + Mockito.verify(execRuntime).connectEndpoint(context); Mockito.verify(execRuntime, Mockito.never()).execute(Mockito.any(), Mockito.any()); } @@ -144,13 +144,13 @@ public class TestConnectExec { final ClassicHttpRequest request = new HttpGet("http://bar/test"); final ConnectionState connectionState = new ConnectionState(); - Mockito.doAnswer(connectionState.connectAnswer()).when(execRuntime).connect(Mockito.any()); - Mockito.when(execRuntime.isConnected()).thenAnswer(connectionState.isConnectedAnswer()); + Mockito.doAnswer(connectionState.connectAnswer()).when(execRuntime).connectEndpoint(Mockito.any()); + Mockito.when(execRuntime.isEndpointConnected()).thenAnswer(connectionState.isConnectedAnswer()); final ExecChain.Scope scope = new ExecChain.Scope("test", route, request, execRuntime, context); exec.execute(request, scope, execChain); - Mockito.verify(execRuntime).connect(context); + Mockito.verify(execRuntime).connectEndpoint(context); Mockito.verify(execRuntime, Mockito.never()).execute(Mockito.any(), Mockito.any()); } @@ -162,8 +162,8 @@ public class TestConnectExec { final ClassicHttpResponse response = new BasicClassicHttpResponse(200, "OK"); final ConnectionState connectionState = new ConnectionState(); - Mockito.doAnswer(connectionState.connectAnswer()).when(execRuntime).connect(Mockito.any()); - Mockito.when(execRuntime.isConnected()).thenAnswer(connectionState.isConnectedAnswer()); + Mockito.doAnswer(connectionState.connectAnswer()).when(execRuntime).connectEndpoint(Mockito.any()); + Mockito.when(execRuntime.isEndpointConnected()).thenAnswer(connectionState.isConnectedAnswer()); Mockito.when(execRuntime.execute( Mockito.any(), Mockito.any())).thenReturn(response); @@ -171,7 +171,7 @@ public class TestConnectExec { final ExecChain.Scope scope = new ExecChain.Scope("test", route, request, execRuntime, context); exec.execute(request, scope, execChain); - Mockito.verify(execRuntime).connect(context); + Mockito.verify(execRuntime).connectEndpoint(context); final ArgumentCaptor reqCaptor = ArgumentCaptor.forClass(ClassicHttpRequest.class); Mockito.verify(execRuntime).execute( reqCaptor.capture(), @@ -191,8 +191,8 @@ public class TestConnectExec { final ClassicHttpResponse response = new BasicClassicHttpResponse(101, "Lost"); final ConnectionState connectionState = new ConnectionState(); - Mockito.doAnswer(connectionState.connectAnswer()).when(execRuntime).connect(Mockito.any()); - Mockito.when(execRuntime.isConnected()).thenAnswer(connectionState.isConnectedAnswer()); + Mockito.doAnswer(connectionState.connectAnswer()).when(execRuntime).connectEndpoint(Mockito.any()); + Mockito.when(execRuntime.isEndpointConnected()).thenAnswer(connectionState.isConnectedAnswer()); Mockito.when(execRuntime.execute( Mockito.any(), Mockito.any())).thenReturn(response); @@ -210,8 +210,8 @@ public class TestConnectExec { response.setEntity(new StringEntity("Ka-boom")); final ConnectionState connectionState = new ConnectionState(); - Mockito.doAnswer(connectionState.connectAnswer()).when(execRuntime).connect(Mockito.any()); - Mockito.when(execRuntime.isConnected()).thenAnswer(connectionState.isConnectedAnswer()); + Mockito.doAnswer(connectionState.connectAnswer()).when(execRuntime).connectEndpoint(Mockito.any()); + Mockito.when(execRuntime.isEndpointConnected()).thenAnswer(connectionState.isConnectedAnswer()); Mockito.when(execRuntime.execute( Mockito.any(), Mockito.any())).thenReturn(response); @@ -221,8 +221,8 @@ public class TestConnectExec { exec.execute(request, scope, execChain); } catch (final TunnelRefusedException ex) { Assert.assertEquals("Ka-boom", ex.getResponseMessage()); - Mockito.verify(execRuntime).disconnect(); - Mockito.verify(execRuntime).discardConnection(); + Mockito.verify(execRuntime).disconnectEndpoint(); + Mockito.verify(execRuntime).discardEndpoint(); throw ex; } } @@ -245,8 +245,8 @@ public class TestConnectExec { context.setCredentialsProvider(credentialsProvider); final ConnectionState connectionState = new ConnectionState(); - Mockito.doAnswer(connectionState.connectAnswer()).when(execRuntime).connect(Mockito.any()); - Mockito.when(execRuntime.isConnected()).thenAnswer(connectionState.isConnectedAnswer()); + Mockito.doAnswer(connectionState.connectAnswer()).when(execRuntime).connectEndpoint(Mockito.any()); + Mockito.when(execRuntime.isEndpointConnected()).thenAnswer(connectionState.isConnectedAnswer()); Mockito.when(reuseStrategy.keepAlive( Mockito.same(request), Mockito.any(), @@ -263,7 +263,7 @@ public class TestConnectExec { final ExecChain.Scope scope = new ExecChain.Scope("test", route, request, execRuntime, context); exec.execute(request, scope, execChain); - Mockito.verify(execRuntime).connect(context); + Mockito.verify(execRuntime).connectEndpoint(context); Mockito.verify(inStream1).close(); } @@ -285,8 +285,8 @@ public class TestConnectExec { context.setCredentialsProvider(credentialsProvider); final ConnectionState connectionState = new ConnectionState(); - Mockito.doAnswer(connectionState.connectAnswer()).when(execRuntime).connect(Mockito.any()); - Mockito.when(execRuntime.isConnected()).thenAnswer(connectionState.isConnectedAnswer()); + Mockito.doAnswer(connectionState.connectAnswer()).when(execRuntime).connectEndpoint(Mockito.any()); + Mockito.when(execRuntime.isEndpointConnected()).thenAnswer(connectionState.isConnectedAnswer()); Mockito.when(reuseStrategy.keepAlive( Mockito.same(request), Mockito.any(), @@ -303,9 +303,9 @@ public class TestConnectExec { final ExecChain.Scope scope = new ExecChain.Scope("test", route, request, execRuntime, context); exec.execute(request, scope, execChain); - Mockito.verify(execRuntime).connect(context); + Mockito.verify(execRuntime).connectEndpoint(context); Mockito.verify(inStream1, Mockito.never()).close(); - Mockito.verify(execRuntime).disconnect(); + Mockito.verify(execRuntime).disconnectEndpoint(); } @Test(expected = HttpException.class) @@ -318,8 +318,8 @@ public class TestConnectExec { final ClassicHttpRequest request = new HttpGet("http://bar/test"); final ConnectionState connectionState = new ConnectionState(); - Mockito.doAnswer(connectionState.connectAnswer()).when(execRuntime).connect(Mockito.any()); - Mockito.when(execRuntime.isConnected()).thenAnswer(connectionState.isConnectedAnswer()); + Mockito.doAnswer(connectionState.connectAnswer()).when(execRuntime).connectEndpoint(Mockito.any()); + Mockito.when(execRuntime.isEndpointConnected()).thenAnswer(connectionState.isConnectedAnswer()); final ExecChain.Scope scope = new ExecChain.Scope("test", route, request, execRuntime, context); exec.execute(request, scope, execChain); diff --git a/httpclient5/src/test/java/org/apache/hc/client5/http/impl/classic/TestFutureRequestExecutionService.java b/httpclient5/src/test/java/org/apache/hc/client5/http/impl/classic/TestFutureRequestExecutionService.java index 461cb341d..7b6c4b0d4 100644 --- a/httpclient5/src/test/java/org/apache/hc/client5/http/impl/classic/TestFutureRequestExecutionService.java +++ b/httpclient5/src/test/java/org/apache/hc/client5/http/impl/classic/TestFutureRequestExecutionService.java @@ -35,6 +35,7 @@ import java.util.concurrent.ExecutionException; import java.util.concurrent.ExecutorService; import java.util.concurrent.Executors; import java.util.concurrent.Future; +import java.util.concurrent.FutureTask; import java.util.concurrent.TimeUnit; import java.util.concurrent.TimeoutException; import java.util.concurrent.atomic.AtomicBoolean; @@ -108,14 +109,14 @@ public class TestFutureRequestExecutionService { @Test public void shouldExecuteSingleCall() throws InterruptedException, ExecutionException { - final HttpRequestFutureTask task = httpAsyncClientWithFuture.execute( + final FutureTask task = httpAsyncClientWithFuture.execute( new HttpGet(uri), HttpClientContext.create(), new OkidokiHandler()); Assert.assertTrue("request should have returned OK", task.get().booleanValue()); } @Test(expected=CancellationException.class) public void shouldCancel() throws InterruptedException, ExecutionException { - final HttpRequestFutureTask task = httpAsyncClientWithFuture.execute( + final FutureTask task = httpAsyncClientWithFuture.execute( new HttpGet(uri), HttpClientContext.create(), new OkidokiHandler()); task.cancel(true); task.get(); @@ -124,7 +125,7 @@ public class TestFutureRequestExecutionService { @Test(expected=TimeoutException.class) public void shouldTimeout() throws InterruptedException, ExecutionException, TimeoutException { blocked.set(true); - final HttpRequestFutureTask task = httpAsyncClientWithFuture.execute( + final FutureTask task = httpAsyncClientWithFuture.execute( new HttpGet(uri), HttpClientContext.create(), new OkidokiHandler()); task.get(10, TimeUnit.MILLISECONDS); } diff --git a/httpclient5/src/test/java/org/apache/hc/client5/http/impl/classic/TestInternalExecRuntime.java b/httpclient5/src/test/java/org/apache/hc/client5/http/impl/classic/TestInternalExecRuntime.java index 29e38de5b..6ec3afbb1 100644 --- a/httpclient5/src/test/java/org/apache/hc/client5/http/impl/classic/TestInternalExecRuntime.java +++ b/httpclient5/src/test/java/org/apache/hc/client5/http/impl/classic/TestInternalExecRuntime.java @@ -92,11 +92,11 @@ public class TestInternalExecRuntime { Mockito.when(leaseRequest.get( Mockito.anyLong(), Mockito.any())).thenReturn(connectionEndpoint); - execRuntime.acquireConnection(route, null, context); + execRuntime.acquireEndpoint(route, null, context); - Assert.assertTrue(execRuntime.isConnectionAcquired()); + Assert.assertTrue(execRuntime.isEndpointAcquired()); Assert.assertSame(connectionEndpoint, execRuntime.ensureValid()); - Assert.assertFalse(execRuntime.isConnected()); + Assert.assertFalse(execRuntime.isEndpointConnected()); Assert.assertFalse(execRuntime.isConnectionReusable()); Mockito.verify(leaseRequest).get(345, TimeUnit.MILLISECONDS); @@ -113,12 +113,12 @@ public class TestInternalExecRuntime { Mockito.when(leaseRequest.get( Mockito.anyLong(), Mockito.any())).thenReturn(connectionEndpoint); - execRuntime.acquireConnection(route, null, context); + execRuntime.acquireEndpoint(route, null, context); - Assert.assertTrue(execRuntime.isConnectionAcquired()); + Assert.assertTrue(execRuntime.isEndpointAcquired()); Assert.assertSame(connectionEndpoint, execRuntime.ensureValid()); - execRuntime.acquireConnection(route, null, context); + execRuntime.acquireEndpoint(route, null, context); } @Test(expected = ConnectionRequestTimeoutException.class) @@ -129,7 +129,7 @@ public class TestInternalExecRuntime { Mockito.when(leaseRequest.get( Mockito.anyLong(), Mockito.any())).thenThrow(new TimeoutException("timeout")); - execRuntime.acquireConnection(route, null, context); + execRuntime.acquireEndpoint(route, null, context); } @Test(expected = RequestFailedException.class) @@ -140,7 +140,7 @@ public class TestInternalExecRuntime { Mockito.when(leaseRequest.get( Mockito.anyLong(), Mockito.any())).thenThrow(new ExecutionException(new IllegalStateException())); - execRuntime.acquireConnection(route, null, context); + execRuntime.acquireEndpoint(route, null, context); } @Test @@ -150,16 +150,16 @@ public class TestInternalExecRuntime { Mockito.when(leaseRequest.get( Mockito.anyLong(), Mockito.any())).thenReturn(connectionEndpoint); - execRuntime.acquireConnection(new HttpRoute(new HttpHost("host", 80)), null, context); - Assert.assertTrue(execRuntime.isConnectionAcquired()); - execRuntime.discardConnection(); + execRuntime.acquireEndpoint(new HttpRoute(new HttpHost("host", 80)), null, context); + Assert.assertTrue(execRuntime.isEndpointAcquired()); + execRuntime.discardEndpoint(); - Assert.assertFalse(execRuntime.isConnectionAcquired()); + Assert.assertFalse(execRuntime.isEndpointAcquired()); Mockito.verify(connectionEndpoint).close(CloseMode.IMMEDIATE); Mockito.verify(mgr).release(connectionEndpoint, null, TimeValue.ZERO_MILLISECONDS); - execRuntime.discardConnection(); + execRuntime.discardEndpoint(); Mockito.verify(connectionEndpoint, Mockito.times(1)).close(CloseMode.IMMEDIATE); Mockito.verify(mgr, Mockito.times(1)).release( @@ -176,12 +176,12 @@ public class TestInternalExecRuntime { Mockito.when(leaseRequest.get( Mockito.anyLong(), Mockito.any())).thenReturn(connectionEndpoint); - execRuntime.acquireConnection(route, null, context); - Assert.assertTrue(execRuntime.isConnectionAcquired()); + execRuntime.acquireEndpoint(route, null, context); + Assert.assertTrue(execRuntime.isEndpointAcquired()); Assert.assertTrue(execRuntime.cancel()); - Assert.assertFalse(execRuntime.isConnectionAcquired()); + Assert.assertFalse(execRuntime.isEndpointAcquired()); Mockito.verify(connectionEndpoint).close(CloseMode.IMMEDIATE); Mockito.verify(mgr).release(connectionEndpoint, null, TimeValue.ZERO_MILLISECONDS); @@ -203,19 +203,19 @@ public class TestInternalExecRuntime { Mockito.when(leaseRequest.get( Mockito.anyLong(), Mockito.any())).thenReturn(connectionEndpoint); - execRuntime.acquireConnection(route, null, context); - Assert.assertTrue(execRuntime.isConnectionAcquired()); + execRuntime.acquireEndpoint(route, null, context); + Assert.assertTrue(execRuntime.isEndpointAcquired()); execRuntime.markConnectionReusable("some state", TimeValue.ofMillis(100000)); - execRuntime.releaseConnection(); + execRuntime.releaseEndpoint(); - Assert.assertFalse(execRuntime.isConnectionAcquired()); + Assert.assertFalse(execRuntime.isEndpointAcquired()); Mockito.verify(connectionEndpoint, Mockito.never()).close(); Mockito.verify(mgr).release(connectionEndpoint, "some state", TimeValue.ofMillis(100000)); - execRuntime.releaseConnection(); + execRuntime.releaseEndpoint(); Mockito.verify(mgr, Mockito.times(1)).release( Mockito.any(), @@ -231,20 +231,20 @@ public class TestInternalExecRuntime { Mockito.when(leaseRequest.get( Mockito.anyLong(), Mockito.any())).thenReturn(connectionEndpoint); - execRuntime.acquireConnection(route, null, context); - Assert.assertTrue(execRuntime.isConnectionAcquired()); + execRuntime.acquireEndpoint(route, null, context); + Assert.assertTrue(execRuntime.isEndpointAcquired()); execRuntime.markConnectionReusable("some state", TimeValue.ofMillis(100000)); execRuntime.markConnectionNonReusable(); - execRuntime.releaseConnection(); + execRuntime.releaseEndpoint(); - Assert.assertFalse(execRuntime.isConnectionAcquired()); + Assert.assertFalse(execRuntime.isEndpointAcquired()); Mockito.verify(connectionEndpoint, Mockito.times(1)).close(); Mockito.verify(mgr).release(connectionEndpoint, null, TimeValue.ZERO_MILLISECONDS); - execRuntime.releaseConnection(); + execRuntime.releaseEndpoint(); Mockito.verify(mgr, Mockito.times(1)).release( Mockito.any(), @@ -265,13 +265,13 @@ public class TestInternalExecRuntime { Mockito.when(leaseRequest.get( Mockito.anyLong(), Mockito.any())).thenReturn(connectionEndpoint); - execRuntime.acquireConnection(route, null, context); - Assert.assertTrue(execRuntime.isConnectionAcquired()); + execRuntime.acquireEndpoint(route, null, context); + Assert.assertTrue(execRuntime.isEndpointAcquired()); Mockito.when(connectionEndpoint.isConnected()).thenReturn(false); - Assert.assertFalse(execRuntime.isConnected()); + Assert.assertFalse(execRuntime.isEndpointConnected()); - execRuntime.connect(context); + execRuntime.connectEndpoint(context); Mockito.verify(mgr).connect(connectionEndpoint, TimeValue.ofMillis(123), context); Mockito.verify(connectionEndpoint).setSocketTimeout(123); @@ -285,18 +285,18 @@ public class TestInternalExecRuntime { Mockito.when(leaseRequest.get( Mockito.anyLong(), Mockito.any())).thenReturn(connectionEndpoint); - execRuntime.acquireConnection(route, null, context); - Assert.assertTrue(execRuntime.isConnectionAcquired()); + execRuntime.acquireEndpoint(route, null, context); + Assert.assertTrue(execRuntime.isEndpointAcquired()); Mockito.when(connectionEndpoint.isConnected()).thenReturn(true); - Assert.assertTrue(execRuntime.isConnected()); + Assert.assertTrue(execRuntime.isEndpointConnected()); - execRuntime.connect(context); + execRuntime.connectEndpoint(context); Mockito.verify(mgr, Mockito.never()).connect( Mockito.same(connectionEndpoint), Mockito.any(), Mockito.any()); - execRuntime.disconnect(); + execRuntime.disconnectEndpoint(); Mockito.verify(connectionEndpoint).close(); } diff --git a/httpclient5/src/test/java/org/apache/hc/client5/http/impl/classic/TestMainClientExec.java b/httpclient5/src/test/java/org/apache/hc/client5/http/impl/classic/TestMainClientExec.java index 5991849d8..9b4ef4df1 100644 --- a/httpclient5/src/test/java/org/apache/hc/client5/http/impl/classic/TestMainClientExec.java +++ b/httpclient5/src/test/java/org/apache/hc/client5/http/impl/classic/TestMainClientExec.java @@ -90,7 +90,7 @@ public class TestMainClientExec { .setStream(new ByteArrayInputStream(new byte[]{})) .build()); - Mockito.when(endpoint.isConnectionAcquired()).thenReturn(false); + Mockito.when(endpoint.isEndpointAcquired()).thenReturn(false); Mockito.when(endpoint.execute( Mockito.same(request), Mockito.any())).thenReturn(response); @@ -103,7 +103,7 @@ public class TestMainClientExec { final ClassicHttpResponse finalResponse = mainClientExec.execute(request, scope, null); Mockito.verify(endpoint).execute(request, context); Mockito.verify(endpoint, Mockito.times(1)).markConnectionNonReusable(); - Mockito.verify(endpoint, Mockito.never()).releaseConnection(); + Mockito.verify(endpoint, Mockito.never()).releaseEndpoint(); Assert.assertNull(context.getUserToken()); Assert.assertNotNull(finalResponse); @@ -118,7 +118,7 @@ public class TestMainClientExec { final ClassicHttpResponse response = new BasicClassicHttpResponse(200, "OK"); response.setEntity(null); - Mockito.when(endpoint.isConnectionAcquired()).thenReturn(false); + Mockito.when(endpoint.isEndpointAcquired()).thenReturn(false); Mockito.when(endpoint.execute( Mockito.same(request), Mockito.any())).thenReturn(response); @@ -132,7 +132,7 @@ public class TestMainClientExec { Mockito.verify(endpoint).execute(request, context); Mockito.verify(endpoint).markConnectionNonReusable(); - Mockito.verify(endpoint).releaseConnection(); + Mockito.verify(endpoint).releaseEndpoint(); Assert.assertNotNull(finalResponse); Assert.assertTrue(finalResponse instanceof CloseableHttpResponse); @@ -150,8 +150,8 @@ public class TestMainClientExec { .build()); final ConnectionState connectionState = new ConnectionState(); - Mockito.doAnswer(connectionState.connectAnswer()).when(endpoint).connect(Mockito.any()); - Mockito.when(endpoint.isConnected()).thenAnswer(connectionState.isConnectedAnswer()); + Mockito.doAnswer(connectionState.connectAnswer()).when(endpoint).connectEndpoint(Mockito.any()); + Mockito.when(endpoint.isEndpointConnected()).thenAnswer(connectionState.isConnectedAnswer()); Mockito.when(endpoint.execute( Mockito.same(request), Mockito.any())).thenReturn(response); @@ -168,7 +168,7 @@ public class TestMainClientExec { Mockito.verify(endpoint).execute(request, context); Mockito.verify(endpoint).markConnectionReusable(null, TimeValue.ofMillis(678L)); - Mockito.verify(endpoint, Mockito.never()).releaseConnection(); + Mockito.verify(endpoint, Mockito.never()).releaseEndpoint(); Assert.assertNotNull(finalResponse); Assert.assertTrue(finalResponse instanceof CloseableHttpResponse); @@ -182,8 +182,8 @@ public class TestMainClientExec { final ClassicHttpResponse response = new BasicClassicHttpResponse(200, "OK"); final ConnectionState connectionState = new ConnectionState(); - Mockito.doAnswer(connectionState.connectAnswer()).when(endpoint).connect(Mockito.any()); - Mockito.when(endpoint.isConnected()).thenAnswer(connectionState.isConnectedAnswer()); + Mockito.doAnswer(connectionState.connectAnswer()).when(endpoint).connectEndpoint(Mockito.any()); + Mockito.when(endpoint.isEndpointConnected()).thenAnswer(connectionState.isConnectedAnswer()); Mockito.when(endpoint.execute( Mockito.same(request), Mockito.any())).thenReturn(response); @@ -199,7 +199,7 @@ public class TestMainClientExec { final ClassicHttpResponse finalResponse = mainClientExec.execute(request, scope, null); Mockito.verify(endpoint).execute(request, context); - Mockito.verify(endpoint).releaseConnection(); + Mockito.verify(endpoint).releaseEndpoint(); Assert.assertNotNull(finalResponse); Assert.assertTrue(finalResponse instanceof CloseableHttpResponse); @@ -217,8 +217,8 @@ public class TestMainClientExec { .build()); final ConnectionState connectionState = new ConnectionState(); - Mockito.doAnswer(connectionState.connectAnswer()).when(endpoint).connect(Mockito.any()); - Mockito.when(endpoint.isConnected()).thenAnswer(connectionState.isConnectedAnswer()); + Mockito.doAnswer(connectionState.connectAnswer()).when(endpoint).connectEndpoint(Mockito.any()); + Mockito.when(endpoint.isEndpointConnected()).thenAnswer(connectionState.isConnectedAnswer()); Mockito.when(endpoint.execute( Mockito.same(request), Mockito.any())).thenReturn(response); @@ -230,15 +230,15 @@ public class TestMainClientExec { final ExecChain.Scope scope = new ExecChain.Scope("test", route, request, endpoint, context); final ClassicHttpResponse finalResponse = mainClientExec.execute(request, scope, null); Mockito.verify(endpoint, Mockito.times(1)).execute(request, context); - Mockito.verify(endpoint, Mockito.never()).disconnect(); - Mockito.verify(endpoint, Mockito.never()).releaseConnection(); + Mockito.verify(endpoint, Mockito.never()).disconnectEndpoint(); + Mockito.verify(endpoint, Mockito.never()).releaseEndpoint(); Assert.assertNotNull(finalResponse); Assert.assertTrue(finalResponse instanceof CloseableHttpResponse); finalResponse.close(); - Mockito.verify(endpoint).disconnect(); - Mockito.verify(endpoint).discardConnection(); + Mockito.verify(endpoint).disconnectEndpoint(); + Mockito.verify(endpoint).discardEndpoint(); } @Test(expected=InterruptedIOException.class) @@ -255,7 +255,7 @@ public class TestMainClientExec { try { mainClientExec.execute(request, scope, null); } catch (final Exception ex) { - Mockito.verify(endpoint).discardConnection(); + Mockito.verify(endpoint).discardEndpoint(); throw ex; } } @@ -274,7 +274,7 @@ public class TestMainClientExec { try { mainClientExec.execute(request, scope, null); } catch (final Exception ex) { - Mockito.verify(endpoint).discardConnection(); + Mockito.verify(endpoint).discardEndpoint(); throw ex; } } @@ -293,7 +293,7 @@ public class TestMainClientExec { try { mainClientExec.execute(request, scope, null); } catch (final Exception ex) { - Mockito.verify(endpoint).discardConnection(); + Mockito.verify(endpoint).discardEndpoint(); throw ex; } } @@ -312,7 +312,7 @@ public class TestMainClientExec { try { mainClientExec.execute(request, scope, null); } catch (final Exception ex) { - Mockito.verify(endpoint).discardConnection(); + Mockito.verify(endpoint).discardEndpoint(); throw ex; } } diff --git a/httpclient5/src/test/java/org/apache/hc/client5/http/impl/classic/TestProtocolExec.java b/httpclient5/src/test/java/org/apache/hc/client5/http/impl/classic/TestProtocolExec.java index b385dc18a..3ee14be4d 100644 --- a/httpclient5/src/test/java/org/apache/hc/client5/http/impl/classic/TestProtocolExec.java +++ b/httpclient5/src/test/java/org/apache/hc/client5/http/impl/classic/TestProtocolExec.java @@ -160,7 +160,7 @@ public class TestProtocolExec { try { protocolExec.execute(request, scope, chain); } catch (final Exception ex) { - Mockito.verify(execRuntime).discardConnection(); + Mockito.verify(execRuntime).discardEndpoint(); throw ex; } } @@ -181,7 +181,7 @@ public class TestProtocolExec { try { protocolExec.execute(request, scope, chain); } catch (final Exception ex) { - Mockito.verify(execRuntime).discardConnection(); + Mockito.verify(execRuntime).discardEndpoint(); throw ex; } } @@ -202,7 +202,7 @@ public class TestProtocolExec { try { protocolExec.execute(request, scope, chain); } catch (final Exception ex) { - Mockito.verify(execRuntime).discardConnection(); + Mockito.verify(execRuntime).discardEndpoint(); throw ex; } } @@ -286,7 +286,7 @@ public class TestProtocolExec { final ExecChain.Scope scope = new ExecChain.Scope("test", route, request, execRuntime, context); final ClassicHttpResponse finalResponse = protocolExec.execute(request, scope, chain); Mockito.verify(chain, Mockito.times(2)).proceed(request, scope); - Mockito.verify(execRuntime).disconnect(); + Mockito.verify(execRuntime).disconnectEndpoint(); Mockito.verify(inStream2, Mockito.never()).close(); Assert.assertNotNull(finalResponse); diff --git a/httpclient5/src/test/java/org/apache/hc/client5/http/impl/classic/TestResponseEntityWrapper.java b/httpclient5/src/test/java/org/apache/hc/client5/http/impl/classic/TestResponseEntityWrapper.java index a8ad4e46a..3f74f0a80 100644 --- a/httpclient5/src/test/java/org/apache/hc/client5/http/impl/classic/TestResponseEntityWrapper.java +++ b/httpclient5/src/test/java/org/apache/hc/client5/http/impl/classic/TestResponseEntityWrapper.java @@ -63,7 +63,7 @@ public class TestResponseEntityWrapper { EntityUtils.consume(wrapper); Mockito.verify(inStream, Mockito.times(1)).close(); - Mockito.verify(execRuntime).releaseConnection(); + Mockito.verify(execRuntime).releaseEndpoint(); } @Test @@ -76,17 +76,17 @@ public class TestResponseEntityWrapper { Assert.fail("IOException expected"); } catch (final IOException ex) { } - Mockito.verify(execRuntime, Mockito.atLeast(1)).discardConnection(); + Mockito.verify(execRuntime, Mockito.atLeast(1)).discardEndpoint(); } @Test public void testEntityStreamClosedIOErrorAlreadyReleased() throws Exception { Mockito.when(entity.isStreaming()).thenReturn(true); Mockito.when(execRuntime.isConnectionReusable()).thenReturn(true); - Mockito.when(execRuntime.isConnectionAcquired()).thenReturn(false); + Mockito.when(execRuntime.isEndpointAcquired()).thenReturn(false); Mockito.doThrow(new SocketException()).when(inStream).close(); EntityUtils.consume(wrapper); - Mockito.verify(execRuntime).discardConnection(); + Mockito.verify(execRuntime).discardEndpoint(); } @Test @@ -95,7 +95,7 @@ public class TestResponseEntityWrapper { Mockito.when(entity.isStreaming()).thenReturn(true); Mockito.when(execRuntime.isConnectionReusable()).thenReturn(true); wrapper.writeTo(outStream); - Mockito.verify(execRuntime).releaseConnection(); + Mockito.verify(execRuntime).releaseEndpoint(); } @Test @@ -109,8 +109,8 @@ public class TestResponseEntityWrapper { Assert.fail("IOException expected"); } catch (final IOException ex) { } - Mockito.verify(execRuntime, Mockito.never()).releaseConnection(); - Mockito.verify(execRuntime, Mockito.atLeast(1)).discardConnection(); + Mockito.verify(execRuntime, Mockito.never()).releaseEndpoint(); + Mockito.verify(execRuntime, Mockito.atLeast(1)).discardEndpoint(); } @Test @@ -121,7 +121,7 @@ public class TestResponseEntityWrapper { final InputStream content = wrapper.getContent(); Assert.assertEquals(-1, content.read()); Mockito.verify(inStream).close(); - Mockito.verify(execRuntime).releaseConnection(); + Mockito.verify(execRuntime).releaseEndpoint(); } @Test @@ -136,7 +136,7 @@ public class TestResponseEntityWrapper { Assert.fail("IOException expected"); } catch (final IOException ex) { } - Mockito.verify(execRuntime, Mockito.atLeast(1)).discardConnection(); + Mockito.verify(execRuntime, Mockito.atLeast(1)).discardEndpoint(); } }