diff options
Diffstat (limited to 'gson/src/main/java/com/google/gson/annotations')
6 files changed, 398 insertions, 0 deletions
diff --git a/gson/src/main/java/com/google/gson/annotations/Expose.java b/gson/src/main/java/com/google/gson/annotations/Expose.java new file mode 100644 index 00000000..1b9c70df --- /dev/null +++ b/gson/src/main/java/com/google/gson/annotations/Expose.java @@ -0,0 +1,79 @@ +/* + * Copyright (C) 2008 Google Inc. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.google.gson.annotations; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * An annotation that indicates this member should be exposed for JSON + * serialization or deserialization. + * + * <p>This annotation has no effect unless you build {@link com.google.gson.Gson} + * with a {@link com.google.gson.GsonBuilder} and invoke + * {@link com.google.gson.GsonBuilder#excludeFieldsWithoutExposeAnnotation()} + * method.</p> + * + * <p>Here is an example of how this annotation is meant to be used: + * <p><pre> + * public class User { + * @Expose private String firstName; + * @Expose(serialize = false) private String lastName; + * @Expose (serialize = false, deserialize = false) private String emailAddress; + * private String password; + * } + * </pre></p> + * If you created Gson with {@code new Gson()}, the {@code toJson()} and {@code fromJson()} + * methods will use the {@code password} field along-with {@code firstName}, {@code lastName}, + * and {@code emailAddress} for serialization and deserialization. However, if you created Gson + * with {@code Gson gson = new GsonBuilder().excludeFieldsWithoutExposeAnnotation().create()} + * then the {@code toJson()} and {@code fromJson()} methods of Gson will exclude the + * {@code password} field. This is because the {@code password} field is not marked with the + * {@code @Expose} annotation. Gson will also exclude {@code lastName} and {@code emailAddress} + * from serialization since {@code serialize} is set to {@code false}. Similarly, Gson will + * exclude {@code emailAddress} from deserialization since {@code deserialize} is set to false. + * + * <p>Note that another way to achieve the same effect would have been to just mark the + * {@code password} field as {@code transient}, and Gson would have excluded it even with default + * settings. The {@code @Expose} annotation is useful in a style of programming where you want to + * explicitly specify all fields that should get considered for serialization or deserialization. + * + * @author Inderjeet Singh + * @author Joel Leitch + */ +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.FIELD) +public @interface Expose { + + /** + * If {@code true}, the field marked with this annotation is written out in the JSON while + * serializing. If {@code false}, the field marked with this annotation is skipped from the + * serialized output. Defaults to {@code true}. + * @since 1.4 + */ + public boolean serialize() default true; + + /** + * If {@code true}, the field marked with this annotation is deserialized from the JSON. + * If {@code false}, the field marked with this annotation is skipped during deserialization. + * Defaults to {@code true}. + * @since 1.4 + */ + public boolean deserialize() default true; +} diff --git a/gson/src/main/java/com/google/gson/annotations/JsonAdapter.java b/gson/src/main/java/com/google/gson/annotations/JsonAdapter.java new file mode 100644 index 00000000..2ee3e682 --- /dev/null +++ b/gson/src/main/java/com/google/gson/annotations/JsonAdapter.java @@ -0,0 +1,97 @@ +/* + * Copyright (C) 2014 Google Inc. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.google.gson.annotations; + +import com.google.gson.TypeAdapter; +import com.google.gson.TypeAdapterFactory; +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * An annotation that indicates the Gson {@link TypeAdapter} to use with a class + * or field. + * + * <p>Here is an example of how this annotation is used:</p> + * <pre> + * @JsonAdapter(UserJsonAdapter.class) + * public class User { + * public final String firstName, lastName; + * private User(String firstName, String lastName) { + * this.firstName = firstName; + * this.lastName = lastName; + * } + * } + * public class UserJsonAdapter extends TypeAdapter<User> { + * @Override public void write(JsonWriter out, User user) throws IOException { + * // implement write: combine firstName and lastName into name + * out.beginObject(); + * out.name("name"); + * out.value(user.firstName + " " + user.lastName); + * out.endObject(); + * // implement the write method + * } + * @Override public User read(JsonReader in) throws IOException { + * // implement read: split name into firstName and lastName + * in.beginObject(); + * in.nextName(); + * String[] nameParts = in.nextString().split(" "); + * in.endObject(); + * return new User(nameParts[0], nameParts[1]); + * } + * } + * </pre> + * + * Since User class specified UserJsonAdapter.class in @JsonAdapter annotation, it + * will automatically be invoked to serialize/deserialize User instances. <br> + * + * <p> Here is an example of how to apply this annotation to a field. + * <pre> + * private static final class Gadget { + * @JsonAdapter(UserJsonAdapter2.class) + * final User user; + * Gadget(User user) { + * this.user = user; + * } + * } + * </pre> + * + * It's possible to specify different type adapters on a field, that + * field's type, and in the {@link com.google.gson.GsonBuilder}. Field + * annotations take precedence over {@code GsonBuilder}-registered type + * adapters, which in turn take precedence over annotated types. + * + * <p>The class referenced by this annotation must be either a {@link + * TypeAdapter} or a {@link TypeAdapterFactory}. Using the factory interface + * makes it possible to delegate to the enclosing {@code Gson} instance. + * + * @since 2.3 + * + * @author Inderjeet Singh + * @author Joel Leitch + * @author Jesse Wilson + */ +// Note that the above example is taken from AdaptAnnotationTest. +@Retention(RetentionPolicy.RUNTIME) +@Target({ElementType.TYPE, ElementType.FIELD}) +public @interface JsonAdapter { + + /** Either a {@link TypeAdapter} or {@link TypeAdapterFactory}. */ + Class<?> value(); + +} diff --git a/gson/src/main/java/com/google/gson/annotations/SerializedName.java b/gson/src/main/java/com/google/gson/annotations/SerializedName.java new file mode 100644 index 00000000..06c0a14c --- /dev/null +++ b/gson/src/main/java/com/google/gson/annotations/SerializedName.java @@ -0,0 +1,89 @@ +/* + * Copyright (C) 2008 Google Inc. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.google.gson.annotations; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * An annotation that indicates this member should be serialized to JSON with + * the provided name value as its field name. + * + * <p>This annotation will override any {@link com.google.gson.FieldNamingPolicy}, including + * the default field naming policy, that may have been set on the {@link com.google.gson.Gson} + * instance. A different naming policy can set using the {@code GsonBuilder} class. See + * {@link com.google.gson.GsonBuilder#setFieldNamingPolicy(com.google.gson.FieldNamingPolicy)} + * for more information.</p> + * + * <p>Here is an example of how this annotation is meant to be used:</p> + * <pre> + * public class MyClass { + * @SerializedName("name") String a; + * @SerializedName(value="name1", alternate={"name2", "name3"}) String b; + * String c; + * + * public MyClass(String a, String b, String c) { + * this.a = a; + * this.b = b; + * this.c = c; + * } + * } + * </pre> + * + * <p>The following shows the output that is generated when serializing an instance of the + * above example class:</p> + * <pre> + * MyClass target = new MyClass("v1", "v2", "v3"); + * Gson gson = new Gson(); + * String json = gson.toJson(target); + * System.out.println(json); + * + * ===== OUTPUT ===== + * {"name":"v1","name1":"v2","c":"v3"} + * </pre> + * + * <p>NOTE: The value you specify in this annotation must be a valid JSON field name.</p> + * While deserializing, all values specified in the annotation will be deserialized into the field. + * For example: + * <pre> + * MyClass target = gson.fromJson("{'name1':'v1'}", MyClass.class); + * assertEquals("v1", target.b); + * target = gson.fromJson("{'name2':'v2'}", MyClass.class); + * assertEquals("v2", target.b); + * target = gson.fromJson("{'name3':'v3'}", MyClass.class); + * assertEquals("v3", target.b); + * </pre> + * Note that MyClass.b is now deserialized from either name1, name2 or name3. + * + * @see com.google.gson.FieldNamingPolicy + * + * @author Inderjeet Singh + * @author Joel Leitch + */ +@Retention(RetentionPolicy.RUNTIME) +@Target({ElementType.FIELD, ElementType.METHOD}) +public @interface SerializedName { + + /** + * @return the desired names of the field when it is deserialized or serialized. All of the specified names will be deserialized from. + * The specified first name is what is used for serialization. + */ + String value(); + String[] alternate() default {}; +} diff --git a/gson/src/main/java/com/google/gson/annotations/Since.java b/gson/src/main/java/com/google/gson/annotations/Since.java new file mode 100644 index 00000000..541f154b --- /dev/null +++ b/gson/src/main/java/com/google/gson/annotations/Since.java @@ -0,0 +1,61 @@ +/* + * Copyright (C) 2008 Google Inc. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.google.gson.annotations; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * An annotation that indicates the version number since a member or a type has been present. + * This annotation is useful to manage versioning of your Json classes for a web-service. + * + * <p> + * This annotation has no effect unless you build {@link com.google.gson.Gson} with a + * {@link com.google.gson.GsonBuilder} and invoke + * {@link com.google.gson.GsonBuilder#setVersion(double)} method. + * + * <p>Here is an example of how this annotation is meant to be used:</p> + * <pre> + * public class User { + * private String firstName; + * private String lastName; + * @Since(1.0) private String emailAddress; + * @Since(1.0) private String password; + * @Since(1.1) private Address address; + * } + * </pre> + * + * <p>If you created Gson with {@code new Gson()}, the {@code toJson()} and {@code fromJson()} + * methods will use all the fields for serialization and deserialization. However, if you created + * Gson with {@code Gson gson = new GsonBuilder().setVersion(1.0).create()} then the + * {@code toJson()} and {@code fromJson()} methods of Gson will exclude the {@code address} field + * since it's version number is set to {@code 1.1}.</p> + * + * @author Inderjeet Singh + * @author Joel Leitch + */ +@Retention(RetentionPolicy.RUNTIME) +@Target({ElementType.FIELD, ElementType.TYPE}) +public @interface Since { + /** + * the value indicating a version number since this member + * or type has been present. + */ + double value(); +} diff --git a/gson/src/main/java/com/google/gson/annotations/Until.java b/gson/src/main/java/com/google/gson/annotations/Until.java new file mode 100644 index 00000000..4648b8a2 --- /dev/null +++ b/gson/src/main/java/com/google/gson/annotations/Until.java @@ -0,0 +1,66 @@ +/* + * Copyright (C) 2008 Google Inc. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.google.gson.annotations; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * An annotation that indicates the version number until a member or a type should be present. + * Basically, if Gson is created with a version number that exceeds the value stored in the + * {@code Until} annotation then the field will be ignored from the JSON output. This annotation + * is useful to manage versioning of your JSON classes for a web-service. + * + * <p> + * This annotation has no effect unless you build {@link com.google.gson.Gson} with a + * {@link com.google.gson.GsonBuilder} and invoke + * {@link com.google.gson.GsonBuilder#setVersion(double)} method. + * + * <p>Here is an example of how this annotation is meant to be used:</p> + * <pre> + * public class User { + * private String firstName; + * private String lastName; + * @Until(1.1) private String emailAddress; + * @Until(1.1) private String password; + * } + * </pre> + * + * <p>If you created Gson with {@code new Gson()}, the {@code toJson()} and {@code fromJson()} + * methods will use all the fields for serialization and deserialization. However, if you created + * Gson with {@code Gson gson = new GsonBuilder().setVersion(1.2).create()} then the + * {@code toJson()} and {@code fromJson()} methods of Gson will exclude the {@code emailAddress} + * and {@code password} fields from the example above, because the version number passed to the + * GsonBuilder, {@code 1.2}, exceeds the version number set on the {@code Until} annotation, + * {@code 1.1}, for those fields. + * + * @author Inderjeet Singh + * @author Joel Leitch + * @since 1.3 + */ +@Retention(RetentionPolicy.RUNTIME) +@Target({ElementType.FIELD, ElementType.TYPE}) +public @interface Until { + + /** + * the value indicating a version number until this member + * or type should be ignored. + */ + double value(); +} diff --git a/gson/src/main/java/com/google/gson/annotations/package-info.java b/gson/src/main/java/com/google/gson/annotations/package-info.java new file mode 100644 index 00000000..1c461fd6 --- /dev/null +++ b/gson/src/main/java/com/google/gson/annotations/package-info.java @@ -0,0 +1,6 @@ +/** + * This package provides annotations that can be used with {@link com.google.gson.Gson}. + * + * @author Inderjeet Singh, Joel Leitch + */ +package com.google.gson.annotations;
\ No newline at end of file |