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