1. /*
  2. * @(#)Writer.java 1.21 03/01/23
  3. *
  4. * Copyright 2003 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.21, 03/01/23
  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. * @param lock Object to synchronize on.
  58. */
  59. protected Writer(Object lock) {
  60. if (lock == null) {
  61. throw new NullPointerException();
  62. }
  63. this.lock = lock;
  64. }
  65. /**
  66. * Write a single character. The character to be written is contained in
  67. * the 16 low-order bits of the given integer value; the 16 high-order bits
  68. * are ignored.
  69. *
  70. * <p> Subclasses that intend to support efficient single-character output
  71. * should override this method.
  72. *
  73. * @param c int specifying a character to be written.
  74. * @exception IOException If an I/O error occurs
  75. */
  76. public void write(int c) throws IOException {
  77. synchronized (lock) {
  78. if (writeBuffer == null){
  79. writeBuffer = new char[writeBufferSize];
  80. }
  81. writeBuffer[0] = (char) c;
  82. write(writeBuffer, 0, 1);
  83. }
  84. }
  85. /**
  86. * Write an array of characters.
  87. *
  88. * @param cbuf Array of characters to be written
  89. *
  90. * @exception IOException If an I/O error occurs
  91. */
  92. public void write(char cbuf[]) throws IOException {
  93. write(cbuf, 0, cbuf.length);
  94. }
  95. /**
  96. * Write a portion of an array of characters.
  97. *
  98. * @param cbuf Array of characters
  99. * @param off Offset from which to start writing characters
  100. * @param len Number of characters to write
  101. *
  102. * @exception IOException If an I/O error occurs
  103. */
  104. abstract public void write(char cbuf[], int off, int len) throws IOException;
  105. /**
  106. * Write a string.
  107. *
  108. * @param str String to be written
  109. *
  110. * @exception IOException If an I/O error occurs
  111. */
  112. public void write(String str) throws IOException {
  113. write(str, 0, str.length());
  114. }
  115. /**
  116. * Write a portion of a string.
  117. *
  118. * @param str A String
  119. * @param off Offset from which to start writing characters
  120. * @param len Number of characters to write
  121. *
  122. * @exception IOException If an I/O error occurs
  123. */
  124. public void write(String str, int off, int len) throws IOException {
  125. synchronized (lock) {
  126. char cbuf[];
  127. if (len <= writeBufferSize) {
  128. if (writeBuffer == null) {
  129. writeBuffer = new char[writeBufferSize];
  130. }
  131. cbuf = writeBuffer;
  132. } else { // Don't permanently allocate very large buffers.
  133. cbuf = new char[len];
  134. }
  135. str.getChars(off, (off + len), cbuf, 0);
  136. write(cbuf, 0, len);
  137. }
  138. }
  139. /**
  140. * Flush the stream. If the stream has saved any characters from the
  141. * various write() methods in a buffer, write them immediately to their
  142. * intended destination. Then, if that destination is another character or
  143. * byte stream, flush it. Thus one flush() invocation will flush all the
  144. * buffers in a chain of Writers and OutputStreams.
  145. *
  146. * @exception IOException If an I/O error occurs
  147. */
  148. abstract public void flush() throws IOException;
  149. /**
  150. * Close the stream, flushing it first. Once a stream has been closed,
  151. * further write() or flush() invocations will cause an IOException to be
  152. * thrown. Closing a previously-closed stream, however, has no effect.
  153. *
  154. * @exception IOException If an I/O error occurs
  155. */
  156. abstract public void close() throws IOException;
  157. }