    001    /*
    002     * Copyright (C) 2009 The Guava Authors
    003     *
    004     * Licensed under the Apache License, Version 2.0 (the "License");
    005     * you may not use this file except in compliance with the License.
    006     * You may obtain a copy of the License at
    007     *
    008     * http://www.apache.org/licenses/LICENSE-2.0
    009     *
    010     * Unless required by applicable law or agreed to in writing, software
    011     * distributed under the License is distributed on an "AS IS" BASIS,
    012     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    013     * See the License for the specific language governing permissions and
    014     * limitations under the License.
    015     */
    016
    017    package com.google.common.annotations;
    018
    019    import java.lang.annotation.Documented;
    020    import java.lang.annotation.ElementType;
    021    import java.lang.annotation.Retention;
    022    import java.lang.annotation.RetentionPolicy;
    023    import java.lang.annotation.Target;
    024
    025    /**
    026     * The presence of this annotation on a type indicates that the type may be
    027     * used with the
    028     * <a href="http://code.google.com/webtoolkit/">Google Web Toolkit</a> (GWT).
    029     * When applied to a method, the return type of the method is GWT compatible.
    030     * It's useful to indicate that an instance created by factory methods has a GWT
    031     * serializable type.  In the following example,
    032     *
    033     * <pre style="code">
    034     * {@literal @}GwtCompatible
    035     * class Lists {
    036     *   ...
    037     *   {@literal @}GwtCompatible(serializable = true)
    038     *   static &lt;E> List&lt;E> newArrayList(E... elements) {
    039     *     ...
    040     *   }
    041     * }
    042     * </pre>
    043     * The return value of {@code Lists.newArrayList(E[])} has GWT
    044     * serializable type.  It is also useful in specifying contracts of interface
    045     * methods.  In the following example,
    046     *
    047     * <pre style="code">
    048     * {@literal @}GwtCompatible
    049     * interface ListFactory {
    050     *   ...
    051     *   {@literal @}GwtCompatible(serializable = true)
    052     *   &lt;E> List&lt;E> newArrayList(E... elements);
    053     * }
    054     * </pre>
    055     * The {@code newArrayList(E[])} method of all implementations of {@code
    056     * ListFactory} is expected to return a value with a GWT serializable type.
    057     *
    058     * <p>Note that a {@code GwtCompatible} type may have some {@link
    059     * GwtIncompatible} methods.
    060     *
    061     * @author Charles Fry
    062     * @author Hayward Chan
    063     */
    064    @Retention(RetentionPolicy.CLASS)
    065    @Target({ ElementType.TYPE, ElementType.METHOD })
    066    @Documented
    067    @GwtCompatible
    068    public @interface GwtCompatible {
    069
    070      /**
    071       * When {@code true}, the annotated type or the type of the method return
    072       * value is GWT serializable.
    073       *
    074       * @see <a href="http://code.google.com/webtoolkit/doc/latest/DevGuideServerCommunication.html#DevGuideSerializableTypes">
    075       *     Documentation about GWT serialization</a>
    076       */
    077      boolean serializable() default false;
    078
    079      /**
    080       * When {@code true}, the annotated type is emulated in GWT. The emulated
    081       * source (also known as super-source) is different from the implementation
    082       * used by the JVM.
    083       *
    084       * @see <a href="http://code.google.com/webtoolkit/doc/latest/DevGuideOrganizingProjects.html#DevGuideModules">
    085       *     Documentation about GWT emulated source</a>
    086       */
    087      boolean emulated() default false;
    088    }