001    /*
002     * Copyright (C) 2009 Google Inc.
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.ElementType;
020    import java.lang.annotation.Retention;
021    import java.lang.annotation.RetentionPolicy;
022    import java.lang.annotation.Target;
023    
024    /**
025     * The presence of this annotation on a type indicates that the type may be
026     * used with the
027     * <a href="http://code.google.com/webtoolkit/">Google Web Toolkit</a> (GWT).
028     * When applied to a method, the return type of the method is GWT compatible.
029     * It's useful to indicate that an instance created by factory methods has a GWT
030     * serializable type.  In the following example,
031     *
032     * <pre style="code">
033     * {@literal @}GwtCompatible
034     * class Lists {
035     *   ...
036     *   {@literal @}GwtCompatible(serializable = true)
037     *   static &lt;E> List&lt;E> newArrayList(E... elements) {
038     *     ...
039     *   }
040     * }
041     * </pre>
042     * The return value of {@code Lists.newArrayList(E[])} has GWT
043     * serializable type.  It is also useful in specifying contracts of interface
044     * methods.  In the following example,
045     *
046     * <pre style="code">
047     * {@literal @}GwtCompatible
048     * interface ListFactory {
049     *   ...
050     *   {@literal @}GwtCompatible(serializable = true)
051     *   &lt;E> List&lt;E> newArrayList(E... elements);
052     * }
053     * </pre>
054     * The {@code newArrayList(E[])} method of all implementations of {@code
055     * ListFactory} is expected to return a value with a GWT serializable type.
056     *
057     * <p>Note that a {@code GwtCompatible} type may have some {@link
058     * GwtIncompatible} methods.
059     *
060     * @author Charles Fry
061     * @author Hayward Chan
062     */
063    @Retention(RetentionPolicy.CLASS)
064    @Target({ ElementType.TYPE, ElementType.METHOD })
065    
066    @GwtCompatible
067    public @interface GwtCompatible {
068    
069      /**
070       * When {@code true}, the annotated type or the type of the method return
071       * value is GWT serializable.
072       *
073       * @see <a href="http://code.google.com/docreader/#p=google-web-toolkit-doc-1-5&t=DevGuideSerializableTypes">
074       *     Documentation about GWT serialization</a>
075       */
076      boolean serializable() default false;
077    
078      /**
079       * When {@code true}, the annotated type is emulated in GWT. The emulated
080       * source (also known as super-source) is different from the implementation
081       * used by the JVM.
082       *
083       * @see <a href="http://code.google.com/docreader/#p=google-web-toolkit-doc-1-5&t=DevGuideModuleXml">
084       *     Documentation about GWT emulated source</a>
085       */
086      boolean emulated() default false;
087    }