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 * 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.NuxeoException; 034import org.nuxeo.ecm.core.blob.BlobManager.UsageHint; 035import org.nuxeo.ecm.core.blob.apps.AppLink; 036import org.nuxeo.ecm.core.blob.binary.BinaryManager; 037 038/** 039 * Interface for a provider of {@link Blob}s, which knows how to read and write them. 040 * 041 * @since 7.2 042 */ 043public interface BlobProvider { 044 045 /** 046 * Initializes the blob provider. 047 * 048 * @param blobProviderId the blob provider id for this binary manager 049 * @param properties initialization properties 050 * 051 * @since 7.3 052 */ 053 void initialize(String blobProviderId, Map<String, String> properties) throws IOException; 054 055 /** 056 * Closes this blob provider and releases resources that may be held by it. 057 * 058 * @since 7.3 059 */ 060 void close(); 061 062 /** 063 * Checks whether this blob provider is transient: blobs may disappear after a while, so a caller should not rely on 064 * them being available forever. 065 * 066 * @since 10.1 067 */ 068 default boolean isTransient() { 069 return false; 070 } 071 072 /** 073 * Reads a {@link Blob} from storage. 074 * 075 * @param blobInfo the blob information 076 * @return the blob 077 */ 078 Blob readBlob(BlobInfo blobInfo) throws IOException; 079 080 /** 081 * Writes a {@link Blob} to storage and returns information about it. 082 * <p> 083 * Called to store a user-created blob. 084 * 085 * @param blob the blob 086 * @return the blob key 087 * @since 9.2 088 */ 089 String writeBlob(Blob blob) throws IOException; 090 091 /** 092 * Checks if user update is supported. 093 * <p> 094 * A user update refers to the fact that a blob from this provider may be overwritten with another blob, wherever 095 * the original blob may occur (usually in a document property). 096 * 097 * @return {@code true} if user update is supported 098 * @since 7.10 099 */ 100 boolean supportsUserUpdate(); 101 102 /** 103 * Gets an {@link InputStream} for the data of a managed blob. 104 * <p> 105 * Like all {@link InputStream}, the result must be closed when done with it to avoid resource leaks. 106 * 107 * @param blob the managed blob 108 * @return the stream 109 * @since 7.3 110 */ 111 default InputStream getStream(ManagedBlob blob) throws IOException { 112 return null; 113 } 114 115 /** 116 * Gets an {@link InputStream} for a thumbnail of a managed blob. 117 * <p> 118 * Like all {@link InputStream}, the result must be closed when done with it to avoid resource leaks. 119 * 120 * @param blob the managed blob 121 * @return the stream 122 * @since 7.3 123 */ 124 default InputStream getThumbnail(ManagedBlob blob) throws IOException { 125 return null; 126 } 127 128 /** 129 * Gets an {@link URI} for the content of a managed blob. 130 * 131 * @param blob the managed blob 132 * @param hint {@link UsageHint} 133 * @param servletRequest the servlet request, or {@code null} 134 * @return the {@link URI}, or {@code null} if none available 135 * @since 7.4 136 */ 137 default URI getURI(ManagedBlob blob, UsageHint hint, HttpServletRequest servletRequest) throws IOException { 138 return null; 139 } 140 141 /** 142 * Gets a map of available MIME type conversions and corresponding {@link URI} for a managed blob. 143 * 144 * @param blob the managed blob 145 * @param hint {@link UsageHint} 146 * @return a map of MIME types and {@link URI}, which may be empty 147 * @since 7.3 148 */ 149 default Map<String, URI> getAvailableConversions(ManagedBlob blob, UsageHint hint) throws IOException { 150 return Collections.emptyMap(); 151 } 152 153 /** 154 * Checks if the conversion to the given {@code mimeType} is supported by the {@code blob}. 155 * 156 * @param blob the managed blob 157 * @param mimeType the destination mime type 158 * @return {@code true} if this managed blob supports the conversion to the given mime type 159 * @since 10.1 160 */ 161 default boolean canConvert(ManagedBlob blob, String mimeType) { 162 try { 163 Map<String, URI> availableConversions = getAvailableConversions(blob, UsageHint.STREAM); 164 return availableConversions.containsKey(mimeType); 165 } catch (IOException e) { 166 throw new NuxeoException(e); 167 } 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 /** 202 * Checks if the blob provider performs external access control checks. 203 * 204 * @param blobInfo the blob information to be read 205 * @return {@code true} if the provider performs security checks before reading a blob, {@code false} otherwise 206 * @since 8.4 207 */ 208 default boolean performsExternalAccessControl(BlobInfo blobInfo) { 209 return false; 210 } 211 212 /** 213 * Returns the properties of the blob provider. 214 * 215 * @since 10.2 216 */ 217 Map<String, String> getProperties(); 218 219 /** 220 * Checks if current user has the rights to create blobs in the blob provider using a key. 221 * 222 * @since 10.2 223 */ 224 default boolean hasCreateFromKeyPermission() { 225 return false; 226 } 227 228}