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}