001: /*
002: * Environment.java: Alternative System interface.
003: *
004: * Copyright (C) 2002 Heiko Blau
005: *
006: * This file belongs to the Susebox Java Core Library (Susebox JCL).
007: * The Susebox JCL is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU Lesser General Public License as published by the
009: * Free Software Foundation; either version 2.1 of the License, or (at your
010: * option) any later version.
011: *
012: * This software is distributed in the hope that it will be useful, but WITHOUT
013: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
014: * FITNESS FOR A PARTICULAR PURPOSE.
015: * See the GNU Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public License along
018: * with the Susebox JCL. If not, write to the
019: *
020: * Free Software Foundation, Inc.
021: * 59 Temple Place, Suite 330,
022: * Boston, MA 02111-1307
023: * USA
024: *
025: * or check the Internet: http://www.fsf.org
026: *
027: * Contact:
028: * email: heiko@susebox.de
029: */
030:
031: package de.susebox.java.lang;
032:
033: //-----------------------------------------------------------------------------
034: // Imports
035: //
036: import java.io.InputStream;
037: import java.io.PrintStream;
038:
039: //-----------------------------------------------------------------------------
040: // Interface Environment
041: //
042:
043: /**<p>
044: * A <code>Environment</code> object is a substitute for the usual environment
045: * as defined in the {@link java.lang.System} class, most important the
046: * <code>stdin</code> and <code>stdout</code> channels {@link java.lang.System#in}
047: * and {@link java.lang.System#out}.
048: *</p><p>
049: * Environments are especially useful in classes that can be used both standalone
050: * (having a <code>main</code> method) or in an application where the class is
051: * only one of many. Another scenario would be a simple class designed for use
052: * from the command line that should suddenly be invoked in GUI framework without
053: * redirecting the default channels {@link java.lang.System#in} and
054: * {@link java.lang.System#out}.
055: *</p><p>
056: * To obtain an <code>Environment</code> instance or to store such instances
057: * use the class {@link EnvironmentProvider}:
058: *<block><pre>
059: * Environment env = EnvironmentProvider.getEnvironment(this);
060: *</pre></block>
061: *</p>
062: *
063: * @author Heiko Blau
064: */
065: public interface Environment {
066:
067: /**
068: * This method returns the substitution for {@link java.lang.System#in}, the
069: * standard input channel. Instead of a public member like in the <code>System</code>
070: * class, we prefer the method version since it is more flexible.
071: *
072: * @return the {@link java.io.InputStream} that serves as standard input
073: * @throws UnsupportedOperationException if there is no stdin channel available
074: * @see java.lang.System#in
075: */
076: public InputStream in() throws UnsupportedOperationException;
077:
078: /*-->
079: {
080: throw UnsupportedOperationException;
081: }
082: -->*/
083:
084: /**
085: * This method returns the substitution for {@link java.lang.System#out}, the
086: * standard output channel. Instead of a public member like in the <code>System</code>
087: * class, we prefer the method version since it is more flexible.
088: *
089: * @return the {@link java.io.PrintStream} that serves as standard output
090: * @throws UnsupportedOperationException if there is no stdout channel available
091: * @see java.lang.System#out
092: */
093: public PrintStream out() throws UnsupportedOperationException;
094:
095: /*-->
096: {
097: throw UnsupportedOperationException;
098: }
099: -->*/
100:
101: /**
102: * This method returns the substitution for {@link java.lang.System#err}, the
103: * standard error channel. Instead of a public member like in the <code>System</code>
104: * class, we prefer the method version since it is more flexible.
105: *
106: * @return the {@link java.io.PrintStream} that serves as standard error output
107: * @throws UnsupportedOperationException if there is no stderr channel available
108: * @see java.lang.System#err
109: */
110: public PrintStream err() throws UnsupportedOperationException;
111:
112: /*-->
113: {
114: throw UnsupportedOperationException;
115: }
116: -->*/
117:
118: /**
119: * During different stages of program execution various exit codes can be set
120: * using this method. For instance, a program may set the exit code to a positive
121: * number indicating that it is still running. A negative exit code may stand
122: * for errors while 0 is the usual OK code.
123: *
124: * @param status the exit code of an application
125: * @see java.lang.System#exit
126: * @see #getExitStatus
127: * @see #exit
128: */
129: public void setExitStatus(int status);
130:
131: /*-->
132: {
133: _exitStatus = status;
134: }
135: -->*/
136:
137: /**
138: * Retrieving the currently set exit code.
139: *
140: * @return the currently set exit code of an application
141: */
142: public int getExitStatus();
143:
144: /*-->
145: {
146: return _exitStatus;
147: }
148: -->*/
149:
150: /**
151: * This method exits the instance of its <code>Environment</code> implementation.
152: * After calling <code>exit</code> the <code>Environment</code> instance is
153: * generally not any longer usable. In particular, an implementation can choose
154: * to call {@link java.lang.System#exit}.
155: *
156: * @throws UnsupportedOperationException if the method is not available
157: * @see #setExitStatus
158: * @see java.lang.System#exit
159: */
160: public void exit() throws UnsupportedOperationException;
161: /*-->
162: {
163: throw UnsupportedOperationException;
164: }
165: -->*/
166:
167: //---------------------------------------------------------------------------
168: // members
169: //
170: /*-->
171: private int _exitStatus = 0;
172: -->*/
173: }
|