The I/O framework

To provide a uniform I/O interface, the application framework includes an I/O framework. This framework is sometimes also called the output framework, as it mainly handles output. The main goals of this framework are:

Output components

The I/O framework works with output components. All output that the application generates, is given to the output components. Each output component can decide for itself what to do with that output. All applications include at least a StreamOutputComponent, that redirects stream output to the console. For stand-alone applications, this means redirection to stdout and stderr. For application running within the Eclipse IDE, this means redirection to a Console view.

Applications that only need to provide error, warning, normal, and debug textual output, the default output component interface (IOutputComponent) suffices. Applications that want to provide additional (typed) output, should create a derived interface that inherits from IOutputComponent, and extends the interface with additional callback methods. For an example of this, see the org.eclipse.escet.cif.simulator.output.SimulatorOutputComponent interface.

The OutputComponentBase class can be used as a base class for output components. It implements the full IOutputComponent interface, but does nothing with the output that is generated by the application. Derived classes can easily override one or more methods to process output.

Output provider

Each instance of an application has its own output provider. The output provider keeps track of the output components that are registered, and allows sending of output to the output components through static methods.

If an application uses the default IOutputComponent as its output interface, an instance of OutputProvider<IOutputComponent> can be used. This will suffice for most applications. If an extended output component interface is defined, the OutputProvider class should be extended to provide additional static methods. For an example of this, see the org.eclipse.escet.cif.simulator.output.SimulatorOutputComponent class.

For details on how and where to create an instance of the output provider for an application, see the section on how to implement your own application.

Stdout and stderr

Command line applications generally write output to stdout and/or stderr streams. For applications running within the Eclipse IDE, those streams are connected to the Eclipse IDE as a whole, and not to the applications running within Eclipse. The I/O framework solves this issue, by providing a uniform I/O interface.

The org.eclipse.escet.common.app.framework.output.OutputProvider<T> class provides several static methods that can be used to generate output. Several forms of output are supported by default:

  • Error output is automatically generated by the exception framework, for uncaught exceptions. It is however possible to manually generate error output, by using the OutputProvider.err method. This could for instance be useful if multiple error messages are to be outputted.

  • Warning output can be generated by applications, by using the OutputProvider.warn method. The application framework counts the number of warnings generated by an application, and the count can be retrieved using the OutputProvider.getWarningCount method.

  • Normal output can be generated by applications, by using the OutputProvider.out method. To support structured output, the I/O frame maintains an indentation level, which can be increased and decreased one level at a time.

  • Debug output can be generated by applications, by using the OutputProvider.dbg method. To support structured output, the I/O frame maintains an indentation level, which can be increased and decreased one level at a time.

One of the default options of the application framework is the output mode option (OutputModeOption class). It can be used to control what output gets forwarded to the output components. For performance reasons, it may be useful to query whether certain output gets forwarded. The OutputProvider class provides the dowarn, doout, and dodbg methods for this.

It should now be clear that application should never access System.out and System.err directly. Instead, they should use the output provider.

Stdin

There is no equivalent to the OutputProvider for stdin. Instead, use the AppEnv.getStreams() method to obtain the streams for the current application. The AppEnv.getStreams().IN streams can be used to read data from the stdin stream associated with the current application.

Buffering and flushing

The I/O framework buffers all input and output streams by default, and also automatically performs line based flushing for output and error streams.