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.File; 022import java.io.IOException; 023import java.io.InputStream; 024import java.net.URI; 025import java.util.Map; 026 027import javax.servlet.http.HttpServletRequest; 028 029import org.nuxeo.ecm.core.api.Blob; 030 031/** 032 * Service managing the storage and retrieval of {@link Blob}s, through internally-registered {@link BlobProvider}s. 033 * 034 * @since 7.2 035 */ 036public interface BlobManager { 037 038 /** 039 * Hints for returning {@link URI}s appropriate for the expected usage. 040 * 041 * @since 7.3 042 */ 043 enum UsageHint { 044 /** Obtaining an {@link InputStream}. */ 045 STREAM, // 046 /** Downloading. */ 047 DOWNLOAD, // 048 /** Viewing. */ 049 VIEW, // 050 /** Editing. */ 051 EDIT, // 052 /** Embedding / previewing. */ 053 EMBED 054 } 055 056 /** 057 * Gets the blob provider with the given id. 058 * 059 * @param id the blob provider id 060 * @return the blob provider 061 */ 062 BlobProvider getBlobProvider(String id); 063 064 /** 065 * Gets the blob provider with the given id, or, if none has been registered, a namespaced version of the default 066 * blob provider. 067 * 068 * @param id the blob provider id or namespace 069 * @return the blob provider 070 * @since 10.10 071 * @deprecated since 11.1, use {@link #getBlobProviderWithNamespace(String, String)} instead 072 */ 073 @Deprecated 074 default BlobProvider getBlobProviderWithNamespace(String id) { 075 return getBlobProviderWithNamespace(id, "default"); 076 } 077 078 /** 079 * Gets the blob provider with the given id, or, if none has been registered, a namespaced version of the blob 080 * provider with the given default id. 081 * 082 * @param id the blob provider id or namespace 083 * @param defaultId the blob provider to use as a fallback to create a namespaced version 084 * @return the blob provider 085 * @since 11.1 086 */ 087 BlobProvider getBlobProviderWithNamespace(String id, String defaultId); 088 089 /** 090 * Gets the blob provider for the given blob. 091 * 092 * @return the blob provider 093 * @since 7.4 094 */ 095 BlobProvider getBlobProvider(Blob blob); 096 097 /** 098 * Gets an {@link InputStream} for the data of a managed blob. 099 * <p> 100 * If the blob is managed this is equivalent to {@link ManagedBlob#getStream()}, otherwise returns {@code null}. 101 * 102 * @param blob the blob 103 * @return the stream, or {@code null} if the blob is not managed 104 * @deprecated since 11.1, use {@link Blob#getStream()} instead 105 */ 106 @Deprecated 107 InputStream getStream(Blob blob) throws IOException; 108 109 /** 110 * Gets a {@link File} (if one exists) for the data of a managed blob. 111 * <p> 112 * If the blob is managed this is equivalent to {@link ManagedBlob#getFile()}, otherwise returns {@code null}. 113 * 114 * @param blob the blob 115 * @return the file, or {@code null} if no underlying file is available or the blob is not managed 116 * @since 11.1 117 * @deprecated since 11.1, use {@link Blob#getFile()} instead 118 */ 119 @Deprecated 120 File getFile(Blob blob); 121 122 /** 123 * Gets an {@link InputStream} for a thumbnail of a blob. 124 * <p> 125 * Like all {@link InputStream}, the result must be closed when done with it to avoid resource leaks. 126 * 127 * @param blob the blob 128 * @return the thumbnail stream 129 */ 130 InputStream getThumbnail(Blob blob) throws IOException; 131 132 /** 133 * Gets an {@link URI} for the content of a blob. 134 * 135 * @param blob the blob 136 * @param hint {@link UsageHint} 137 * @param servletRequest the servlet request, or {@code null} 138 * @return the {@link URI}, or {@code null} if none available 139 */ 140 URI getURI(Blob blob, UsageHint hint, HttpServletRequest servletRequest) throws IOException; 141 142 /** 143 * Gets a map of available MIME type conversions and corresponding {@link URI} for a blob. 144 * 145 * @return a map of MIME types and {@link URI}, which may be empty 146 */ 147 Map<String, URI> getAvailableConversions(Blob blob, UsageHint hint) throws IOException; 148 149 /** 150 * Get the map of blob providers 151 * 152 * @return the list of blob providers 153 * @since 7.3 154 */ 155 Map<String, BlobProvider> getBlobProviders(); 156 157}