KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > de > susebox > jtopas > ReaderSource


1 /*
2  * ReaderSource.java: java.io.Reader-backed data source for the Tokenizer.
3  *
4  * Copyright (C) 2002 Heiko Blau
5  *
6  * This file belongs to the JTopas Library.
7  * JTopas is free software; you can redistribute it and/or modify it
8  * under the terms of the GNU Lesser General Public License as published by the
9  * Free Software Foundation; either version 2.1 of the License, or (at your
10  * option) any later version.
11  *
12  * This software is distributed in the hope that it will be useful, but WITHOUT
13  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
14  * FITNESS FOR A PARTICULAR PURPOSE.
15  * See the GNU Lesser General Public License for more details.
16  *
17  * You should have received a copy of the GNU Lesser General Public License along
18  * with JTopas. If not, write to the
19  *
20  * Free Software Foundation, Inc.
21  * 59 Temple Place, Suite 330,
22  * Boston, MA 02111-1307
23  * USA
24  *
25  * or check the Internet: http://www.fsf.org
26  *
27  * Contact:
28  * email: heiko@susebox.de
29  */
30
31 package de.susebox.jtopas;
32
33 //-----------------------------------------------------------------------------
34 // Imports
35 //
36 import java.io.InputStream JavaDoc;
37 import java.io.FileInputStream JavaDoc;
38 import java.io.Reader JavaDoc;
39 import java.io.InputStreamReader JavaDoc;
40 import java.io.File JavaDoc;
41 import java.io.IOException JavaDoc;
42
43
44 //-----------------------------------------------------------------------------
45 // Class ReaderSource
46 //
47
48 /**<p>
49  * This implementation of the {@link TokenizerSource} interface uses the JDK
50  * {@link java.io.Reader} class to realize the requested functionality. Note that
51  * the backing <code>Reader</code> can be changed during the parse operations of
52  * the {@link Tokenizer} instance that accesses this <code>ReaderSource</code>.
53  *</p>
54  *
55  * @see de.susebox.java.util.Tokenizer
56  * @see de.susebox.java.util.AbstractTokenizer
57  * @author Heiko Blau
58  * @see java.io.Reader
59  */
60 public class ReaderSource implements TokenizerSource {
61   
62   //---------------------------------------------------------------------------
63 // Constructors
64 //
65
66   /**
67    * The default constructor constructs a <code>ReaderSource</code> instance
68    * that reads from nowhere. A call to the {@link #read} method will immediately
69    * return the end-of-file condition.
70    *
71    * @see #read
72    */
73   public ReaderSource() {
74     this((Reader JavaDoc)null);
75   }
76   
77   /**
78    * Constructing an <code>ReaderSource</code> object with the given {@link java.io.Reader}
79    * instance to get input data from. <code>null</code> is a valid value. The
80    * {@link #read} method will return an end-of-file condition in that case.
81    *<br>
82    * The given {@link java.io.Reader} instance can be closed manually or by
83    * calling the {@link #close} method of this <code>ReaderSource</code> object.
84    *
85    * @param reader the backing {@link java.io.Reader} or <code>null</code>
86    */
87   public ReaderSource(Reader JavaDoc reader) {
88     setReader(reader);
89   }
90   
91   /**
92    * This Constructor takes an {@link java.io.InputStream}. It is comfortable
93    * when You dont have a {@link java.io.Reader} in the first place. However,
94    * when using this constructor, the method {@link #close} should be called
95    * after tokenizing has been finished. It will also close the given
96    * <code>InputStream</code>.
97    *<br>
98    * The method accepts <code>null</code> leading to an end-of-file condition
99    * in the first call to {@link #read}.
100    *
101    * @param is the input stream or <code>null</code>
102    */
103   public ReaderSource(InputStream JavaDoc is) {
104     if ((_inputStream = is) != null) {
105       setReader(new InputStreamReader JavaDoc(is));
106     }
107   }
108   
109   /**
110    * This Constructor takes an {@link java.io.File} to create a {@link java.io.Reader}
111    * from. When using this constructor, the method {@link #close} should be
112    * called after tokenizing has been finished.
113    *<br>
114    * The method accepts <code>null</code> leading to an end-of-file condition
115    * in the first call to {@link #read}.
116    *
117    * @param file the {@link java.io.File} object that should be read or <code>null</code>
118    */
119   public ReaderSource(File JavaDoc file) throws IOException JavaDoc {
120     if (file != null) {
121       _inputStream = new FileInputStream JavaDoc(file);
122       setReader(new InputStreamReader JavaDoc(_inputStream));
123     }
124   }
125   
126   /**
127    * This Constructor takes an {@link java.lang.String} as a file path to create
128    * a {@link java.io.Reader} from. When using this constructor, the method
129    * {@link #close} should be called after tokenizing has been finished.
130    *<br>
131    * The method accepts <code>null</code> leading to an end-of-file condition
132    * in the first call to {@link #read}.
133    *
134    * @param path a file path or <code>null</code>
135    */
136   public ReaderSource(String JavaDoc path) throws IOException JavaDoc {
137     if (path != null) {
138       _inputStream = new FileInputStream JavaDoc(path);
139       setReader(new InputStreamReader JavaDoc(_inputStream));
140     }
141   }
142   
143   
144   //---------------------------------------------------------------------------
145 // Methods of the TokenizerSource interface
146 //
147
148   /**
149    * The method calls the {@link java.io.Reader#read(char[], int, int)} method of
150    * the currently backing {@link java.io.Reader}. If no <code>Reader is set so far,
151    * -1 (end-of-file) is returned.
152    *
153    * @param cbuf buffer to receive data
154    * @param offset position from where the data should be inserted in <CODE>cbuf</CODE>
155    * @param maxChars maximum number of characters to be read into <CODE>cbuf</CODE>
156    * @return actually read characters or -1 on an end-of-file condition
157    * @throws Exception anything that could happen during read, most likely {@link java.io.IOException}
158    */
159   public int read(char[] cbuf, int offset, int maxChars) throws Exception JavaDoc {
160     if (_reader != null) {
161       return _reader.read(cbuf, offset, maxChars);
162     } else {
163       return -1;
164     }
165   }
166   
167   //---------------------------------------------------------------------------
168 // Implementation
169 //
170
171   /**
172    * This method can be called to close streams (either {@link java.io.Reader}
173    * or {@link java.io.InputStream} passed to the constructors or implicitely
174    * created when this <code>ReaderSource</code> is setup.
175    *<br>
176    * It is a shortcut for otherwise nessecary operations that will usually consist
177    * of calling {@link java.io.Reader#close} and {@link java.io.InputStream#close}
178    * probably combined with an exception handling to catch {@link java.io.IOException}.
179    */
180   public void close() {
181     if (_reader != null) {
182       try { _reader.close(); } catch (IOException JavaDoc ex) {}
183     }
184     if (_inputStream != null) {
185       try { _inputStream.close(); } catch (IOException JavaDoc ex) {}
186     }
187   }
188   
189   /**
190    * Setting the backing {@link java.io.Reader} instance. <code>null</code> is a
191    * valid value. The {@link #read} method will return no data (end-of-file) in
192    * that case.
193    *
194    * @param reader the backing {@link java.io.Reader}
195    * @see #read
196    * @see #getReader
197    */
198   public void setReader(Reader JavaDoc reader) {
199     _reader = reader;
200   }
201   
202   /**
203    * Retrieving the current {@link java.io.Reader}. The method may return <code>null</code>
204    * if a {@link #setReader} with null has occured before.
205    *
206    * @return the current {@link java.io.Reader} or <code>null</code>
207    * @see #setReader
208    */
209   public Reader JavaDoc getReader() {
210     return _reader;
211   }
212   
213   /**
214    * Release ressources
215    */
216   protected void finalize() {
217     close();
218   }
219   
220   //---------------------------------------------------------------------------
221 // Members
222 //
223 private Reader JavaDoc _reader = null;
224   private InputStream JavaDoc _inputStream = null;
225 }
226
Popular Tags