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 */ 019package org.nuxeo.ecm.core.blob; 020 021import java.io.IOException; 022import java.io.InputStream; 023import java.net.URI; 024import java.util.Map; 025 026import javax.servlet.http.HttpServletRequest; 027 028import org.nuxeo.ecm.core.api.Blob; 029 030/** 031 * Service managing the storage and retrieval of {@link Blob}s, through internally-registered {@link BlobProvider}s. 032 * 033 * @since 7.2 034 */ 035public interface BlobManager { 036 037 /** 038 * Hints for returning {@link URI}s appropriate for the expected usage. 039 * 040 * @since 7.3 041 */ 042 enum UsageHint { 043 /** Obtaining an {@link InputStream}. */ 044 STREAM, // 045 /** Downloading. */ 046 DOWNLOAD, // 047 /** Viewing. */ 048 VIEW, // 049 /** Editing. */ 050 EDIT, // 051 /** Embedding / previewing. */ 052 EMBED 053 } 054 055 /** 056 * Gets the blob provider with the given id. 057 * 058 * @param id the blob provider id 059 * @return the blob provider 060 */ 061 BlobProvider getBlobProvider(String id); 062 063 /** 064 * Gets the blob provider for the given blob. 065 * 066 * @return the blob provider 067 * @since 7.4 068 */ 069 BlobProvider getBlobProvider(Blob blob); 070 071 /** 072 * INTERNAL - Gets an {@link InputStream} for the data of a managed blob. Used by internal implementations, regular 073 * callers should call {@link Blob#getStream}. 074 * 075 * @param blob the blob 076 * @return the stream 077 */ 078 InputStream getStream(Blob blob) throws IOException; 079 080 /** 081 * Gets an {@link InputStream} for a thumbnail of a blob. 082 * <p> 083 * Like all {@link InputStream}, the result must be closed when done with it to avoid resource leaks. 084 * 085 * @param blob the blob 086 * @return the thumbnail stream 087 */ 088 InputStream getThumbnail(Blob blob) throws IOException; 089 090 /** 091 * Gets an {@link URI} for the content of a blob. 092 * 093 * @param blob the blob 094 * @param hint {@link UsageHint} 095 * @param servletRequest the servlet request, or {@code null} 096 * @return the {@link URI}, or {@code null} if none available 097 */ 098 URI getURI(Blob blob, UsageHint hint, HttpServletRequest servletRequest) throws IOException; 099 100 /** 101 * Gets a map of available MIME type conversions and corresponding {@link URI} for a blob. 102 * 103 * @return a map of MIME types and {@link URI}, which may be empty 104 */ 105 Map<String, URI> getAvailableConversions(Blob blob, UsageHint hint) throws IOException; 106 107 /** 108 * Get the map of blob providers 109 * 110 * @return the list of blob providers 111 * @since 7.3 112 */ 113 Map<String, BlobProvider> getBlobProviders(); 114 115}