1. /*
  2. * @(#)Writer.java 1.17 01/11/29
  3. *
  4. * Copyright 2002 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.io;
  8. /**
  9. * Abstract class for writing to character streams. The only methods that a
  10. * subclass must implement are write(char[], int, int), flush(), and close().
  11. * Most subclasses, however, will override some of the methods defined here in
  12. * order to provide higher efficiency, additional functionality, or both.
  13. *
  14. * @see Writer
  15. * @see BufferedWriter
  16. * @see CharArrayWriter
  17. * @see FilterWriter
  18. * @see OutputStreamWriter
  19. * @see FileWriter
  20. * @see PipedWriter
  21. * @see PrintWriter
  22. * @see StringWriter
  23. * @see Reader
  24. *
  25. * @version 1.17, 01/11/29
  26. * @author Mark Reinhold
  27. * @since JDK1.1
  28. */
  29. public abstract class Writer {
  30. /**
  31. * Temporary buffer used to hold writes of strings and single characters
  32. */
  33. private char[] writeBuffer;
  34. /**
  35. * Size of writeBuffer, must be >= 1
  36. */
  37. private final int writeBufferSize = 1024;
  38. /**
  39. * The object used to synchronize operations on this stream. For
  40. * efficiency, a character-stream object may use an object other than
  41. * itself to protect critical sections. A subclass should therefore use
  42. * the object in this field rather than <tt>this</tt> or a synchronized
  43. * method.
  44. */
  45. protected Object lock;
  46. /**
  47. * Create a new character-stream writer whose critical sections will
  48. * synchronize on the writer itself.
  49. */
  50. protected Writer() {
  51. this.lock = this;
  52. }
  53. /**
  54. * Create a new character-stream writer whose critical sections will
  55. * synchronize on the given object.
  56. */
  57. protected Writer(Object lock) {
  58. if (lock == null) {
  59. throw new NullPointerException();
  60. }
  61. this.lock = lock;
  62. }
  63. /**
  64. * Write a single character. The character to be written is contained in
  65. * the 16 low-order bits of the given integer value; the 16 high-order bits
  66. * are ignored.
  67. *
  68. * <p> Subclasses that intend to support efficient single-character output
  69. * should override this method.
  70. *
  71. * @exception IOException If an I/O error occurs
  72. */
  73. public void write(int c) throws IOException {
  74. synchronized (lock) {
  75. if (writeBuffer == null){
  76. writeBuffer = new char[writeBufferSize];
  77. }
  78. writeBuffer[0] = (char) c;
  79. write(writeBuffer, 0, 1);
  80. }
  81. }
  82. /**
  83. * Write an array of characters.
  84. *
  85. * @param cbuf Array of characters to be written
  86. *
  87. * @exception IOException If an I/O error occurs
  88. */
  89. public void write(char cbuf[]) throws IOException {
  90. write(cbuf, 0, cbuf.length);
  91. }
  92. /**
  93. * Write a portion of an array of characters.
  94. *
  95. * @param cbuf Array of characters
  96. * @param off Offset from which to start writing characters
  97. * @param len Number of characters to write
  98. *
  99. * @exception IOException If an I/O error occurs
  100. */
  101. abstract public void write(char cbuf[], int off, int len) throws IOException;
  102. /**
  103. * Write a string.
  104. *
  105. * @param str String to be written
  106. *
  107. * @exception IOException If an I/O error occurs
  108. */
  109. public void write(String str) throws IOException {
  110. write(str, 0, str.length());
  111. }
  112. /**
  113. * Write a portion of a string.
  114. *
  115. * @param str A String
  116. * @param off Offset from which to start writing characters
  117. * @param len Number of characters to write
  118. *
  119. * @exception IOException If an I/O error occurs
  120. */
  121. public void write(String str, int off, int len) throws IOException {
  122. synchronized (lock) {
  123. char cbuf[];
  124. if (len <= writeBufferSize) {
  125. if (writeBuffer == null) {
  126. writeBuffer = new char[writeBufferSize];
  127. }
  128. cbuf = writeBuffer;
  129. } else { // Don't permanently allocate very large buffers.
  130. cbuf = new char[len];
  131. }
  132. str.getChars(off, (off + len), cbuf, 0);
  133. write(cbuf, 0, len);
  134. }
  135. }
  136. /**
  137. * Flush the stream. If the stream has saved any characters from the
  138. * various write() methods in a buffer, write them immediately to their
  139. * intended destination. Then, if that destination is another character or
  140. * byte stream, flush it. Thus one flush() invocation will flush all the
  141. * buffers in a chain of Writers and OutputStreams.
  142. *
  143. * @exception IOException If an I/O error occurs
  144. */
  145. abstract public void flush() throws IOException;
  146. /**
  147. * Close the stream, flushing it first. Once a stream has been closed,
  148. * further write() or flush() invocations will cause an IOException to be
  149. * thrown. Closing a previously-closed stream, however, has no effect.
  150. *
  151. * @exception IOException If an I/O error occurs
  152. */
  153. abstract public void close() throws IOException;
  154. }