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.blob.BlobManager.UsageHint; 034import org.nuxeo.ecm.core.blob.apps.AppLink; 035import org.nuxeo.ecm.core.blob.binary.BinaryManager; 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 * @return the blob key 076 * @since 9.2 077 */ 078 String writeBlob(Blob blob) 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 * Returns true if version of the blob is a version. 144 * <p> 145 * 146 * @param blob the managed blob 147 * @return true if the blob is a version or a revision 148 * @since 7.3 149 */ 150 default boolean isVersion(ManagedBlob blob) { 151 return false; 152 } 153 154 /** 155 * Returns a list of application links for the given blob. 156 * 157 * @since 7.3 158 */ 159 default List<AppLink> getAppLinks(String user, ManagedBlob blob) throws IOException { 160 return Collections.emptyList(); 161 } 162 163 /** 164 * Gets the associated binary manager, if any. 165 * 166 * @return the binary manager, or {@code null} 167 * @since 7.4 168 */ 169 default BinaryManager getBinaryManager() { 170 return null; 171 } 172 173 /** 174 * Checks if the blob provider performs external access control checks. 175 * 176 * @param blobInfo the blob information to be read 177 * @return {@code true} if the provider performs security checks before reading a blob, {@code false} otherwise 178 * @since 8.4 179 */ 180 default boolean performsExternalAccessControl(BlobInfo blobInfo) { 181 return false; 182 } 183 184}