001/*
002 * (C) Copyright 2015-2017 Nuxeo (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;
020
021import java.io.IOException;
022import java.io.InputStream;
023import java.util.Calendar;
024import java.util.Set;
025
026import org.nuxeo.ecm.core.api.Blob;
027import org.nuxeo.ecm.core.api.DocumentModel;
028import org.nuxeo.ecm.core.blob.binary.BinaryManagerStatus;
029import org.nuxeo.ecm.core.model.Document;
030
031/**
032 * Service managing {@link Blob}s associated to a {@link Document} or a repository.
033 *
034 * @since 9.2
035 */
036public interface DocumentBlobManager {
037
038    /**
039     * Reads a {@link Blob} from storage.
040     *
041     * @param blobInfo the blob information
042     * @param doc the document to which this blob belongs
043     * @param xpath the xpath of the blob in the document
044     * @return a managed blob
045     * @since 11.1
046     */
047    Blob readBlob(BlobInfo blobInfo, Document doc, String xpath) throws IOException;
048
049    /**
050     * Reads a {@link Blob} from storage.
051     *
052     * @param blobInfo the blob information
053     * @param repositoryName the repository to which this blob belongs
054     * @return a managed blob
055     * @since 7.2
056     * @deprecated since 11.1, use {@link #readBlob(BlobInfo, Document, String)} instead
057     */
058    @Deprecated
059    Blob readBlob(BlobInfo blobInfo, String repositoryName) throws IOException;
060
061    /**
062     * Writes a {@link Blob} to storage and returns its key.
063     * <p>
064     * The passed blob may be {@code null}, in which case a {@code null} key is returned after checking that deleting
065     * this blob is allowed.
066     *
067     * @param blob the blob
068     * @param doc the document to which this blob belongs
069     * @param xpath the xpath of blob in doc
070     * @return the blob key
071     * @since 9.1
072     */
073    String writeBlob(Blob blob, Document doc, String xpath) throws IOException;
074
075    /**
076     * Gets an {@link InputStream} for a conversion to the given MIME type.
077     * <p>
078     * Like all {@link InputStream}, the result must be closed when done with it to avoid resource leaks.
079     *
080     * @param blob the blob
081     * @param mimeType the MIME type to convert to
082     * @param doc the document that holds the blob
083     * @return the stream, or {@code null} if no conversion is available for the given MIME type
084     * @since 7.2
085     */
086    InputStream getConvertedStream(Blob blob, String mimeType, DocumentModel doc) throws IOException;
087
088    /**
089     * Freezes the blobs' versions on a document version when it is created via a check in.
090     *
091     * @param doc the new document version
092     * @since 7.3
093     */
094    void freezeVersion(Document doc);
095
096    /**
097     * Notifies the blob manager that a set of xpaths have changed on a document.
098     *
099     * @param doc the document
100     * @param xpaths the set of changed xpaths
101     * @since 7.3
102     */
103    void notifyChanges(Document doc, Set<String> xpaths);
104
105    /**
106     * Notifies the blob manager that the document was made a record.
107     *
108     * @param doc the document
109     * @since 11.1
110     */
111    void notifyMakeRecord(Document doc);
112
113    /**
114     * Notifies the blob manager that the document has been copied.
115     *
116     * @param doc the new document, the result of the copy
117     * @since 11.1
118     */
119    void notifyAfterCopy(Document doc);
120
121    /**
122     * Notifies the blob manager that the document is about to be removed.
123     *
124     * @param doc the document
125     * @since 11.1
126     */
127    void notifyBeforeRemove(Document doc);
128
129    /**
130     * Notifies the blob manager that the document's retention date was changed.
131     *
132     * @param doc the document
133     * @since 11.1
134     */
135    void notifySetRetainUntil(Document doc, Calendar retainUntil);
136
137    /**
138     * Notifies the blob manager that the document's legal hold status was changed.
139     *
140     * @param doc the document
141     * @since 11.1
142     */
143    void notifySetLegalHold(Document doc, boolean hold);
144
145    /**
146     * Garbage collect the unused binaries.
147     *
148     * @param delete if {@code false} don't actually delete the garbage collected binaries (but still return statistics
149     *            about them), if {@code true} delete them
150     * @return a status about the number of garbage collected binaries
151     * @since 7.4
152     */
153    BinaryManagerStatus garbageCollectBinaries(boolean delete);
154
155    /**
156     * Checks if a garbage collection of the binaries in progress.
157     *
158     * @return {@code true} if a garbage collection of the binaries is in progress
159     * @since 7.4
160     */
161    boolean isBinariesGarbageCollectionInProgress();
162
163    /**
164     * INTERNAL. Marks a binary as referenced during garbage collection. Called back by repository implementations
165     * during {@link #garbageCollectBinaries}.
166     *
167     * @param key the binary key
168     * @param repositoryName the repository name
169     * @since 7.4
170     */
171    void markReferencedBinary(String key, String repositoryName);
172
173}