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 * Nelson Silva 017 */ 018package org.nuxeo.ecm.core.blob; 019 020import java.io.IOException; 021import java.io.InputStream; 022import java.net.URI; 023import java.util.Collections; 024import java.util.List; 025import java.util.Map; 026 027import javax.servlet.http.HttpServletRequest; 028 029import org.nuxeo.ecm.core.api.Blob; 030import org.nuxeo.ecm.core.api.DocumentModel; 031import org.nuxeo.ecm.core.blob.BlobManager.BlobInfo; 032import org.nuxeo.ecm.core.blob.BlobManager.UsageHint; 033import org.nuxeo.ecm.core.blob.apps.AppLink; 034import org.nuxeo.ecm.core.blob.binary.BinaryManager; 035import org.nuxeo.ecm.core.model.Document; 036 037/** 038 * Interface for a provider of {@link Blob}s, which knows how to read and write them. 039 * 040 * @since 7.2 041 */ 042public interface BlobProvider { 043 044 /** 045 * Initializes the blob provider. 046 * 047 * @param blobProviderId the blob provider id for this binary manager 048 * @param properties initialization properties 049 * 050 * @since 7.3 051 */ 052 void initialize(String blobProviderId, Map<String, String> properties) throws IOException; 053 054 /** 055 * Closes this blob provider and releases resources that may be held by it. 056 * 057 * @since 7.3 058 */ 059 void close(); 060 061 /** 062 * Reads a {@link Blob} from storage. 063 * 064 * @param blobInfo the blob information 065 * @return the blob 066 */ 067 Blob readBlob(BlobInfo blobInfo) throws IOException; 068 069 /** 070 * Writes a {@link Blob} to storage and returns information about it. 071 * <p> 072 * Called to store a user-created blob. 073 * 074 * @param blob the blob 075 * @param doc the document to which this blob belongs 076 * @return the blob key 077 */ 078 String writeBlob(Blob blob, Document doc) throws IOException; 079 080 /** 081 * Checks if user update is supported. 082 * <p> 083 * A user update refers to the fact that a blob from this provider may be overwritten with another blob, wherever 084 * the original blob may occur (usually in a document property). 085 * 086 * @return {@code true} if user update is supported 087 * @since 7.10 088 */ 089 boolean supportsUserUpdate(); 090 091 /** 092 * Gets an {@link InputStream} for the data of a managed blob. 093 * <p> 094 * Like all {@link InputStream}, the result must be closed when done with it to avoid resource leaks. 095 * 096 * @param blob the managed blob 097 * @return the stream 098 * @since 7.3 099 */ 100 default InputStream getStream(ManagedBlob blob) throws IOException { 101 return null; 102 } 103 104 /** 105 * Gets an {@link InputStream} for a thumbnail of a managed blob. 106 * <p> 107 * Like all {@link InputStream}, the result must be closed when done with it to avoid resource leaks. 108 * 109 * @param blob the managed blob 110 * @return the stream 111 * @since 7.3 112 */ 113 default InputStream getThumbnail(ManagedBlob blob) throws IOException { 114 return null; 115 } 116 117 /** 118 * Gets an {@link URI} for the content of a managed blob. 119 * 120 * @param blob the managed blob 121 * @param hint {@link UsageHint} 122 * @param servletRequest the servlet request, or {@code null} 123 * @return the {@link URI}, or {@code null} if none available 124 * @since 7.4 125 */ 126 default URI getURI(ManagedBlob blob, UsageHint hint, HttpServletRequest servletRequest) throws IOException { 127 return null; 128 } 129 130 /** 131 * Gets a map of available MIME type conversions and corresponding {@link URI} for a managed blob. 132 * 133 * @param blob the managed blob 134 * @param hint {@link UsageHint} 135 * @return a map of MIME types and {@link URI}, which may be empty 136 * @since 7.3 137 */ 138 default Map<String, URI> getAvailableConversions(ManagedBlob blob, UsageHint hint) throws IOException { 139 return Collections.emptyMap(); 140 } 141 142 /** 143 * Gets an {@link InputStream} for a conversion to the given MIME type. 144 * <p> 145 * Like all {@link InputStream}, the result must be closed when done with it to avoid resource leaks. 146 * 147 * @param blob the managed blob 148 * @param mimeType the MIME type to convert to 149 * @param doc the document that holds the blob 150 * @return the stream, or {@code null} if no conversion is available for the given MIME type 151 * @since 7.3 152 */ 153 default InputStream getConvertedStream(ManagedBlob blob, String mimeType, DocumentModel doc) throws IOException { 154 return null; 155 } 156 157 /** 158 * Returns a new managed blob pointing to a fixed version of the original blob. 159 * <p> 160 * 161 * @param blob the original managed blob 162 * @param doc the document that holds the blob 163 * @return a managed blob with fixed version, or {@code null} if no change is needed 164 * @since 7.3 165 */ 166 default ManagedBlob freezeVersion(ManagedBlob blob, Document doc) throws IOException { 167 return null; 168 } 169 170 /** 171 * Returns true if version of the blob is a version. 172 * <p> 173 * 174 * @param blob the managed blob 175 * @return true if the blob is a version or a revision 176 * @since 7.3 177 */ 178 default boolean isVersion(ManagedBlob blob) { 179 return false; 180 } 181 182 /** 183 * Returns a list of application links for the given blob. 184 * 185 * @since 7.3 186 */ 187 default List<AppLink> getAppLinks(String user, ManagedBlob blob) throws IOException { 188 return Collections.emptyList(); 189 } 190 191 /** 192 * Gets the associated binary manager, if any. 193 * 194 * @return the binary manager, or {@code null} 195 * @since 7.4 196 */ 197 default BinaryManager getBinaryManager() { 198 return null; 199 } 200 201}