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.Map;
017
018import org.nuxeo.ecm.core.api.Blob;
019import org.nuxeo.ecm.core.api.impl.blob.FileBlob;
020
021/**
022 * A binary manager stores binaries according to their digest.
023 */
024public interface BinaryManager {
025
026    /** In the initialization properties, the property for the store path. */
027    String PROP_PATH = "path";
028
029    /** In the initialization properties, the property for a generic key. */
030    String PROP_KEY = "key";
031
032    /**
033     * Initializes the binary manager.
034     *
035     * @param blobProviderId the blob provider id for this binary manager
036     * @param properties initialization properties
037     * @since 7.3
038     */
039    void initialize(String blobProviderId, Map<String, String> properties) throws IOException;
040
041    /**
042     * Saves the given blob into a {@link Binary}.
043     * <p>
044     * Returns a {@link Binary} representing the stream. The {@link Binary} includes a digest that is a sufficient
045     * representation to persist it.
046     * <p>
047     * If the blob is a temporary {@link FileBlob}, then the temporary file may be reused as the final storage location
048     * after being moved.
049     *
050     * @param blob the blob
051     * @return the corresponding binary
052     * @throws IOException
053     * @since 7.2
054     */
055    Binary getBinary(Blob blob) throws IOException;
056
057    /**
058     * Returns a {@link Binary} corresponding to the given digest.
059     * <p>
060     * A {@code null} is returned if the digest could not be found.
061     *
062     * @param digest the digest, or {@code null}
063     * @return the corresponding binary
064     */
065    Binary getBinary(String digest);
066
067    /**
068     * Returns the Binary Garbage Collector that can be used for this binary manager.
069     * <p>
070     * Several calls to this method will return the same GC, so that its status can be monitored using
071     * {@link BinaryGarbageCollector#isInProgress}.
072     *
073     * @return the binary GC
074     */
075    BinaryGarbageCollector getGarbageCollector();
076
077    /**
078     * Closes the binary manager and releases all resources and temporary objects held by it.
079     */
080    void close();
081
082    /**
083     * Returns the digest algorithm used to store and digest binaries.
084     *
085     * @since 7.4
086     */
087    String getDigestAlgorithm();
088
089}