Device


1   /*
2    * $Id: Device.java,v 1.3 2004/12/01 07:54:08 hengels Exp $
3    * Copyright 2000,2005 wingS development team.
4    *
5    * This file is part of wingS (http://www.j-wings.org).
6    *
7    * wingS is free software; you can redistribute it and/or modify
8    * it under the terms of the GNU Lesser General Public License
9    * as published by the Free Software Foundation; either version 2.1
10   * of the License, or (at your option) any later version.
11   *
12   * Please see COPYING for the complete licence.
13   */
14  package org.wings.io;
15  
16  import java.io.IOException  ;
17  
18  /**
19   * A general interface for a Output-Device.
20   * A Device is the destination, where the HTML-code is written to. This is
21   * like the 'Graphics' - device in GUI applications.
22   * <p/>
23   * <p>All the printing methods return the Device itself, to allow simple
24   * chaining:
25   * <hr /><pre>
26   *    someDevice.print("foo").print("bar");
27   * </pre><hr />
28   * <p/>
29   * <p>Usually, the underlying data sink of a Device would be some OutputStream,
30   * as it finally writes through some socket to the client browser.
31   * The Device, however, offers basically two methods for writing to the
32   * output: with print() and write() like methods. The print() like
33   * methods get character input that has to be converted to a byte-stream
34   * before it actually can be written to the underlying OutputStream, while
35   * the write() like methods directly handle arrays of bytes to do this. So
36   * if possible, try to always use the write() methods, if you can
37   * pre-calculate the byte-representation of the output (if you have some
38   * static Strings, for instance, consider using String.getBytes()).
39   *
40   * @author <a HREF="mailto:H.Zeller@acm.org">Henner Zeller</a>
41   * @version $Revision: 1.3 $
42   */
43  public interface Device {
44      /**
45       * Flush this Device.
46       */
47      void flush() throws IOException  ;
48  
49      /**
50       * close the Device.
51       */
52      void close() throws IOException  ;
53  
54      /**
55       * returns, whether this the size of data put into this device is
56       * the same as comes out. This is necessary to know if we want to send the
57       * content size: if we know the content size, but this device changes
58       * the size, we must not send it.
59       *
60       * @return 'true', if this device leaves the size of the data going through
61       *         it, untouched. This is usually true.
62       */
63      boolean isSizePreserving();
64  
65      // ------------*
66      // Methods which deal with characers using the platform's
67      // default character encoding to convert characters into bytes.
68      // much like a PrintWriter
69      // ------------*/
70      
71      // -- print basic characters --
72  
73      /**
74       * Print a character.
75       */
76      Device print(char c) throws IOException  ;
77  
78      /**
79       * Print a character array.
80       */
81      Device print(char[] c) throws IOException  ;
82  
83      /**
84       * Print len characters from the specified char array starting at offset
85       * off to this Device.
86       */
87      Device print(char[] c, int start, int len) throws IOException  ;
88  
89      //-- print basic objects --
90  
91      /**
92       * Print a String.
93       */
94      Device print(String   s) throws IOException  ;
95  
96      /**
97       * Print an integer.
98       */
99      Device print(int i) throws IOException  ;
100 
101     /**
102      * Print any Object
103      */
104     Device print(Object   o) throws IOException  ;
105 
106     /*-------------*
107      ** Methods which write raw bytes to the Device. Much like an OutputStream.
108      **-------------*/
109 
110     /**
111      * Writes the specified byte to this data output stream.
112      */
113     Device write(int c) throws IOException  ;
114 
115     /**
116      * Writes b.length bytes from the specified byte array to this
117      * output stream.
118      */
119     Device write(byte b[]) throws IOException  ;
120 
121     /**
122      * Writes len bytes from the specified byte array starting at offset
123      * off to this Device.
124      */
125     Device write(byte b[], int off, int len) throws IOException  ;
126 }
127 
128 
129
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags