1 /* 2 * Copyright (C) 2009 Google Inc. 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.ElementType; 20 import java.lang.annotation.Retention; 21 import java.lang.annotation.RetentionPolicy; 22 import java.lang.annotation.Target; 23 24 /** 25 * The presence of this annotation on a type indicates that the type may be 26 * used with the 27 * <a href="http://code.google.com/webtoolkit/">Google Web Toolkit</a> (GWT). 28 * When applied to a method, the return type of the method is GWT compatible. 29 * It's useful to indicate that an instance created by factory methods has a GWT 30 * serializable type. In the following example, 31 * 32 * <pre style="code"> 33 * {@literal @}GwtCompatible 34 * class Lists { 35 * ... 36 * {@literal @}GwtCompatible(serializable = true) 37 * static <E> List<E> newArrayList(E... elements) { 38 * ... 39 * } 40 * } 41 * </pre> 42 * The return value of {@code Lists.newArrayList(E[])} has GWT 43 * serializable type. It is also useful in specifying contracts of interface 44 * methods. In the following example, 45 * 46 * <pre style="code"> 47 * {@literal @}GwtCompatible 48 * interface ListFactory { 49 * ... 50 * {@literal @}GwtCompatible(serializable = true) 51 * <E> List<E> newArrayList(E... elements); 52 * } 53 * </pre> 54 * The {@code newArrayList(E[])} method of all implementations of {@code 55 * ListFactory} is expected to return a value with a GWT serializable type. 56 * 57 * <p>Note that a {@code GwtCompatible} type may have some {@link 58 * GwtIncompatible} methods. 59 * 60 * @author Charles Fry 61 * @author Hayward Chan 62 */ 63 @Retention(RetentionPolicy.CLASS) 64 @Target({ ElementType.TYPE, ElementType.METHOD }) 65 // @Documented - uncomment when GWT support is official 66 @GwtCompatible 67 public @interface GwtCompatible { 68 69 /** 70 * When {@code true}, the annotated type or the type of the method return 71 * value is GWT serializable. 72 * 73 * @see <a href="http://code.google.com/docreader/#p=google-web-toolkit-doc-1-5&t=DevGuideSerializableTypes"> 74 * Documentation about GWT serialization</a> 75 */ serializable()76 boolean serializable() default false; 77 78 /** 79 * When {@code true}, the annotated type is emulated in GWT. The emulated 80 * source (also known as super-source) is different from the implementation 81 * used by the JVM. 82 * 83 * @see <a href="http://code.google.com/docreader/#p=google-web-toolkit-doc-1-5&t=DevGuideModuleXml"> 84 * Documentation about GWT emulated source</a> 85 */ emulated()86 boolean emulated() default false; 87 } 88