Component docs improved for http4
Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/7c11420c Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/7c11420c Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/7c11420c Branch: refs/heads/master Commit: 7c11420c80ce3753b717b8bc233c84eaaf3c888d Parents: 6c66df2 Author: Claus Ibsen <davscl...@apache.org> Authored: Wed Mar 15 11:19:32 2017 +0100 Committer: Claus Ibsen <davscl...@apache.org> Committed: Wed Mar 15 11:53:47 2017 +0100 ---------------------------------------------------------------------- .../camel/http/common/HttpCommonComponent.java | 8 +- .../src/main/docs/http4-component.adoc | 10 +-- .../camel/component/http4/HttpComponent.java | 54 ++++-------- .../camel/component/http4/HttpEndpoint.java | 58 ++++++------- .../springboot/HttpComponentConfiguration.java | 86 ++++++++++---------- 5 files changed, 98 insertions(+), 118 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/7c11420c/components/camel-http-common/src/main/java/org/apache/camel/http/common/HttpCommonComponent.java ---------------------------------------------------------------------- diff --git a/components/camel-http-common/src/main/java/org/apache/camel/http/common/HttpCommonComponent.java b/components/camel-http-common/src/main/java/org/apache/camel/http/common/HttpCommonComponent.java index 20191d1..c5036ee 100644 --- a/components/camel-http-common/src/main/java/org/apache/camel/http/common/HttpCommonComponent.java +++ b/components/camel-http-common/src/main/java/org/apache/camel/http/common/HttpCommonComponent.java @@ -24,11 +24,13 @@ import org.apache.camel.util.CamelContextHelper; public abstract class HttpCommonComponent extends HeaderFilterStrategyComponent { - @Metadata(label = "advanced") + @Metadata(label = "advanced", description = "To use a custom HttpBinding to control the mapping between Camel message and HttpClient.") protected HttpBinding httpBinding; - @Metadata(label = "advanced") + @Metadata(label = "advanced", description = "To use the shared HttpConfiguration as base configuration.") protected HttpConfiguration httpConfiguration; - @Metadata(label = "advanced") + @Metadata(label = "advanced", description = "Whether to allow java serialization when a request uses context-type=application/x-java-serialized-object." + + " This is by default turned off. " + + " If you enable this then be aware that Java will deserialize the incoming data from the request to Java and that can be a potential security risk.") protected boolean allowJavaSerializedObject; public HttpCommonComponent(Class<? extends HttpCommonEndpoint> endpointClass) { http://git-wip-us.apache.org/repos/asf/camel/blob/7c11420c/components/camel-http4/src/main/docs/http4-component.adoc ---------------------------------------------------------------------- diff --git a/components/camel-http4/src/main/docs/http4-component.adoc b/components/camel-http4/src/main/docs/http4-component.adoc index ddfc98c..3e95fc2 100644 --- a/components/camel-http4/src/main/docs/http4-component.adoc +++ b/components/camel-http4/src/main/docs/http4-component.adoc @@ -60,9 +60,6 @@ The HTTP4 component supports 14 options which are listed below. | Name | Group | Default | Java Type | Description | httpClientConfigurer | advanced | | HttpClientConfigurer | To use the custom HttpClientConfigurer to perform configuration of the HttpClient that will be used. | clientConnectionManager | advanced | | HttpClientConnectionManager | To use a custom and shared HttpClientConnectionManager to manage connections. If this has been configured then this is always used for all endpoints created by this component. -| httpBinding | producer | | HttpBinding | To use a custom HttpBinding to control the mapping between Camel message and HttpClient. -| httpConfiguration | producer | | HttpConfiguration | To use the shared HttpConfiguration as base configuration. -| allowJavaSerializedObject | producer | false | boolean | Whether to allow java serialization when a request uses context-type=application/x-java-serialized-object This is by default turned off. If you enable this then be aware that Java will deserialize the incoming data from the request to Java and that can be a potential security risk. | httpContext | advanced | | HttpContext | To use a custom org.apache.http.protocol.HttpContext when executing requests. | sslContextParameters | security | | SSLContextParameters | To configure security using SSLContextParameters. Important: Only one instance of org.apache.camel.util.jsse.SSLContextParameters is supported per HttpComponent. If you need to use 2 or more different instances you need to define a new HttpComponent per instance you need. | x509HostnameVerifier | security | | HostnameVerifier | To use a custom X509HostnameVerifier such as DefaultHostnameVerifier or org.apache.http.conn.ssl.NoopHostnameVerifier. @@ -70,6 +67,9 @@ The HTTP4 component supports 14 options which are listed below. | connectionsPerRoute | advanced | 20 | int | The maximum number of connections per route. | connectionTimeToLive | advanced | | long | The time for connection to live the time unit is millisecond the default value is always keep alive. | cookieStore | producer | | CookieStore | To use a custom org.apache.http.client.CookieStore. By default the org.apache.http.impl.client.BasicCookieStore is used which is an in-memory only cookie store. Notice if bridgeEndpoint=true then the cookie store is forced to be a noop cookie store as cookie shouldn't be stored as we are just bridging (eg acting as a proxy). +| httpBinding | advanced | | HttpBinding | To use a custom HttpBinding to control the mapping between Camel message and HttpClient. +| httpConfiguration | advanced | | HttpConfiguration | To use the shared HttpConfiguration as base configuration. +| allowJavaSerializedObject | advanced | false | boolean | Whether to allow java serialization when a request uses context-type=application/x-java-serialized-object. This is by default turned off. If you enable this then be aware that Java will deserialize the incoming data from the request to Java and that can be a potential security risk. | headerFilterStrategy | filter | | HeaderFilterStrategy | To use a custom org.apache.camel.spi.HeaderFilterStrategy to filter header to and from Camel message. | resolvePropertyPlaceholders | advanced | true | boolean | Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders. |======================================================================= @@ -112,7 +112,7 @@ with the following path and query parameters: | chunked | producer | true | boolean | If this option is false the Servlet will disable the HTTP streaming and set the content-length header on the response | clearExpiredCookies | producer | true | boolean | Whether to clear expired cookies before sending the HTTP request. This ensures the cookies store does not keep growing by adding new cookies which is newer removed when they are expired. | connectionClose | producer | false | boolean | Specifies whether a Connection Close header must be added to HTTP Request. By default connectionClose is false. -| cookieStore | producer | | CookieStore | To use a custom org.apache.http.client.CookieStore. By default the org.apache.http.impl.client.BasicCookieStore is used which is an in-memory only cookie store. Notice if bridgeEndpoint=true then the cookie store is forced to be a noop cookie store as cookie shouldn't be stored as we are just bridging (eg acting as a proxy). If a cookieHandler is set then the cookie store is also forced to be a noop cookie store as cookie handling is then performed by the cookieHandler. +| cookieStore | producer | | CookieStore | To use a custom CookieStore. By default the BasicCookieStore is used which is an in-memory only cookie store. Notice if bridgeEndpoint=true then the cookie store is forced to be a noop cookie store as cookie shouldn't be stored as we are just bridging (eg acting as a proxy). If a cookieHandler is set then the cookie store is also forced to be a noop cookie store as cookie handling is then performed by the cookieHandler. | copyHeaders | producer | true | boolean | If this option is true then IN exchange headers will be copied to OUT exchange headers according to copy strategy. Setting this to false allows to only include the headers from the HTTP response (not propagating IN headers). | deleteWithBody | producer | false | boolean | Whether the HTTP DELETE should include the message body or not. By default HTTP DELETE do not include any HTTP message. However in some rare cases users may need to be able to include the message body. | httpMethod | producer | | HttpMethods | Configure the HTTP method to use. The HttpMethod header cannot override this option if set. @@ -126,7 +126,7 @@ with the following path and query parameters: | clientBuilder | advanced | | HttpClientBuilder | Provide access to the http client request parameters used on new RequestConfig instances used by producers or consumers of this endpoint. | clientConnectionManager | advanced | | HttpClientConnectionManager | To use a custom HttpClientConnectionManager to manage connections | connectionsPerRoute | advanced | 20 | int | The maximum number of connections per route. -| httpClient | advanced | | HttpClient | Gets the HttpClient to be used by org.apache.camel.component.http4.HttpProducer +| httpClient | advanced | | HttpClient | Sets a custom HttpClient to be used by the producer | httpClientConfigurer | advanced | | HttpClientConfigurer | Register a custom configuration strategy for new HttpClient instances created by producers or consumers such as to configure authentication mechanisms etc | httpClientOptions | advanced | | Map | To configure the HttpClient using the key/values from the Map. | httpContext | advanced | | HttpContext | To use a custom HttpContext instance http://git-wip-us.apache.org/repos/asf/camel/blob/7c11420c/components/camel-http4/src/main/java/org/apache/camel/component/http4/HttpComponent.java ---------------------------------------------------------------------- diff --git a/components/camel-http4/src/main/java/org/apache/camel/component/http4/HttpComponent.java b/components/camel-http4/src/main/java/org/apache/camel/component/http4/HttpComponent.java index 1f84508..0a9ced9 100644 --- a/components/camel-http4/src/main/java/org/apache/camel/component/http4/HttpComponent.java +++ b/components/camel-http4/src/main/java/org/apache/camel/component/http4/HttpComponent.java @@ -34,7 +34,6 @@ import org.apache.camel.VerifiableComponent; import org.apache.camel.ResolveEndpointFailedException; import org.apache.camel.http.common.HttpBinding; import org.apache.camel.http.common.HttpCommonComponent; -import org.apache.camel.http.common.HttpConfiguration; import org.apache.camel.http.common.HttpHelper; import org.apache.camel.http.common.HttpRestHeaderFilterStrategy; import org.apache.camel.http.common.UrlRewrite; @@ -75,26 +74,32 @@ public class HttpComponent extends HttpCommonComponent implements RestProducerFa private static final Logger LOG = LoggerFactory.getLogger(HttpComponent.class); - @Metadata(label = "advanced") + @Metadata(label = "advanced", description = "To use the custom HttpClientConfigurer to perform configuration of the HttpClient that will be used.") protected HttpClientConfigurer httpClientConfigurer; - @Metadata(label = "advanced") + @Metadata(label = "advanced", description = "To use a custom and shared HttpClientConnectionManager to manage connections." + + " If this has been configured then this is always used for all endpoints created by this component.") protected HttpClientConnectionManager clientConnectionManager; - @Metadata(label = "advanced") + @Metadata(label = "advanced", description = "To use a custom org.apache.http.protocol.HttpContext when executing requests.") protected HttpContext httpContext; - @Metadata(label = "security") + @Metadata(label = "security", description = "To configure security using SSLContextParameters." + + " Important: Only one instance of org.apache.camel.util.jsse.SSLContextParameters is supported per HttpComponent." + + " If you need to use 2 or more different instances, you need to define a new HttpComponent per instance you need.") protected SSLContextParameters sslContextParameters; - @Metadata(label = "security") + @Metadata(label = "security", description = "To use a custom X509HostnameVerifier such as DefaultHostnameVerifier or NoopHostnameVerifier.") protected HostnameVerifier x509HostnameVerifier = new DefaultHostnameVerifier(); - @Metadata(label = "producer") + @Metadata(label = "producer", description = "To use a custom org.apache.http.client.CookieStore." + + " By default the org.apache.http.impl.client.BasicCookieStore is used which is an in-memory only cookie store." + + " Notice if bridgeEndpoint=true then the cookie store is forced to be a noop cookie store as cookie" + + " shouldn't be stored as we are just bridging (eg acting as a proxy).") protected CookieStore cookieStore; // options to the default created http connection manager - @Metadata(label = "advanced", defaultValue = "200") + @Metadata(label = "advanced", defaultValue = "200", description = "The maximum number of connections.") protected int maxTotalConnections = 200; - @Metadata(label = "advanced", defaultValue = "20") + @Metadata(label = "advanced", defaultValue = "20", description = "The maximum number of connections per route.") protected int connectionsPerRoute = 20; // It's MILLISECONDS, the default value is always keep alive - @Metadata(label = "advanced") + @Metadata(label = "advanced", description = "The time for connection to live, the time unit is millisecond, the default value is always keep alive.") protected long connectionTimeToLive = -1; public HttpComponent() { @@ -426,35 +431,6 @@ public class HttpComponent extends HttpCommonComponent implements RestProducerFa this.clientConnectionManager = clientConnectionManager; } - /** - * To use a custom HttpBinding to control the mapping between Camel message and HttpClient. - */ - public void setHttpBinding(HttpBinding httpBinding) { - // need to override and call super for component docs - super.setHttpBinding(httpBinding); - } - - /** - * To use the shared HttpConfiguration as base configuration. - */ - @Override - public void setHttpConfiguration(HttpConfiguration httpConfiguration) { - // need to override and call super for component docs - super.setHttpConfiguration(httpConfiguration); - } - - /** - * Whether to allow java serialization when a request uses context-type=application/x-java-serialized-object - * <p/> - * This is by default turned off. If you enable this then be aware that Java will deserialize the incoming - * data from the request to Java and that can be a potential security risk. - */ - @Override - public void setAllowJavaSerializedObject(boolean allowJavaSerializedObject) { - // need to override and call super for component docs - super.setAllowJavaSerializedObject(allowJavaSerializedObject); - } - public HttpContext getHttpContext() { return httpContext; } http://git-wip-us.apache.org/repos/asf/camel/blob/7c11420c/components/camel-http4/src/main/java/org/apache/camel/component/http4/HttpEndpoint.java ---------------------------------------------------------------------- diff --git a/components/camel-http4/src/main/java/org/apache/camel/component/http4/HttpEndpoint.java b/components/camel-http4/src/main/java/org/apache/camel/component/http4/HttpEndpoint.java index 6e3315b..0ffaab4 100644 --- a/components/camel-http4/src/main/java/org/apache/camel/component/http4/HttpEndpoint.java +++ b/components/camel-http4/src/main/java/org/apache/camel/component/http4/HttpEndpoint.java @@ -54,35 +54,41 @@ public class HttpEndpoint extends HttpCommonEndpoint { private static final Logger LOG = LoggerFactory.getLogger(HttpEndpoint.class); - @UriParam(label = "advanced") + @UriParam(label = "advanced", description = "To use a custom HttpContext instance") private HttpContext httpContext; - @UriParam(label = "advanced") + @UriParam(label = "advanced", description = "Register a custom configuration strategy for new HttpClient instances" + + " created by producers or consumers such as to configure authentication mechanisms etc.") private HttpClientConfigurer httpClientConfigurer; - @UriParam(label = "advanced", prefix = "httpClient.", multiValue = true) + @UriParam(label = "advanced", prefix = "httpClient.", multiValue = true, description = "To configure the HttpClient using the key/values from the Map.") private Map<String, Object> httpClientOptions; - @UriParam(label = "advanced") + @UriParam(label = "advanced", description = "To use a custom HttpClientConnectionManager to manage connections") private HttpClientConnectionManager clientConnectionManager; - @UriParam(label = "advanced") + @UriParam(label = "advanced", description = "Provide access to the http client request parameters used on new RequestConfig instances used by producers or consumers of this endpoint.") private HttpClientBuilder clientBuilder; - @UriParam(label = "advanced") + @UriParam(label = "advanced", description = "Sets a custom HttpClient to be used by the producer") private HttpClient httpClient; - @UriParam(label = "advanced", defaultValue = "false") + @UriParam(label = "advanced", defaultValue = "false", description = "To use System Properties as fallback for configuration") private boolean useSystemProperties; - @UriParam(label = "producer") + @UriParam(label = "producer", description = "To use a custom CookieStore." + + " By default the BasicCookieStore is used which is an in-memory only cookie store." + + " Notice if bridgeEndpoint=true then the cookie store is forced to be a noop cookie store as cookie shouldn't be stored as we are just bridging (eg acting as a proxy)." + + " If a cookieHandler is set then the cookie store is also forced to be a noop cookie store as cookie handling is then performed by the cookieHandler.") private CookieStore cookieStore = new BasicCookieStore(); - @UriParam(label = "producer") - private boolean authenticationPreemptive; - @UriParam(label = "producer", defaultValue = "true") + @UriParam(label = "producer", defaultValue = "true", description = "Whether to clear expired cookies before sending the HTTP request." + + " This ensures the cookies store does not keep growing by adding new cookies which is newer removed when they are expired.") private boolean clearExpiredCookies = true; - @UriParam(label = "producer") + @UriParam(label = "producer", description = "If this option is true, camel-http4 sends preemptive basic authentication to the server.") + private boolean authenticationPreemptive; + @UriParam(label = "producer", description = "Whether the HTTP DELETE should include the message body or not." + + " By default HTTP DELETE do not include any HTTP message. However in some rare cases users may need to be able to include the message body.") private boolean deleteWithBody; - @UriParam(label = "advanced", defaultValue = "200") + @UriParam(label = "advanced", defaultValue = "200", description = "The maximum number of connections.") private int maxTotalConnections; - @UriParam(label = "advanced", defaultValue = "20") + @UriParam(label = "advanced", defaultValue = "20", description = "The maximum number of connections per route.") private int connectionsPerRoute; - @UriParam(label = "security") + @UriParam(label = "security", description = "To use a custom X509HostnameVerifier such as DefaultHostnameVerifier or NoopHostnameVerifier") private HostnameVerifier x509HostnameVerifier; public HttpEndpoint() { @@ -124,9 +130,6 @@ public class HttpEndpoint extends HttpCommonEndpoint { return answer; } - /** - * Gets the HttpClient to be used by {@link org.apache.camel.component.http4.HttpProducer} - */ public synchronized HttpClient getHttpClient() { if (httpClient == null) { httpClient = createHttpClient(); @@ -134,6 +137,9 @@ public class HttpEndpoint extends HttpCommonEndpoint { return httpClient; } + /** + * Sets a custom HttpClient to be used by the producer + */ public void setHttpClient(HttpClient httpClient) { this.httpClient = httpClient; } @@ -211,10 +217,6 @@ public class HttpEndpoint extends HttpCommonEndpoint { // Properties //------------------------------------------------------------------------- - /** - * Provide access to the http client request parameters used on new {@link RequestConfig} instances - * used by producers or consumers of this endpoint. - */ public HttpClientBuilder getClientBuilder() { return clientBuilder; } @@ -231,10 +233,6 @@ public class HttpEndpoint extends HttpCommonEndpoint { return httpClientConfigurer; } - public HttpContext getHttpContext() { - return httpContext; - } - /** * Register a custom configuration strategy for new {@link HttpClient} instances * created by producers or consumers such as to configure authentication mechanisms etc @@ -243,6 +241,10 @@ public class HttpEndpoint extends HttpCommonEndpoint { this.httpClientConfigurer = httpClientConfigurer; } + public HttpContext getHttpContext() { + return httpContext; + } + /** * To use a custom HttpContext instance */ @@ -292,8 +294,8 @@ public class HttpEndpoint extends HttpCommonEndpoint { } /** - * To use a custom org.apache.http.client.CookieStore. - * By default the org.apache.http.impl.client.BasicCookieStore is used which is an in-memory only cookie store. + * To use a custom CookieStore. + * By default the BasicCookieStore is used which is an in-memory only cookie store. * Notice if bridgeEndpoint=true then the cookie store is forced to be a noop cookie store as cookie * shouldn't be stored as we are just bridging (eg acting as a proxy). * If a cookieHandler is set then the cookie store is also forced to be a noop cookie store as cookie handling is http://git-wip-us.apache.org/repos/asf/camel/blob/7c11420c/platforms/spring-boot/components-starter/camel-http4-starter/src/main/java/org/apache/camel/component/http4/springboot/HttpComponentConfiguration.java ---------------------------------------------------------------------- diff --git a/platforms/spring-boot/components-starter/camel-http4-starter/src/main/java/org/apache/camel/component/http4/springboot/HttpComponentConfiguration.java b/platforms/spring-boot/components-starter/camel-http4-starter/src/main/java/org/apache/camel/component/http4/springboot/HttpComponentConfiguration.java index e47e608..5bf2dac 100644 --- a/platforms/spring-boot/components-starter/camel-http4-starter/src/main/java/org/apache/camel/component/http4/springboot/HttpComponentConfiguration.java +++ b/platforms/spring-boot/components-starter/camel-http4-starter/src/main/java/org/apache/camel/component/http4/springboot/HttpComponentConfiguration.java @@ -50,25 +50,6 @@ public class HttpComponentConfiguration { @NestedConfigurationProperty private HttpClientConnectionManager clientConnectionManager; /** - * To use a custom HttpBinding to control the mapping between Camel message - * and HttpClient. - */ - @NestedConfigurationProperty - private HttpBinding httpBinding; - /** - * To use the shared HttpConfiguration as base configuration. - */ - @NestedConfigurationProperty - private HttpConfiguration httpConfiguration; - /** - * Whether to allow java serialization when a request uses - * context-type=application/x-java-serialized-object This is by default - * turned off. If you enable this then be aware that Java will deserialize - * the incoming data from the request to Java and that can be a potential - * security risk. - */ - private Boolean allowJavaSerializedObject = false; - /** * To use a custom org.apache.http.protocol.HttpContext when executing * requests. */ @@ -110,6 +91,25 @@ public class HttpComponentConfiguration { @NestedConfigurationProperty private CookieStore cookieStore; /** + * To use a custom HttpBinding to control the mapping between Camel message + * and HttpClient. + */ + @NestedConfigurationProperty + private HttpBinding httpBinding; + /** + * To use the shared HttpConfiguration as base configuration. + */ + @NestedConfigurationProperty + private HttpConfiguration httpConfiguration; + /** + * Whether to allow java serialization when a request uses + * context-type=application/x-java-serialized-object. This is by default + * turned off. If you enable this then be aware that Java will deserialize + * the incoming data from the request to Java and that can be a potential + * security risk. + */ + private Boolean allowJavaSerializedObject = false; + /** * To use a custom org.apache.camel.spi.HeaderFilterStrategy to filter * header to and from Camel message. */ @@ -140,30 +140,6 @@ public class HttpComponentConfiguration { this.clientConnectionManager = clientConnectionManager; } - public HttpBinding getHttpBinding() { - return httpBinding; - } - - public void setHttpBinding(HttpBinding httpBinding) { - this.httpBinding = httpBinding; - } - - public HttpConfiguration getHttpConfiguration() { - return httpConfiguration; - } - - public void setHttpConfiguration(HttpConfiguration httpConfiguration) { - this.httpConfiguration = httpConfiguration; - } - - public Boolean getAllowJavaSerializedObject() { - return allowJavaSerializedObject; - } - - public void setAllowJavaSerializedObject(Boolean allowJavaSerializedObject) { - this.allowJavaSerializedObject = allowJavaSerializedObject; - } - public HttpContext getHttpContext() { return httpContext; } @@ -221,6 +197,30 @@ public class HttpComponentConfiguration { this.cookieStore = cookieStore; } + public HttpBinding getHttpBinding() { + return httpBinding; + } + + public void setHttpBinding(HttpBinding httpBinding) { + this.httpBinding = httpBinding; + } + + public HttpConfiguration getHttpConfiguration() { + return httpConfiguration; + } + + public void setHttpConfiguration(HttpConfiguration httpConfiguration) { + this.httpConfiguration = httpConfiguration; + } + + public Boolean getAllowJavaSerializedObject() { + return allowJavaSerializedObject; + } + + public void setAllowJavaSerializedObject(Boolean allowJavaSerializedObject) { + this.allowJavaSerializedObject = allowJavaSerializedObject; + } + public HeaderFilterStrategy getHeaderFilterStrategy() { return headerFilterStrategy; }
