From 477946a63dee474c725243ae0d998f4cba1bfc0a Mon Sep 17 00:00:00 2001 From: Mark Wielaard Date: Mon, 1 Oct 2001 18:24:54 +0000 Subject: FileWriter.java: Merge with Classpath. * java/io/FileWriter.java: Merge with Classpath. * java/io/FilterInputStream.java: Ditto. (mark): no longer synchronized (reset): Likewise * java/io/FilterOutputStream.java: Merge with Classpath. * java/io/FilterReader.java: Ditto. (mark): no longer synchronized (reset): Likewise * java/io/FilterWriter.java: Merge with Classpath. * java/io/Writer.java: Ditto. * java/lang/Compiler.java: Ditto. * java/lang/Process.java: Ditto. * java/lang/Void.java: Ditto. * java/net/ContentHandler.java: Ditto. * java/net/DatagramPacket.java: Ditto. * java/net/MulticastSocket.java: Merge comments with Classpath. From-SVN: r45930 --- libjava/java/io/FileWriter.java | 142 ++++++++++++---- libjava/java/io/FilterInputStream.java | 286 +++++++++++++++++++++++++------- libjava/java/io/FilterOutputStream.java | 205 +++++++++++++++++------ libjava/java/io/FilterReader.java | 263 ++++++++++++++++++++++------- libjava/java/io/FilterWriter.java | 198 +++++++++++++++++----- libjava/java/io/Writer.java | 250 ++++++++++++++++++++++------ 6 files changed, 1045 insertions(+), 299 deletions(-) (limited to 'libjava/java/io') diff --git a/libjava/java/io/FileWriter.java b/libjava/java/io/FileWriter.java index 5c49e5f..53e3658 100644 --- a/libjava/java/io/FileWriter.java +++ b/libjava/java/io/FileWriter.java @@ -1,44 +1,126 @@ -// FileWriter.java - Character output to a file. +/* FileWriter.java -- Convenience class for writing to files. + Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc. -/* Copyright (C) 1998, 1999 Free Software Foundation +This file is part of GNU Classpath. - This file is part of libgcj. +GNU Classpath is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2, or (at your option) +any later version. + +GNU Classpath 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 +General Public License for more details. -This software is copyrighted work licensed under the terms of the -Libgcj License. Please consult the file "LIBGCJ_LICENSE" for -details. */ +You should have received a copy of the GNU General Public License +along with GNU Classpath; see the file COPYING. If not, write to the +Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA +02111-1307 USA. -package java.io; +As a special exception, if you link this library with other files to +produce an executable, this library does not by itself cause the +resulting executable to be covered by the GNU General Public License. +This exception does not however invalidate any other reasons why the +executable file might be covered by the GNU General Public License. */ -/** - * @author Tom Tromey - * @date September 25, 1998 - */ + +package java.io; /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3 * "The Java Language Specification", ISBN 0-201-63451-1 * Status: Complete to version 1.1. */ +/** + * This is a convenience class for writing to files. It creates an + * FileOutputStream and initializes an + * OutputStreamWriter to write to it. + * + * @author Aaron M. Renn (arenn@urbanophile.com) + * @author Tom Tromey + */ public class FileWriter extends OutputStreamWriter { - public FileWriter (String fileName) throws IOException - { - super (new FileOutputStream (fileName)); - } - - public FileWriter (String fileName, boolean append) throws IOException - { - super (new FileOutputStream (fileName, append)); - } - - public FileWriter (File file) throws IOException - { - super (new FileOutputStream (file)); - } - - public FileWriter (FileDescriptor fd) - { - super (new FileOutputStream (fd)); - } + +/*************************************************************************/ + +/* + * Constructors + */ + +/** + * This method initializes a new FileWriter object to write + * to the specified File object. + * + * @param file The File object to write to. + * + * @param SecurityException If writing to this file is forbidden by the + * SecurityManager. + * @param IOException If any other error occurs + */ +public +FileWriter(File file) throws SecurityException, IOException +{ + super(new FileOutputStream(file)); +} + +/*************************************************************************/ + +/** + * This method initializes a new FileWriter object to write + * to the specified FileDescriptor object. + * + * @param fd The FileDescriptor object to write to + * + * @param SecurityException If writing to this file is forbidden by the + * SecurityManager. + */ +public +FileWriter(FileDescriptor fd) throws SecurityException +{ + super(new FileOutputStream(fd)); +} + +/*************************************************************************/ + +/** + * This method intializes a new FileWriter object to write to the + * specified named file. + * + * @param name The name of the file to write to + * + * @param SecurityException If writing to this file is forbidden by the + * SecurityManager. + * @param IOException If any other error occurs + */ +public +FileWriter(String name) throws IOException +{ + super(new FileOutputStream(name)); } + +/*************************************************************************/ + +/** + * This method intializes a new FileWriter object to write to the + * specified named file. This form of the constructor allows the caller + * to determin whether data should be written starting at the beginning or + * the end of the file. + * + * @param name The name of the file to write to + * @param append true to start adding data at the end of the + * file, false otherwise. + * + * @param SecurityException If writing to this file is forbidden by the + * SecurityManager. + * @param IOException If any other error occurs + */ +public +FileWriter(String name, boolean append) throws IOException +{ + super(new FileOutputStream(name, append)); +} + +} // class FileWriter + diff --git a/libjava/java/io/FilterInputStream.java b/libjava/java/io/FilterInputStream.java index 712be92..5b09312 100644 --- a/libjava/java/io/FilterInputStream.java +++ b/libjava/java/io/FilterInputStream.java @@ -1,75 +1,237 @@ -/* Copyright (C) 1998, 1999 Free Software Foundation +/* FilterInputStream.java -- Base class for classes that filter input + Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc. - This file is part of libgcj. +This file is part of GNU Classpath. -This software is copyrighted work licensed under the terms of the -Libgcj License. Please consult the file "LIBGCJ_LICENSE" for -details. */ +GNU Classpath is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2, or (at your option) +any later version. +GNU Classpath 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 +General Public License for more details. + +You should have received a copy of the GNU General Public License +along with GNU Classpath; see the file COPYING. If not, write to the +Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA +02111-1307 USA. + +As a special exception, if you link this library with other files to +produce an executable, this library does not by itself cause the +resulting executable to be covered by the GNU General Public License. +This exception does not however invalidate any other reasons why the +executable file might be covered by the GNU General Public License. */ + + package java.io; -/** - * @author Warren Levy - * @date October 8, 1998. - */ /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3 * "The Java Language Specification", ISBN 0-201-63451-1 * plus online API docs for JDK 1.2 beta from http://www.javasoft.com. * Status: Believed complete and correct. */ - + +/** + * This is the common superclass of all standard classes that filter + * input. It acts as a layer on top of an underlying InputStream + * and simply redirects calls made to it to the subordinate InputStream + * instead. Subclasses of this class perform additional filtering + * functions in addition to simply redirecting the call. + *

+ * This class is not abstract. However, since it only redirects calls + * to a subordinate InputStream without adding any functionality + * on top of it, this class should not be used directly. Instead, various + * subclasses of this class should be used. This is enforced with a + * protected constructor. Do not try to hack around it. + *

+ * When creating a subclass of FilterInputStream, override the + * appropriate methods to implement the desired filtering. However, note + * that the read(byte[]) method does not need to be overridden + * as this class redirects calls to that method to + * read(byte[], int, int) instead of to the subordinate + * InputStream read(byte[]) method. + * + * @author Aaron M. Renn (arenn@urbanophile.com) + * @author Warren Levy + */ public class FilterInputStream extends InputStream { - /* The input stream to be filtered. */ - protected InputStream in; - - protected FilterInputStream(InputStream in) - { - this.in = in; - } - - public int available() throws IOException - { - return in.available(); - } - - public void close() throws IOException - { - in.close(); - } - - public synchronized void mark(int readlimit) - { - in.mark(readlimit); - } - - public boolean markSupported() - { - return in.markSupported(); - } - - public int read() throws IOException - { - return in.read(); - } - - public int read(byte[] b) throws IOException - { - return read(b, 0, b.length); - } - - public int read(byte[] b, int off, int len) throws IOException - { - return in.read(b, off, len); - } - - public synchronized void reset() throws IOException - { - in.reset(); - } - - public long skip(long n) throws IOException - { - return in.skip(n); - } + +/*************************************************************************/ + +/* + * Instance Variables + */ + +/** + * This is the subordinate InputStream to which method calls + * are redirected + */ +protected InputStream in; + +/*************************************************************************/ + +/* + * Constructors + */ + +/** + * Create a FilterInputStream with the specified subordinate + * InputStream. + * + * @param in The subordinate InputStream + */ +protected +FilterInputStream(InputStream in) +{ + this.in = in; +} + +/*************************************************************************/ + +/* + * Instance Methods + */ + +/** + * Calls the in.mark(int) method. + * + * @param readlimit The parameter passed to in.mark(int) + */ +public void +mark(int readlimit) +{ + in.mark(readlimit); +} + +/*************************************************************************/ + +/** + * Calls the in.markSupported() method. + * + * @return true if mark/reset is supported, false + * otherwise + */ +public boolean +markSupported() +{ + return(in.markSupported()); +} + +/*************************************************************************/ + +/** + * Calls the in.reset() method. + * + * @exception IOException If an error occurs + */ +public void +reset() throws IOException +{ + in.reset(); +} + +/*************************************************************************/ + +/** + * Calls the in.available() method. + * + * @return The value returned from in.available() + * + * @exception IOException If an error occurs + */ +public int +available() throws IOException +{ + return(in.available()); +} + +/*************************************************************************/ + +/** + * Calls the in.skip(long) method + * + * @param The requested number of bytes to skip. + * + * @return The value returned from in.skip(long) + * + * @exception IOException If an error occurs + */ +public long +skip(long num_bytes) throws IOException +{ + return(in.skip(num_bytes)); +} + +/*************************************************************************/ + +/** + * Calls the in.read() method + * + * @return The value returned from in.read() + * + * @exception IOException If an error occurs + */ +public int +read() throws IOException +{ + return(in.read()); } + +/*************************************************************************/ + +/** + * Calls the read(byte[], int, int) overloaded method. Note that + * this method does not redirect its call directly to a corresponding + * method in in. This allows subclasses to override only the + * three argument version of read. + * + * @param buf The buffer to read bytes into + * + * @return The value retured from in.read(byte[], int, int) + * + * @exception IOException If an error occurs + */ +public int +read(byte[] buf) throws IOException +{ + return(read(buf, 0, buf.length)); +} + +/*************************************************************************/ + +/** + * Calls the in.read(byte[], int, int) method. + * + * @param buf The buffer to read bytes into + * @param offset The index into the buffer to start storing bytes + * @param len The maximum number of bytes to read. + * + * @return The value retured from in.read(byte[], int, int) + * + * @exception IOException If an error occurs + */ +public int +read(byte[] buf, int offset, int len) throws IOException +{ + return(in.read(buf, offset, len)); +} + +/*************************************************************************/ + +/** + * This method closes the input stream by closing the input stream that + * this object is filtering. Future attempts to access this stream may + * throw an exception. + * + * @exception IOException If an error occurs + */ +public void +close() throws IOException +{ + in.close(); +} + +} // class FilterInputStream diff --git a/libjava/java/io/FilterOutputStream.java b/libjava/java/io/FilterOutputStream.java index c17ea26..53e519c 100644 --- a/libjava/java/io/FilterOutputStream.java +++ b/libjava/java/io/FilterOutputStream.java @@ -1,62 +1,171 @@ -// FilterOutputStream.java - A filtered stream +/* FilterOutputStream.java -- Parent class for output streams that filter + Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc. -/* Copyright (C) 1998, 1999 Free Software Foundation +This file is part of GNU Classpath. - This file is part of libgcj. +GNU Classpath is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2, or (at your option) +any later version. + +GNU Classpath 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 +General Public License for more details. -This software is copyrighted work licensed under the terms of the -Libgcj License. Please consult the file "LIBGCJ_LICENSE" for -details. */ +You should have received a copy of the GNU General Public License +along with GNU Classpath; see the file COPYING. If not, write to the +Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA +02111-1307 USA. -package java.io; +As a special exception, if you link this library with other files to +produce an executable, this library does not by itself cause the +resulting executable to be covered by the GNU General Public License. +This exception does not however invalidate any other reasons why the +executable file might be covered by the GNU General Public License. */ -/** - * @author Tom Tromey - * @date September 24, 1998 - */ + +package java.io; /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3 * "The Java Language Specification", ISBN 0-201-63451-1 * Status: Complete to version 1.1. */ +/** + * This class is the common superclass of output stream classes that + * filter the output they write. These classes typically transform the + * data in some way prior to writing it out to another underlying + * OutputStream. This class simply overrides all the + * methods in OutputStream to redirect them to the + * underlying stream. Subclasses provide actual filtering. + * + * @author Aaron M. Renn (arenn@urbanophile.com) + * @author Tom Tromey + */ public class FilterOutputStream extends OutputStream { - public void close () throws IOException - { - flush (); - out.close(); - } - - public FilterOutputStream (OutputStream ox) - { - out = ox; - } - - public void flush () throws IOException - { - out.flush(); - } - - public void write (int b) throws IOException - { - out.write(b); - } - - public void write (byte[] b) throws IOException, NullPointerException - { - // Don't do checking here, per Java Lang Spec. - write (b, 0, b.length); - } - - public void write (byte[] b, int off, int len) - throws IOException, NullPointerException, IndexOutOfBoundsException - { - // Don't do checking here, per Java Lang Spec. - for (int i=0; i < len; i++) - write (b[off + i]); - } - - // The output stream. - protected OutputStream out; + +/*************************************************************************/ + +/* + * Instance Variables + */ + +/** + * This is the subordinate OutputStream that this class + * redirects its method calls to. + */ +protected OutputStream out; + +/*************************************************************************/ + +/* + * Constructors + */ + +/** + * This method initializes an instance of FilterOutputStream + * to write to the specified subordinate OutputStream. + * + * @param out The OutputStream to write to + */ +public +FilterOutputStream(OutputStream out) +{ + this.out = out; +} + +/*************************************************************************/ + +/* + * Instance Methods + */ + +/** + * This method closes the underlying OutputStream. Any + * further attempts to write to this stream may throw an exception. + * + * @exception IOException If an error occurs + */ +public void +close() throws IOException +{ + flush(); + out.close(); +} + +/*************************************************************************/ + +/** + * This method attempt to flush all buffered output to be written to the + * underlying output sink. + * + * @exception IOException If an error occurs + */ +public void +flush() throws IOException +{ + out.flush(); } + +/*************************************************************************/ + +/** + * This method writes a single byte of output to the underlying + * OutputStream. + * + * @param b The byte to write, passed as an int. + * + * @exception IOException If an error occurs + */ +public void +write(int b) throws IOException +{ + out.write(b); +} + +/*************************************************************************/ + +/** + * This method writes all the bytes in the specified array to the underlying + * OutputStream. It does this by calling the three parameter + * version of this method - write(byte[], int, int) in this + * class instead of writing to the underlying OutputStream + * directly. This allows most subclasses to avoid overriding this method. + * + * @param buf The byte array to write bytes from + * + * @exception IOException If an error occurs + */ +public void +write(byte[] buf) throws IOException +{ + // Don't do checking here, per Java Lang Spec. + write(buf, 0, buf.length); +} + +/*************************************************************************/ + +/** + * This method calls the write(int) method len + * times for all bytes from the array buf starting at index + * offset. Subclasses should overwrite this method to get a + * more efficient implementation. + * + * @param buf The byte array to write bytes from + * @param offset The index into the array to start writing bytes from + * @param len The number of bytes to write + * + * @exception IOException If an error occurs + */ +public void +write(byte[] buf, int offset, int len) throws IOException +{ + // Don't do checking here, per Java Lang Spec. + for (int i=0; i < len; i++) + write(buf[offset + i]); + +} + +} // class FilterOutputStream diff --git a/libjava/java/io/FilterReader.java b/libjava/java/io/FilterReader.java index 608f910..a3897bc 100644 --- a/libjava/java/io/FilterReader.java +++ b/libjava/java/io/FilterReader.java @@ -1,75 +1,214 @@ -/* Copyright (C) 1998, 1999, 2001 Free Software Foundation +/* FilterReader.java -- Base class for char stream classes that filter input + Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc. - This file is part of libgcj. +This file is part of GNU Classpath. + +GNU Classpath is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2, or (at your option) +any later version. + +GNU Classpath 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 +General Public License for more details. + +You should have received a copy of the GNU General Public License +along with GNU Classpath; see the file COPYING. If not, write to the +Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA +02111-1307 USA. + +As a special exception, if you link this library with other files to +produce an executable, this library does not by itself cause the +resulting executable to be covered by the GNU General Public License. +This exception does not however invalidate any other reasons why the +executable file might be covered by the GNU General Public License. */ -This software is copyrighted work licensed under the terms of the -Libgcj License. Please consult the file "LIBGCJ_LICENSE" for -details. */ package java.io; -/** - * @author Warren Levy - * @date October 15, 1998. - */ /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3 * "The Java Language Specification", ISBN 0-201-63451-1 * plus online API docs for JDK 1.2 beta from http://www.javasoft.com. * Status: Believed complete and correct. */ - + +/** + * This is the common superclass of all standard classes that filter + * input. It acts as a layer on top of an underlying Reader + * and simply redirects calls made to it to the subordinate Reader + * instead. Subclasses of this class perform additional filtering + * functions in addition to simply redirecting the call. + *

+ * When creating a subclass of FilterReader, override the + * appropriate methods to implement the desired filtering. However, note + * that the read(char[]) method does not need to be overridden + * as this class redirects calls to that method to + * read(yte[], int, int) instead of to the subordinate + * Reader} read(yte[]) method. + * + * @author Aaron M. Renn (arenn@urbanophile.com) + * @author Warren Levy + */ public abstract class FilterReader extends Reader { - /* The input stream to be filtered. */ - protected Reader in; - - protected FilterReader(Reader in) - { - super(in.lock); - this.in = in; - } - - public void close() throws IOException - { - // We used to set `in = null' here. We don't, though, because - // that is the simplest way to ensure that read-after-close will - // throw the appropriate exception -- we rely on the filtered - // stream to do it. - in.close(); - } - - public synchronized void mark(int readlimit) throws IOException - { - in.mark(readlimit); - } - - public boolean markSupported() - { - return in.markSupported(); - } - - public int read() throws IOException - { - return in.read(); - } - - public int read(char[] b, int off, int len) throws IOException - { - return in.read(b, off, len); - } - - public boolean ready() throws IOException - { - return in.ready(); - } - - public synchronized void reset() throws IOException - { - in.reset(); - } - - public long skip(long n) throws IOException - { - return in.skip(n); - } + +/*************************************************************************/ + +/* + * Instance Variables + */ + +/** + * This is the subordinate Reader to which method calls + * are redirected + */ +protected Reader in; + +/*************************************************************************/ + +/* + * Constructors + */ + +/** + * Create a FilterReader with the specified subordinate + * Reader. + * The lock of the new FilterReader will be set + * to in.lock. + * + * @param in The subordinate Reader + */ +protected +FilterReader(Reader in) +{ + super(in.lock); + this.in = in; +} + +/*************************************************************************/ + +/* + * Instance Methods + */ + +/** + * Calls the in.mark(int) method. + * + * @param readlimit The parameter passed to in.mark(int) + * + * @exception IOException If an error occurs + */ +public void +mark(int readlimit) throws IOException +{ + in.mark(readlimit); +} + +/*************************************************************************/ + +/** + * Calls the in.markSupported() method. + * + * @return true if mark/reset is supported, false otherwise + */ +public boolean +markSupported() +{ + return(in.markSupported()); } + +/*************************************************************************/ + +/** + * Calls the in.reset() method. + * + * @exception IOException If an error occurs + */ +public void +reset() throws IOException +{ + in.reset(); +} + +/*************************************************************************/ + +/** + * Calls the in.read() method. + * + * @return The value returned from in.available() + * + * @exception IOException If an error occurs + */ +public boolean +ready() throws IOException +{ + return(in.ready()); +} + +/*************************************************************************/ + +/** + * Calls the in.skip(long) method + * + * @param The requested number of chars to skip. + * + * @return The value returned from in.skip(long) + * + * @exception IOException If an error occurs + */ +public long +skip(long num_chars) throws IOException +{ + return(in.skip(num_chars)); +} + +/*************************************************************************/ + +/** + * Calls the in.read() method + * + * @return The value returned from in.read() + * + * @exception IOException If an error occurs + */ +public int +read() throws IOException +{ + return(in.read()); +} + +/*************************************************************************/ + +/** + * Calls the in.read(char[], int, int) method. + * + * @param buf The buffer to read chars into + * @param offset The index into the buffer to start storing chars + * @param len The maximum number of chars to read. + * + * @return The value retured from in.read(char[], int, int) + * + * @exception IOException If an error occurs + */ +public int +read(char[] buf, int offset, int len) throws IOException +{ + return(in.read(buf, offset, len)); +} + +/*************************************************************************/ + +/** + * This method closes the stream by calling the close() method + * of the underlying stream. + * + * @exception IOException If an error occurs + */ +public void +close() throws IOException +{ + in.close(); +} + +} // class FilterReader diff --git a/libjava/java/io/FilterWriter.java b/libjava/java/io/FilterWriter.java index aa6600c..eaa7066 100644 --- a/libjava/java/io/FilterWriter.java +++ b/libjava/java/io/FilterWriter.java @@ -1,58 +1,168 @@ -// FilterWriter.java - Filtered character output stream. +/* FilterWriter.java -- Parent class for output streams that filter + Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc. -/* Copyright (C) 1998, 1999 Free Software Foundation +This file is part of GNU Classpath. - This file is part of libgcj. +GNU Classpath is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2, or (at your option) +any later version. + +GNU Classpath 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 +General Public License for more details. -This software is copyrighted work licensed under the terms of the -Libgcj License. Please consult the file "LIBGCJ_LICENSE" for -details. */ +You should have received a copy of the GNU General Public License +along with GNU Classpath; see the file COPYING. If not, write to the +Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA +02111-1307 USA. -package java.io; +As a special exception, if you link this library with other files to +produce an executable, this library does not by itself cause the +resulting executable to be covered by the GNU General Public License. +This exception does not however invalidate any other reasons why the +executable file might be covered by the GNU General Public License. */ -/** - * @author Tom Tromey - * @date September 25, 1998 - */ + +package java.io; /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3 * "The Java Language Specification", ISBN 0-201-63451-1 * Status: Complete to version 1.1. */ +/** + * This class is the common superclass of output character stream classes + * that filter the output they write. These classes typically transform the + * data in some way prior to writing it out to another underlying + * Writer. This class simply overrides all the + * methods in Writer to redirect them to the + * underlying stream. Subclasses provide actual filtering. + * + * @author Aaron M. Renn (arenn@urbanophile.com) + * @author Tom Tromey + */ public abstract class FilterWriter extends Writer { - public void close () throws IOException - { - out.close(); - } - - protected FilterWriter (Writer ox) - { - super (ox); - out = ox; - } - - public void flush () throws IOException - { - out.flush(); - } - - public void write (int oneChar) throws IOException - { - out.write(oneChar); - } - - public void write (char[] buffer, int offset, int count) throws IOException - { - out.write(buffer, offset, count); - } - - public void write (String str, int offset, int count) throws IOException - { - out.write(str, offset, count); - } - - // Where our writes should go. - protected Writer out; + +/*************************************************************************/ + +/* + * Instance Variables + */ + +/** + * This is the subordinate Writer that this class + * redirects its method calls to. + */ +protected Writer out; + +/*************************************************************************/ + +/* + * Constructors + */ + +/** + * This method initializes an instance of FilterWriter + * to write to the specified subordinate Writer. + * The given Writer will be used as lock for + * the newly created FilterWriter. + * + * @param out The Writer to write to + */ +protected +FilterWriter(Writer out) +{ + super(out); + this.out = out; +} + +/*************************************************************************/ + +/* + * Instance Methods + */ + +/** + * This method closes the underlying Writer. Any + * further attempts to write to this stream may throw an exception. + * + * @exception IOException If an error occurs + */ +public void +close() throws IOException +{ + out.close(); +} + +/*************************************************************************/ + +/** + * This method attempt to flush all buffered output to be written to the + * underlying output sink. + * + * @exception IOException If an error occurs + */ +public void +flush() throws IOException +{ + out.flush(); } + +/*************************************************************************/ + +/** + * This method writes a single char of output to the underlying + * Writer. + * + * @param b The char to write, passed as an int. + * + * @exception IOException If an error occurs + */ +public void +write(int b) throws IOException +{ + out.write(b); +} + +/*************************************************************************/ + +/** + * This method writes len chars from the array buf + * starting at index offset to the underlying + * Writer. + * + * @param buf The char array to write chars from + * @param offset The index into the array to start writing chars from + * @param len The number of chars to write + * + * @exception IOException If an error occurs + */ +public void +write(char[] buf, int offset, int len) throws IOException +{ + out.write(buf, offset, len); +} + +/*************************************************************************/ + +/** + * This method writes len chars from the String + * starting at position offset. + * + * @param str The String that is to be written + * @param offset The character offset into the String to start writing from + * @param len The number of chars to write + * + * @exception IOException If an error occurs + */ +public void +write(String str, int offset, int len) throws IOException +{ + out.write(str, offset, len); +} + +} // class FilterWriter + diff --git a/libjava/java/io/Writer.java b/libjava/java/io/Writer.java index 96fa0fb..2ce5ca3 100644 --- a/libjava/java/io/Writer.java +++ b/libjava/java/io/Writer.java @@ -1,67 +1,211 @@ -/* Copyright (C) 1998, 1999 Free Software Foundation +/* Writer.java -- Base class for character output streams + Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc. - This file is part of libgcj. +This file is part of GNU Classpath. -This software is copyrighted work licensed under the terms of the -Libgcj License. Please consult the file "LIBGCJ_LICENSE" for -details. */ +GNU Classpath is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2, or (at your option) +any later version. +GNU Classpath 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 +General Public License for more details. + +You should have received a copy of the GNU General Public License +along with GNU Classpath; see the file COPYING. If not, write to the +Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA +02111-1307 USA. + +As a special exception, if you link this library with other files to +produce an executable, this library does not by itself cause the +resulting executable to be covered by the GNU General Public License. +This exception does not however invalidate any other reasons why the +executable file might be covered by the GNU General Public License. */ + + package java.io; -/** - * @author Per Bothner - * @date April 17, 1998. - */ /* Written using "Java Class Libraries", 2nd edition, plus online * API docs for JDK 1.2 beta from http://www.javasoft.com. * Status: Believed complete and correct. - * However, write(String, int, int) should be made a native method. */ +/** + * This abstract class forms the base of the hierarchy of classes that + * write output as a stream of chars. It provides a common set of methods + * for writing chars to stream. Subclasses implement and/or extend these + * methods to write chars in a particular manner or to a particular + * destination such as a file on disk or network connection. + * + * @author Aaron M. Renn (arenn@urbanophile.com) + * @author Per Bothner + */ public abstract class Writer { - protected Object lock; - - protected Writer () - { - lock = this; - } - - protected Writer (Object lock) - { - this.lock = lock; - } - - abstract public void close() throws IOException; - - abstract public void flush() throws IOException; - - abstract public void write(char[] buf, int offset, int count) - throws IOException; - - public void write(char[] buf) throws IOException - { - write(buf, 0, buf.length); - } - - public void write(int ch) throws IOException - { - char[] buf = new char[1]; - buf[0] = (char) ch; - write(buf, 0, 1); - } - - // FIXME - re-write using native code to not require copied buffer. - public void write (String str, int offset, int count) throws IOException - { - char[] buf = new char[count]; - str.getChars(offset, offset + count, buf, 0); - write(buf, 0, count); - } - - public void write (String str) throws IOException - { - write(str, 0, str.length()); - } +/*************************************************************************/ + +/** + * This is the object used to synchronize criticial code sections for + * thread safety. Subclasses should use this field instead of using + * synchronized methods or explicity synchronizations on this + */ +protected Object lock; + +/*************************************************************************/ + +/* + * Constructors + */ + +/** + * This is the default no-argument constructor for this class. This method + * will set up the class to synchronize criticial sections on itself. + */ +protected +Writer() +{ + lock = this; } + +/*************************************************************************/ + +/** + * This method initializes a Writer that will synchronize + * on the specified Object. + * + * @param obj The Object to use for synchronizing critical + * sections + */ +protected +Writer(Object lock) +{ + this.lock = lock; +} + +/*************************************************************************/ + +/* + * Instance Methods + */ + +/** + * This method forces any data that may have been buffered to be written + * to the underlying output device. Please note that the host environment + * might perform its own buffering unbeknowst to Java. In that case, a + * write made (for example, to a disk drive) might be cached in OS + * buffers instead of actually being written to disk. + * + * @exception IOException If an error occurs + */ +public abstract void +flush() throws IOException; + +/*************************************************************************/ + +/** + * This method closes the stream. Any internal or native resources associated + * with this stream are freed. Any subsequent attempt to access the stream + * might throw an exception. + *

+ * This method in this class does nothing. + * + * @exception IOException If an error occurs + */ +public abstract void +close() throws IOException; + +/*************************************************************************/ + +/** + * This method writes a single char to the output stream. + * + * @param b The char to be written to the output stream, passed as an int + * + * @exception IOException If an error occurs + */ +public void +write(int b) throws IOException +{ + char[] buf = new char[1]; + + buf[0] = (char)b; + write(buf, 0, buf.length); +} + +/*************************************************************************/ + +/** + * This method all the writes char from the passed array to the output stream. + * This method is equivalent to write(buf, 0, buf.length) which + * is exactly how it is implemented in this class. + * + * @param buf The array of char to write + * + * @exception IOException If an error occurs + */ +public void +write(char[] buf) throws IOException +{ + write(buf, 0, buf.length); +} + +/*************************************************************************/ + +/** + * This method writes len char from the specified array + * buf starting at index offset into the array. + *

+ * Subclasses must provide an implementation of this abstract method. + * + * @param buf The array of char to write from + * @param offset The index into the array to start writing from + * @param len The number of char to write + * + * @exception IOException If an error occurs + */ +public abstract void +write(char[] buf, int offset, int len) throws IOException; + +/*************************************************************************/ + +/** + * This method writes all the characters in a String to the + * output. + * + * @param str The String whose chars are to be written. + * + * @param IOException If an error occurs + */ +public void +write(String str) throws IOException +{ + write(str, 0, str.length()); +} + +/*************************************************************************/ + +/** + * This method writes len chars from the String + * starting at position offset. + * + * @param str The String that is to be written + * @param offset The character offset into the String to start + * writing from + * @param len The number of chars to write + * + * @exception IOException If an error occurs + */ +public void +write(String str, int offset, int len) throws IOException +{ + // FIXME - for libgcj re-write using native code to not require copied buffer. + char[] buf = new char[len]; + + str.getChars(offset, offset + len, buf, 0); + write(buf, 0, len); +} + +} // class Writer -- cgit v1.1