KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > io > output > ThresholdingOutputStream


1 /*
2  * Copyright 2001-2004 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17
18 package org.apache.commons.io.output;
19
20 import java.io.IOException JavaDoc;
21 import java.io.OutputStream JavaDoc;
22
23
24 /**
25  * An output stream which triggers an event when a specified number of bytes of
26  * data have been written to it. The event can be used, for example, to throw
27  * an exception if a maximum has been reached, or to switch the underlying
28  * stream type when the threshold is exceeded.
29  * <p>
30  * This class overrides all <code>OutputStream</code> methods. However, these
31  * overrides ultimately call the corresponding methods in the underlying output
32  * stream implementation.
33  * <p>
34  * NOTE: This implementation may trigger the event <em>before</em> the threshold
35  * is actually reached, since it triggers when a pending write operation would
36  * cause the threshold to be exceeded.
37  *
38  * @author <a HREF="mailto:martinc@apache.org">Martin Cooper</a>
39  *
40  * @version $Id: ThresholdingOutputStream.java,v 1.2 2004/02/23 04:40:29 bayard Exp $
41  */
42 public abstract class ThresholdingOutputStream
43     extends OutputStream JavaDoc
44 {
45
46     // ----------------------------------------------------------- Data members
47
48
49     /**
50      * The threshold at which the event will be triggered.
51      */
52     private int threshold;
53
54
55     /**
56      * The number of bytes written to the output stream.
57      */
58     private long written;
59
60
61     /**
62      * Whether or not the configured threshold has been exceeded.
63      */
64     private boolean thresholdExceeded;
65
66
67     // ----------------------------------------------------------- Constructors
68
69
70     /**
71      * Constructs an instance of this class which will trigger an event at the
72      * specified threshold.
73      *
74      * @param threshold The number of bytes at which to trigger an event.
75      */
76     public ThresholdingOutputStream(int threshold)
77     {
78         this.threshold = threshold;
79     }
80
81
82     // --------------------------------------------------- OutputStream methods
83
84
85     /**
86      * Writes the specified byte to this output stream.
87      *
88      * @param b The byte to be written.
89      *
90      * @exception IOException if an error occurs.
91      */
92     public void write(int b) throws IOException JavaDoc
93     {
94         checkThreshold(1);
95         getStream().write(b);
96         written++;
97     }
98
99
100     /**
101      * Writes <code>b.length</code> bytes from the specified byte array to this
102      * output stream.
103      *
104      * @param b The array of bytes to be written.
105      *
106      * @exception IOException if an error occurs.
107      */
108     public void write(byte b[]) throws IOException JavaDoc
109     {
110         checkThreshold(b.length);
111         getStream().write(b);
112         written += b.length;
113     }
114
115
116     /**
117      * Writes <code>len</code> bytes from the specified byte array starting at
118      * offset <code>off</code> to this output stream.
119      *
120      * @param b The byte array from which the data will be written.
121      * @param off The start offset in the byte array.
122      * @param len The number of bytes to write.
123      *
124      * @exception IOException if an error occurs.
125      */
126     public void write(byte b[], int off, int len) throws IOException JavaDoc
127     {
128         checkThreshold(len);
129         getStream().write(b, off, len);
130         written += len;
131     }
132
133
134     /**
135      * Flushes this output stream and forces any buffered output bytes to be
136      * written out.
137      *
138      * @exception IOException if an error occurs.
139      */
140     public void flush() throws IOException JavaDoc
141     {
142         getStream().flush();
143     }
144
145
146     /**
147      * Closes this output stream and releases any system resources associated
148      * with this stream.
149      *
150      * @exception IOException if an error occurs.
151      */
152     public void close() throws IOException JavaDoc
153     {
154         try
155         {
156             flush();
157         }
158         catch (IOException JavaDoc ignored)
159         {
160             // ignore
161 }
162         getStream().close();
163     }
164
165
166     // --------------------------------------------------------- Public methods
167
168
169     /**
170      * Returns the threshold, in bytes, at which an event will be triggered.
171      *
172      * @return The threshold point, in bytes.
173      */
174     public int getThreshold()
175     {
176         return threshold;
177     }
178
179
180     /**
181      * Returns the number of bytes that have been written to this output stream.
182      *
183      * @return The number of bytes written.
184      */
185     public long getByteCount()
186     {
187         return written;
188     }
189
190
191     /**
192      * Determines whether or not the configured threshold has been exceeded for
193      * this output stream.
194      *
195      * @return <code>true</code> if the threshold has been reached;
196      * <code>false</code> otherwise.
197      */
198     public boolean isThresholdExceeded()
199     {
200         return (written > threshold);
201     }
202
203
204     // ------------------------------------------------------ Protected methods
205
206
207     /**
208      * Checks to see if writing the specified number of bytes would cause the
209      * configured threshold to be exceeded. If so, triggers an event to allow
210      * a concrete implementation to take action on this.
211      *
212      * @param count The number of bytes about to be written to the underlying
213      * output stream.
214      *
215      * @exception IOException if an error occurs.
216      */
217     protected void checkThreshold(int count) throws IOException JavaDoc
218     {
219         if (!thresholdExceeded && (written + count > threshold))
220         {
221             thresholdReached();
222             thresholdExceeded = true;
223         }
224     }
225
226
227     // ------------------------------------------------------- Abstract methods
228
229
230     /**
231      * Returns the underlying output stream, to which the corresponding
232      * <code>OutputStream</code> methods in this class will ultimately delegate.
233      *
234      * @return The underlying output stream.
235      *
236      * @exception IOException if an error occurs.
237      */
238     protected abstract OutputStream JavaDoc getStream() throws IOException JavaDoc;
239
240
241     /**
242      * Indicates that the configured threshold has been reached, and that a
243      * subclass should take whatever action necessary on this event. This may
244      * include changing the underlying output stream.
245      *
246      * @exception IOException if an error occurs.
247      */
248     protected abstract void thresholdReached() throws IOException JavaDoc;
249 }
250
Popular Tags