001: /*
002: * Copyright 2000,2005 wingS development team.
003: *
004: * This file is part of wingS (http://wingsframework.org).
005: *
006: * wingS is free software; you can redistribute it and/or modify
007: * it under the terms of the GNU Lesser General Public License
008: * as published by the Free Software Foundation; either version 2.1
009: * of the License, or (at your option) any later version.
010: *
011: * Please see COPYING for the complete licence.
012: */
013: package org.wings.io;
014:
015: import java.io.IOException;
016:
017: /**
018: * A general interface for a Output-Device.
019: * A Device is the destination, where the HTML-code is written to. This is
020: * like the 'Graphics' - device in GUI applications.
021: * <p/>
022: * <p>All the printing methods return the Device itself, to allow simple
023: * chaining:
024: * <hr /><pre>
025: * someDevice.print("foo").print("bar");
026: * </pre><hr />
027: * <p/>
028: * <p>Usually, the underlying data sink of a Device would be some OutputStream,
029: * as it finally writes through some socket to the client browser.
030: * The Device, however, offers basically two methods for writing to the
031: * output: with print() and write() like methods. The print() like
032: * methods get character input that has to be converted to a byte-stream
033: * before it actually can be written to the underlying OutputStream, while
034: * the write() like methods directly handle arrays of bytes to do this. So
035: * if possible, try to always use the write() methods, if you can
036: * pre-calculate the byte-representation of the output (if you have some
037: * static Strings, for instance, consider using String.getBytes()).
038: *
039: * @author <a href="mailto:H.Zeller@acm.org">Henner Zeller</a>
040: */
041: public interface Device {
042: /**
043: * Flush this Device.
044: */
045: void flush() throws IOException;
046:
047: /**
048: * close the Device.
049: */
050: void close() throws IOException;
051:
052: /**
053: * returns, whether this the size of data put into this device is
054: * the same as comes out. This is necessary to know if we want to send the
055: * content size: if we know the content size, but this device changes
056: * the size, we must not send it.
057: *
058: * @return 'true', if this device leaves the size of the data going through
059: * it, untouched. This is usually true.
060: */
061: boolean isSizePreserving();
062:
063: // ------------*
064: // Methods which deal with characers using the platform's
065: // default character encoding to convert characters into bytes.
066: // much like a PrintWriter
067: // ------------*/
068:
069: // -- print basic characters --
070:
071: /**
072: * Print a character.
073: */
074: Device print(char c) throws IOException;
075:
076: /**
077: * Print a character array.
078: */
079: Device print(char[] c) throws IOException;
080:
081: /**
082: * Print len characters from the specified char array starting at offset
083: * off to this Device.
084: */
085: Device print(char[] c, int start, int len) throws IOException;
086:
087: //-- print basic objects --
088:
089: /**
090: * Print a String.
091: */
092: Device print(String s) throws IOException;
093:
094: /**
095: * Print an integer.
096: */
097: Device print(int i) throws IOException;
098:
099: /**
100: * Print any Object
101: */
102: Device print(Object o) throws IOException;
103:
104: /*-------------*
105: ** Methods which write raw bytes to the Device. Much like an OutputStream.
106: **-------------*/
107:
108: /**
109: * Writes the specified byte to this data output stream.
110: */
111: Device write(int c) throws IOException;
112:
113: /**
114: * Writes b.length bytes from the specified byte array to this
115: * output stream.
116: */
117: Device write(byte b[]) throws IOException;
118:
119: /**
120: * Writes len bytes from the specified byte array starting at offset
121: * off to this Device.
122: */
123: Device write(byte b[], int off, int len) throws IOException;
124: }
|