/*
 * Copyright 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 com.google.gwt.user.server.rpc;

import com.google.gwt.user.client.rpc.CustomFieldSerializer;
import com.google.gwt.user.client.rpc.SerializationException;
import com.google.gwt.user.server.rpc.impl.DequeMap;
import com.google.gwt.user.server.rpc.impl.ServerSerializationStreamReader;

import java.lang.reflect.Type;
import java.lang.reflect.TypeVariable;

/**
 * An interface that may be implemented by server-side class-based custom field
 * serializers.
 * 
 * Usage of this class will reduce the amount of server-side reflection during
 * serialization and provide type safety.
 * 
 * @param <T> the type of the object being serialized
 */
public abstract class ServerCustomFieldSerializer<T> extends CustomFieldSerializer<T> {
  /**
   * Deserializes the content of the object from the
   * {@link ServerSerializationStreamReader}, with type checking.
   * 
   * The calling code has verified that the instance this method is
   * deserializing is of the correct type for the RPC call. However, is has not
   * verified the objects that this deserializer will read. It is this method's
   * responsibility to verify the types of objects that it reads. Failure to
   * do so leaves the server vulnerable to an attacker who replaces
   * deserialized data in the RPC message with data that takes an exponential
   * time to deserialize or otherwise causes problems.
   * 
   * In practice, any call to ServerSerilizationStreamReader.readObject() should
   * use the type checking version, passing in the expected type of the object
   * to be read. For classes that deserialize objects of generic types, the
   * expectedParameterTypes array provides the type bound to each type
   * generic parameter defined by the instance. See the built-in GWT
   * server custom field serializers for examples.
   * 
   * @param streamReader the {@link ServerSerializationStreamReader} to read the
   *          object's content from
   * @param instance the object instance to deserialize
   * @param expectedParameterTypes the types we expect for any generic
   *          parameters used by this class, in the order in which they
   *          appear in the instance.getTypeParameters()
   * @param resolvedTypes map from generic types to actual types
   * 
   * @throws SerializationException if the deserialization operation is not
   *           successful
   */
  public abstract void deserializeInstance(ServerSerializationStreamReader streamReader,
      T instance, Type[] expectedParameterTypes,
      DequeMap<TypeVariable<?>, Type> resolvedTypes) throws SerializationException;

  /**
   * Instantiates an object from the {@link ServerSerializationStreamReader},
   * without type checking.
   * 
   * @param streamReader the {@link ServerSerializationStreamReader} to read the
   *          object's content from
   * @return an object that has been loaded from the
   *         {@link ServerSerializationStreamReader}
   * 
   * @throws SerializationException if the instantiation operation is not
   *           successful
   */
  public T instantiateInstance(ServerSerializationStreamReader streamReader)
      throws SerializationException {
    return super.instantiateInstance(streamReader);
  }

  /**
   * Instantiates an object from the {@link ServerSerializationStreamReader},
   * with type checking.
   * <p>
   * Most of the time, this can be left unimplemented and the framework will
   * instantiate the instance itself. This is typically used when the object
   * being deserialized is immutable, hence it has to be created with its state
   * already set.
   * <p>
   * If this is overridden, the
   * {@link CustomFieldSerializer#hasCustomInstantiateInstance()} method must
   * return <code>true</code> in order for the framework to know to call it.
   * 
   * The calling code has verified that the instance this method is
   * instantiating is of the correct type for the RPC call. However, is has not
   * verified the objects that this instantiator will read. It is this method's
   * responsibility to verify the types of objects that it reads. Failure to
   * do so leaves the server vulnerable to an attacker who replaces
   * deserialized data in the RPC message with data that takes an exponential
   * time to instantiate or otherwise causes problems.
   * 
   * In practice, any call to ServerSerilizationStreamReader.readObject() should
   * use the type checking version, passing in the expected type of the object
   * to be read. For classes that instantiate objects of generic types, the
   * expectedParameterTypes array provides the type bound to each type
   * generic parameter defined by the instance. See the built-in GWT
   * server custom field serializers for examples.
   *
   * @param streamReader the {@link ServerSerializationStreamReader} to read the
   *          object's content from
   * @param expectedParameterTypes the types we expect for any generic
   *          parameters used by this class, in the order returned by
   *          instance.getTypeParameters()
   * @param resolvedTypes map from generic types to actual types
   * 
   * @return an object that has been loaded from the
   *         {@link ServerSerializationStreamReader}
   * 
   * @throws SerializationException if the instantiation operation is not
   *           successful
   */
  public T instantiateInstance(ServerSerializationStreamReader streamReader,
      Type[] expectedParameterTypes,
      DequeMap<TypeVariable<?>, Type> resolvedTypes) throws SerializationException {
    return super.instantiateInstance(streamReader);
  }
}