/***************************************************************
 *  This file is part of the [fleXive](R) framework.
 *
 *  Copyright (c) 1999-2008
 *  UCS - unique computing solutions gmbh (http://www.ucs.at)
 *  All rights reserved
 *
 *  The [fleXive](R) project is free software; you can redistribute
 *  it and/or modify it under the terms of the GNU Lesser General Public
 *  License version 2.1 or higher as published by the Free Software Foundation.
 *
 *  The GNU Lesser General Public License can be found at
 *  http://www.gnu.org/licenses/lgpl.html.
 *  A copy is found in the textfile LGPL.txt and important notices to the
 *  license from the author are found in LICENSE.txt distributed with
 *  these libraries.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  For further information about UCS - unique computing solutions gmbh,
 *  please see the company website: http://www.ucs.at
 *
 *  For further information about [fleXive](R), please see the
 *  project website: http://www.flexive.org
 *
 *
 *  This copyright notice MUST APPEAR in all copies of the file!
 ***************************************************************/
package com.flexive.stream;

import java.io.InputStream;
import java.io.OutputStream;
import java.io.Serializable;

/**
 * StreamServer client.
 * StreamClient instances can only be created by <code>StreamClientFactory</Code>
 *
 * @author Markus Plesser (markus.plesser@flexive.com), UCS - unique computing solutions gmbh (http://www.ucs.at)
 * @see com.flexive.stream.StreamClientFactory
 */
public interface StreamClient {

    /**
     * Connect to the server
     *
     * @param initialPacket the initial DataPacket to send
     * @return a DataPacket (if the initial packet expects a response) or <code>null</code>
     * @throws StreamException on errors
     */
    public <T extends Serializable> DataPacket<T> connect(DataPacket<T> initialPacket) throws StreamException;

    /**
     * Submit a DataPacket to the server
     *
     * @param packet the DataPacket to send
     * @return a DataPacket (if the sent packet expects a response) or <code>null</code>
     * @throws StreamException on errors
     */
    public <T extends Serializable> DataPacket<T> submitPacket(DataPacket<T> packet) throws StreamException;

    /**
     * Return an InputStream for reading the binary.
     *
     * @return  an InputStream for reading the binary.
     * @throws StreamException on errors
     * @since 3.1
     */
    public InputStream getInputStream() throws StreamException;

    /**
     * Receive a stream from the server.
     * Streams can only be received if a DataPacket has been sent with <code>isExpectStream()</code> set to <code>true</code>!
     * Is is preferred to receive a stream with an already known length/size since this method might terminate
     * the connection if the server side stream is exhausted!
     *
     * @param stream the stream the received data is written to
     * @return number of bytes received
     * @throws StreamException on errors
     * @see DataPacket#isExpectStream()
     */
    public long receiveStream(OutputStream stream) throws StreamException;

    /**
     * Receive a stream from the server.
     * Streams can only be received if a DataPacket has been sent with <code>isExpectStream()</code> set to <code>true</code>!
     *
     * @param stream the stream the received data is written to
     * @param expectedSize expected length of the stream in bytes
     * @return number of bytes received
     * @throws StreamException on errors
     * @see DataPacket#isExpectStream()
     */
    public long receiveStream(OutputStream stream, long expectedSize) throws StreamException;

    
    /**
     * Send a stream to the server.
     * Streams can only be sent if a DataPacket has been received serverside with <code>isExpectStream()</code> set to <code>true</code>!
     * Is is preferred to send a stream with an already known length/size since this method might terminate
     * the connection if the client side stream is exhausted!
     *
     * @param stream the stream the data is read from
     * @return number of bytes sent
     * @throws StreamException on errors
     * @see DataPacket#isExpectStream()
     */
    long sendStream(InputStream stream) throws StreamException;

    /**
     * Send a stream to the server.
     * Streams can only be sent if a DataPacket has been received serverside with <code>isExpectStream()</code> set to <code>true</code>!
     *
     * @param stream the stream the data is read from
     * @param expectedSize expected length of the stream in bytes
     * @return number of bytes sent
     * @throws StreamException on errors
     * @see DataPacket#isExpectStream()
     */
    long sendStream(InputStream stream, long expectedSize) throws StreamException;

    /**
     * Close the client (shutdown the connection)
     *
     * @throws StreamException on errors
     */
    void close() throws StreamException;

    /**
     * Is this StreamClient operating in the same java virtual machine as the server (bypassing socket NIO) or connected
     * via sockets?
     *
     * @return client and server in same JVM?
     */
    boolean isLocal();
    
}