Package: groovy.transform

## [Java] Annotation Type WithReadLock

- groovy.transform.WithReadLock

-     @Documented
      @Retention(RetentionPolicy.SOURCE)
      @Target(ElementType.METHOD)
      @GroovyASTTransformationClass("org.codehaus.groovy.transform.ReadWriteLockASTTransformation")
      public @interface WithReadLock

  This annotation is used in conjunction with WithWriteLock to support read and write synchronization on a method.

  To use this annotation, declare `@WithReadLock` on your method. The method may be either an instance method or a static method. The resulting method will allow multiple threads to read the information at the same time. However, if some other method obtains a write lock, then this method will force callers to wait until the write is complete.

  This annotation is a declarative wrapper around the JDK's `java.util.concurrent.locks.ReentrantReadWriteLock`. Objects containing this annotation will have a ReentrantReadWriteLock field named `$reentrantLock` added to the class, and method access is protected by the lock. If the method is static then the field is static and named `$REENTRANTLOCK`.

  The annotation takes an optional parameter for the name of the field. This field must exist on the class and must be of type ReentrantReadWriteLock.

  To understand how this annotation works, it is convenient to think in terms of the source code it replaces. The following is a typical usage of this annotation from Groovy:

       import groovy.transform.*;

       public class ResourceProvider {

           private final Map<String, String> data = new HashMap<String, String>();

          @WithReadLock
           public String getResource(String key) throws Exception {
                   return data.get(key);
           }

          @WithWriteLock
           public void refresh() throws Exception {
                   //reload the resources into memory
           }
       }

  As part of the Groovy compiler, code resembling this is produced:

       import java.util.concurrent.locks.ReentrantReadWriteLock;
       import java.util.concurrent.locks.ReadWriteLock;

       public class ResourceProvider {

           private final ReadWriteLock $reentrantlock = new ReentrantReadWriteLock();
           private final Map<String, String> data = new HashMap<String, String>();

           public String getResource(String key) throws Exception {
               $reentrantlock.readLock().lock();
               try {
                   return data.get(key);
               } finally {
                   $reentrantlock.readLock().unlock();
               }
           }

           public void refresh() throws Exception {
               $reentrantlock.writeLock().lock();
               try {
                   //reload the resources into memory
               } finally {
                   $reentrantlock.writeLock().unlock();
               }
           }
       }

  Since:
    1.8.0

- - ### Element Summary

    Optional Element Summary
    Type | Name and Description
    --- | ---
    `String` | `value` Returns: if a user specified lock object with the given name should be used the lock object must exist.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `wait, wait, wait, equals, toString, hashCode, getClass, notify, notifyAll`

- - ### Element Detail

    - #### public String value

      Returns:
        if a user specified lock object with the given name should be used the lock object must exist. If the annotated method is static then the lock object must be static. If the annotated method is not static then the lock object must not be static.
      Default:
        ""