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