hc-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject svn commit: r807948 - in /httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/annotation: GuardedBy.java Immutable.java NotThreadSafe.java ThreadSafe.java
Date Wed, 26 Aug 2009 09:55:58 GMT
Author: sebb
Date: Wed Aug 26 09:55:57 2009
New Revision: 807948

URL: http://svn.apache.org/viewvc?rev=807948&view=rev
Log:
Might as well use original Javadoc
Changed RetentionPolicy to CLASS (i.e. the default)

Modified:
    httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/annotation/GuardedBy.java
    httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/annotation/Immutable.java
    httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/annotation/NotThreadSafe.java
    httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/annotation/ThreadSafe.java

Modified: httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/annotation/GuardedBy.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/annotation/GuardedBy.java?rev=807948&r1=807947&r2=807948&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/annotation/GuardedBy.java
(original)
+++ httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/annotation/GuardedBy.java
Wed Aug 26 09:55:57 2009
@@ -32,8 +32,36 @@
 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 @@
  */
 @Documented
 @Target({ElementType.FIELD, ElementType.METHOD})
-@Retention(RetentionPolicy.SOURCE)
+@Retention(RetentionPolicy.CLASS) // The original version used RUNTIME
 public @interface GuardedBy {
     String value();
 }

Modified: httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/annotation/Immutable.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/annotation/Immutable.java?rev=807948&r1=807947&r2=807948&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/annotation/Immutable.java
(original)
+++ httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/annotation/Immutable.java
Wed Aug 26 09:55:57 2009
@@ -32,8 +32,20 @@
 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 @@
  */
 @Documented
 @Target(ElementType.TYPE)
-@Retention(RetentionPolicy.SOURCE)
+@Retention(RetentionPolicy.CLASS) // The original version used RUNTIME
 public @interface Immutable {
 }

Modified: httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/annotation/NotThreadSafe.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/annotation/NotThreadSafe.java?rev=807948&r1=807947&r2=807948&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/annotation/NotThreadSafe.java
(original)
+++ httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/annotation/NotThreadSafe.java
Wed Aug 26 09:55:57 2009
@@ -32,8 +32,11 @@
 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 @@
  */
 @Documented
 @Target(ElementType.TYPE)
-@Retention(RetentionPolicy.SOURCE)
+@Retention(RetentionPolicy.CLASS) // The original version used RUNTIME
 public @interface NotThreadSafe {
 }

Modified: httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/annotation/ThreadSafe.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/annotation/ThreadSafe.java?rev=807948&r1=807947&r2=807948&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/annotation/ThreadSafe.java
(original)
+++ httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/annotation/ThreadSafe.java
Wed Aug 26 09:55:57 2009
@@ -32,9 +32,12 @@
 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 @@
  */
 @Documented
 @Target(ElementType.TYPE)
-@Retention(RetentionPolicy.SOURCE)
+@Retention(RetentionPolicy.CLASS) // The original version used RUNTIME
 public @interface ThreadSafe {
 }



Mime
View raw message