com.gemstone.gemfire.DataSerializable Maven / Gradle / Ivy
Show all versions of gemfire-core Show documentation
/*
* Copyright (c) 2010-2015 Pivotal Software, Inc. All rights reserved.
*
* 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. See accompanying
* LICENSE file.
*/
package com.gemstone.gemfire;
import java.io.*;
/**
* An interface for objects whose state can be written/read as
* primitive types and strings ("data"). That is, instead of
* serializing itself to an {@link java.io.ObjectOutputStream}, a
* DataSerializable can serialize itself to a {@link
* DataOutput}. By implementing this interface, objects can be
* serialized faster and in a more compact format than standard Java
* serialization. The {@link DataSerializer} class contains a number
* of static methods that may be helpful to implementations of
* DataSerializable.
*
*
*
* When possible, GemFire respects the DataSerializable
* contract to provide optimal object serialization. For instance, if
* a DataSerializable object is
* {@linkplain com.gemstone.gemfire.cache.Region#put(Object, Object) placed} into a distributed
* cache region, its toData method will be used to
* serialize it when it is sent to another member of the distributed
* system.
*
*
*
* To avoid the overhead of Java reflection,
* DataSerializable classes may register an {@link
* Instantiator} to be used during deserialization. Alternatively,
* classes that implement DataSerializable can provide a
* zero-argument constructor that will be invoked when they are read
* with {@link DataSerializer#readObject}.
*
*
*
* Some classes (especially third-party classes that you may not have
* the source code to) cannot be modified to implement
* DataSerializable. These classes can be data
* serialized by an instance of {@link DataSerializer}.
*
*
*
* DataSerializable offers improved performance over
* standard Java serialization, but does not offer all of the features
* of standard Java serialization. In particular, data serialization
* does not attempt to maintain referential integrity among the
* objects it is writing or reading. As a result, data serialization
* should not be used with complex object graphs. Attempting to data
* serialize graphs that contain object cycles will result in infinite
* recursion and a {@link StackOverflowError}. Attempting to
* deserialize an object graph that contains multiple reference
* paths to the same object will result in multiple copies of the
* objects that are referred to through multiple paths.
*
*
*
*
* 
*
*
* @see java.io.Serializable
* @see DataSerializer
* @see Instantiator
*
* @author David Whitlock
* @since 3.5 */
public interface DataSerializable extends Serializable {
/**
* Writes the state of this object as primitive data to the given
* DataOutput.
*
* Since 5.7 it is possible for any method call to the specified
* DataOutput to throw {@link GemFireRethrowable}.
* It should not be caught by user code.
* If it is it must be rethrown.
*
* @throws IOException
* A problem occurs while writing to out
*/
public void toData(DataOutput out) throws IOException;
/**
* Reads the state of this object as primitive data from the given
* DataInput.
*
* @throws IOException
* A problem occurs while reading from in
* @throws ClassNotFoundException
* A class could not be loaded while reading from
* in
*/
public void fromData(DataInput in)
throws IOException, ClassNotFoundException;
//////////////////////// Inner Classes ////////////////////////
/**
* Replaceable allows an object to write an alternative
* version of itself to a DataOutput. It is similar to
* the writeReplace method of standard Java
* {@linkplain java.io.Serializable serialization}.
*
*
*
* Note that if a Replaceable is also
* DataSerializable, its toData method
* will not be invoked. Instead, its replacement object will
* be written to the stream using {@link DataSerializer#writeObject(Object, DataOutput)}.
*
* @see DataSerializer#writeObject(Object, DataOutput)
*/
public interface Replaceable {
/**
* Replaces this object with another in the "output stream"
* written by {@link DataSerializer#writeObject(Object, DataOutput)}.
*/
public Object replace() throws IOException;
}
}