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