001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * Portions Copyright Apache Software Foundation.
007: *
008: * The contents of this file are subject to the terms of either the GNU
009: * General Public License Version 2 only ("GPL") or the Common Development
010: * and Distribution License("CDDL") (collectively, the "License"). You
011: * may not use this file except in compliance with the License. You can obtain
012: * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
013: * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
014: * language governing permissions and limitations under the License.
015: *
016: * When distributing the software, include this License Header Notice in each
017: * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
018: * Sun designates this particular file as subject to the "Classpath" exception
019: * as provided by Sun in the GPL Version 2 section of the License file that
020: * accompanied this code. If applicable, add the following below the License
021: * Header, with the fields enclosed by brackets [] replaced by your own
022: * identifying information: "Portions Copyrighted [year]
023: * [name of copyright owner]"
024: *
025: * Contributor(s):
026: *
027: * If you wish your version of this file to be governed by only the CDDL or
028: * only the GPL Version 2, indicate your decision by adding "[Contributor]
029: * elects to include this software in this distribution under the [CDDL or GPL
030: * Version 2] license." If you don't indicate a single choice of license, a
031: * recipient has the option to distribute your version of this file under
032: * either the CDDL, the GPL Version 2 or to extend the choice of license to
033: * its licensees as provided above. However, if you add GPL Version 2 code
034: * and therefore, elected the GPL Version 2 license, then the option applies
035: * only if the new code is made subject to such option by the copyright
036: * holder.
037: */
038:
039: package javax.servlet.jsp;
040:
041: import java.io.IOException;
042:
043: /**
044: * <p>
045: * The actions and template data in a JSP page is written using the
046: * JspWriter object that is referenced by the implicit variable out which
047: * is initialized automatically using methods in the PageContext object.
048: *<p>
049: * This abstract class emulates some of the functionality found in the
050: * java.io.BufferedWriter and java.io.PrintWriter classes,
051: * however it differs in that it throws java.io.IOException from the print
052: * methods while PrintWriter does not.
053: * <p><B>Buffering</B>
054: * <p>
055: * The initial JspWriter object is associated with the PrintWriter object
056: * of the ServletResponse in a way that depends on whether the page is or
057: * is not buffered. If the page is not buffered, output written to this
058: * JspWriter object will be written through to the PrintWriter directly,
059: * which will be created if necessary by invoking the getWriter() method
060: * on the response object. But if the page is buffered, the PrintWriter
061: * object will not be created until the buffer is flushed and
062: * operations like setContentType() are legal. Since this flexibility
063: * simplifies programming substantially, buffering is the default for JSP
064: * pages.
065: * <p>
066: * Buffering raises the issue of what to do when the buffer is
067: * exceeded. Two approaches can be taken:
068: * <ul>
069: * <li>
070: * Exceeding the buffer is not a fatal error; when the buffer is
071: * exceeded, just flush the output.
072: * <li>
073: * Exceeding the buffer is a fatal error; when the buffer is exceeded,
074: * raise an exception.
075: * </ul>
076: * <p>
077: * Both approaches are valid, and thus both are supported in the JSP
078: * technology. The behavior of a page is controlled by the autoFlush
079: * attribute, which defaults to true. In general, JSP pages that need to
080: * be sure that correct and complete data has been sent to their client
081: * may want to set autoFlush to false, with a typical case being that
082: * where the client is an application itself. On the other hand, JSP
083: * pages that send data that is meaningful even when partially
084: * constructed may want to set autoFlush to true; such as when the
085: * data is sent for immediate display through a browser. Each application
086: * will need to consider their specific needs.
087: * <p>
088: * An alternative considered was to make the buffer size unbounded; but,
089: * this had the disadvantage that runaway computations would consume an
090: * unbounded amount of resources.
091: * <p>
092: * The "out" implicit variable of a JSP implementation class is of this type.
093: * If the page directive selects autoflush="true" then all the I/O operations
094: * on this class shall automatically flush the contents of the buffer if an
095: * overflow condition would result if the current operation were performed
096: * without a flush. If autoflush="false" then all the I/O operations on this
097: * class shall throw an IOException if performing the current operation would
098: * result in a buffer overflow condition.
099: *
100: * @see java.io.Writer
101: * @see java.io.BufferedWriter
102: * @see java.io.PrintWriter
103: */
104:
105: abstract public class JspWriter extends java.io.Writer {
106:
107: /**
108: * Constant indicating that the Writer is not buffering output.
109: */
110:
111: public static final int NO_BUFFER = 0;
112:
113: /**
114: * Constant indicating that the Writer is buffered and is using the
115: * implementation default buffer size.
116: */
117:
118: public static final int DEFAULT_BUFFER = -1;
119:
120: /**
121: * Constant indicating that the Writer is buffered and is unbounded; this
122: * is used in BodyContent.
123: */
124:
125: public static final int UNBOUNDED_BUFFER = -2;
126:
127: /**
128: * Protected constructor.
129: *
130: * @param bufferSize the size of the buffer to be used by the JspWriter
131: * @param autoFlush whether the JspWriter should be autoflushing
132: */
133:
134: protected JspWriter(int bufferSize, boolean autoFlush) {
135: this .bufferSize = bufferSize;
136: this .autoFlush = autoFlush;
137: }
138:
139: /**
140: * Write a line separator. The line separator string is defined by the
141: * system property <tt>line.separator</tt>, and is not necessarily a single
142: * newline ('\n') character.
143: *
144: * @exception IOException If an I/O error occurs
145: */
146:
147: abstract public void newLine() throws IOException;
148:
149: /**
150: * Print a boolean value. The string produced by <code>{@link
151: * java.lang.String#valueOf(boolean)}</code> is written to the
152: * JspWriter's buffer or, if no buffer is used, directly to the
153: * underlying writer.
154: *
155: * @param b The <code>boolean</code> to be printed
156: * @throws java.io.IOException If an error occured while writing
157: */
158:
159: abstract public void print(boolean b) throws IOException;
160:
161: /**
162: * Print a character. The character is written to the
163: * JspWriter's buffer or, if no buffer is used, directly to the
164: * underlying writer.
165: *
166: * @param c The <code>char</code> to be printed
167: * @throws java.io.IOException If an error occured while writing
168: */
169:
170: abstract public void print(char c) throws IOException;
171:
172: /**
173: * Print an integer. The string produced by <code>{@link
174: * java.lang.String#valueOf(int)}</code> is written to the
175: * JspWriter's buffer or, if no buffer is used, directly to the
176: * underlying writer.
177: *
178: * @param i The <code>int</code> to be printed
179: * @see java.lang.Integer#toString(int)
180: * @throws java.io.IOException If an error occured while writing
181: */
182:
183: abstract public void print(int i) throws IOException;
184:
185: /**
186: * Print a long integer. The string produced by <code>{@link
187: * java.lang.String#valueOf(long)}</code> is written to the
188: * JspWriter's buffer or, if no buffer is used, directly to the
189: * underlying writer.
190: *
191: * @param l The <code>long</code> to be printed
192: * @see java.lang.Long#toString(long)
193: * @throws java.io.IOException If an error occured while writing
194: */
195:
196: abstract public void print(long l) throws IOException;
197:
198: /**
199: * Print a floating-point number. The string produced by <code>{@link
200: * java.lang.String#valueOf(float)}</code> is written to the
201: * JspWriter's buffer or, if no buffer is used, directly to the
202: * underlying writer.
203: *
204: * @param f The <code>float</code> to be printed
205: * @see java.lang.Float#toString(float)
206: * @throws java.io.IOException If an error occured while writing
207: */
208:
209: abstract public void print(float f) throws IOException;
210:
211: /**
212: * Print a double-precision floating-point number. The string produced by
213: * <code>{@link java.lang.String#valueOf(double)}</code> is written to
214: * the JspWriter's buffer or, if no buffer is used, directly to the
215: * underlying writer.
216: *
217: * @param d The <code>double</code> to be printed
218: * @see java.lang.Double#toString(double)
219: * @throws java.io.IOException If an error occured while writing
220: */
221:
222: abstract public void print(double d) throws IOException;
223:
224: /**
225: * Print an array of characters. The characters are written to the
226: * JspWriter's buffer or, if no buffer is used, directly to the
227: * underlying writer.
228: *
229: * @param s The array of chars to be printed
230: *
231: * @throws NullPointerException If <code>s</code> is <code>null</code>
232: * @throws java.io.IOException If an error occured while writing
233: */
234:
235: abstract public void print(char s[]) throws IOException;
236:
237: /**
238: * Print a string. If the argument is <code>null</code> then the string
239: * <code>"null"</code> is printed. Otherwise, the string's characters are
240: * written to the JspWriter's buffer or, if no buffer is used, directly
241: * to the underlying writer.
242: *
243: * @param s The <code>String</code> to be printed
244: * @throws java.io.IOException If an error occured while writing
245: */
246:
247: abstract public void print(String s) throws IOException;
248:
249: /**
250: * Print an object. The string produced by the <code>{@link
251: * java.lang.String#valueOf(Object)}</code> method is written to the
252: * JspWriter's buffer or, if no buffer is used, directly to the
253: * underlying writer.
254: *
255: * @param obj The <code>Object</code> to be printed
256: * @see java.lang.Object#toString()
257: * @throws java.io.IOException If an error occured while writing
258: */
259:
260: abstract public void print(Object obj) throws IOException;
261:
262: /**
263: * Terminate the current line by writing the line separator string. The
264: * line separator string is defined by the system property
265: * <code>line.separator</code>, and is not necessarily a single newline
266: * character (<code>'\n'</code>).
267: * @throws java.io.IOException If an error occured while writing
268: */
269:
270: abstract public void println() throws IOException;
271:
272: /**
273: * Print a boolean value and then terminate the line. This method behaves
274: * as though it invokes <code>{@link #print(boolean)}</code> and then
275: * <code>{@link #println()}</code>.
276: *
277: * @param x the boolean to write
278: * @throws java.io.IOException If an error occured while writing
279: */
280:
281: abstract public void println(boolean x) throws IOException;
282:
283: /**
284: * Print a character and then terminate the line. This method behaves as
285: * though it invokes <code>{@link #print(char)}</code> and then <code>{@link
286: * #println()}</code>.
287: *
288: * @param x the char to write
289: * @throws java.io.IOException If an error occured while writing
290: */
291:
292: abstract public void println(char x) throws IOException;
293:
294: /**
295: * Print an integer and then terminate the line. This method behaves as
296: * though it invokes <code>{@link #print(int)}</code> and then <code>{@link
297: * #println()}</code>.
298: *
299: * @param x the int to write
300: * @throws java.io.IOException If an error occured while writing
301: */
302:
303: abstract public void println(int x) throws IOException;
304:
305: /**
306: * Print a long integer and then terminate the line. This method behaves
307: * as though it invokes <code>{@link #print(long)}</code> and then
308: * <code>{@link #println()}</code>.
309: *
310: * @param x the long to write
311: * @throws java.io.IOException If an error occured while writing
312: */
313:
314: abstract public void println(long x) throws IOException;
315:
316: /**
317: * Print a floating-point number and then terminate the line. This method
318: * behaves as though it invokes <code>{@link #print(float)}</code> and then
319: * <code>{@link #println()}</code>.
320: *
321: * @param x the float to write
322: * @throws java.io.IOException If an error occured while writing
323: */
324:
325: abstract public void println(float x) throws IOException;
326:
327: /**
328: * Print a double-precision floating-point number and then terminate the
329: * line. This method behaves as though it invokes <code>{@link
330: * #print(double)}</code> and then <code>{@link #println()}</code>.
331: *
332: * @param x the double to write
333: * @throws java.io.IOException If an error occured while writing
334: */
335:
336: abstract public void println(double x) throws IOException;
337:
338: /**
339: * Print an array of characters and then terminate the line. This method
340: * behaves as though it invokes <code>print(char[])</code> and then
341: * <code>println()</code>.
342: *
343: * @param x the char[] to write
344: * @throws java.io.IOException If an error occured while writing
345: */
346:
347: abstract public void println(char x[]) throws IOException;
348:
349: /**
350: * Print a String and then terminate the line. This method behaves as
351: * though it invokes <code>{@link #print(String)}</code> and then
352: * <code>{@link #println()}</code>.
353: *
354: * @param x the String to write
355: * @throws java.io.IOException If an error occured while writing
356: */
357:
358: abstract public void println(String x) throws IOException;
359:
360: /**
361: * Print an Object and then terminate the line. This method behaves as
362: * though it invokes <code>{@link #print(Object)}</code> and then
363: * <code>{@link #println()}</code>.
364: *
365: * @param x the Object to write
366: * @throws java.io.IOException If an error occured while writing
367: */
368:
369: abstract public void println(Object x) throws IOException;
370:
371: /**
372: * Clear the contents of the buffer. If the buffer has been already
373: * been flushed then the clear operation shall throw an IOException
374: * to signal the fact that some data has already been irrevocably
375: * written to the client response stream.
376: *
377: * @throws IOException If an I/O error occurs
378: */
379:
380: abstract public void clear() throws IOException;
381:
382: /**
383: * Clears the current contents of the buffer. Unlike clear(), this
384: * method will not throw an IOException if the buffer has already been
385: * flushed. It merely clears the current content of the buffer and
386: * returns.
387: *
388: * @throws IOException If an I/O error occurs
389: */
390:
391: abstract public void clearBuffer() throws IOException;
392:
393: /**
394: * Flush the stream. If the stream has saved any characters from the
395: * various write() methods in a buffer, write them immediately to their
396: * intended destination. Then, if that destination is another character or
397: * byte stream, flush it. Thus one flush() invocation will flush all the
398: * buffers in a chain of Writers and OutputStreams.
399: * <p>
400: * The method may be invoked indirectly if the buffer size is exceeded.
401: * <p>
402: * Once a stream has been closed,
403: * further write() or flush() invocations will cause an IOException to be
404: * thrown.
405: *
406: * @exception IOException If an I/O error occurs
407: */
408:
409: abstract public void flush() throws IOException;
410:
411: /**
412: * Close the stream, flushing it first.
413: * <p>
414: * This method needs not be invoked explicitly for the initial JspWriter
415: * as the code generated by the JSP container will automatically
416: * include a call to close().
417: * <p>
418: * Closing a previously-closed stream, unlike flush(), has no effect.
419: *
420: * @exception IOException If an I/O error occurs
421: */
422:
423: abstract public void close() throws IOException;
424:
425: /**
426: * This method returns the size of the buffer used by the JspWriter.
427: *
428: * @return the size of the buffer in bytes, or 0 is unbuffered.
429: */
430:
431: public int getBufferSize() {
432: return bufferSize;
433: }
434:
435: /**
436: * This method returns the number of unused bytes in the buffer.
437: *
438: * @return the number of bytes unused in the buffer
439: */
440:
441: abstract public int getRemaining();
442:
443: /**
444: * This method indicates whether the JspWriter is autoFlushing.
445: *
446: * @return if this JspWriter is auto flushing or throwing IOExceptions
447: * on buffer overflow conditions
448: */
449:
450: public boolean isAutoFlush() {
451: return autoFlush;
452: }
453:
454: /*
455: * fields
456: */
457:
458: /**
459: * The size of the buffer used by the JspWriter.
460: */
461: protected int bufferSize;
462:
463: /**
464: * Whether the JspWriter is autoflushing.
465: */
466: protected boolean autoFlush;
467: }
|