How to visualize a Stream object (and some other data types)?

Question

I want to make a small programming tutorial which will have a number of images visualizing various data types, but I am not sure how to draw these images of the data types.

Assume that I have a FileOutputStream object that writes to the file 1.txt.

How can I think of this FileOutputStream object, do I think about it as a container of the stream of data (i.e. a pipe), for example:

Or do I think about it as the stream of data only, for example:

I think the term "stream of water" in real life only means the flowing water (without having a container that contains the flowing water).

---

My question also apply to other data types, for example do I think of a Stack of integers as the container of the stack of integers, for example:

Or do I think about it as the stack of integers only, for example:

I think the term "stack of books" in real life only means the stacked books (without having a container that contains the stacked books).

---

Same thing for the int data type, do I think of an int as the container of the integer, for example:

Or do I think about it as the integer only, for example:

Answer 1

Objective elements

There is no standard for representing stream objects.

But as you explained it, the stream is an abstraction of a flow of data. But this abstraction also hides the origin and the size of the stream:

• it can be a file stored on the file system, and that has a finished size;
• it can be a file object representing itself a stream of incoming characters typed on the console, with no end until you shut-down the computer;
• it can be data coming from a network connection that streams a potentially infinite set of data (e.g. temperature measurements in you house, measurements of factory sensors, etc...)

The potentially infinite size of the data is an important element to get the concept of a stream and more generally stream-based architectures right. This is why you should not show the stream as a boxed (finished) content, but suggest the uncertainty about the source of the flow in some way.

Subjective remarks

Your first representation of a pipe conveys well the idea. This kind of representation is used in several books dedicated to stream based architetures (e.g. Streaming Architecture by Ted Dunning & Ellen Friedman).

But maybe do not connect it to a a boxed file, but rather some cloud with a question mark? or at least show some tap on the side of the file to suggest that it's just a possible connection.

Another alternative is to show the stream like your pipe, but with an arrow on one side. This clarifies that there's a direction for reading and another direction for writing; and it allows to link the stream concept with conventions of data-flow diagramming, which uses (thin) arrows to connect processes. Your large arrow would then be understood as a zoom on such an arrow. (This convention was for example used in the book Streaming Data: Understanding the real-time pipeline by Andrew Psaltis).

But I give these subjective elements only as additional info on the top of the objective part, since opinions are a matter of taste, and there's no best way to do it.

Answer 2

Streams

In my view the best way to visualise a stream, from the point of view of a coder, is as a shared variable. That is, it is a volatile variable with concurrent access from elsewhere.

The problem with pipework analogies and the like, is that what you have in scope is not a pipe or even the spigot, but the bucket which is being filled by the pipe and from which you are periodically drawing off water (or the other way around, a bucket into which you are periodically placing water, which is then piped and drawn off elsewhere by mechanisms which are outside of the scope of your code).

Ints

On ints, you ask "do I think of an int as the container of the integer ... or as the integer only?"

In my view, unless I've misunderstood your question, an int is the data type. That is, for a given field, the data type defines the relevant set of symbols which the field can hold, and the operators which correctly manipulate those symbols. So it is neither the container nor the value itself, but a kind of metadata which specifies what type of value the field holds (or can hold).

Answer 3

There's plenty of images in internet that use:

• the pipe metaphor
• the road metaphor (like a row of ants)
• the river metaphor
• and simple arrows.

See some samples: https://cutt.ly/mfvcNoR

But if we take a look at the Java documentation we see they used a pipe metaphor. The OutputStream abstract class has an open() method, a close() method() and a flush() method. All of that indicate the piped water metaphor.

You should not forget that streams usually have a buffer, at the input end, at the output end or at both ends, so you could actually draw like a small tank where a buffer should be, meaning that most streams are not written or read from until some buffer is full. If you want go go full with such a metaphor, you could put a spigot meaning close() and open() .

A metaphor is a tool to help understanding, I believe this pipes metaphor is good enough regarding Java InputStream, OutOutStream and their specializations, but you could really go with almost any of the examples the Google Image Search brings up.

But when it's time to user readers, buffers and all the plumbing I believe abstract symbols, arrows etc. will suffice, since the "piped fluids" metaphor begins to leak (pun intended).

Regarding a stack, you can use a vertical rectangle open at the top. thick lines represent items in the stack, but items should always be flushed with the top of the stack and perhaps an upwards pointing arrow in the empty space in the lower side of the rectangle.