001package co.codewizards.cloudstore.core.io;
002
003import java.io.IOException;
004import java.io.UnsupportedEncodingException;
005
006/**
007 * {@link java.io.ByteArrayOutputStream ByteArrayOutputStream}-representing interface to be used in API contracts.
008 * <p>
009 * See {@link IOutputStream} for further details.
010 *
011 * @author Marco หงุ่ยตระกูล-Schulze - marco at codewizards dot co
012 */
013public interface IByteArrayOutputStream extends IOutputStream {
014
015        /**
016     * Writes the complete contents of this byte array output stream to
017     * the specified output stream argument, as if by calling the output
018     * stream's write method using <code>out.write(buf, 0, count)</code>.
019     *
020     * @param      out   the output stream to which to write the data.
021     * @exception  IOException  if an I/O error occurs.
022     */
023    void writeTo(IOutputStream out) throws IOException;
024
025    /**
026     * Resets the <code>count</code> field of this byte array output
027     * stream to zero, so that all currently accumulated output in the
028     * output stream is discarded. The output stream can be used again,
029     * reusing the already allocated buffer space.
030     *
031     * @see     java.io.ByteArrayInputStream#count
032     */
033    void reset();
034
035    /**
036     * Creates a newly allocated byte array. Its size is the current
037     * size of this output stream and the valid contents of the buffer
038     * have been copied into it.
039     *
040     * @return  the current contents of this output stream, as a byte array.
041     * @see     java.io.ByteArrayOutputStream#size()
042     */
043    byte[] toByteArray();
044
045    /**
046     * Returns the current size of the buffer.
047     *
048     * @return  the value of the <code>count</code> field, which is the number
049     *          of valid bytes in this output stream.
050     * @see     java.io.ByteArrayOutputStream#count
051     */
052    int size();
053
054//    /**
055//     * Converts the buffer's contents into a string decoding bytes using the
056//     * platform's default character set. The length of the new <tt>String</tt>
057//     * is a function of the character set, and hence may not be equal to the
058//     * size of the buffer.
059//     *
060//     * <p> This method always replaces malformed-input and unmappable-character
061//     * sequences with the default replacement string for the platform's
062//     * default character set. The {@linkplain java.nio.charset.CharsetDecoder}
063//     * class should be used when more control over the decoding process is
064//     * required.
065//     *
066//     * @return String decoded from the buffer's contents.
067//     * @since  JDK1.1
068//     */
069//    public synchronized String toString() {
070//        return new String(buf, 0, count);
071//    }
072
073    /**
074     * Converts the buffer's contents into a string by decoding the bytes using
075     * the named {@link java.nio.charset.Charset charset}. The length of the new
076     * <tt>String</tt> is a function of the charset, and hence may not be equal
077     * to the length of the byte array.
078     *
079     * <p> This method always replaces malformed-input and unmappable-character
080     * sequences with this charset's default replacement string. The {@link
081     * java.nio.charset.CharsetDecoder} class should be used when more control
082     * over the decoding process is required.
083     *
084     * @param      charsetName  the name of a supported
085     *             {@link java.nio.charset.Charset charset}
086     * @return     String decoded from the buffer's contents.
087     * @exception  UnsupportedEncodingException
088     *             If the named charset is not supported
089     * @since      JDK1.1
090     */
091    String toString(String charsetName) throws UnsupportedEncodingException;
092}