IOConsole


1   /*******************************************************************************
2    * Copyright (c) 2000, 2007 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  
12  package org.eclipse.ui.console;
13  
14  import java.io.IOException  ;
15  import java.util.ArrayList  ;
16  import java.util.List  ;
17  
18  import org.eclipse.jface.resource.ImageDescriptor;
19  import org.eclipse.ui.WorkbenchEncoding;
20  import org.eclipse.ui.internal.console.IOConsolePage;
21  import org.eclipse.ui.internal.console.IOConsolePartitioner;
22  import org.eclipse.ui.part.IPageBookViewPage;
23  
24  /**
25   * A console that displays text from I/O streams. An I/O console can have multiple
26   * output streams connected to it and provides one input stream connected to the
27   * keyboard.
28   * <p>
29   * Clients may instantiate and subclass this class.
30   * </p>
31   * @since 3.1
32   */
33  public class IOConsole extends TextConsole {
34      /**
35       * The document partitioner
36       */
37      private IOConsolePartitioner partitioner;
38      
39      /**
40       * The stream from which user input may be read
41       */
42      private IOConsoleInputStream inputStream;
43          
44      /**
45       * A collection of open streams connected to this console.
46       */
47      private List   openStreams;
48  
49      /**
50       * The encoding used to for displaying console output.
51       */
52      private String   fEncoding = WorkbenchEncoding.getWorkbenchDefaultEncoding();
53  
54      
55      /**
56       * Constructs a console with the given name, type, image, and lifecycle, with the
57       * workbench's default encoding.
58       * 
59       * @param name name to display for this console
60       * @param consoleType console type identifier or <code>null</code>
61       * @param imageDescriptor image to display for this console or <code>null</code>
62       * @param autoLifecycle whether lifecycle methods should be called automatically
63       *  when this console is added/removed from the console manager
64       */
65      public IOConsole(String   name, String   consoleType, ImageDescriptor imageDescriptor, boolean autoLifecycle) {
66          this(name, consoleType, imageDescriptor, null, autoLifecycle);
67      }
68  
69      /**
70       * Constructs a console with the given name, type, image, encoding and lifecycle.
71       * 
72       * @param name name to display for this console
73       * @param consoleType console type identifier or <code>null</code>
74       * @param imageDescriptor image to display for this console or <code>null</code>
75       * @param autoLifecycle whether lifecycle methods should be called automatically
76       *  when this console is added/removed from the console manager
77       */
78      public IOConsole(String   name, String   consoleType, ImageDescriptor imageDescriptor, String   encoding, boolean autoLifecycle) {
79          super(name, consoleType, imageDescriptor, autoLifecycle);
80          if (encoding != null) {
81              fEncoding = encoding;
82          }
83          openStreams = new ArrayList  ();
84          inputStream = new IOConsoleInputStream(this);
85          synchronized (openStreams) {
86              openStreams.add(inputStream);   
87          }
88          
89          partitioner = new IOConsolePartitioner(inputStream, this);
90          partitioner.connect(getDocument());
91      }
92      
93      /**
94       * Constructs a console with the given name, type, and image with the workbench's
95       * default encoding. Lifecycle methods will be called when this console is
96       * added/removed from the console manager.
97       * 
98       * @param name name to display for this console
99       * @param consoleType console type identifier or <code>null</code>
100      * @param imageDescriptor image to display for this console or <code>null</code>
101      */
102     public IOConsole(String   name, String   consoleType, ImageDescriptor imageDescriptor) {
103         this(name, consoleType, imageDescriptor, true);
104     }    
105     
106     /**
107      * Constructs a console with the given name and image. Lifecycle methods
108      * will be called when this console is added/removed from the console manager.
109      * This console will have an unspecified (<code>null</code>) type.
110      * 
111      * @param name name to display for this console
112      * @param imageDescriptor image to display for this console or <code>null</code>
113      */
114     public IOConsole(String   name, ImageDescriptor imageDescriptor) {
115         this(name, null, imageDescriptor);
116     }
117     
118     /* (non-Javadoc)
119      * @see org.eclipse.ui.console.IConsole#createPage(org.eclipse.ui.console.IConsoleView)
120      */
121     public IPageBookViewPage createPage(IConsoleView view) {
122         return new IOConsolePage(this, view);
123     }
124     
125     /**
126      * Creates and returns a new output stream which may be used to write to this console.
127      * A console may be connected to more than one output stream at once. Clients are
128      * responsible for closing any output streams created on this console.
129      * <p>
130      * Clients should avoid writing large amounts of output to this stream in the UI
131      * thread. The console needs to process the output in the UI thread and if the client
132      * hogs the UI thread writing output to the console, the console will not be able
133      * to process the output.
134      * </p>
135      * @return a new output stream connected to this console
136      */
137     public IOConsoleOutputStream newOutputStream() {
138         IOConsoleOutputStream outputStream = new IOConsoleOutputStream(this);
139         outputStream.setEncoding(fEncoding);
140         synchronized(openStreams) {
141             openStreams.add(outputStream);
142         }
143         return outputStream;
144     }
145     
146     /**
147      * Returns the input stream connected to the keyboard.
148      * 
149      * @return the input stream connected to the keyboard.
150      */
151     public IOConsoleInputStream getInputStream() {
152         return inputStream;
153     }
154 
155     /**
156      * Returns this console's document partitioner.
157      * 
158      * @return this console's document partitioner
159      */
160     protected IConsoleDocumentPartitioner getPartitioner() {
161         return partitioner;
162     }
163 
164     /**
165      * Returns the maximum number of characters that the console will display at
166      * once. This is analogous to the size of the text buffer this console
167      * maintains.
168      * 
169      * @return the maximum number of characters that the console will display
170      */
171     public int getHighWaterMark() {
172         return partitioner.getHighWaterMark();
173     }
174     
175     /**
176      * Returns the number of characters that will remain in this console
177      * when its high water mark is exceeded.
178      *  
179      * @return the number of characters that will remain in this console
180      *  when its high water mark is exceeded
181      */
182     public int getLowWaterMark() {
183         return partitioner.getLowWaterMark();
184     }
185     
186     /**
187      * Sets the text buffer size for this console. The high water mark indicates
188      * the maximum number of characters stored in the buffer. The low water mark
189      * indicates the number of characters remaining in the buffer when the high
190      * water mark is exceeded.
191      * 
192      * @param low the number of characters remaining in the buffer when the high
193      *  water mark is exceeded (if -1 the console does not limit output)
194      * @param high the maximum number of characters this console will cache in
195      *  its text buffer (if -1 the console does not limit output)
196      * @exception IllegalArgumentException if low >= high & low != -1
197      */
198     public void setWaterMarks(int low, int high) {
199         if (low >= 0) {
200             if (low >= high) {
201                 throw new IllegalArgumentException  ("High water mark must be greater than low water mark"); //$NON-NLS-1$
202             }
203         }
204         partitioner.setWaterMarks(low, high);
205     }
206 
207     /**
208      * Check if all streams connected to this console are closed. If so,
209      * notify the partitioner that this console is finished. 
210      */
211     private void checkFinished() {
212         if (openStreams.isEmpty()) {
213             partitioner.streamsClosed();
214         }
215     }
216     
217     /**
218      * Notification that an output stream connected to this console has been closed.
219      * 
220      * @param stream stream that closed
221      */
222     void streamClosed(IOConsoleOutputStream stream) {
223         synchronized (openStreams) {
224             openStreams.remove(stream);
225             checkFinished();
226         }
227     }
228     
229     /**
230      * Notification that the input stream connected to this console has been closed.
231      * 
232      * @param stream stream that closed
233      */
234     void streamClosed(IOConsoleInputStream stream) {
235         synchronized (openStreams) {
236             openStreams.remove(stream);
237             checkFinished();
238         }
239     }
240     
241     /* (non-Javadoc)
242      * @see org.eclipse.ui.console.TextConsole#clearConsole()
243      */
244     public void clearConsole() {
245         if (partitioner != null) {
246             partitioner.clearBuffer();
247         }
248     }
249     
250     /**
251      * Disposes this console.
252      */
253     protected void dispose() {
254         super.dispose();
255         partitioner.disconnect();
256         //make a copy of the open streams and close them all
257         //a copy is needed as close the streams results in a callback that 
258         //removes the streams from the openStreams collection (bug 152794)
259         Object  [] allStreams= openStreams.toArray();
260         for (int i = 0; i < allStreams.length; i++) {
261             Object   stream = allStreams[i];
262             if (stream instanceof IOConsoleInputStream) {
263                 IOConsoleInputStream is = (IOConsoleInputStream) stream;
264                 try {
265                     is.close();
266                 } catch (IOException   e) {
267                 }
268             } else if (stream instanceof IOConsoleOutputStream) {
269                 IOConsoleOutputStream os = (IOConsoleOutputStream) stream;
270                 try {
271                     os.close();
272                 } catch (IOException   e) {
273                 }                   
274             }
275         }
276         inputStream = null;
277     }
278 
279     /**
280      * Returns the encoding for this console, or <code>null</code> to indicate
281      * default encoding.
282      * 
283      * @return the encoding set for this console, or <code>null</code> to indicate
284      *  default encoding
285      * @since 3.3
286      */
287     public String   getEncoding() {
288         return fEncoding;
289     }
290 }
291
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags