001/*
002 * (C) Copyright 2006-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 *     Bogdan Stefanescu
018 *     Florent Guillaume
019 */
020package org.nuxeo.ecm.core.api;
021
022import java.io.File;
023import java.io.IOException;
024import java.io.InputStream;
025import java.io.OutputStream;
026
027/**
028 * A blob contains large binary data, and is associated with a MIME type, encoding, and filename. It also has a fixed
029 * length, and a digest.
030 * <p>
031 * This interface requires that implementations of {@link #getStream} can be called several times, so the first call
032 * must not "exhaust" the stream.
033 */
034public interface Blob {
035
036    /**
037     * Gets an {@link InputStream} for the data of this blob.
038     * <p>
039     * The contract of {@link Blob} is that this method can be called several times and will correctly return a new
040     * {@link InputStream} each time. In other words, several reads of the {@link Blob} can be done.
041     * <p>
042     * Like all {@link InputStream}, the result must be closed when done with it to avoid resource leaks.
043     *
044     * @return the stream
045     */
046    InputStream getStream() throws IOException;
047
048    /**
049     * Gets the data length in bytes if known.
050     *
051     * @return the data length or -1 if not known
052     */
053    long getLength();
054
055    String getMimeType();
056
057    String getEncoding();
058
059    String getFilename();
060
061    /**
062     * @since 7.4
063     */
064    String getDigestAlgorithm();
065
066    String getDigest();
067
068    void setMimeType(String mimeType);
069
070    void setEncoding(String encoding);
071
072    void setFilename(String filename);
073
074    void setDigest(String digest);
075
076    byte[] getByteArray() throws IOException;
077
078    String getString() throws IOException;
079
080    void transferTo(OutputStream out) throws IOException;
081
082    void transferTo(File file) throws IOException;
083
084    /**
085     * If this blob is backed by an actual file, returns it.
086     * <p>
087     * The returned file may be short-lived (temporary), so should be used immediately.
088     *
089     * @return a file, or {@code null} if the blob is not backed by a file
090     * @since 7.2
091     */
092    File getFile();
093
094    /**
095     * Gets a {@link CloseableFile} backing this blob, which must be closed when done by the caller.
096     * <p>
097     * The returned file may be the original file, a temporary file, or a symbolic link.
098     *
099     * @return a closeable file, to be closed when done
100     * @since 7.2
101     */
102    CloseableFile getCloseableFile() throws IOException;
103
104    /**
105     * Gets a {@link CloseableFile} backing this blob, which must be closed when done by the caller.
106     * <p>
107     * The returned file may be the original file, a temporary file, or a symbolic link.
108     *
109     * @param ext the required extension for the file, or {@code null} if it doesn't matter
110     * @return a closeable file, to be closed when done
111     * @since 7.2
112     */
113    CloseableFile getCloseableFile(String ext) throws IOException;
114
115}