001    /* PushbackReader.java -- An character stream that can unread chars
002       Copyright (C) 1998, 2000, 2001, 2003, 2005  Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package java.io;
040    
041    /**
042     * This subclass of <code>FilterReader</code> provides the ability to
043     * unread data from a stream.  It maintains an internal buffer of unread
044     * data that is supplied to the next read operation.  This is conceptually
045     * similar to mark/reset functionality, except that in this case the
046     * position to reset the stream to does not need to be known in advance.
047     * <p>
048     * The default pushback buffer size one char, but this can be overridden
049     * by the creator of the stream.
050     *
051     * @author Aaron M. Renn (arenn@urbanophile.com)
052     * @author Warren Levy (warrenl@cygnus.com)
053     */
054    public class PushbackReader extends FilterReader
055    {
056      /**
057       * This is the default buffer size
058       */
059      private static final int DEFAULT_BUFFER_SIZE = 1;
060    
061      /**
062       * This is the buffer that is used to store the pushed back data
063       */
064      private char[] buf;
065    
066      /**
067       * This is the position in the buffer from which the next char will be
068       * read.  Bytes are stored in reverse order in the buffer, starting from
069       * <code>buf[buf.length - 1]</code> to <code>buf[0]</code>.  Thus when
070       * <code>pos</code> is 0 the buffer is full and <code>buf.length</code> when
071       * it is empty
072       */
073      private int pos;
074    
075      /**
076       * This method initializes a <code>PushbackReader</code> to read from the
077       * specified subordinate <code>Reader</code> with a default pushback buffer
078       * size of 1.
079       *
080       * @param in The subordinate stream to read from
081       */
082      public PushbackReader(Reader in)
083      {
084        this(in, DEFAULT_BUFFER_SIZE);
085      }
086    
087      /**
088       * This method initializes a <code>PushbackReader</code> to read from the
089       * specified subordinate <code>Reader</code> with the specified buffer
090       * size
091       *
092       * @param in The subordinate <code>Reader</code> to read from
093       * @param bufsize The pushback buffer size to use
094       */
095      public PushbackReader(Reader in, int bufsize)
096      {
097        super(in);
098    
099        if (bufsize < 0)
100          throw new IllegalArgumentException("buffer size must be positive");
101    
102        buf = new char[bufsize];
103        pos = bufsize;
104      }
105    
106      /**
107       * This method closes the stream and frees any associated resources.
108       *
109       * @exception IOException If an error occurs.
110       */
111      public void close() throws IOException
112      {
113        synchronized (lock)
114          {
115            buf = null;
116            super.close();
117          }
118      }
119    
120      /**
121       * This method throws an exception when called since this class does
122       * not support mark/reset.
123       *
124       * @param read_limit Not used.
125       *
126       * @exception IOException Always thrown to indicate mark/reset not supported.
127       */
128      public void mark(int read_limit) throws IOException
129      {
130        throw new IOException("mark not supported in this class");
131      }
132    
133      /**
134       * This method returns <code>false</code> to indicate that it does not support
135       * mark/reset functionality.
136       *
137       * @return This method returns <code>false</code> to indicate that this
138       * class does not support mark/reset functionality
139       *
140       */
141      public boolean markSupported()
142      {
143        return(false);
144      }
145    
146      /**
147       * This method always throws an IOException in this class because
148       * mark/reset functionality is not supported.
149       *
150       * @exception IOException Always thrown for this class
151       */
152      public void reset() throws IOException
153      {
154        throw new IOException("reset not supported in this class");
155      }
156    
157      /**
158       * This method determines whether or not this stream is ready to be read.
159       * If it returns <code>false</code> to indicate that the stream is not
160       * ready, any attempt to read from the stream could (but is not
161       * guaranteed to) block.
162       * <p>
163       * This stream is ready to read if there are either chars waiting to be
164       * read in the pushback buffer or if the underlying stream is ready to
165       * be read.
166       *
167       * @return <code>true</code> if this stream is ready to be read,
168       * <code>false</code> otherwise
169       *
170       * @exception IOException If an error occurs
171       */
172      public boolean ready() throws IOException
173      {
174        synchronized (lock)
175          {
176            if (buf == null)
177              throw new IOException ("stream closed");
178    
179            if (((buf.length - pos) > 0) || super.ready())
180              return(true);
181            else
182              return(false);
183          }
184      }
185    
186      // Don't delete this method just because the spec says it shouldn't be there!
187      // See the CVS log for details.
188      /**
189        * This method skips the specified number of chars in the stream.  It
190        * returns the actual number of chars skipped, which may be less than the
191        * requested amount.
192        * <p>
193        * This method first discards chars from the buffer, then calls the
194        * <code>skip</code> method on the underlying <code>Reader</code> to
195        * skip additional chars if necessary.
196        *
197        * @param num_chars The requested number of chars to skip
198        *
199        * @return The actual number of chars skipped.
200        *
201        * @exception IOException If an error occurs
202        */
203      public long skip(long num_chars) throws IOException
204      {
205        synchronized (lock)
206          {
207            if (num_chars <= 0)
208              return(0);
209    
210            if ((buf.length - pos) >= num_chars)
211              {
212                pos += num_chars;
213                return(num_chars);
214              }
215    
216            int chars_discarded = buf.length - pos;
217            pos = buf.length;
218    
219            long chars_skipped = in.skip(num_chars - chars_discarded);
220    
221            return(chars_discarded + chars_skipped);
222          }
223      }
224    
225      /**
226       * This method reads an unsigned char from the input stream and returns it
227       * as an int in the range of 0-65535.  This method also will return -1 if
228       * the end of the stream has been reached.  The char returned will be read
229       * from the pushback buffer, unless the buffer is empty, in which case
230       * the char will be read from the underlying stream.
231       * <p>
232       * This method will block until the char can be read.
233       *
234       * @return The char read or -1 if end of stream
235       *
236       * @exception IOException If an error occurs
237       */
238      public int read() throws IOException
239      {
240        synchronized (lock)
241          {
242            if (buf == null)
243              throw new IOException("stream closed");
244    
245            if (pos == buf.length)
246              return(super.read());
247    
248            ++pos;
249            return((buf[pos - 1] & 0xFFFF));
250          }
251      }
252    
253      /**
254       * This method read chars from a stream and stores them into a caller
255       * supplied buffer.  It starts storing the data at index <code>offset</code>
256       * into
257       * the buffer and attempts to read <code>len</code> chars.  This method can
258       * return before reading the number of chars requested.  The actual number
259       * of chars read is returned as an int.  A -1 is returned to indicate the
260       * end of the stream.
261       *  <p>
262       * This method will block until some data can be read.
263       * <p>
264       * This method first reads chars from the pushback buffer in order to
265       * satisfy the read request.  If the pushback buffer cannot provide all
266       * of the chars requested, the remaining chars are read from the
267       * underlying stream.
268       *
269       * @param buffer The array into which the chars read should be stored
270       * @param offset The offset into the array to start storing chars
271       * @param length The requested number of chars to read
272       *
273       * @return The actual number of chars read, or -1 if end of stream.
274       *
275       * @exception IOException If an error occurs.
276       */
277      public synchronized int read(char[] buffer, int offset, int length)
278        throws IOException
279      {
280        synchronized (lock)
281          {
282            if (buf == null)
283              throw new IOException("stream closed");
284    
285            if (offset < 0 || length < 0 || offset + length > buffer.length)
286              throw new ArrayIndexOutOfBoundsException();
287    
288            int numBytes = Math.min(buf.length - pos, length);
289            if (numBytes > 0)
290              {
291                System.arraycopy (buf, pos, buffer, offset, numBytes);
292                pos += numBytes;
293                return numBytes;
294              }
295    
296            return super.read(buffer, offset, length);
297          }
298      }
299    
300      /**
301       * This method pushes a single char of data into the pushback buffer.
302       * The char pushed back is the one that will be returned as the first char
303       * of the next read.
304       * <p>
305       * If the pushback buffer is full, this method throws an exception.
306       * <p>
307       * The argument to this method is an <code>int</code>.  Only the low eight
308       * bits of this value are pushed back.
309       *
310       * @param b The char to be pushed back, passed as an int
311       *
312       * @exception IOException If the pushback buffer is full.
313       */
314      public void unread(int b) throws IOException
315      {
316        synchronized (lock)
317          {
318            if (buf == null)
319              throw new IOException("stream closed");
320            if (pos == 0)
321              throw new IOException("Pushback buffer is full");
322    
323            --pos;
324            buf[pos] = (char)(b & 0xFFFF);
325          }
326      }
327    
328      /**
329       * This method pushes all of the chars in the passed char array into
330       * the pushback buffer.  These chars are pushed in reverse order so that
331       * the next char read from the stream after this operation will be
332       * <code>buf[0]</code> followed by <code>buf[1]</code>, etc.
333       * <p>
334       * If the pushback buffer cannot hold all of the requested chars, an
335       * exception is thrown.
336       *
337       * @param buf The char array to be pushed back
338       *
339       * @exception IOException If the pushback buffer is full
340       */
341      public synchronized void unread(char[] buf) throws IOException
342      {
343        unread(buf, 0, buf.length);
344      }
345    
346      /**
347       * This method pushed back chars from the passed in array into the pushback
348       * buffer.  The chars from <code>buf[offset]</code> to
349       * <code>buf[offset + len]</code>
350       * are pushed in reverse order so that the next char read from the stream
351       * after this operation will be <code>buf[offset]</code> followed by
352       * <code>buf[offset + 1]</code>, etc.
353       * <p>
354       * If the pushback buffer cannot hold all of the requested chars, an
355       * exception is thrown.
356       *
357       * @param buffer The char array to be pushed back
358       * @param offset The index into the array where the chars to be push start
359       * @param length The number of chars to be pushed.
360       *
361       * @exception IOException If the pushback buffer is full
362       */
363      public synchronized void unread(char[] buffer, int offset, int length)
364        throws IOException
365      {
366        synchronized (lock)
367          {
368            if (buf == null)
369              throw new IOException("stream closed");
370            if (pos < length)
371              throw new IOException("Pushback buffer is full");
372    
373            // Note the order that these chars are being added is the opposite
374            // of what would be done if they were added to the buffer one at a time.
375            // See the Java Class Libraries book p. 1397.
376            System.arraycopy(buffer, offset, buf, pos - length, length);
377    
378            // Don't put this into the arraycopy above, an exception might be thrown
379            // and in that case we don't want to modify pos.
380            pos -= length;
381          }
382      }
383    }