com.sleepycat.je.log.entry.ReplicableLogEntry Maven / Gradle / Ivy
/*-
* Copyright (C) 2002, 2018, Oracle and/or its affiliates. All rights reserved.
*
* This file was distributed by Oracle as part of a version of Oracle Berkeley
* DB Java Edition made available at:
*
* http://www.oracle.com/technetwork/database/database-technologies/berkeleydb/downloads/index.html
*
* Please see the LICENSE file included in the top-level directory of the
* appropriate version of Oracle Berkeley DB Java Edition for a copy of the
* license and additional information.
*/
package com.sleepycat.je.log.entry;
import java.nio.ByteBuffer;
import java.util.Collection;
import com.sleepycat.je.log.LogEntryType;
import com.sleepycat.je.log.VersionedWriteLoggable;
/**
* A sub-interface of {@link LogEntry} that must be implemented by all log
* entries that can be replicated. Replicable log entries are all those
* entries for which the associated {@link LogEntryType}'s {@link
* LogEntryType#isReplicationPossible} method returns {@code true}. These are
* the log entries that can be included in the replication stream distributed
* from feeders to replicas during replication. See [#22336].
*
* Starting with the release using log version 9, as specified by {@link
* LogEntryType#LOG_VERSION_REPLICATE_OLDER}, all replicable log entries
* need to support writing themselves in earlier log formats, to support
* replication during an upgrade when the master is replicated first. Any
* loggable objects that they reference should also implement {@link
* com.sleepycat.je.log.VersionedWriteLoggable} for the same reason.
*
*
The {@link #getLastFormatChange} method identifies the log version for
* which the entry's log format has most recently changed. This information is
* used to determine if the current log format is compatible with a
* non-upgraded replica.
*
*
The {@link #getSize(int, boolean)} method overloading is used when
* creating the buffer that will be used to transmit the log entry data in the
* earlier format.
*
*
The {@link #writeEntry(ByteBuffer, int, boolean)} method overloading is
* used to convert the in-memory format of the log entry into the log data in
* the earlier format.
*
*
To simplify the implementation of writing log entries in multiple log
* version formats, a log entry that needs to be written in a previous format
* will first be read into its in-memory format in the current version, and
* then written from there to the previous format.
*/
public interface ReplicableLogEntry extends LogEntry {
/**
* Returns the log version of the most recent format change for this log
* entry.
*
* @return the log version of the most recent format change
*/
int getLastFormatChange();
/**
* Returns all possible {@link VersionedWriteLoggable} objects that may be
* embedded in the binary data of this log entry.
*
*
This is used by tests to ensure that for each X:Y pair, where X is a
* ReplicableLogEntry and Y is a VersionedWriteLoggable, and X embeds Y
* either directly or indirectly, X.getLastFormatChange is greater than or
* equal to Y.getLastFormatChange.
*
*
Each ReplicableLogEntry and VersionedWriteLoggable class typically
* has a LAST_FORMAT_CHANGE constant that is returned by its
* getLastFormatChange method. When bumping this constant for an object X
* embedded by an log entry Y, Y.LAST_FORMAT_CHANGE should also be set to
* the minimum of its current value and X.LAST_FORMAT_CHANGE.
*
*
Enforcing this rule in a general way is made possible by the
* getEmbeddedLoggables method of each ReplicableLogEntry and
* VersionedWriteLoggable. Note that this method is not intended to be
* called outside of tests.
*/
Collection getEmbeddedLoggables();
/**
* Returns the number of bytes needed to store this entry in the format for
* the specified log version. Earlier log versions only need to be
* supported for log entries with format changes made in {@link
* LogEntryType#LOG_VERSION_REPLICATE_OLDER} or greater.
*
* @param logVersion the log version
* @param forReplication whether the entry will be sent over the wire,
* and not written to the log.
* @return the number of bytes to store this entry for the log version
*/
int getSize(int logVersion, boolean forReplication);
/**
* Serializes this object into the specified buffer in the format for the
* the specified log version. Earlier log versions only need to be
* supported for log entries with format changes made in {@link
* LogEntryType#LOG_VERSION_REPLICATE_OLDER} or greater.
*
* @param logBuffer the destination buffer
* @param forReplication whether the entry will be sent over the wire,
* and not written to the log.
* @param logVersion the log version
*/
void writeEntry(ByteBuffer logBuffer,
int logVersion,
boolean forReplication);
/**
* Returns whether this format has a variant that is optimized for
* replication.
*/
boolean hasReplicationFormat();
/**
* Returns whether it is worthwhile to materialize and then re-serialize a
* log entry in a format optimized for replication. Implementations should
* attempt to check efficiently, without instantiating the log entry
* object. Some implementations will simply return false.
*
* WARNING: The logBuffer position must not be changed by this method.
*
*
WARNING: The shared LogEntry object is used for calling this method,
* and this method must not change any of the fields in the object.
*
* @param logBuffer contains the entry that would be re-serialized.
* @param srcVersion the log version of entry in logBuffer.
* @param destVersion the version that would be used for re-serialization.
*/
boolean isReplicationFormatWorthwhile(ByteBuffer logBuffer,
int srcVersion,
int destVersion);
}