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 * @author Charles Fry 058 * @author Hayward Chan 059 */ 060@Retention(RetentionPolicy.CLASS) 061@Target({ElementType.TYPE, ElementType.METHOD}) 062@Documented 063@GwtCompatible 064public @interface GwtCompatible { 065 066 /** 067 * When {@code true}, the annotated type or the type of the method return value is GWT 068 * serializable. 069 * 070 * @see <a href= 071 * "http://code.google.com/webtoolkit/doc/latest/DevGuideServerCommunication.html#DevGuideSerializableTypes"> 072 * Documentation about GWT serialization</a> 073 */ 074 boolean serializable() default false; 075 076 /** 077 * When {@code true}, the annotated type is emulated in GWT. The emulated source (also known as 078 * super-source) is different from the implementation used by the JVM. 079 * 080 * @see <a href= 081 * "http://code.google.com/webtoolkit/doc/latest/DevGuideOrganizingProjects.html#DevGuideModules"> 082 * Documentation about GWT emulated source</a> 083 */ 084 boolean emulated() default false; 085}