001/*
002 * (C) Copyright 2011 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 *
016 * Contributors:
017 *     Florent Guillaume
018 */
019package org.nuxeo.ecm.core.blob.binary;
020
021/**
022 * A Garbage Collector for a {@link BinaryManager}.
023 * <p>
024 * First, inform the GC that it is started by calling {@link #start}.
025 * <p>
026 * Then for all binaries to mark, call {@link #mark}.
027 * <p>
028 * Finally when all binaries have been marked, call{@link #stop} to delete the non-marked binaries.
029 * <p>
030 * After this, {@link #getStatus} returns information about the binaries remaining and those that have been GCed.
031 */
032public interface BinaryGarbageCollector {
033
034    /**
035     * Gets a unique identifier for this garbage collector. Two garbage collectors that would impact the same files must
036     * have the same identifier.
037     *
038     * @return a unique identifier
039     */
040    String getId();
041
042    /**
043     * Starts the garbage collection process.
044     * <p>
045     * After this, all active binaries must be fed to the {@link #mark} method.
046     */
047    void start();
048
049    /**
050     * Marks a binary as being in use.
051     *
052     * @param digest the binary's digest
053     */
054    void mark(String digest);
055
056    /**
057     * Stops the garbage collection process and deletes all binaries that have not been marked (sweep).
058     *
059     * @param delete {@code true} if actual deletion must be performed, {@code false} if the binaries to delete should
060     *            simply be counted in the status
061     */
062    void stop(boolean delete);
063
064    /**
065     * Gets the status of the binaries to GC and of those that won't be.
066     * <p>
067     * Available after {@link #stop}.
068     *
069     * @return the status
070     */
071    BinaryManagerStatus getStatus();
072
073    /**
074     * Checks if a GC is in progress.
075     * <p>
076     * A GC is in progress is {@code #start} has been called but not {@code #stop}.
077     * <p>
078     * It's only useful to call this from a separate thread from the one that calls {@link #mark}.
079     *
080     * @return {@code true} if a GC is in progress
081     */
082    boolean isInProgress();
083
084}