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