001/*
002 * (C) Copyright 2015 Nuxeo SA (http://nuxeo.com/) and contributors.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the GNU Lesser General Public License
006 * (LGPL) version 2.1 which accompanies this distribution, and is available at
007 * http://www.gnu.org/licenses/lgpl-2.1.html
008 *
009 * This library is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012 * Lesser General Public License for more details.
013 *
014 * Contributors:
015 *     Florent Guillaume
016 *     Nelson Silva
017 */
018package org.nuxeo.ecm.core.blob;
019
020import java.io.IOException;
021import java.io.InputStream;
022import java.net.URI;
023import java.util.Collections;
024import java.util.List;
025import java.util.Map;
026
027import javax.servlet.http.HttpServletRequest;
028
029import org.nuxeo.ecm.core.api.Blob;
030import org.nuxeo.ecm.core.api.DocumentModel;
031import org.nuxeo.ecm.core.blob.BlobManager.BlobInfo;
032import org.nuxeo.ecm.core.blob.BlobManager.UsageHint;
033import org.nuxeo.ecm.core.blob.apps.AppLink;
034import org.nuxeo.ecm.core.blob.binary.BinaryManager;
035import org.nuxeo.ecm.core.model.Document;
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     * @param doc the document to which this blob belongs
076     * @return the blob key
077     */
078    String writeBlob(Blob blob, Document doc) 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     * Gets an {@link InputStream} for a conversion to the given MIME type.
144     * <p>
145     * Like all {@link InputStream}, the result must be closed when done with it to avoid resource leaks.
146     *
147     * @param blob the managed blob
148     * @param mimeType the MIME type to convert to
149     * @param doc the document that holds the blob
150     * @return the stream, or {@code null} if no conversion is available for the given MIME type
151     * @since 7.3
152     */
153    default InputStream getConvertedStream(ManagedBlob blob, String mimeType, DocumentModel doc) throws IOException {
154        return null;
155    }
156
157    /**
158     * Returns a new managed blob pointing to a fixed version of the original blob.
159     * <p>
160     *
161     * @param blob the original managed blob
162     * @param doc the document that holds the blob
163     * @return a managed blob with fixed version, or {@code null} if no change is needed
164     * @since 7.3
165     */
166    default ManagedBlob freezeVersion(ManagedBlob blob, Document doc) throws IOException {
167        return null;
168    }
169
170    /**
171     * Returns true if version of the blob is a version.
172     * <p>
173     *
174     * @param blob the managed blob
175     * @return true if the blob is a version or a revision
176     * @since 7.3
177     */
178    default boolean isVersion(ManagedBlob blob) {
179        return false;
180    }
181
182    /**
183     * Returns a list of application links for the given blob.
184     *
185     * @since 7.3
186     */
187    default List<AppLink> getAppLinks(String user, ManagedBlob blob) throws IOException {
188        return Collections.emptyList();
189    }
190
191    /**
192     * Gets the associated binary manager, if any.
193     *
194     * @return the binary manager, or {@code null}
195     * @since 7.4
196     */
197    default BinaryManager getBinaryManager() {
198        return null;
199    }
200
201}