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