001/*
002 * Copyright (c) 2006-2011 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the Eclipse Public License v1.0
006 * which accompanies this distribution, and is available at
007 * http://www.eclipse.org/legal/epl-v10.html
008 *
009 * Contributors:
010 *     Florent Guillaume
011 */
012
013package org.nuxeo.ecm.core.blob.binary;
014
015import java.io.IOException;
016import java.util.Collection;
017import java.util.Map;
018
019import org.nuxeo.ecm.core.api.Blob;
020import org.nuxeo.ecm.core.api.impl.blob.FileBlob;
021
022/**
023 * A binary manager stores binaries according to their digest.
024 */
025public interface BinaryManager {
026
027    /** In the initialization properties, the property for the store path. */
028    String PROP_PATH = "path";
029
030    /** In the initialization properties, the property for a generic key. */
031    String PROP_KEY = "key";
032
033    /**
034     * Initializes the binary manager.
035     *
036     * @param blobProviderId the blob provider id for this binary manager
037     * @param properties initialization properties
038     * @since 7.3
039     */
040    void initialize(String blobProviderId, Map<String, String> properties) throws IOException;
041
042    /**
043     * Saves the given blob into a {@link Binary}.
044     * <p>
045     * Returns a {@link Binary} representing the stream. The {@link Binary} includes a digest that is a sufficient
046     * representation to persist it.
047     * <p>
048     * If the blob is a temporary {@link FileBlob}, then the temporary file may be reused as the final storage location
049     * after being moved.
050     *
051     * @param blob the blob
052     * @return the corresponding binary
053     * @throws IOException
054     * @since 7.2
055     */
056    Binary getBinary(Blob blob) throws IOException;
057
058    /**
059     * Returns a {@link Binary} corresponding to the given digest.
060     * <p>
061     * A {@code null} is returned if the digest could not be found.
062     *
063     * @param digest the digest, or {@code null}
064     * @return the corresponding binary
065     */
066    Binary getBinary(String digest);
067
068    /**
069     * Remove definitively a set of binaries
070     *
071     * @since 7.10
072     * @param digests a set of digests, must not be {@code null}.
073     */
074    void removeBinaries(Collection<String> digests);
075
076    /**
077     * Returns the Binary Garbage Collector that can be used for this binary manager.
078     * <p>
079     * Several calls to this method will return the same GC, so that its status can be monitored using
080     * {@link BinaryGarbageCollector#isInProgress}.
081     *
082     * @return the binary GC
083     */
084    BinaryGarbageCollector getGarbageCollector();
085
086    /**
087     * Closes the binary manager and releases all resources and temporary objects held by it.
088     */
089    void close();
090
091    /**
092     * Returns the digest algorithm used to store and digest binaries.
093     *
094     * @since 7.4
095     */
096    String getDigestAlgorithm();
097
098}