[sling-site] branch master updated: Add documentation for the Connection Timeout Agent

[ro...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

rombert pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-site.git


The following commit(s) were added to refs/heads/master by this push:
     new 0de72b6  Add documentation for the Connection Timeout Agent
0de72b6 is described below

commit 0de72b6eb419965167c9f3de89ca04faa3db4653
Author: Robert Munteanu <ro...@apache.org>
AuthorDate: Wed Jun 19 15:07:29 2019 +0200

    Add documentation for the Connection Timeout Agent
---
 .../connection-timeout-agent/jmx-mbeans.png        | Bin 0 -> 274874 bytes
 src/main/jbake/content/documentation/bundles.md    |   1 +
 .../bundles/connection-timeout-agent.md            |  71 +++++++++++++++++++++
 3 files changed, 72 insertions(+)

diff --git a/src/main/jbake/assets/documentation/bundles/connection-timeout-agent/jmx-mbeans.png b/src/main/jbake/assets/documentation/bundles/connection-timeout-agent/jmx-mbeans.png
new file mode 100644
index 0000000..7dba603
Binary files /dev/null and b/src/main/jbake/assets/documentation/bundles/connection-timeout-agent/jmx-mbeans.png differ
diff --git a/src/main/jbake/content/documentation/bundles.md b/src/main/jbake/content/documentation/bundles.md
index 28bd8f0..3e87c00 100644
--- a/src/main/jbake/content/documentation/bundles.md
+++ b/src/main/jbake/content/documentation/bundles.md
@@ -63,6 +63,7 @@ The OSGi installer is a very flexible and powerful service to manage provisionin
 * [Context-Aware Configuration](/documentation/bundles/context-aware-configuration/context-aware-configuration.html)
 * [HApi - Hypermedia API tools](/documentation/bundles/hapi.html)
 * [Capabilities](https://github.com/apache/sling-org-apache-sling-capabilities)
+* [Connection Timeout Agent](/documentation/bundles/connection-timeout-agent.html)
 
 ## Content Presentation and Rendering
 * [Scripting](/documentation/bundles/scripting.html) (aka Templating)
diff --git a/src/main/jbake/content/documentation/bundles/connection-timeout-agent.md b/src/main/jbake/content/documentation/bundles/connection-timeout-agent.md
new file mode 100644
index 0000000..0b63c01
--- /dev/null
+++ b/src/main/jbake/content/documentation/bundles/connection-timeout-agent.md
@@ -0,0 +1,71 @@
+title=Connection Timeout Agent (org.apache.sling.fsresource)		
+type=page
+status=published
+expandVariables=true
+~~~~~~
+[TOC]
+
+## Connection Timeout Agent
+
+This module provides a java agent that uses the [instrumentation API](https://docs.oracle.com/javase/7/docs/api/java/lang/instrument/package-summary.html) to add connect and read timeouts to connections made via HTTP or HTTPs. It only applies these timeouts if none were set explicitly.
+
+The agent is intended as an additional layer of control to use when running untrusted client code that may make calls without explicitly setting timeouts. It is always recommended to set timeouts in client code, rather than relying on this agent.
+
+It currently supports setting timeouts for HTTP connections done using:
+
+* [java.net.URL](https://docs.oracle.com/javase/7/docs/api/java/net/URL.html) and/or [java.net.URLConnection](https://docs.oracle.com/javase/7/docs/api/java/net/URLConnection.html)
+* [Apache Commons HttpClient 3.x](https://hc.apache.org/httpclient-3.x/)
+* [Apache HttpComponents Client 4.x](https://hc.apache.org/httpcomponents-client-ga/)
+* [OK Http](https://square.github.io/okhttp/)
+
+## Usage
+
+The agent can be loaded using the standard Java CLI invocation, by using the `-javaagent:...` argument.
+
+    java -javaagent:org.apache.sling.connection-timeout-agent-jar-with-dependencies.jar=<agent-connect-timeout>,<agent-read-timeout>[,<logspec>] -jar org.apache.sling.starter-${sling_releaseVersion}.jar
+
+It support two mandatory arguments and an optional one:
+
+ - `<agent-connect-timeout>` - connection timeout in milliseconds to apply via the agent
+ - `<agent-read-timeout>`- read timeout in milliseconds to apply via the agent
+ - `<logspec>` - if set to `v`, it will enter verbose mode and print additional information to `System.out`
+ 
+If started in verbose mode, output similar to the following will be printed
+
+
+	[AGENT] Preparing to install URL transformers. Configured timeouts - connectTimeout : 1000, readTimeout: 1000 
+	[AGENT] All transformers installed 
+	[AGENT] JavaNetTimeoutTransformer asked to transform sun/net/www/protocol/https/AbstractDelegateHttpsURLConnection 
+	[AGENT] Transformation of sun/net/www/protocol/https/AbstractDelegateHttpsURLConnection complete 
+	[AGENT] JavaNetTimeoutTransformer asked to transform sun/net/www/protocol/http/HttpURLConnection 
+	[AGENT] Transformation of sun/net/www/protocol/http/HttpURLConnection complete 
+
+
+Note that classes will be transformed when they are loaded. It is expected for a transformer for class _A_ to be active but the class not to be transformed until it is actually used.
+
+## JMX
+
+Various runtime information is exposed through a JMX MBean registered at `org.apache.sling.cta;ObjectType=Agent`. 
+
+![JMX MBeans](/documentation/bundles/connection-timeout-agent/jmx-mbeans.png)
+
+## Alternatives
+
+It is always recommended to set timeouts in the client code directly. The agent carries some risks, namely:
+
+- it is not transparent why and where timeouts are set and can lead to hard-to-debug scenarios
+- it only sets one timeout for the whole JVM, whereas various services may need different timeouts
+
+All HTTP client libraries offer a way of setting connect and read timeouts, and it strongly recommended to do so. Alternatively, various bundles offer a way of centrally defining timeouts, amongst them:
+
+* [Code Distillery - OSGi Configuration Support for Apache HttpComponents Client](https://github.com/code-distillery/httpclient-configuration-support)
+* [WCM.io Caravan - Commons HTTP Client](https://caravan.wcm.io/commons/httpclient/)
+
+
+## Tested platforms
+
+* openjdk version "1.8.0_212"
+* openjdk version "11.0.2" 2019-01-15
+* commons-httpclient 3.1
+* httpclient 4.5.4
+* okhttp 3.14.2