001package co.codewizards.cloudstore.core.io; 002 003import java.io.IOException; 004import java.lang.reflect.Proxy; 005 006/** 007 * {@link OutputStream}-representing interface to be used in API contracts. 008 * <p> 009 * Interfaces modelling API should always use {@link IOutputStream} instead 010 * of {@link OutputStream}, because this facilitates the usage of 011 * {@linkplain Proxy proxies}. Proxies are needed to use APIs accross 012 * local-server/-client boundaries. 013 * <p> 014 * To convert between {@link OutputStream} and {@link IOutputStream}, use 015 * {@link StreamUtil#castStream(IOutputStream)} or {@link StreamUtil#castStream(OutputStream)}. 016 * <p> 017 * It is recommended that you statically import {@code StreamUtil.*} whenever 018 * you need a {@code castStream(...)}. Also, you should register this in your IDE 019 * as a favorite for static method imports. 020 * <p> 021 * <b>Important note about the naming:</b> We usually <i>never</i> use the "I-for-interface" 022 * naming scheme! It sucks! But due to the fact that we already have "OutputStream" rather than 023 * "OutputStreamImpl", we exceptionally use the "I"-prefix here. 024 * 025 * @author Marco หงุ่ยตระกูล-Schulze - marco at codewizards dot co 026 * @see StreamUtil 027 */ 028public interface IOutputStream extends AutoCloseable { 029 030 /** 031 * Writes the specified byte to this output stream. The general 032 * contract for <code>write</code> is that one byte is written 033 * to the output stream. The byte to be written is the eight 034 * low-order bits of the argument <code>b</code>. The 24 035 * high-order bits of <code>b</code> are ignored. 036 * <p> 037 * Subclasses of <code>IOutputStream</code> must provide an 038 * implementation for this method. 039 * 040 * @param b the <code>byte</code>. 041 * @exception IOException if an I/O error occurs. In particular, 042 * an <code>IOException</code> may be thrown if the 043 * output stream has been closed. 044 */ 045 void write(int b) throws IOException; 046 047 /** 048 * Writes <code>b.length</code> bytes from the specified byte array 049 * to this output stream. The general contract for <code>write(b)</code> 050 * is that it should have exactly the same effect as the call 051 * <code>write(b, 0, b.length)</code>. 052 * 053 * @param b the data. 054 * @exception IOException if an I/O error occurs. 055 * @see java.io.OutputStream#write(byte[], int, int) 056 */ 057 void write(byte b[]) throws IOException; 058 059 /** 060 * Writes <code>len</code> bytes from the specified byte array 061 * starting at offset <code>off</code> to this output stream. 062 * The general contract for <code>write(b, off, len)</code> is that 063 * some of the bytes in the array <code>b</code> are written to the 064 * output stream in order; element <code>b[off]</code> is the first 065 * byte written and <code>b[off+len-1]</code> is the last byte written 066 * by this operation. 067 * <p> 068 * The <code>write</code> method of <code>IOutputStream</code> calls 069 * the write method of one argument on each of the bytes to be 070 * written out. Subclasses are encouraged to override this method and 071 * provide a more efficient implementation. 072 * <p> 073 * If <code>b</code> is <code>null</code>, a 074 * <code>NullPointerException</code> is thrown. 075 * <p> 076 * If <code>off</code> is negative, or <code>len</code> is negative, or 077 * <code>off+len</code> is greater than the length of the array 078 * <code>b</code>, then an <tt>IndexOutOfBoundsException</tt> is thrown. 079 * 080 * @param b the data. 081 * @param off the start offset in the data. 082 * @param len the number of bytes to write. 083 * @exception IOException if an I/O error occurs. In particular, 084 * an <code>IOException</code> is thrown if the output 085 * stream is closed. 086 */ 087 void write(byte b[], int off, int len) throws IOException; 088 089 /** 090 * Flushes this output stream and forces any buffered output bytes 091 * to be written out. The general contract of <code>flush</code> is 092 * that calling it is an indication that, if any bytes previously 093 * written have been buffered by the implementation of the output 094 * stream, such bytes should immediately be written to their 095 * intended destination. 096 * <p> 097 * If the intended destination of this stream is an abstraction provided by 098 * the underlying operating system, for example a file, then flushing the 099 * stream guarantees only that bytes previously written to the stream are 100 * passed to the operating system for writing; it does not guarantee that 101 * they are actually written to a physical device such as a disk drive. 102 * <p> 103 * The <code>flush</code> method of <code>IOutputStream</code> does nothing. 104 * 105 * @exception IOException if an I/O error occurs. 106 */ 107 void flush() throws IOException; 108 109 /** 110 * Closes this output stream and releases any system resources 111 * associated with this stream. The general contract of <code>close</code> 112 * is that it closes the output stream. A closed stream cannot perform 113 * output operations and cannot be reopened. 114 * <p> 115 * The <code>close</code> method of <code>IOutputStream</code> does nothing. 116 * 117 * @exception IOException if an I/O error occurs. 118 */ 119 @Override 120 void close() throws IOException; 121}