1 /* 2 * Copyright (C) 2009 The Guava Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.google.common.annotations; 18 19 import java.lang.annotation.Documented; 20 import java.lang.annotation.ElementType; 21 import java.lang.annotation.Retention; 22 import java.lang.annotation.RetentionPolicy; 23 import java.lang.annotation.Target; 24 25 /** 26 * The presence of this annotation on a type indicates that the type may be 27 * used with the 28 * <a href="http://code.google.com/webtoolkit/">Google Web Toolkit</a> (GWT). 29 * When applied to a method, the return type of the method is GWT compatible. 30 * It's useful to indicate that an instance created by factory methods has a GWT 31 * serializable type. In the following example, 32 * 33 * <pre style="code"> 34 * {@literal @}GwtCompatible 35 * class Lists { 36 * ... 37 * {@literal @}GwtCompatible(serializable = true) 38 * static <E> List<E> newArrayList(E... elements) { 39 * ... 40 * } 41 * } 42 * </pre> 43 * The return value of {@code Lists.newArrayList(E[])} has GWT 44 * serializable type. It is also useful in specifying contracts of interface 45 * methods. In the following example, 46 * 47 * <pre style="code"> 48 * {@literal @}GwtCompatible 49 * interface ListFactory { 50 * ... 51 * {@literal @}GwtCompatible(serializable = true) 52 * <E> List<E> newArrayList(E... elements); 53 * } 54 * </pre> 55 * The {@code newArrayList(E[])} method of all implementations of {@code 56 * ListFactory} is expected to return a value with a GWT serializable type. 57 * 58 * <p>Note that a {@code GwtCompatible} type may have some {@link 59 * GwtIncompatible} methods. 60 * 61 * @author Charles Fry 62 * @author Hayward Chan 63 */ 64 @Retention(RetentionPolicy.CLASS) 65 @Target({ ElementType.TYPE, ElementType.METHOD }) 66 @Documented 67 @GwtCompatible 68 public @interface GwtCompatible { 69 70 /** 71 * When {@code true}, the annotated type or the type of the method return 72 * value is GWT serializable. 73 * 74 * @see <a href="http://code.google.com/webtoolkit/doc/latest/DevGuideServerCommunication.html#DevGuideSerializableTypes"> 75 * Documentation about GWT serialization</a> 76 */ 77 boolean serializable() default false; 78 79 /** 80 * When {@code true}, the annotated type is emulated in GWT. The emulated 81 * source (also known as super-source) is different from the implementation 82 * used by the JVM. 83 * 84 * @see <a href="http://code.google.com/webtoolkit/doc/latest/DevGuideOrganizingProjects.html#DevGuideModules"> 85 * Documentation about GWT emulated source</a> 86 */ 87 boolean emulated() default false; 88 } 89
