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}