/*
 * Copyright (C) 2009 eXo Platform SAS.
 *
 * This is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This software 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
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */
package org.exoplatform.services.jcr.dataflow.serialization;

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

/**
 * Created by The eXo Platform SAS.
 * 
 * <br>
 * Date: 13.02.2009
 * 
 * @author <a href="mailto:alex.reshetnyak@exoplatform.com.ua">Alex Reshetnyak</a>
 * @version $Id: JCRObjectOutput.java 111 2008-11-11 11:11:11Z rainf0x $
 */
public interface ObjectWriter
{

   /**
    * Writes an array of bytes. This method will block until the bytes are actually written.
    * 
    * @param b
    *          the data to be written
    * @exception IOException
    *              If an I/O error has occurred.
    */
   void write(byte b[]) throws IOException;

   /**
    * Writes a string. String transformed to bytes using Constants.DEFAULT_ENCODING.
    * 
    * @param str
    *          - String.
    * @throws IOException
    *           If an I/O error has occurred.
    */
   void writeString(String str) throws IOException;

   /**
    * Writes a sub array of bytes.
    * 
    * @param b
    *          the data to be written
    * @param off
    *          the start offset in the data
    * @param len
    *          the number of bytes that are written
    * @exception IOException
    *              If an I/O error has occurred.
    */
   void write(byte b[], int off, int len) throws IOException;

   /**
    * Write <code>InputStream</code> content to this writer using NIO.
    * 
    * @param stream
    *          InputStream source stream
    * @throws IOException
    *           if error occurs
    */
   void writeStream(InputStream stream) throws IOException;

   /**
    * Flushes the stream. This will write any buffered output bytes.
    * 
    * @exception IOException
    *              If an I/O error has occurred.
    */
   void flush() throws IOException;

   /**
    * Closes the stream. This method must be called to release any resources associated with the
    * stream.
    * 
    * @exception IOException
    *              If an I/O error has occurred.
    */
   void close() throws IOException;

   /**
    * Writes a <code>boolean</code> value to this output stream. If the argument <code>v</code> is
    * <code>true</code>, the value <code>(byte)1</code> is written; if <code>v</code> is
    * <code>false</code>, the value <code>(byte)0</code> is written. The byte written by this method
    * may be read by the <code>readBoolean</code> method of interface <code>DataInput</code>, which
    * will then return a <code>boolean</code> equal to <code>v</code>.
    * 
    * @param v
    *          the boolean to be written.
    * @exception IOException
    *              if an I/O error occurs.
    */
   void writeBoolean(boolean v) throws IOException;

   /**
    * Writes an <code>byte</code> value to the output stream.
    * 
    * @param b
    *          the <code>byte</code> value to be written
    * @exception IOException
    *              If an I/O error has occurred.
    */
   void writeByte(byte b) throws IOException;

   /**
    * Writes an <code>int</code> value, which is comprised of four bytes, to the output stream. The
    * byte values to be written, in the order shown, are:
    * <p>
    * 
    * <pre>
    * {@code
    * (byte)(0xff & (v >> 24))
    * (byte)(0xff & (v >> 16))
    * (byte)(0xff & (v >>    8))
    * (byte)(0xff & v)
    * }
    * </pre>
    * <p>
    * The bytes written by this method may be read by the <code>readInt</code> method of interface
    * <code>DataInput</code> , which will then return an <code>int</code> equal to <code>v</code>.
    * 
    * @param v
    *          the <code>int</code> value to be written.
    * @exception IOException
    *              if an I/O error occurs.
    */
   void writeInt(int v) throws IOException;

   /**
    * Writes a <code>long</code> value, which is comprised of eight bytes, to the output stream. The
    * byte values to be written, in the order shown, are:
    * <p>
    * 
    * <pre>
    * {@code
    * (byte)(0xff & (v >> 56))
    * (byte)(0xff & (v >> 48))
    * (byte)(0xff & (v >> 40))
    * (byte)(0xff & (v >> 32))
    * (byte)(0xff & (v >> 24))
    * (byte)(0xff & (v >> 16))
    * (byte)(0xff & (v >>  8))
    * (byte)(0xff & v)
    * }
    * </pre>
    * <p>
    * The bytes written by this method may be read by the <code>readLong</code> method of interface
    * <code>DataInput</code> , which will then return a <code>long</code> equal to <code>v</code>.
    * 
    * @param v
    *          the <code>long</code> value to be written.
    * @exception IOException
    *              if an I/O error occurs.
    */
   void writeLong(long v) throws IOException;

}