/*
 * 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.qpid.protonj2.client;

import java.io.OutputStream;

import org.apache.qpid.protonj2.client.exceptions.ClientException;
import org.apache.qpid.protonj2.client.exceptions.ClientIllegalStateException;
import org.apache.qpid.protonj2.types.messaging.Data;
import org.apache.qpid.protonj2.types.messaging.Section;
import org.apache.qpid.protonj2.types.transport.Transfer;

/**
 * Streaming Message Tracker object used to operate on and track the state of a streamed message
 * at the remote. The {@link StreamSenderMessage} allows for local settlement and disposition management
 * as well as waiting for remote settlement of a streamed message.
 */
public interface StreamSenderMessage extends AdvancedMessage<OutputStream> {

    /**
     * @return The {@link Tracker} assigned to monitor the life-cycle of this {@link StreamSenderMessage}
     */
    StreamTracker tracker();

    /**
     * @return the {@link Sender} that was used to send the delivery that is being tracked.
     */
    StreamSender sender();

    /**
     * Sets the configured message format value that will be set on the first outgoing
     * AMQP {@link Transfer} frame for the delivery that comprises this streamed message.
     * This value can only be updated before write operation is attempted and will throw
     * an {@link ClientIllegalStateException} if any attempt to alter the value is made
     * following a write.
     *
     * @param messageFormat
     *      The assigned AMQP message format for this streamed message.
     *
     * @return this {@link StreamSenderMessage} instance.
     *
     * @throws ClientException if an error occurs while attempting set the message format.
     */
    @Override
    StreamSenderMessage messageFormat(int messageFormat) throws ClientException;

    /**
     * Marks the currently streaming message as being complete.
     * <p>
     * Marking a message as complete finalizes the streaming send operation and causes a
     * final {@link Transfer} frame to be sent to the remote indicating that the ongoing
     * streaming delivery is done and no more message data will arrive.
     *
     * @return this {@link StreamSenderMessage} instance.
     *
     * @throws ClientException if an error occurs while initiating the completion operation.
     */
    StreamSenderMessage complete() throws ClientException;

    /**
     * @return true if this message has been marked as being complete.
     */
    boolean completed();

    /**
     * Marks the currently streaming message as being aborted. Once aborted no further
     * writes regardless of whether any writes have yet been performed or not.
     *
     * @return this {@link StreamSenderMessage} instance.
     *
     * @throws ClientException if an error occurs while initiating the abort operation.
     */
    StreamSenderMessage abort() throws ClientException;

    /**
     * @return true if this {@link StreamSenderMessage} has been marked as aborted previously.
     */
    boolean aborted();

    /**
     * Creates an {@link OutputStream} instance configured with the given options which will
     * write the bytes as the payload of one or more AMQP {@link Data} sections based on the
     * provided configuration..
     * <p>
     * The returned {@link OutputStream} can be used to write the payload of an AMQP Message in
     * chunks when the source is not readily available in memory or as part of a larger streams
     * based component.  The {@link Data} section based stream allows for control over the AMQP
     * message {@link Section} values that are sent but does the encoding itself.  For stream
     * of message data where the content source already consists of an AMQP encoded message refer
     * to the {@link #rawOutputStream} method.
     *
     * @param options
     *      The stream options to use to configure the returned {@link OutputStream}
     *
     * @return a {@link OutputStream} instance configured using the given options.
     *
     * @throws ClientException if an error occurs while creating the {@link OutputStream}.
     *
     * @see #rawOutputStream
     */
    OutputStream body(OutputStreamOptions options) throws ClientException;

    /**
     * Creates an {@link OutputStream} instance that writes the bytes given without additional
     * encoding or transformation.  Using this stream option disables use of any other {@link Message}
     * APIs and the message transfer is completed upon close of this {@link OutputStream}.
     * <p>
     * The returned {@link OutputStream} can be used to write the payload of an AMQP Message in
     * chunks when the source is not readily available in memory or as part of a larger streams
     * based component.  The source of the bytes written to the {@link OutputStream} should
     * consist of already encoded AMQP {@link Message} data.  For an {@link OutputStream} that
     * performs the encoding of message data refer to the {@link #body(OutputStreamOptions)}
     * method.
     *
     * @return an {@link OutputStream} instance that performs no encoding.
     *
     * @throws ClientException if an error occurs while creating the {@link OutputStream}.
     *
     * @see #body
     * @see #body(OutputStreamOptions)
     */
    OutputStream rawOutputStream() throws ClientException;

}