1 /* 2 * Environment.java: Alternative System interface. 3 * 4 * Copyright (C) 2002 Heiko Blau 5 * 6 * This file belongs to the Susebox Java Core Library (Susebox JCL). 7 * The Susebox JCL 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 the Susebox JCL. 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.java.lang; 32 33 //----------------------------------------------------------------------------- 34 // Imports 35 // 36 import java.io.InputStream; 37 import java.io.PrintStream; 38 39 40 //----------------------------------------------------------------------------- 41 // Interface Environment 42 // 43 44 /**<p> 45 * A <code>Environment</code> object is a substitute for the usual environment 46 * as defined in the {@link java.lang.System} class, most important the 47 * <code>stdin</code> and <code>stdout</code> channels {@link java.lang.System#in} 48 * and {@link java.lang.System#out}. 49 *</p><p> 50 * Environments are especially useful in classes that can be used both standalone 51 * (having a <code>main</code> method) or in an application where the class is 52 * only one of many. Another scenario would be a simple class designed for use 53 * from the command line that should suddenly be invoked in GUI framework without 54 * redirecting the default channels {@link java.lang.System#in} and 55 * {@link java.lang.System#out}. 56 *</p><p> 57 * To obtain an <code>Environment</code> instance or to store such instances 58 * use the class {@link EnvironmentProvider}: 59 *<block><pre> 60 * Environment env = EnvironmentProvider.getEnvironment(this); 61 *</pre></block> 62 *</p> 63 * 64 * @author Heiko Blau 65 */ 66 public interface Environment { 67 68 /** 69 * This method returns the substitution for {@link java.lang.System#in}, the 70 * standard input channel. Instead of a public member like in the <code>System</code> 71 * class, we prefer the method version since it is more flexible. 72 * 73 * @return the {@link java.io.InputStream} that serves as standard input 74 * @throws UnsupportedOperationException if there is no stdin channel available 75 * @see java.lang.System#in 76 */ 77 public InputStream in() throws UnsupportedOperationException; 78 /*--> 79 { 80 throw UnsupportedOperationException; 81 } 82 -->*/ 83 84 /** 85 * This method returns the substitution for {@link java.lang.System#out}, the 86 * standard output channel. Instead of a public member like in the <code>System</code> 87 * class, we prefer the method version since it is more flexible. 88 * 89 * @return the {@link java.io.PrintStream} that serves as standard output 90 * @throws UnsupportedOperationException if there is no stdout channel available 91 * @see java.lang.System#out 92 */ 93 public PrintStream out() throws UnsupportedOperationException; 94 /*--> 95 { 96 throw UnsupportedOperationException; 97 } 98 -->*/ 99 100 /** 101 * This method returns the substitution for {@link java.lang.System#err}, the 102 * standard error channel. Instead of a public member like in the <code>System</code> 103 * class, we prefer the method version since it is more flexible. 104 * 105 * @return the {@link java.io.PrintStream} that serves as standard error output 106 * @throws UnsupportedOperationException if there is no stderr channel available 107 * @see java.lang.System#err 108 */ 109 public PrintStream err() throws UnsupportedOperationException; 110 /*--> 111 { 112 throw UnsupportedOperationException; 113 } 114 -->*/ 115 116 /** 117 * During different stages of program execution various exit codes can be set 118 * using this method. For instance, a program may set the exit code to a positive 119 * number indicating that it is still running. A negative exit code may stand 120 * for errors while 0 is the usual OK code. 121 * 122 * @param status the exit code of an application 123 * @see java.lang.System#exit 124 * @see #getExitStatus 125 * @see #exit 126 */ 127 public void setExitStatus(int status); 128 /*--> 129 { 130 _exitStatus = status; 131 } 132 -->*/ 133 134 /** 135 * Retrieving the currently set exit code. 136 * 137 * @return the currently set exit code of an application 138 */ 139 public int getExitStatus(); 140 /*--> 141 { 142 return _exitStatus; 143 } 144 -->*/ 145 146 147 /** 148 * This method exits the instance of its <code>Environment</code> implementation. 149 * After calling <code>exit</code> the <code>Environment</code> instance is 150 * generally not any longer usable. In particular, an implementation can choose 151 * to call {@link java.lang.System#exit}. 152 * 153 * @throws UnsupportedOperationException if the method is not available 154 * @see #setExitStatus 155 * @see java.lang.System#exit 156 */ 157 public void exit() throws UnsupportedOperationException; 158 /*--> 159 { 160 throw UnsupportedOperationException; 161 } 162 -->*/ 163 164 165 //--------------------------------------------------------------------------- 166 // members 167 // 168 /*--> 169 private int _exitStatus = 0; 170 -->*/ 171 } 172