************************************************
Following new methods overload the standard each() methods vor certain classes.
************************************************

    /**
     * Allows readers to be iterated line by line.
     * Overloaded to allow closing of resource if an exception occurs.
     * @see #eachLine(Reader, Closure)
     */
    public static void each(Reader self, Closure closure) throws IOException {
        eachLine(self, closure);
    }

    /**
     * Allows input streams to be iterated byte by byte.
     * Overloaded to allow closing of resource if an exception occurs.
     * @see #eachByte(InputStream, Closure)
     */
    public static void each(InputStream self, Closure closure) throws IOException {
        eachByte(self,closure);
    }

    /**
     * Allows object input streams to be iterated byte by byte.
     * Overloaded to allow closing of resource if an exception occurs.
     * @see #eachByte(ObjectInputStream, Closure)
     */
    public static void each(ObjectInputStream self, Closure closure) throws IOException {
        eachByte(self,closure);
    }


************************************************
An additional inner class as a base class for closing iterators.
************************************************

    /**
     * Abstract Iterator that provides a methode to close
     * an underlying resource at end and if an exception occurs.
     */
    private abstract static class ClosableIterator implements Iterator {
        Object nextVal = null;
        boolean hasNext = true;

        /**
         * Overwrite this method to get the next element.
         * @return the next element.
         * @throws Exception
         */
        protected abstract Object readElement() throws Exception;

        /**
         * Overwrite this method to provide a mean to close the
         * underlying ressource.
         * @throws Exception
         */
        protected abstract void closeResource() throws Exception;

        /*
         * @see Iterator#hasNext()
         */
        public boolean hasNext() {
            readNext();
            return hasNext;
        }

        /*
         * @see Iterator#next()
         */
        public Object next() {
            readNext();
            Object retval = nextVal;
            nextVal = null;
            return retval;
        }

        // Read next element, close resource when no more elements
        // available or if an exception is thrown.
        private void readNext() {
            if (nextVal!=null || !hasNext) return;
            try {
                nextVal = readElement();
            } catch (Exception e) {
                // Handle exception as if it were an eof.
            }
            if (nextVal==null) {
                try {
                    hasNext = false;
                    closeResource();
                } catch (Exception e) {
                    throw new RuntimeException(e);
                }
            }
        }

        /**
         * Remove is not supported.
         */
        public void remove() {
            throw new UnsupportedOperationException("Cannot remove() from a Reader Iterator");
        }
    }

************************************************
The following classes replace existing ones.
************************************************

    /**
     * Standard iterator for a reader which iterates through the
     * reader content in a line-based fashion.
     *
     * @param self a Reader object
     * @return an Iterator for the Reader
     */
    public static Iterator iterator(Reader self) {
        final BufferedReader bufferedReader;
        if (self instanceof BufferedReader) {
            bufferedReader = (BufferedReader) self;
        } else {
            bufferedReader = new BufferedReader(self);
        }
        return new ClosableIterator() {
            protected Object readElement() throws IOException {
                return bufferedReader.readLine();
            }
            protected void closeResource() throws IOException {
                bufferedReader.close();
            }
        };
    }

    /**
     * Standard iterator for a input stream which iterates through the stream content in a byte-based fashion.
     *
     * @param self an InputStream object
     * @return an Iterator for the InputStream
     */
    public static Iterator iterator(InputStream self) {
        return iterator(new DataInputStream(self));
    }

    /**
     * Standard iterator for a data input stream which iterates through the stream content in a byte-based fashion.
     *
     * @param self a DataInputStream object
     * @return an Iterator for the DataInputStream
     */
    public static Iterator iterator(final DataInputStream self) {
        return new ClosableIterator() {
            protected Object readElement() throws IOException {
                return Byte.valueOf(self.readByte());
            }
            protected void closeResource() throws IOException {
                self.close();
            }
        };
    }

    /**
     * Standard iterator for a file.
     * Not to be used any more, because exceptions in for-loops
     * cannot be handled properly.
     * @throws DeprecationException
     * @deprecated
     */
    public static Iterator iterator(File self) throws IOException {
        throw new DeprecationException(
           "Iterators on files are not supported any more. "+
           "Use File.eachLine() instead. Alternatively you can use FileReader.iterator() "+
           "and provide your own exception handling."
        );
    }