From 62f1705b0ccbb7ab7ad369b16aa93473a7f48342 Mon Sep 17 00:00:00 2001
From: Sebastian Bazley <sebb@apache.org>
Date: Wed, 26 Aug 2009 09:55:57 +0000
Subject: [PATCH] Might as well use original Javadoc Changed RetentionPolicy to
 CLASS (i.e. the default)

git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@807948 13f79535-47bb-0310-9956-ffa450edef68
---
 .../org/apache/http/annotation/GuardedBy.java | 34 +++++++++++++++++--
 .../org/apache/http/annotation/Immutable.java | 18 ++++++++--
 .../apache/http/annotation/NotThreadSafe.java |  9 +++--
 .../apache/http/annotation/ThreadSafe.java    | 11 +++---
 4 files changed, 59 insertions(+), 13 deletions(-)

diff --git a/httpclient/src/main/java/org/apache/http/annotation/GuardedBy.java b/httpclient/src/main/java/org/apache/http/annotation/GuardedBy.java
index 76689573d..5907d268c 100644
--- a/httpclient/src/main/java/org/apache/http/annotation/GuardedBy.java
+++ b/httpclient/src/main/java/org/apache/http/annotation/GuardedBy.java
@@ -32,8 +32,36 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * This annotation can be applied to a field or a method to indicate that its
- * thread-safety is guaranteed by a synchronization particular lock.
+ * The field or method to which this annotation is applied can only be accessed
+ * when holding a particular lock, which may be a built-in (synchronization) lock,
+ * or may be an explicit java.util.concurrent.Lock.
+ *
+ * The argument determines which lock guards the annotated field or method:
+ * <ul>
+ * <li>
+ * <code>this</code> : The intrinsic lock of the object in whose class the field is defined.
+ * </li>
+ * <li>
+ * <code>class-name.this</code> : For inner classes, it may be necessary to disambiguate 'this';
+ * the <em>class-name.this</em> designation allows you to specify which 'this' reference is intended
+ * </li>
+ * <li>
+ * <code>itself</code> : For reference fields only; the object to which the field refers.
+ * </li>
+ * <li>
+ * <code>field-name</code> : The lock object is referenced by the (instance or static) field
+ * specified by <em>field-name</em>.
+ * </li>
+ * <li>
+ * <code>class-name.field-name</code> : The lock object is reference by the static field specified
+ * by <em>class-name.field-name</em>.
+ * </li>
+ * <li>
+ * <code>method-name()</code> : The lock object is returned by calling the named nil-ary method.
+ * </li>
+ * <li>
+ * <code>class-name.class</code> : The Class object for the specified class should be used as the lock object.
+ * </li>
  * <p>
  * Based on code developed by Brian Goetz and Tim Peierls and concepts
  * published in 'Java Concurrency in Practice' by Brian Goetz, Tim Peierls,
@@ -41,7 +69,7 @@ import java.lang.annotation.Target;
  */
 @Documented
 @Target({ElementType.FIELD, ElementType.METHOD})
-@Retention(RetentionPolicy.SOURCE)
+@Retention(RetentionPolicy.CLASS) // The original version used RUNTIME
 public @interface GuardedBy {
     String value();
 }
diff --git a/httpclient/src/main/java/org/apache/http/annotation/Immutable.java b/httpclient/src/main/java/org/apache/http/annotation/Immutable.java
index 9c0bd1c9a..da201b39f 100644
--- a/httpclient/src/main/java/org/apache/http/annotation/Immutable.java
+++ b/httpclient/src/main/java/org/apache/http/annotation/Immutable.java
@@ -32,8 +32,20 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * This annotation can be applied to a class to indicate that its
- * internal state cannot mutate and therefore it is thread-safe.
+ * The class to which this annotation is applied is immutable.  This means that
+ * its state cannot be seen to change by callers, which implies that
+ * <ul>
+ * <li> all public fields are final, </li>
+ * <li> all public final reference fields refer to other immutable objects, and </li>
+ * <li> constructors and methods do not publish references to any internal state
+ *      which is potentially mutable by the implementation. </li>
+ * </ul>
+ * Immutable objects may still have internal mutable state for purposes of performance
+ * optimization; some state variables may be lazily computed, so long as they are computed
+ * from immutable state and that callers cannot tell the difference.
+ * <p>
+ * Immutable objects are inherently thread-safe; they may be passed between threads or
+ * published without synchronization.
  * <p>
  * Based on code developed by Brian Goetz and Tim Peierls and concepts
  * published in 'Java Concurrency in Practice' by Brian Goetz, Tim Peierls,
@@ -41,6 +53,6 @@ import java.lang.annotation.Target;
  */
 @Documented
 @Target(ElementType.TYPE)
-@Retention(RetentionPolicy.SOURCE)
+@Retention(RetentionPolicy.CLASS) // The original version used RUNTIME
 public @interface Immutable {
 }
diff --git a/httpclient/src/main/java/org/apache/http/annotation/NotThreadSafe.java b/httpclient/src/main/java/org/apache/http/annotation/NotThreadSafe.java
index 3232d24c8..ddc678744 100644
--- a/httpclient/src/main/java/org/apache/http/annotation/NotThreadSafe.java
+++ b/httpclient/src/main/java/org/apache/http/annotation/NotThreadSafe.java
@@ -32,8 +32,11 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * This annotation can be applied to a class to indicate that it is not 
- * thread-safe and therefore should not be accessed concurrently.
+ * The class to which this annotation is applied is not thread-safe.
+ * This annotation primarily exists for clarifying the non-thread-safety of a class
+ * that might otherwise be assumed to be thread-safe, despite the fact that it is a bad
+ * idea to assume a class is thread-safe without good reason.
+ * @see ThreadSafe
  * <p>
  * Based on code developed by Brian Goetz and Tim Peierls and concepts
  * published in 'Java Concurrency in Practice' by Brian Goetz, Tim Peierls,
@@ -41,6 +44,6 @@ import java.lang.annotation.Target;
  */
 @Documented
 @Target(ElementType.TYPE)
-@Retention(RetentionPolicy.SOURCE)
+@Retention(RetentionPolicy.CLASS) // The original version used RUNTIME
 public @interface NotThreadSafe {
 }
diff --git a/httpclient/src/main/java/org/apache/http/annotation/ThreadSafe.java b/httpclient/src/main/java/org/apache/http/annotation/ThreadSafe.java
index d7337df96..53c91b9c5 100644
--- a/httpclient/src/main/java/org/apache/http/annotation/ThreadSafe.java
+++ b/httpclient/src/main/java/org/apache/http/annotation/ThreadSafe.java
@@ -32,9 +32,12 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * This annotation can be applied to a class to indicate that it is 
- * thread-safe and therefore can be accessed concurrently by multiple
- * threads.
+ * The class to which this annotation is applied is thread-safe.  This means that
+ * no sequences of accesses (reads and writes to public fields, calls to public methods)
+ * may put the object into an invalid state, regardless of the interleaving of those actions
+ * by the runtime, and without requiring any additional synchronization or coordination on the
+ * part of the caller.
+ * @see NotThreadSafe
  * <p>
  * Based on code developed by Brian Goetz and Tim Peierls and concepts
  * published in 'Java Concurrency in Practice' by Brian Goetz, Tim Peierls,
@@ -42,6 +45,6 @@ import java.lang.annotation.Target;
  */
 @Documented
 @Target(ElementType.TYPE)
-@Retention(RetentionPolicy.SOURCE)
+@Retention(RetentionPolicy.CLASS) // The original version used RUNTIME
 public @interface ThreadSafe {
 }