io.atomix.catalyst.serializer.CatalystSerializable Maven / Gradle / Ivy
/*
* Copyright 2015 the original author or authors.
*
* 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 io.atomix.catalyst.serializer;
import io.atomix.catalyst.buffer.Buffer;
import io.atomix.catalyst.buffer.BufferInput;
import io.atomix.catalyst.buffer.BufferOutput;
/**
* Provides an interface for serializable types.
*
* Classes can implement this interface as an alternative to providing a separate {@link TypeSerializer} instance. Note,
* however, that {@link CatalystSerializable} classes must still be registered via {@link Serializer#register(Class)}.
*
* Types that implement this interface should provide a no-argument constructor via which Catalyst can allocate new
* instances of the class. During serialization, Catalyst will call {@link CatalystSerializable#writeObject(BufferOutput, Serializer)}
* to serialize the object to a {@link Buffer}. During deserialization, Catalyst will call
* {@link CatalystSerializable#readObject(BufferInput, Serializer)} to deserialize
* the object from a {@link Buffer}.
*
* @author Jordan Halterman
*/
public interface CatalystSerializable {
/**
* Writes the object to the given buffer.
*
* Implementations of this method should write object attributes to the given buffer. Note that assumptions cannot be
* safely made about the given buffer's {@link Buffer#position()}, {@link Buffer#limit()},
* or any other navigational attributes of the provided {@link Buffer}. To navigate the buffer,
* set the buffer's {@link Buffer#mark()} and {@link Buffer#reset()}.
*
* When writing dynamically sized attributes such as strings and collections, users should always write the attribute's
* count to the given buffer. Catalyst makes no guarantee that the buffer provided to
* {@link CatalystSerializable#readObject(BufferInput, Serializer)} will reflect the
* number of bytes written to the buffer during serialization.
*
* @param buffer The buffer to which to write the object.
* @param serializer The serializer with which the object is being serialized.
* @see CatalystSerializable#readObject(BufferInput, Serializer)
*/
void writeObject(BufferOutput buffer, Serializer serializer);
/**
* Reads the object from the given buffer.
*
* Implementations of this method should read object attributes from the given buffer in the same order with which they
* were written to the buffer in {@link CatalystSerializable#writeObject(BufferOutput, Serializer)}.
* Catalyst guarantees only that the current {@link Buffer#position()} will reflect the start
* of the bytes written by {@link CatalystSerializable#writeObject(BufferOutput, Serializer)},
* but not that the {@link Buffer#remaining()} bytes reflect the number of bytes written by
* {@link CatalystSerializable#writeObject(BufferOutput, Serializer)}.
*
* @param buffer The buffer from which to read the object.
* @param serializer The serializer with which the object is being serialized.
* @see CatalystSerializable#writeObject(BufferOutput, Serializer)
*/
void readObject(BufferInput buffer, Serializer serializer);
}