001/*
002 * (C) Copyright 2011 Nuxeo SA (http://nuxeo.com/) and contributors.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the GNU Lesser General Public License
006 * (LGPL) version 2.1 which accompanies this distribution, and is available at
007 * http://www.gnu.org/licenses/lgpl.html
008 *
009 * This library is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012 * Lesser General Public License for more details.
013 *
014 * Contributors:
015 *     Florent Guillaume
016 */
017package org.nuxeo.ecm.core.blob.binary;
018
019/**
020 * A Garbage Collector for a {@link BinaryManager}.
021 * <p>
022 * First, inform the GC that it is started by calling {@link #start}.
023 * <p>
024 * Then for all binaries to mark, call {@link #mark}.
025 * <p>
026 * Finally when all binaries have been marked, call{@link #stop} to delete the non-marked binaries.
027 * <p>
028 * After this, {@link #getStatus} returns information about the binaries remaining and those that have been GCed.
029 */
030public interface BinaryGarbageCollector {
031
032    /**
033     * Gets a unique identifier for this garbage collector. Two garbage collectors that would impact the same files must
034     * have the same identifier.
035     *
036     * @return a unique identifier
037     */
038    String getId();
039
040    /**
041     * Starts the garbage collection process.
042     * <p>
043     * After this, all active binaries must be fed to the {@link #mark} method.
044     */
045    void start();
046
047    /**
048     * Marks a binary as being in use.
049     *
050     * @param digest the binary's digest
051     */
052    void mark(String digest);
053
054    /**
055     * Stops the garbage collection process and deletes all binaries that have not been marked (sweep).
056     *
057     * @param delete {@code true} if actual deletion must be performed, {@code false} if the binaries to delete should
058     *            simply be counted in the status
059     */
060    void stop(boolean delete);
061
062    /**
063     * Gets the status of the binaries to GC and of those that won't be.
064     * <p>
065     * Available after {@link #stop}.
066     *
067     * @return the status
068     */
069    BinaryManagerStatus getStatus();
070
071    /**
072     * Checks if a GC is in progress.
073     * <p>
074     * A GC is in progress is {@code #start} has been called but not {@code #stop}.
075     * <p>
076     * It's only useful to call this from a separate thread from the one that calls {@link #mark}.
077     *
078     * @return {@code true} if a GC is in progress
079     */
080    boolean isInProgress();
081
082}