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}