/*
 * Copyright (C) 2011 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 cn.emay.sdk.util.json.gson;

import cn.emay.sdk.util.json.gson.reflect.TypeToken;

/**
 * Creates type adapters for set of related types. Type adapter factories are
 * most useful when several types share similar structure in their JSON form.
 *
 * <h3>Example: Converting enums to lowercase</h3> In this example, we implement
 * a factory that creates type adapters for all enums. The type adapters will
 * write enums in lowercase, despite the fact that they're defined in
 * {@code CONSTANT_CASE} in the corresponding Java model:
 * 
 * <pre>
 * {
 * 	&#64;code
 *
 * 	public class LowercaseEnumTypeAdapterFactory implements TypeAdapterFactory {
 * 		public <T> TypeAdapter<T> create(Gson gson, TypeToken<T> type) {
 * 			Class<T> rawType = (Class<T>) type.getRawType();
 * 			if (!rawType.isEnum()) {
 * 				return null;
 * 			}
 *
 * 			final Map<String, T> lowercaseToConstant = new HashMap<String, T>();
 * 			for (T constant : rawType.getEnumConstants()) {
 * 				lowercaseToConstant.put(toLowercase(constant), constant);
 * 			}
 *
 * 			return new TypeAdapter<T>() {
 * 				public void write(JsonWriter out, T value) throws IOException {
 * 					if (value == null) {
 * 						out.nullValue();
 * 					} else {
 * 						out.value(toLowercase(value));
 * 					}
 * 				}
 *
 * 				public T read(JsonReader reader) throws IOException {
 * 					if (reader.peek() == JsonToken.NULL) {
 * 						reader.nextNull();
 * 						return null;
 * 					} else {
 * 						return lowercaseToConstant.get(reader.nextString());
 * 					}
 * 				}
 * 			};
 * 		}
 *
 * 		private String toLowercase(Object o) {
 * 			return o.toString().toLowerCase(Locale.US);
 * 		}
 * 	}
 * }
 * </pre>
 *
 * <p>
 * Type adapter factories select which types they provide type adapters for. If
 * a factory cannot support a given type, it must return null when that type is
 * passed to {@link #create}. Factories should expect {@code
 * create()} to be called on them for many types and should return null for most
 * of those types. In the above example the factory returns null for calls to
 * {@code create()} where {@code type} is not an enum.
 *
 * <p>
 * A factory is typically called once per type, but the returned type adapter
 * may be used many times. It is most efficient to do expensive work like
 * reflection in {@code create()} so that the type adapter's {@code
 * read()} and {@code write()} methods can be very fast. In this example the
 * mapping from lowercase name to enum value is computed eagerly.
 *
 * <p>
 * As with type adapters, factories must be <i>registered</i> with a
 * {@link com.google.gson.GsonBuilder} for them to take effect:
 * 
 * <pre>
 *    {@code
 *
 *  GsonBuilder builder = new GsonBuilder();
 *  builder.registerTypeAdapterFactory(new LowercaseEnumTypeAdapterFactory());
 *  ...
 *  Gson gson = builder.create();
 * }
 * </pre>
 * 
 * If multiple factories support the same type, the factory registered earlier
 * takes precedence.
 *
 * <h3>Example: composing other type adapters</h3> In this example we implement
 * a factory for Guava's {@code Multiset} collection type. The factory can be
 * used to create type adapters for multisets of any element type: the type
 * adapter for {@code
 * Multiset<String>} is different from the type adapter for {@code
 * Multiset<URL>}.
 *
 * <p>
 * The type adapter <i>delegates</i> to another type adapter for the multiset
 * elements. It figures out the element type by reflecting on the multiset's
 * type token. A {@code Gson} is passed in to {@code create} for just this
 * purpose:
 * 
 * <pre>
 * {
 * 	&#64;code
 *
 * 	public class MultisetTypeAdapterFactory implements TypeAdapterFactory {
 * 		public <T> TypeAdapter<T> create(Gson gson, TypeToken<T> typeToken) {
 * 			Type type = typeToken.getType();
 * 			if (typeToken.getRawType() != Multiset.class || !(type instanceof ParameterizedType)) {
 * 				return null;
 * 			}
 *
 * 			Type elementType = ((ParameterizedType) type).getActualTypeArguments()[0];
 * 			TypeAdapter<?> elementAdapter = gson.getAdapter(TypeToken.get(elementType));
 * 			return (TypeAdapter<T>) newMultisetAdapter(elementAdapter);
 * 		}
 *
 * 		private <E> TypeAdapter<Multiset<E>> newMultisetAdapter(final TypeAdapter<E> elementAdapter) {
 * 			return new TypeAdapter<Multiset<E>>() {
 * 				public void write(JsonWriter out, Multiset<E> value) throws IOException {
 * 					if (value == null) {
 * 						out.nullValue();
 * 						return;
 * 					}
 *
 * 					out.beginArray();
 * 					for (Multiset.Entry<E> entry : value.entrySet()) {
 * 						out.value(entry.getCount());
 * 						elementAdapter.write(out, entry.getElement());
 * 					}
 * 					out.endArray();
 * 				}
 *
 * 				public Multiset<E> read(JsonReader in) throws IOException {
 * 					if (in.peek() == JsonToken.NULL) {
 * 						in.nextNull();
 * 						return null;
 * 					}
 *
 * 					Multiset<E> result = LinkedHashMultiset.create();
 * 					in.beginArray();
 * 					while (in.hasNext()) {
 * 						int count = in.nextInt();
 * 						E element = elementAdapter.read(in);
 * 						result.add(element, count);
 * 					}
 * 					in.endArray();
 * 					return result;
 * 				}
 * 			};
 * 		}
 * 	}
 * }
 * </pre>
 * 
 * Delegating from one type adapter to another is extremely powerful; it's the
 * foundation of how Gson converts Java objects and collections. Whenever
 * possible your factory should retrieve its delegate type adapter in the
 * {@code create()} method; this ensures potentially-expensive type adapter
 * creation happens only once.
 *
 * @since 2.1
 */
public interface TypeAdapterFactory {

	/**
	 * Returns a type adapter for {@code type}, or null if this factory doesn't
	 * support {@code type}.
	 */
	<T> TypeAdapter<T> create(Gson gson, TypeToken<T> type);
}