chemistry-opencmis-commons/chemistry-opencmis-commons-api/src/main/java/org/apache/chemistry/opencmis/commons/server/TempStoreOutputStream.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package org.apache.chemistry.opencmis.commons.server;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;

/**
 * Subclasses of this class are used to store document content for a short
 * period of time.
 * 
 * The OpenCMIS server framework creates such a new stream when it needs to
 * offload document content for a moment. That can happen when a document is
 * created, new content is set for an existing document, or a new document
 * version is created. How and where subclasses of this output stream store the
 * content is not specified.
 * 
 * The {@link #getInputStream()} and {@link #getLength()} methods are not called
 * before all bytes have been written to this output stream and the
 * {@link #close()} method has been called. The {@link #destroy(Throwable)}
 * method can be called at any time and indicates that this stream is not needed
 * anymore and attached resources can be cleaned up.
 */
public abstract class TempStoreOutputStream extends OutputStream {

    /**
     * Sets the MIME type of the stream.
     * 
     * This method is usually be called once before {@link #getInputStream()} is
     * called. It might never be called if the MIME type is unknown or multiple
     * times if previous MIME type detections were inaccurate.
     * 
     * @param mimeType
     *            the MIME type or {@code null} if the MIME type is unknown or
     *            should be reset to unknown
     */
    public abstract void setMimeType(String mimeType);

    /**
     * Sets the file name.
     * 
     * This method is usually be called once before {@link #getInputStream()} is
     * called. It might never be called if the file name is unknown.
     * 
     * @param filename
     *            the file name or {@code null} if the file name is unknown or
     *            should be reset to unknown
     */
    public abstract void setFileName(String filename);

    /**
     * Returns an {@link InputStream} that serves the content that has been
     * provided to this {@link TempStoreOutputStream} instance.
     * 
     * If this method is called multiple times, the same {@link InputStream}
     * object must be returned.
     * 
     * Implementations should clean up all attached resources when this stream
     * is closed.
     * 
     * @return the input stream
     * 
     * @throws IOException
     *             if the input stream could not be created
     */
    public abstract InputStream getInputStream() throws IOException;

    /**
     * Returns the length of the stream in bytes.
     * 
     * @return the length of the stream
     */
    public abstract long getLength();

    /**
     * This method is called if the stream has to be released before it is fully
     * written or read.
     * 
     * Implementations should clean up all attached resources.
     * 
     * @param cause
     *            the throwable that caused the call of this method or
     *            {@code null} if no throwable object is available
     */
    public abstract void destroy(Throwable cause);
}