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}