/*
 * Copyright 2009-2010 by The Regents of the University of California
 * Licensed 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 from
 * 
 *     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 edu.uci.ics.hyracks.api.comm;

import java.nio.ByteBuffer;

import edu.uci.ics.hyracks.api.exceptions.HyracksDataException;

/**
 * {@link IFrameWriter} is the interface implemented by a stream consumer. An
 * {@link IFrameWriter} could be in one of the following states:
 * <ul>
 * <li>INITIAL</li>
 * <li>OPENED</li>
 * <li>CLOSED</li>
 * <li>FAILED</li>
 * </ul>
 * A producer follows the following protocol when using an {@link IFrameWriter}.
 * Initially, the {@link IFrameWriter} is in the INITIAL state.
 * The first valid call to an {@link IFrameWriter} is always the
 * {@link IFrameWriter#open()}. This call provides the opportunity for the
 * {@link IFrameWriter} implementation to allocate any resources for its
 * processing. Once this call returns, the {@link IFrameWriter} is in the OPENED
 * state. If an error occurs
 * during the {@link IFrameWriter#open()} call, a {@link HyracksDataException}
 * is thrown and it stays in the INITIAL state.
 * While the {@link IFrameWriter} is in the OPENED state, the producer can call
 * one of:
 * <ul>
 * <li> {@link IFrameWriter#close()} to give up any resources owned by the
 * {@link IFrameWriter} and enter the CLOSED state.</li>
 * <li> {@link IFrameWriter#nextFrame(ByteBuffer)} to provide data to the
 * {@link IFrameWriter}. The call returns normally on success and the
 * {@link IFrameWriter} remains in the OPENED state. On failure, the call throws
 * a {@link HyracksDataException}, and the {@link IFrameWriter} enters the ERROR
 * state.</li>
 * <li> {@link IFrameWriter#fail()} to indicate that stream is to be aborted. The
 * {@link IFrameWriter} enters the FAILED state.</li>
 * </ul>
 * In the FAILED state, the only call allowed is the
 * {@link IFrameWriter#close()} to move the {@link IFrameWriter} into the CLOSED
 * state and give up all resources.
 * No calls are allowed when the {@link IFrameWriter} is in the CLOSED state.
 * 
 * Note: If the call to {@link IFrameWriter#open()} failed, the
 * {@link IFrameWriter#close()} is not called by the producer. So an exceptional
 * return from the {@link IFrameWriter#open()} call must clean up all partially
 * allocated resources.
 * 
 * @author vinayakb
 */
public interface IFrameWriter {
    /**
     * First call to allocate any resources.
     */
    public void open() throws HyracksDataException;

    /**
     * Provide data to the stream of this {@link IFrameWriter}.
     * 
     * @param buffer
     *            - Buffer containing data.
     * @throws HyracksDataException
     */
    public void nextFrame(ByteBuffer buffer) throws HyracksDataException;

    /**
     * Indicate that a failure was encountered and the current stream is to be
     * aborted.
     * 
     * @throws HyracksDataException
     */
    public void fail() throws HyracksDataException;

    /**
     * Close this {@link IFrameWriter} and give up all resources.
     * 
     * @throws HyracksDataException
     */
    public void close() throws HyracksDataException;
}