001/*
002 * (C) Copyright 2015 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-2.1.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;
018
019import java.io.IOException;
020import java.io.InputStream;
021import java.net.URI;
022import java.util.Map;
023import java.util.Set;
024
025import javax.servlet.http.HttpServletRequest;
026
027import org.nuxeo.ecm.core.api.Blob;
028import org.nuxeo.ecm.core.api.DocumentModel;
029import org.nuxeo.ecm.core.blob.binary.BinaryManager;
030import org.nuxeo.ecm.core.blob.binary.BinaryManagerStatus;
031import org.nuxeo.ecm.core.model.Document;
032
033/**
034 * Service managing the storage and retrieval of {@link Blob}s, through internally-registered {@link BlobProvider}s.
035 *
036 * @since 7.2
037 */
038public interface BlobManager {
039
040    /**
041     * Class describing information from a {@link Blob}, suitable for serialization and storage.
042     *
043     * @since 7.2
044     */
045    class BlobInfo {
046        public String key;
047
048        public String mimeType;
049
050        public String encoding;
051
052        public String filename;
053
054        public Long length;
055
056        public String digest;
057    }
058
059    /**
060     * Hints for returning {@link URI}s appropriate for the expected usage.
061     *
062     * @since 7.3
063     */
064    enum UsageHint {
065        /** Obtaining an {@link InputStream}. */
066        STREAM, //
067        /** Downloading. */
068        DOWNLOAD, //
069        /** Viewing. */
070        VIEW, //
071        /** Editing. */
072        EDIT, //
073        /** Embedding / previewing. */
074        EMBED
075    }
076
077    /**
078     * Gets the blob provider with the given id.
079     *
080     * @param id the blob provider id
081     * @return the blob provider
082     */
083    BlobProvider getBlobProvider(String id);
084
085    /**
086     * Gets the blob provider for the given blob.
087     *
088     * @return the blob provider
089     * @since 7.4
090     */
091    BlobProvider getBlobProvider(Blob blob);
092
093    /**
094     * Reads a {@link Blob} from storage.
095     *
096     * @param blobInfo the blob information
097     * @param repositoryName the repository to which this blob belongs
098     * @return a managed blob
099     */
100    Blob readBlob(BlobInfo blobInfo, String repositoryName) throws IOException;
101
102    /**
103     * Writes a {@link Blob} to storage and returns its key.
104     *
105     * @param blob the blob
106     * @param doc the document to which this blob belongs
107     * @return the blob key
108     */
109    String writeBlob(Blob blob, Document doc) throws IOException;
110
111    /**
112     * INTERNAL - Gets an {@link InputStream} for the data of a managed blob. Used by internal implementations, regular
113     * callers should call {@link Blob#getStream}.
114     *
115     * @param blob the blob
116     * @return the stream
117     */
118    InputStream getStream(Blob blob) throws IOException;
119
120    /**
121     * Gets an {@link InputStream} for a thumbnail of a blob.
122     * <p>
123     * Like all {@link InputStream}, the result must be closed when done with it to avoid resource leaks.
124     *
125     * @param blob the blob
126     * @return the thumbnail stream
127     */
128    InputStream getThumbnail(Blob blob) throws IOException;
129
130    /**
131     * Gets an {@link URI} for the content of a blob.
132     *
133     * @param blob the blob
134     * @param hint {@link UsageHint}
135     * @param servletRequest the servlet request, or {@code null}
136     * @return the {@link URI}, or {@code null} if none available
137     */
138    URI getURI(Blob blob, UsageHint hint, HttpServletRequest servletRequest) throws IOException;
139
140    /**
141     * Gets a map of available MIME type conversions and corresponding {@link URI} for a blob.
142     *
143     * @return a map of MIME types and {@link URI}, which may be empty
144     */
145    Map<String, URI> getAvailableConversions(Blob blob, UsageHint hint) throws IOException;
146
147    /**
148     * Gets an {@link InputStream} for a conversion to the given MIME type.
149     * <p>
150     * Like all {@link InputStream}, the result must be closed when done with it to avoid resource leaks.
151     *
152     * @param blob the blob
153     * @param mimeType the MIME type to convert to
154     * @param doc the document that holds the blob
155     * @return the stream, or {@code null} if no conversion is available for the given MIME type
156     */
157    InputStream getConvertedStream(Blob blob, String mimeType, DocumentModel doc) throws IOException;
158
159    /**
160     * Get the map of blob providers
161     *
162     * @return the list of blob providers
163     * @since 7.3
164     */
165    Map<String, BlobProvider> getBlobProviders();
166
167    /**
168     * Freezes the blobs' versions on a document version when it is created via a check in.
169     *
170     * @param doc the new document version
171     * @since 7.3
172     */
173    void freezeVersion(Document doc);
174
175    /**
176     * Notifies the blob manager that a set of xpaths have changed on a document.
177     *
178     * @param doc the document
179     * @param xpaths the set of changed xpaths
180     * @since 7.3
181     */
182    void notifyChanges(Document doc, Set<String> xpaths);
183
184    /**
185     * Garbage collect the unused binaries.
186     *
187     * @param delete if {@code false} don't actually delete the garbage collected binaries (but still return statistics
188     *            about them), if {@code true} delete them
189     * @return a status about the number of garbage collected binaries
190     * @since 7.4
191     */
192    BinaryManagerStatus garbageCollectBinaries(boolean delete);
193
194    /**
195     * Checks if a garbage collection of the binaries in progress.
196     *
197     * @return {@code true} if a garbage collection of the binaries is in progress
198     * @since 7.4
199     */
200    boolean isBinariesGarbageCollectionInProgress();
201
202    /**
203     * INTERNAL. Marks a binary as referenced during garbage collection. Called back by repository implementations
204     * during {@link #garbageCollectBinaries}.
205     *
206     * @param key the binary key
207     * @param repositoryName the repository name
208     * @since 7.4
209     */
210    void markReferencedBinary(String key, String repositoryName);
211
212}