[sling-whiteboard] 04/07: Documentation updates

[ro...@apache.org]

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

rombert pushed a commit to branch url-connection-agent-cleanups
in repository https://gitbox.apache.org/repos/asf/sling-whiteboard.git

commit f459aad3070bab6a9ab3b799136a819f9c314fb1
Author: Robert Munteanu <ro...@apache.org>
AuthorDate: Fri Jun 7 16:07:44 2019 +0200

    Documentation updates
---
 url-connection-agent/README.md                           | 16 +++++++++++++---
 .../sling/uca/impl/HttpClient3TimeoutTransformer.java    |  6 ++++++
 .../sling/uca/impl/HttpClient4TimeoutTransformer.java    |  6 ++++++
 .../apache/sling/uca/impl/JavaNetTimeoutTransformer.java |  6 +++---
 4 files changed, 28 insertions(+), 6 deletions(-)

diff --git a/url-connection-agent/README.md b/url-connection-agent/README.md
index fcc5d06..916c0ca 100644
--- a/url-connection-agent/README.md
+++ b/url-connection-agent/README.md
@@ -1,10 +1,18 @@
-# Apache Sling URL connection agent
+# Apache Sling HTTP timeout enforcer
 
 This module is part of the [Apache Sling](https://sling.apache.org) project.
 
-This module provides a java agent that uses the instrumentation API to add timeouts to `connect` calls made via HTTP or HTTPs without setting read and connect timeouts. It is intended as an additional layer of control to use when running unstrusted client code that may make calls without explicitly setting timeouts.
+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 `connect` made via HTTP or HTTPs. It only applies these timeouts if none were set explicitly.
 
-## Launching
+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/)
+
+## Validation
 
 Build the project with `mvn clean package` and then run a simple connection test with 
 
@@ -31,6 +39,8 @@ In contrast, the execution below should succeed:
 java -javaagent:target/url-connection-agent-0.0.1-SNAPSHOT-jar-with-dependencies.jar=1000,1000 -cp target/test-classes:target/it-dependencies/* org.apache.sling.uca.impl.Main https://sling.apache.org JavaNet
 ```
 
+To use this in your own project you should 
+
 ## Tested platforms
 
 * openjdk version "1.8.0_212"
diff --git a/url-connection-agent/src/main/java/org/apache/sling/uca/impl/HttpClient3TimeoutTransformer.java b/url-connection-agent/src/main/java/org/apache/sling/uca/impl/HttpClient3TimeoutTransformer.java
index b287447..6e57245 100644
--- a/url-connection-agent/src/main/java/org/apache/sling/uca/impl/HttpClient3TimeoutTransformer.java
+++ b/url-connection-agent/src/main/java/org/apache/sling/uca/impl/HttpClient3TimeoutTransformer.java
@@ -25,6 +25,12 @@ import javassist.CtClass;
 import javassist.CtMethod;
 import javassist.bytecode.Descriptor;
 
+/**
+ * Sets timeouts for HTTP calls done using <em>Apache Commons HttpClient 3.x</em>
+ * 
+ * <p>It inserts two calls in <tt>org.apache.commons.httpclient.params.DefaultHttpParamsFactory.createParams</tt> that set
+ * default values for <tt>http.connection.timeout</tt> and <tt>http.socket.timeout</tt>.</p>
+ */
 public class HttpClient3TimeoutTransformer implements ClassFileTransformer {
     
     private static final String DEFAULT_HTTP_PARAMS_FACTORY_CLASS_NAME = Descriptor.toJvmName("org.apache.commons.httpclient.params.DefaultHttpParamsFactory");
diff --git a/url-connection-agent/src/main/java/org/apache/sling/uca/impl/HttpClient4TimeoutTransformer.java b/url-connection-agent/src/main/java/org/apache/sling/uca/impl/HttpClient4TimeoutTransformer.java
index ee62458..e74dabf 100644
--- a/url-connection-agent/src/main/java/org/apache/sling/uca/impl/HttpClient4TimeoutTransformer.java
+++ b/url-connection-agent/src/main/java/org/apache/sling/uca/impl/HttpClient4TimeoutTransformer.java
@@ -26,6 +26,12 @@ import javassist.CtConstructor;
 import javassist.CtField;
 import javassist.bytecode.Descriptor;
 
+/**
+ * Sets timeouts for HTTP calls done using <em>Apache HttpComponents Client 4.x</em>
+ * 
+ * <p>It inserts two calls to <tt>org.apache.http.client.config.RequestConfig$Builder</tt> that set default
+ * values for <tt>connectTimeout</tt> and <tt>socketTimeout</tt>.</p>
+ */
 public class HttpClient4TimeoutTransformer implements ClassFileTransformer {
 
     // org.apache.http.client.config.RequestConfig.Builder
diff --git a/url-connection-agent/src/main/java/org/apache/sling/uca/impl/JavaNetTimeoutTransformer.java b/url-connection-agent/src/main/java/org/apache/sling/uca/impl/JavaNetTimeoutTransformer.java
index d320875..9978c33 100644
--- a/url-connection-agent/src/main/java/org/apache/sling/uca/impl/JavaNetTimeoutTransformer.java
+++ b/url-connection-agent/src/main/java/org/apache/sling/uca/impl/JavaNetTimeoutTransformer.java
@@ -29,10 +29,10 @@ import javassist.NotFoundException;
 import javassist.bytecode.Descriptor;
 
 /**
- * Transforms well-known HTTP URL connection classes
+ * Sets timeouts for HTTP calls done using <tt>java.net.URL</tt>/<tt>java.net.URLConnection</tt>.
  * 
- * <p>This implementation adds connect and read timeouts to those connections
- * if none are defined.</p>
+ * <p>It transforms calls to <tt>connect</tt> methods of internal URL connection classes to set the
+ * connect and read timeout in case they have the default value of <tt>0</tt>.</p>
  * 
  * @see URLConnection#getConnectTimeout()
  * @see URLConnection#getReadTimeout()