org.apache.geode.DataSerializable Maven / Gradle / Ivy
Show all versions of geode-core Show documentation
/*
* Licensed to the Apache Software Foundation (ASF) under one or more contributor license
* agreements. See the NOTICE file distributed with this work for additional information regarding
* copyright ownership. The ASF licenses this file to You 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 org.apache.geode;
import java.io.DataInput;
import java.io.DataOutput;
import java.io.IOException;
import java.io.Serializable;
/**
* 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 org.apache.geode.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
*
* @since GemFire 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.
*
* @param out the {@link DataOutput} to write to
*
* @throws IOException A problem occurs while writing to out
*/
void toData(DataOutput out) throws IOException;
/**
* Reads the state of this object as primitive data from the given DataInput.
*
* @param in the {@link DataInput} to read from
*
* @throws IOException A problem occurs while reading from in
* @throws ClassNotFoundException A class could not be loaded while reading from in
*/
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)
*/
interface Replaceable {
/**
* Replaces this object with another in the "output stream" written by
* {@link DataSerializer#writeObject(Object, DataOutput)}.
*
* @return the object that will be used to replace this object
* @throws IOException if an exception is encountered
*/
Object replace() throws IOException;
}
}