Guava源码解析-Guava中的注解

Guava中的注解

@Beta注解

/**
 * Signifies that a public API (public class, method or field) is subject to incompatible changes,
 * or even removal, in a future release. An API bearing this annotation is exempt from any
 * compatibility guarantees made by its containing library. Note that the presence of this
 * annotation implies nothing about the quality or performance of the API in question, only the fact
 * that it is not "API-frozen."
 *
 * <p>It is generally safe for <i>applications</i> to depend on beta APIs, at the cost of some extra
 * work during upgrades. However it is generally inadvisable for <i>libraries</i> (which get
 * included on users' CLASSPATHs, outside the library developers' control) to do so.
 *
 *
 * @author Kevin Bourrillion
 */
@Retention(RetentionPolicy.CLASS)
@Target({
  ElementType.ANNOTATION_TYPE,
  ElementType.CONSTRUCTOR,
  ElementType.FIELD,
  ElementType.METHOD,
  ElementType.TYPE
})
@Documented
@GwtCompatible
public @interface Beta {}

Beta注解表示被它标识的方法，字段，在将来的版本中存在改变的可能，甚至被删除掉。带有此注解的API不做任何兼容性的保证。因此，被它标记的相关属性和方法，是不建议在生产中使用的。

@GwtCompatible

/**
 * The presence of this annotation on a type indicates that the type may be used with the <a
 * href="http://code.google.com/webtoolkit/">Google Web Toolkit</a> (GWT). When applied to a method,
 * the return type of the method is GWT compatible. It's useful to indicate that an instance created
 * by factory methods has a GWT serializable type. In the following example,
 *
 * <pre>
 * {@literal @}GwtCompatible
 * class Lists {
 *   ...
 *   {@literal @}GwtCompatible(serializable = true)
 *   {@literal static <E> List<E>} newArrayList(E... elements) {
 *     ...
 *   }
 * }
 * </pre>
 *
 * <p>The return value of {@code Lists.newArrayList(E[])} has GWT serializable type. It is also
 * useful in specifying contracts of interface methods. In the following example,
 *
 * <pre>
 * {@literal @}GwtCompatible
 * interface ListFactory {
 *   ...
 *   {@literal @}GwtCompatible(serializable = true)
 *   {@literal <E> List<E>} newArrayList(E... elements);
 * }
 * </pre>
 *
 * <p>The {@code newArrayList(E[])} method of all implementations of {@code ListFactory} is expected
 * to return a value with a GWT serializable type.
 *
 * <p>Note that a {@code GwtCompatible} type may have some {@link GwtIncompatible} methods.
 *
 *
 * @author Charles Fry
 * @author Hayward Chan
 */
@Retention(RetentionPolicy.CLASS)
@Target({ElementType.TYPE, ElementType.METHOD})
@Documented
@GwtCompatible
public @interface GwtCompatible {

  /**
   * When {@code true}, the annotated type or the type of the method return value is GWT
   * serializable.
   *
   * @see <a href=
   *     "http://code.google.com/webtoolkit/doc/latest/DevGuideServerCommunication.html#DevGuideSerializableTypes">
   *     Documentation about GWT serialization</a>
   */
  boolean serializable() default false;

  /**
   * When {@code true}, the annotated type is emulated in GWT. The emulated source (also known as
   * super-source) is different from the implementation used by the JVM.
   *
   * @see <a href=
   *     "http://code.google.com/webtoolkit/doc/latest/DevGuideOrganizingProjects.html#DevGuideModules">
   *     Documentation about GWT emulated source</a>
   */
  boolean emulated() default false;
}

被它修饰的方法或者类型，是可以和GWT，即（Google Tool kit）兼容的，可以一起使用。如果一个方法使用这个注释,说明这个方法的返回值是 GWT 兼容的

@serializable

当设置为true时，说明被它注解的方法或者类型是支持GWT序列化的

@emulated

当设置为true时，说明被它注解的方法或类型是支持在GWT中被模拟的

@GwtIncompatible

/**
 * The presence of this annotation on an API indicates that the method may <em>not</em> be used with
 * the <a href="http://www.gwtproject.org/">Google Web Toolkit</a> (GWT).
 *
 * <p>This annotation behaves identically to <a href=
 * "http://www.gwtproject.org/javadoc/latest/com/google/gwt/core/shared/GwtIncompatible.html">the
 * {@code @GwtIncompatible} annotation in GWT itself</a>.
 *
 * @author Charles Fry
 */
@Retention(RetentionPolicy.CLASS)
@Target({ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.FIELD})
@Documented
@GwtCompatible
public @interface GwtIncompatible {
  /**
   * Describes why the annotated element is incompatible with GWT. Since this is generally due to a
   * dependence on a type/method which GWT doesn't support, it is sufficient to simply reference the
   * unsupported type/method. E.g. "Class.isInstance".
   *
   * <p>As of Guava 20.0, this value is optional. We encourage authors who wish to describe why an
   * API is {@code @GwtIncompatible} to instead leave an implementation comment.
   */
  String value() default "";
}

被它修饰的方式，字段等是不和GWT兼容的。

value()

说明不兼容GWT的原因

@VisibleForTest

/**
 * Annotates a program element that exists, or is more widely visible than otherwise necessary, only
 * for use in test code.
 *
 * <p><b>Do not use this interface</b> for public or protected declarations: it is a fig leaf for
 * bad design, and it does not prevent anyone from using the declaration---and experience has shown
 * that they will. If the method breaks the encapsulation of its class, then its internal
 * representation will be hard to change. Instead, use <a
 * href="http://errorprone.info/bugpattern/RestrictedApiChecker">RestrictedApiChecker</a>, which
 * enforces fine-grained visibility policies.
 *
 * @author Johannes Henkel
 */
@GwtCompatible
public @interface VisibleForTesting {
}

当它标记在一个方法或者类型上的时候，它将给予给类型或者方法更多的可见性，仅仅别用在测试代码中。

意思是什么呢？

它最大的用处就是，可以代替Java 反射来测试私有方法。

看下面的代码

public class PrivateData {
    @VisibleForTesting
    private void testPrivate(int pr) {
		System.out.print(pr);
    }
}

下面是测试类

public class PrivateDataTest {
    @Test
    public void testPrivate() throws Exception {
        PrivateData pm = new PrivateData();
        pm.testPrivate(1);
    }

}

通过上面的代码看出， 被测试的testPrivate方法的可见性还是被改成Protected。也就是,VisibleForTesting只是一个注释，一个元数据metadata，它并没有进入程序逻辑，也没有被转化成字节码byte code 从而被JVM执行。

@GwtTransient

/**
 * Private replacement for {@link com.google.gwt.user.client.rpc.GwtTransient} to work around
 * build-system quirks. This annotation should be used <b>only</b> in {@code
 * com.google.common.collect}.
 */
@Documented
@GwtCompatible
@Retention(RUNTIME)
@Target(FIELD)
@interface GwtTransient {}

它实际上与Java的transient关键字含义相同，但是除了GWT之外，所有的序列化系统都不会对它进行处理。

一般情况下，应该倾向于使用Java中的transient关键字。但是对于多个序列化系统一起使用的类型，它可能很有用。

请注意，GWT实际上将为此目的接受任何名为GwtTransient的注释。这样做是为了允许库支持GWT序列化，而无需直接依赖GWT发行版。

@AllowConcurrentEvents

/**
 * Marks an event subscriber method as being thread-safe. This annotation indicates that EventBus
 * may invoke the event subscriber simultaneously from multiple threads.
 *
 * <p>This does not mark the method, and so should be used in combination with {@link Subscribe}.
 *
 * @author Cliff Biffle
 * @since 10.0
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@Beta
public @interface AllowConcurrentEvents {}

被它修饰的订阅者方法，将会是线程安全的。具体细节，和@Subscribe注解一起，留到事件总线章节一起说明。

@Subscribe

/**
 * Marks a method as an event subscriber.
 *
 * <p>The type of event will be indicated by the method's first (and only) parameter. If this
 * annotation is applied to methods with zero parameters, or more than one parameter, the object
 * containing the method will not be able to register for event delivery from the {@link EventBus}.
 *
 * <p>Unless also annotated with @{@link AllowConcurrentEvents}, event subscriber methods will be
 * invoked serially by each event bus that they are registered with.
 *
 * @author Cliff Biffle
 * @since 10.0
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@Beta
public @interface Subscribe {}

被它修饰的方式，将会是一个事件总线的订阅者。具体细节，和@AllowConcurrentEvents注解一起，留到事件总线章节一起说明。

@IgnoreJRERequirement

@interface IgnoreJRERequirement {}