Design Aspects of the Standard I/O Library. Design with Java:

Transcription

1 Design Aspects of the Standard I/O Library Design with Java: QUOIN 1208 Massachusetts Avenue, Suite 3 Cambridge, Massachusetts tel: fax: info@quoininc.com web:

2 Design with Java Design Aspects of the Standard I/O Library by David M. Papurt and Jean Pierre LeJacq printed in the Journal of Object-Oriented Programming, September 1996 Introduction This is the first column in a series discussing design in the Java programming language that will appear regularly here in JOOP. Each column will focus on one aspect of design; the topics will be taken from a variety of areas: design elements of the standard Java library; patterns for solving particular design problems adapted to the peculiarities of Java; and fundamental Java language design issues. Providing a variety of compile-time, load-time, and run-time error checks, Java is a relatively safe programming language. Nontheless, experience shows that without satisfactory attention paid to program design, brittle, non-extendible, and error ridden programs likely emerge from a large programming effort, no matter what language is used. This series of columns contain descriptions of techniques that enable program designers and programmers to avoid design errors when writing programs in Java. The idea is to provide designers with sophisticated methods that maximize flexibility, minimize maintenance and debugging efforts, and enable extensions. This first column on Design with Java covers design aspects of the Input/Output (I/O) package java.io included in the Java standard library; the structure and design philosophy of the package are described, and techniques for extending processing and for handling new data types are demonstrated. Package Structure The notion of a stream characterizes I/O in Java. A stream is an ordered sequence of data items either read from some source or written to some destination possibly with processing along the way. The Java I/O package abstracts the various and normally encountered sources, destinations, and processing algorithms: large portions of Java programs can

3 operate on InputStream and OutputStream objects independently of whether the ultimate data source or destination is, for example, a disk file, an in-core array, another thread, or a file across the network and independently of whether the data is buffered, translated, or otherwise processed. The means of this abstraction is based on the patterns of design formed by the classes in the java.io package. Figure 1 shows the pattern of input classes; this configuration of classes is sometimes called decorator or wrapper [1], and includes classes representing the ultimate data source and classes that perform processing of stream data items. The crucial feature of the decorator pattern is the reference source from subclass FilterInputStream to root class InputStream. The arrangement of output classes is similar. The figure uses Object Modeling Technique (OMT) notation [2] as enhanced for description of Design Patterns [1] 1. Figure 1: Java I/O input classes pattern. This design is highly run-time configurable; the decorator pattern generates constellations of objects that look like singly-linked lists and that mix and match ultimate data sources and processing. Figure 2 contains three sample object constellations 2 : figure 2a contains an object constellation that represents an ultimate data source of an in-core array without any additional processing; figure 2b represents a separate thread as ultimate data source via a PipedInputStream object with additional single byte pushback buffer processing; figure 2c adds buffering and typed data interpretation to an unbuffered byte stream from a disk file.

4 Other example processing might uppercase a byte stream from across the network, or might count the number of lines in a stream originating from a disk file. Figures 2a-c: Sample input class object constellations. In each case, an object of a class representing an ultimate data source terminates the list. The constructor for each subclass of FilterInputStream (i.e., the processors or decorators) requires an InputStream as argument to initialize reference source: either an ultimate data source object or another processing class object. An arbitrary number of processing class objects can decorate (i.e., can appear in front of) the ultimate data source. Java code for generating the three sample streams in figure 2 appears below.

5 The program passes streama, streamb, and streamc to methods that read directly from the head decorator. Filter Operation An abstract class, InputStream declares the basic operations that all input stream classes provide: three versions of read() read single bytes and byte arrays, blocking until input is available; skip() skips over bytes in the stream; available() returns the number of bytes available without blocking; and close() closes the stream and releases resources held by the stream. A simplified class declaration appears below. The single byte read() provides the single byte in the first 8 bits of its 32 bit return value. All three versions of read() indicate the end of the data stream with a return value of -1. FilterInputStream implements all of the above operations; these implementations simply forward any request to the object referenced by source, so a direct FilterInputStream object would be transparent 3. For example, FilterInputStream's implementation of the single byte read() operation along with its constructor implementation appear below.

6 A processing class inherits and normally overrides some of FilterInputStream's methods. The normal structure of an overriding processing class method implementation includes the following: * A call to the overridden version of the method (which forwards the request to source), and * Additional processing that corresponds to the semantics of the processing class. Consider class PushbackInputStream's implementation of the single byte read() method along with its constructor and push back method unread() 4.

7 The single byte read() above first checks the push back buffer, and returns the buffer contents if it contains a valid byte; otherwise, the method simply returns the byte read() from the InputStream object referenced by source. Other methods of class PushbackInputStream also manipulate the push back buffer: the array versions of read() likewise check the push back buffer, and possibly place buffer in the first position in the byte array; skip() may ask source to skip one less byte than originally requested; and available() may add one to the number of bytes that source has available. Other java.io processing classes add their own processing. BufferedInputStream, for example, provides transparent data buffering. This class contains a multiple byte array buffer so that nearly all read() requests can be filled directly from this buffer; it makes requests to source for more bytes only when the buffer is empty. This is most useful when

8 the ultimate data source is a disk file, and a single read of a large block of bytes is significantly more efficient than multiple reads of small blocks. Extending Processing By mimicking the java.io processing classes, programmers can extend stream processing in a straightforward way. Consider class UpperCaseInputStream below that subclasses FilterInputStream: This class operates on data streams assumed to comprise text, and insures that all alphabetic characters are upper case when they reach the code manipulaing the stream. UpperCaseInputStream is particulary simple, however more complex processing classes are possible: class GrepInputStream could perform a grep-like search for patterns in text streams, forwarding only those lines that match the pattern and consuming all others; StatsInputStream could could accumulate statistics on, for example, the numbers of words, lines, and punctuation, whitespace, and other characters in a text stream; stream compression and decompression or stream encryption and unencryption processing classes could be written in pairs, subclassing FilterOutputStream as well as FilterInputStream.

9 mark() and reset() Base class InputStream defines three functions for marking a position in a stream so that after some reading has taken place, the stream can be reset, and the just read bytes reread another time. When marksupported() returns true, then the stream implements mark() and reset(); reset() will return the stream to the marked postion so long as no more than readlimit bytes have been read() since the mark(). Methods mark() and reset() are useful in a context where the type of the data in the stream is unknown when the stream is opened (for example a stream might contain simple text vs. HTML text), and some amount of the stream must be consumed in order to determine its type. Once the type of the data in the stream is determined, the stream can be reset() and processed appropriately. The idea of mark() and reset() is valuable, but the problem with the standard library solution is that all input stream classes inherit this capability whether it is sensible or not. A more modular and sensible solution removes the three methods above from class InputStream (or disregards them) and implements the idea as a processing class.

10 Indeed, class MarkAndResetInputStream is semantically like java.io class PushbackInputStream with a larger push back buffer capacity. Handling New Data Types For the most part, this article has presented streams whose data items were limited to type byte (or bytes interpreted as characters). However, a stream is an ordered sequence of data items that can have arbitrary type; a data item read from or written to a stream is not restricted to byte, but can have, in principle, any built-in, library, or user-defined type. This section describes how to accommodate different types of data items in Java streams. One approach represents all values, no matter their type, in text; the java.io processing class PrintStream realizes this approach for output streams.

11 Each method in class PrintStream translates its argument into a sequence of bytes (i.e., characters), and passes those bytes towards the ultimate data destination. The methods that take an Object call tostring() on their argument to perform the translation to text. A second approach to accommodating different types in Java streams passes the binary representation of the value (its raw bytes) towards the ultimate data destination or from the ultimate data source. For example, consider java.io processing class DataInputStream. The methods do no translation of the representation beyond collecting and packaging individual bytes from the source into higher level type values. As it stands, only a fixed set of fundamental types can be handled directly by this approach - only those types with corresponding methods in DataInputStream (and DataOutputStream

12 for output). An indirect approach that builds input and output methods on top of the DataInputStream and DataOutputStream methods accommodates other, non-fundamental types. For example, class DateIO below contains static methods read() and write() for the I/O of java.util class Date 5. A class X that includes a Date object would implement its static read(datainputstream,x) and static write(dataoutputstream,x) methods in part via calls to DateIO.read() and DateIO.write(). More generally, composite types would invariably implement their I/O methods in terms of their components' I/O methods 6. References To Decorated Objects Typically, stream creating code keeps a reference only to the head decorator, and passes this reference to other methods that read from or write to the head. However, in some cases the stream creating code may hold onto and manipulate a reference to an internal object along the decorator list other than the head. This manipulation should almost never include actual reads or writes, but instead should be limited to higher level, control operations. Consider the highly decorated input stream below.

13 The program might mark() the beginning of the stream via the internal object mris, and then consume some data from the DataInputStream dis in the process of determining the type of data in the stream. Once the type of data in the stream is known, the stream must be reset(), and then processed appropriately from its beginning. As a matter of good style, all read() operations are performed only to the head decorator in the composite stream object; reading from an internal object like mris breaks the uncomplicated illusion of a single object accessed via a single reference, and makes the code more difficult to understand. Summary The java.io stream package is highly modular. It uses the decorator design pattern of classes to permit run-time configuration of singly linked lists that mix and match ultimate

14 data source and destination stream objects and processing stream objects. By mimicking the java.io processing classes, programmers can extend stream processing in a straightforward and elegant way; nearly any stream processing can be embedded in a modular processing class. A stream can be adapted to read() or write() data items of arbitrary type; a data item read from or written to a stream is not restricted to type byte, but can have, in principle, any built-in, library, or user-defined type. Footnotes 1 In this notation, a rectangle represents a class, the class name appearing inside the rectangle. The notation for inheritance is a triangle; the superclass connects by a line to the triangle apex, and each subclass connects by individual lines to a line attached to the triangle base. The notation for reference containment is a diamond adjacent the containing class anchoring an arrow pointing at the referenced class. 2 A rounded corner rectangle represents an object; the object's class appears in parentheses. An arrow anchored by a solid circle represents a reference instance. 3 PushbackInputStream implements a single-byte push back buffer useful for implementing lexical analyzers [3]. Having read a byte terminating but not included in the current token, the lexical analyzer can push this byte back onto the stream with unread () so that it is the first byte read when processing the next token. 5 The new class DateIO is created to contain these methods rather than modifying the standard library class Date, because standard library classes should never be modified except by the vendor. 6 Though syntactically distinct, this approach is semantically similar to the approach taken by C++ programmers when overloading operator>>() for input and operator<<() for output. Acknowledgments The authors thank Ron LaBonte of SunU Training for his support. References

15 [1] Gamma, E., R. Helm, R. Johnson, and J. Vlissides, Design Patterns: Elements of Reusable Object-Oriented Software, Addison-Wesley, Reading, MA, [2] Rumbaugh, J., M. Blaha, W. Premerlani, F. Eddy, and W. Lorensen, Object-Oriented Modeling and Design, Prentice-Hall, Englewood Cliffs, NJ, [3] Aho, A. V., R. Sethi, and J. D. Ullman, Compilers: Principles, Techniques, and Tools, Addison-Wesley, Reading, MA, Biographies David Papurt is founder of David Papurt Associates, Cambridge, MA, a firm specializing in Java, C++, and object-oriented analysis and design, and is Director of Technology at Terasoft Technology Corp., Milford, MA. He is also author of the highly acclaimed text Inside the Object Model: The Sensible Use of C++ (SIGS Books, 1995). He may be contacted at @compuserve.com. Jean Pierre LeJacq is a founder of Quoin Inc., Cambridge, MA, a company that provides consulting and training services for distributed computing. He may be contacted at jplejacq@quoininc.com article presented with permission of David Papurt Associates Copyright QUOIN, 1997