ErrOutHandle


1   /**
2    * $Id: ErrOutHandle.java 180 2007-03-15 12:56:38Z ssmc $
3    * Copyright 2004 iDare Media, Inc. All rights reserved.
4    *
5    * Originally written by iDare Media, Inc. for release into the public domain. This
6    * library, source form and binary form, is free software; you can redistribute it and/or
7    * modify it under the terms of the GNU Lesser General Public License (LGPL) as published
8    * by the Free Software Foundation; either version 2.1 of the License, or (at your option)
9    * any later version.<p>
10   *
11   * This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
12   * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
13   * See the GNU LGPL for more details.<p>
14   *
15   * You should have received a copy of the GNU Lesser General Public License along with this
16   * library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite
17   * 330, Boston, MA  02111-1307  USA. The GNU LGPL can be found online at
18   * http://www.fsf.org/copyleft/lesser.html<p>
19   *
20   * This product has been influenced by several projects within the open-source community.
21   * The JWare developers wish to acknowledge the open-source community's support. For more
22   * information regarding the open-source products used within JWare, please visit the
23   * JWare website.
24   *----------------------------------------------------------------------------------------*
25   * WEBSITE- http://www.jware.info                            EMAIL- inquiries@jware.info
26   *----------------------------------------------------------------------------------------*
27   **/
28  
29  package com.idaremedia.antx.ownhelpers.io;
30  
31  import  java.io.OutputStream  ;
32  import  java.io.PrintStream  ;
33  
34  import  com.idaremedia.antx.AntX;
35  import com.idaremedia.antx.apis.BuildError;
36  
37  /**
38   * Helper that lets you easily swap (temporarily) the standard err and out streams
39   * with your own handlers.
40   * <p>
41   * <b>Example Usage:</b><pre>
42   *    ErrOutHandle devnull = new ErrOutHandle();
43   *    devnull.install();
44   *      ...//any output generated by these bits will be ignored
45   *    devnull.uninstall(false,true);
46   * </pre>
47   *
48   * @since    JWare/AntX 0.4
49   * @author   ssmc, &copy;2004 <a HREF="http://www.jware.info">iDare&nbsp;Media,&nbsp;Inc.</a>
50   * @version  0.5
51   * @.safety  single
52   * @.group   impl,helper
53   * @see      NullPrintStream
54   * @see      BufferStream
55   **/
56  
57  public final class ErrOutHandle
58  {
59      private static final String   IAM_ = AntX.utilities+"ErrOutHandle";
60  
61  
62  
63      /**
64       * Initializes a new helper.
65       **/
66      public ErrOutHandle()
67      {
68      }
69  
70  
71  
72      /**
73       * Initializes a new helper and immediately swaps out the
74       * two System streams.
75       * @param out new system standard output stream (non-null)
76       * @param err new system error output stream (non-null)
77       * @throws SecurityException if no permission to swap both streams.
78       **/
79      public ErrOutHandle(OutputStream   out, OutputStream   err)
80      {
81          install(new PrintStream  (out),new PrintStream  (err));
82          m_newOut0 = out;
83          m_newErr0 = err;
84      }
85  
86  
87  
88      /**
89       * Installs this two streams in place of current
90       * <span class="src">System&#46;out</span> and
91       * <span class="src">System&#46;err</span>.
92       * @param out new system standard output stream (non-null)
93       * @param err new system error output stream (non-null)
94       * @throws SecurityException if no permission to swap both streams.
95       **/
96      public void install(PrintStream   out, PrintStream   err)
97      {
98          AntX.require_(out!=null && err!=null,IAM_,"install- nonzro streams");
99          try {
100             PrintStream   os;
101 
102             os = System.out;
103             System.setOut(out);
104             m_oldOut = os;
105             m_newOut = out;
106 
107             os = System.err;
108             System.setErr(err);
109             m_oldErr = os;
110             m_newErr = err;
111         }
112         catch(RuntimeException   secX) {
113             //NB: ?is it possible to have perm to do one but not other?
114             if (m_oldErr!=null) {
115                 System.setErr(m_oldErr);
116             }
117             if (m_oldOut!=null) {
118                 System.setOut(m_oldOut);
119             }
120             clear();
121             throw secX;
122         }
123     }
124 
125 
126 
127     /**
128      * Installs two "<span class="src">dev/null</span>" dummies
129      * for <span class="src">System&#46;out</span> and
130      * <span class="src">System&#46;err</span>. All output is
131      * thrown away. <em>Must be followed by a call to
132      * {@linkplain #uninstall(boolean,boolean) uninstall}.</em>
133      * @throws SecurityException if no permission to swap both streams.
134      * @see NullPrintStream
135      **/
136     public final void install()
137     {
138         install(new NullPrintStream(), new NullPrintStream());
139     }
140 
141 
142 
143     /**
144      * Restores the two systems streams that where in place when
145      * this object's {@linkplain #install(PrintStream,PrintStream)
146      * install} method was entered.
147      * @param flush <i>true</i> if current streams should be flushed
148      *    before being replaced.
149      * @param check <i>true</i> if current streams should be checked
150      *    to insure they're the ones this handle installed.
151      * @throws SecurityException if no permission to swap both streams.
152      * @throws BuildError if current streams aren't ours.
153      * @throws IllegalStateException if not installed.
154      **/
155     public void uninstall(boolean flush, boolean check)
156     {
157         AntX.verify_(wasInstalled(),IAM_,"uninstall- installed");
158         if (flush) {
159             try {
160                 System.out.flush();
161                 System.err.flush();
162             } catch(Exception   iox) {/*burp*/}
163         }
164         if (check) {
165             if (System.out!=m_newOut || System.err!=m_newErr) {
166                 String   error = AntX.uistrs().get("fixture.stdio.outof.sync");
167                 throw new BuildError(error);
168             }
169         }
170         System.setErr(m_oldErr);
171         System.setOut(m_oldOut);
172         clear();
173     }
174 
175 
176 
177     /**
178      * Like {@linkplain #uninstall(boolean,boolean)
179      * uninstall(&#8230;)} but with flushing and checking
180      * turned on.
181      **/
182     public final void uninstall()
183     {
184         uninstall(true,true);
185     }
186 
187 
188 
189     /**
190      * Returns <i>true</i> if this handle has been installed.
191      **/
192     public final boolean wasInstalled()
193     {
194         return m_oldOut!=null && m_oldErr!=null;
195     }
196 
197 
198 
199 
200     /**
201      * Returns our underlying <span class="src">System&#46;out</span>
202      * output stream. Returns <i>null</i> if not known.
203      **/
204     public final OutputStream   getOurSystemOut()
205     {
206         return m_newOut0;
207     }
208 
209 
210     /**
211      * Returns our underlying <span class="src">System&#46;err</span>
212      * output stream. Returns <i>null</i> if not known.
213      **/
214     public final OutputStream   getOurSystemErr()
215     {
216         return m_newErr0;
217     }
218 
219 
220 
221     /**
222      * Returns replaced <span class="src">System&#46;out</span>
223      * stream reference. Returns <i>null</i> if not installed.
224      **/
225     public final PrintStream   getReplacedSystemOut()
226     {
227         return m_oldOut;
228     }
229 
230 
231     /**
232      * Returns replaced <span class="src">System&#46;err</span>
233      * stream reference. Returns <i>null</i> if not installed.
234      **/
235     public final PrintStream   getReplacedSystemErr()
236     {
237         return m_oldErr;
238     }
239 
240 
241 
242 
243     /**
244      * Remove all our references to any streams.
245      **/
246     private void clear()
247     {
248         m_newOut  = m_newErr  = null;
249         m_oldOut  = m_oldErr  = null;
250         m_newOut0 = m_newErr0 = null;
251     }
252 
253 
254     private PrintStream   m_newOut, m_newErr;
255     private OutputStream   m_newOut0, m_newErr0;//underlying ps
256     private PrintStream   m_oldOut, m_oldErr;
257 }
258 
259 /* end-of-ErrOutHandle.java */
260
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags