1 /* 2 * Copyright (C) 2008 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.gson; 18 19 import java.lang.reflect.Type; 20 21 /** 22 * This interface is implemented to create instances of a class that does not define a no-args 23 * constructor. If you can modify the class, you should instead add a private, or public 24 * no-args constructor. However, that is not possible for library classes, such as JDK classes, or 25 * a third-party library that you do not have source-code of. In such cases, you should define an 26 * instance creator for the class. Implementations of this interface should be registered with 27 * {@link GsonBuilder#registerTypeAdapter(Type, Object)} method before Gson will be able to use 28 * them. 29 * <p>Let us look at an example where defining an InstanceCreator might be useful. The 30 * {@code Id} class defined below does not have a default no-args constructor.</p> 31 * 32 * <pre> 33 * public class Id<T> { 34 * private final Class<T> clazz; 35 * private final long value; 36 * public Id(Class<T> clazz, long value) { 37 * this.clazz = clazz; 38 * this.value = value; 39 * } 40 * } 41 * </pre> 42 * 43 * <p>If Gson encounters an object of type {@code Id} during deserialization, it will throw an 44 * exception. The easiest way to solve this problem will be to add a (public or private) no-args 45 * constructor as follows:</p> 46 * 47 * <pre> 48 * private Id() { 49 * this(Object.class, 0L); 50 * } 51 * </pre> 52 * 53 * <p>However, let us assume that the developer does not have access to the source-code of the 54 * {@code Id} class, or does not want to define a no-args constructor for it. The developer 55 * can solve this problem by defining an {@code InstanceCreator} for {@code Id}:</p> 56 * 57 * <pre> 58 * class IdInstanceCreator implements InstanceCreator<Id> { 59 * public Id createInstance(Type type) { 60 * return new Id(Object.class, 0L); 61 * } 62 * } 63 * </pre> 64 * 65 * <p>Note that it does not matter what the fields of the created instance contain since Gson will 66 * overwrite them with the deserialized values specified in Json. You should also ensure that a 67 * <i>new</i> object is returned, not a common object since its fields will be overwritten. 68 * The developer will need to register {@code IdInstanceCreator} with Gson as follows:</p> 69 * 70 * <pre> 71 * Gson gson = new GsonBuilder().registerTypeAdapter(Id.class, new IdInstanceCreator()).create(); 72 * </pre> 73 * 74 * @param <T> the type of object that will be created by this implementation. 75 * 76 * @author Inderjeet Singh 77 * @author Joel Leitch 78 */ 79 public interface InstanceCreator<T> { 80 81 /** 82 * Gson invokes this call-back method during deserialization to create an instance of the 83 * specified type. The fields of the returned instance are overwritten with the data present 84 * in the Json. Since the prior contents of the object are destroyed and overwritten, do not 85 * return an instance that is useful elsewhere. In particular, do not return a common instance, 86 * always use {@code new} to create a new instance. 87 * 88 * @param type the parameterized T represented as a {@link Type}. 89 * @return a default object instance of type T. 90 */ createInstance(Type type)91 public T createInstance(Type type); 92 } 93