Package org.apache.jackrabbit.oak.segment

Class Compactor

  • Direct Known Subclasses:
    CheckpointCompactor, ClassicCompactor, LegacyCheckpointCompactor
    public abstract class Compactor
extends Object
    A compactor compacts the differences between two NodeStates (before and after) on top of a third NodeState (onto).

    The compaction can be done in two ways:

    • Compacting down, where the differences between before and after are compacted on top of the after state. This is useful, because it allows for partial compactions. I.e. compactions that are "soft-cancelled" before the full compaction process completes.

      During "down compaction", parts of the tree are compacted and the respective node states are substituted with their compacted counterparts. This results in an {@link #equals(Object)| equal} node state at any moment in the process, which means that if the compaction is cancelled, a valid, albeit only partially compacted state can be returned.

      After a partially completed "down compaction", the segments referenced by the root record can be of different generations. However, the stable identifier of the compacted records remain unchanged.

    • Compacting up, where the differences between before and after are compacted on top of before. This is useful to create a new NodeState that contains the changes from after but is based on before, often on an empty node-state.

      "Up compaction" results in a fully compacted state, but it can only be "hard-canceller", i.e. either the full compaction is done, or nothing at all (null is returned if cancelled).

      Generally, "up compaction" is more thorough than "down compaction", because the entire content tree is rewritten. Furthermore, it guarantees that after compaction all reachable segments are of the same, new generation.

    The compaction process can be cancelled through a Canceller. If cancellation is requested, the compaction will either abort completely or, in case of compacting down, return a partially compacted state.

    • Constructor Detail

      • Compactor

        public Compactor()

    • Method Detail

      • compactDown

        @Nullable
public final @Nullable CompactedNodeState compactDown​(@NotNull
                                                      @NotNull NodeState state,
                                                      @NotNull
                                                      @NotNull Canceller hardCanceller,
                                                      @NotNull
                                                      @NotNull Canceller softCanceller)
                                               throws IOException
        Convenience method to run compactDown(NodeState, NodeState, Canceller, Canceller), where the before state is the empty node state.
        Parameters:
        state - the (after) node state to compact
        hardCanceller - the trigger for hard cancellation, will abandon compaction if cancelled
        softCanceller - the trigger for soft cancellation, will return partially compacted state if cancelled
        Returns:
        the fully or partially compacted node state, or null if hard-cancelled
        Throws:
        IOException - will throw exception if any errors occur during compaction

      • compactDown

        @Nullable
public abstract @Nullable CompactedNodeState compactDown​(@NotNull
                                                         @NotNull NodeState before,
                                                         @NotNull
                                                         @NotNull NodeState after,
                                                         @NotNull
                                                         @NotNull Canceller hardCanceller,
                                                         @NotNull
                                                         @NotNull Canceller softCanceller)
                                                  throws IOException
        compact the differences between after and before on top of after.
        Parameters:
        before - the node state to diff against from after
        after - the node state diffed against before
        hardCanceller - the trigger for hard cancellation, will abandon compaction if cancelled
        softCanceller - the trigger for soft cancellation, will return partially compacted state if cancelled
        Returns:
        the compacted node state or null if hard-cancelled
        Throws:
        IOException - will throw exception if any errors occur during compaction

      • compactUp

        @Nullable
public final @Nullable CompactedNodeState compactUp​(@NotNull
                                                    @NotNull NodeState state,
                                                    @NotNull
                                                    @NotNull Canceller canceller)
                                             throws IOException
        Convenience method to run compactUp(NodeState, NodeState, Canceller), where the before state is the empty node state.
        Parameters:
        state - the (after) node state to compact
        canceller - the trigger for hard cancellation, will abandon compaction if cancelled
        Returns:
        the fully compacted node state, or null if hard-cancelled
        Throws:
        IOException - will throw exception if any errors occur during compaction

      • compact

        @Nullable
public abstract @Nullable CompactedNodeState compact​(@NotNull
                                                     @NotNull NodeState before,
                                                     @NotNull
                                                     @NotNull NodeState after,
                                                     @NotNull
                                                     @NotNull NodeState onto,
                                                     @NotNull
                                                     @NotNull Canceller canceller)
                                              throws IOException
        compact the differences between after and before on top of onto.
        Parameters:
        before - the node state to diff against from after
        after - the node state diffed against before
        onto - the node state to compact to apply the diff to
        canceller - the trigger for hard cancellation, will abandon compaction if cancelled
        Returns:
        the compacted node state or null if hard-cancelled
        Throws:
        IOException - will throw exception if any errors occur during compaction