Command.CompactionMode (Copycat API Reference (1.1.4))

java.lang.Object
- java.lang.Enum<Command.CompactionMode>
- - io.atomix.copycat.Command.CompactionMode

All Implemented Interfaces:

Serializable, Comparable<Command.CompactionMode>

Enclosing interface:

Command<T>
```
public static enum Command.CompactionMode
extends Enum<Command.CompactionMode>
```
Constants for specifying command compaction modes.
Compaction modes dictate how each command is removed from a Copycat server's internal logs. As commands are submitted to the cluster, written to disk, and replicated, the replicated log can grow unbounded. Command compaction modes allow servers to determine when it's safe to remove a command from the log. Ultimately, it is the responsibility of the state machine and the command applied to it to indicate when the command may be removed from the log. Typically, commands should not be removed from the log until they either no longer contribute to the state machine's state or some other mechanism ensures that the command's state will not be loss, such as is the case with snapshotting.
Commands to a Copycat state machine typically come in one of two flavors; commands are either compacted from the log via snapshotting or log cleaning. Log cleaning is the process of removing commands from the log when they no longer contribute to the state machine's state. Commands compacted via log cleaning are represented by the QUORUM, FULL, SEQUENTIAL, and TOMBSTONE compaction modes. These types of commands are removed from the log in a manor consistent with the configured compaction mode.
Alternatively, the simpler mode of compaction is snapshotting. Snapshotted commands are indicated by the SNAPSHOT compaction mode. When a server takes a snapshot of a state machine, all commands applied to the state machine up to the logical time at which the snapshot was taken may be removed from the log.
It's important to note that command compaction modes only take effect once a command applied to a state machine has been released for compaction. State machines effectively manage commands applied to a state machine like memory. It's always the responsibility of a state machine to indicate when a command can be safely compacted according to its compaction mode by releasing the command back to the server's storage layer for compaction. See the state machine documentation for more info.

Author:

Jordan Halterman

See Also:

Command.compaction()

Enum Constant Summary

Enum Constants
Enum Constant and Description
`DEFAULT` The `DEFAULT` compaction mode is a special compaction mode which is dictated by the type of system to which the command is being submitted.
`EXPIRING` The expiring compaction mode is an alias for the `SEQUENTIAL` compaction mode that is specifically intended for expiring commands like TTLs and other time-based operations.
`FULL` The `FULL` compaction mode retains the command in the log until it has been stored and applied on all servers in the cluster.
`QUORUM` The `QUORUM` compaction mode retains the command in the log until it has been stored on a majority of servers in the cluster and has been applied to the state machine.
`RELEASE` The `RELEASE` compaction mode retains the command in the log until it has been stored on a majority of servers in the cluster and has been released by the state machine.
`SEQUENTIAL` The sequential compaction mode retains the command in the log until it has been stored and applied on all servers and until all prior commands have been compacted from the log.
`SNAPSHOT` The `SNAPSHOT` compaction mode indicates commands for which resulting state is stored in state machine snapshots.
`TOMBSTONE` The tombstone compaction mode is an alias for the `SEQUENTIAL` compaction mode that is specifically intended for tombstone commands.
`UNKNOWN` The `UNKNOWN` compaction mode is a special compaction mode that behaves consistently for all system types.

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static Command.CompactionMode`	`valueOf(String name)` Returns the enum constant of this type with the specified name.
`static Command.CompactionMode[]`	`values()` Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum
compareTo, equals, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

- Enum Constant Detail
  - DEFAULT
```
public static final Command.CompactionMode DEFAULT
```
    The DEFAULT compaction mode is a special compaction mode which is dictated by the type of system to which the command is being submitted. If the system's state machine supports snapshotting, the command will be compacted via snapshots.
    The compaction mode for DEFAULT commands is determined by whether the state machine is snapshottable. Commands applied to snapshottable state machines will be cleaned from the log once a snapshot is taken after the command is applied to the state machine.
  - UNKNOWN
```
public static final Command.CompactionMode UNKNOWN
```
    The UNKNOWN compaction mode is a special compaction mode that behaves consistently for all system types.
    This compaction mode ensures that commands will only be removed from the log when safe to do so in all potential cases. In practice, this means UNKNOWN commands will only be removed from the log once they have been applied to the state machine and a snapshot of the state machine has been taken at some point after the command was applied. Additionally, UNKNOWN commands will only be removed from the log during major compaction to ensure that any prior related commands will have been removed as well. For this reason, this compaction mode can be extremely inefficient as servers are able to compact their logs less frequently and infrequent compactions require more disk I/O. It is strongly recommended that commands provide specific compaction modes to improve compaction performance.
  - SNAPSHOT
```
public static final Command.CompactionMode SNAPSHOT
```
    The SNAPSHOT compaction mode indicates commands for which resulting state is stored in state machine snapshots. Snapshot commands will be stored in the Raft log only until a snapshot of the state machine state has been written to disk, at which time they'll be removed from the log.
    While commands with the SNAPSHOT compaction mode may be removed once a snapshot of the state machine state has been taken, it's still safe for SNAPSHOT commands to trigger state machine events. In the event that a command triggers an event to a client, servers will ensure that the command is maintained in the log until all associated events have been received by clients. That is, commands will never be replaced by a snapshot prior to events being received by clients. In the event of a failure and replay of the log, the state machine will always see commands for which events have not been acknowledged.
  - RELEASE
```
public static final Command.CompactionMode RELEASE
```
    The RELEASE compaction mode retains the command in the log until it has been stored on a majority of servers in the cluster and has been released by the state machine.
    This compaction mode typically represents normal writes to a state machine. Once a RELEASE command has been applied on a majority of state machines and have been released from memory, the command may be safely removed from the log. It is the state machine's responsibility to indicate when it's safe for a RELEASE command to be removed from the log by explicitly releasing the command once it no longer contributes to the state machine's state. For instance, when one write overwrites the state that resulted from a previous write, the previous write can be safely released and removed from the log during compaction.
  - QUORUM
```
public static final Command.CompactionMode QUORUM
```
    The QUORUM compaction mode retains the command in the log until it has been stored on a majority of servers in the cluster and has been applied to the state machine.
    This compaction mode typically represents normal writes to a state machine. Once a QUORUM command has been applied on a majority of state machines and have been released from memory, the command may be safely removed from the log. It is the state machine's responsibility to indicate when it's safe for a QUORUM command to be removed from the log by explicitly releasing the command once it no longer contributes to the state machine's state. For instance, when one write overwrites the state that resulted from a previous write, the previous write can be safely released and removed from the log during compaction.
  - FULL
```
public static final Command.CompactionMode FULL
```
    The FULL compaction mode retains the command in the log until it has been stored and applied on all servers in the cluster.
    This compaction mode can be useful for cases where it's essential that a command be seen by all servers in the cluster. Even if a FULL command is applied to a state machine and is subsequently released by that state machine, servers will still ensure the command is replicated and applied to all state machines in the cluster prior to removing the command from the log. Once the command has been applied to and released by all state machines, it may be removed from server logs during compaction.
    In cases where a new server is joining the cluster, the concept of full replication only applies to commands committed to the cluster after the new server joined. In other words, if a new server s joins at logical time t then commands with the FULL compaction mode committed after time t + 1 will be required to be stored and applied on server s to meet the requirements for full replication.
  - SEQUENTIAL
```
public static final Command.CompactionMode SEQUENTIAL
```
    The sequential compaction mode retains the command in the log until it has been stored and applied on all servers and until all prior commands have been compacted from the log.
    The SEQUENTIAL compaction mode adds to the full replication requirement of the FULL compaction mode to also require that commands be removed from the log in sequential order. Typically, this compaction mode is used for so called tombstone commands. Sequential ordering is critical in the handling of tombstones since they essentially represent the absence of state. A tombstone cannot be safely removed from the log until all prior related entries have been removed. Compacting tombstones sequentially ensures that any prior related commands will have been compacted from the log prior to the tombstone being removed.
  - EXPIRING
```
public static final Command.CompactionMode EXPIRING
```
    The expiring compaction mode is an alias for the SEQUENTIAL compaction mode that is specifically intended for expiring commands like TTLs and other time-based operations. Expiring commands will be retained in the log until stored and applied on all servers and will only be removed from the log once all prior released entries have been removed.
    The EXPIRING compaction mode adds to the full replication requirement of the FULL compaction mode to also require that commands be removed from the log in sequential order. Typically, this compaction mode is used for so called tombstone commands. Sequential ordering is critical in the handling of tombstones since they essentially represent the absence of state. A tombstone cannot be safely removed from the log until all prior related entries have been removed. Compacting tombstones sequentially ensures that any prior related commands will have been compacted from the log prior to the tombstone being removed.
  - TOMBSTONE
```
public static final Command.CompactionMode TOMBSTONE
```
    The tombstone compaction mode is an alias for the SEQUENTIAL compaction mode that is specifically intended for tombstone commands. Tombstones will be retained in the log until stored and applied on all servers, and tombstones will only be removed from the log once all prior released entries have been removed.
    The TOMBSTONE compaction mode adds to the full replication requirement of the FULL compaction mode to also require that commands be removed from the log in sequential order. Typically, this compaction mode is used for so called tombstone commands. Sequential ordering is critical in the handling of tombstones since they essentially represent the absence of state. A tombstone cannot be safely removed from the log until all prior related entries have been removed. Compacting tombstones sequentially ensures that any prior related commands will have been compacted from the log prior to the tombstone being removed.
- Method Detail
  - values
```
public static Command.CompactionMode[] values()
```
    Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
```
for (Command.CompactionMode c : Command.CompactionMode.values())
    System.out.println(c);
```
    Returns:
    
    an array containing the constants of this enum type, in the order they are declared
  - valueOf
```
public static Command.CompactionMode valueOf(String name)
```
    Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
    
    Parameters:
    
    name - the name of the enum constant to be returned.
    
    Returns:
    
    the enum constant with the specified name
    
    Throws:
    
    IllegalArgumentException - if this enum type has no constant with the specified name
    
    NullPointerException - if the argument is null

Enum Command.CompactionMode

Enum Constant Summary

Method Summary

Methods inherited from class java.lang.Enum

Methods inherited from class java.lang.Object

Enum Constant Detail

DEFAULT

UNKNOWN

SNAPSHOT

RELEASE

QUORUM

FULL

SEQUENTIAL

EXPIRING

TOMBSTONE

Method Detail

values

valueOf