How ctongfei/progressbar works
1. What this repository is
- A small Java/JVM library for console progress bars with low runtime overhead.
- It is packaged as a Maven artifact and also exposes a Java 9 module.
2. Primary public API
- The main entry point for imperative use is ProgressBar.
- ProgressBarBuilder and ProgressBarStyleBuilder provide configuration/setup APIs.
- The README shows two usage modes: imperative (step, stepBy, stepTo, maxHint, setExtraMessage) and declarative wrapping of collections/streams.
3. Core progress model
- ProgressState is the central mutable/observable state for a bar.
- ProgressUpdateAction likely represents the kinds of state changes that drive redraws.
- This is the boundary between application work and visualization: user code updates state, the library turns that into terminal output.
4. Rendering layer
- ProgressBarRenderer defines how a ProgressState becomes a textual bar.
- DefaultProgressBarRenderer is the standard renderer.
- ProgressBarStyle and ProgressBarStyleBuilder define the visual language of the bar, including ASCII vs box-drawing styles.
- StringDisplayUtils handles text-width/width-alignment concerns, which matter for terminal glyphs and wide characters.
5. Console/output layer
- ProgressBarConsumer is the output abstraction for sending rendered updates somewhere.
- ConsoleProgressBarConsumer and InteractiveConsoleProgressBarConsumer are the concrete console targets.
- DelegatingProgressBarConsumer suggests composition, so output can be wrapped or adapted without changing the core progress logic.
- TerminalUtils likely handles terminal capabilities and behavior that affect redraws, line clearing, or interactive vs non-interactive consoles.
6. Declarative wrappers around workload sources
- The wrapped package adapts existing data sources so progress is tracked automatically:
- ProgressBarWrappedIterable
- ProgressBarWrappedIterator
- ProgressBarWrappedSpliterator
- ProgressBarWrappedInputStream
- ProgressBarWrappedOutputStream
- ProgressBarWrappedReader
- ProgressBarWrappedWriter
- These wrappers form a second major entry path: instead of manually calling step, the library intercepts reads/writes/iteration and advances the bar for the caller.
7. Typical data flow
- Application code performs work or iterates data.
- Work is tracked either directly through ProgressBar or indirectly through a wrapper.
- Progress updates mutate ProgressState.
- The renderer converts state into a terminal line based on the chosen style.
- The consumer sends the rendered line to the console, optionally using terminal-aware behavior for interactive redraws.
8. Parallel / multiple progress bars
- The README explicitly supports multiple simultaneous bars for parallel jobs.
- This means the output layer is designed to handle more than one active ProgressBar instance, not just a single linear task.
9. Platform and compatibility boundaries
- The presence of src/main/java9/module-info.java indicates explicit JPMS/module support.
- Tests like EastAsianDisplayTest imply the library pays attention to character width and locale-dependent terminal rendering, which is important to diagram as part of the rendering boundary.
10. Testing and quality focus
- The test suite is broad and behavior-driven: progress updates, pause/resume, ranges, speed display, wrapped iterables, multi-bar behavior, and logging integration (Slf4jTest).
- This suggests the key risks are not business logic but terminal rendering correctness and state/update semantics.
11. Documentation and developer tooling
- docs/ plus mkdocs.yml indicate a separate documentation site for API/usage guidance.
- Makefile, pom.xml, and Dependabot config show standard Java build/release and dependency maintenance tooling.
12. How to draw the architecture
- The cleanest diagram is a layered one:
- Client application on top
- Progress API / wrappers
- Progress state + rendering
- Console consumers / terminal handling
- Standard output/error terminal
- The wrapper package can be shown as an alternate ingress path that feeds into the same core progress/render/output pipeline.
Main entry points: ProgressState.java Progress state · ProgressBar.java ProgressBar · ProgressBarRenderer.java Renderer · ConsoleProgressBarConsumer.java Console consumer
Components 24
Public API
Main entry points and configuration surfaces for library users.
- ProgressBar · Main imperative handle for creating and updating a progress bar.
src/main/java/me/tongfei/progressbar/ProgressBar.java - Bar builder · Builds configured progress bar instances.
src/main/java/me/tongfei/progressbar/ProgressBarBuilder.java - Style builder · Builds visual styles for bars and glyph sets.
src/main/java/me/tongfei/progressbar/ProgressBarStyleBuilder.java
Core Engine
Progress state, update semantics, and rendering logic.
- Progress state · Central observable state for progress, rate, and messages.
src/main/java/me/tongfei/progressbar/ProgressState.java - Update action · Represents a progress mutation that can trigger redraws.
src/main/java/me/tongfei/progressbar/ProgressUpdateAction.java - Renderer · Converts progress state into a textual bar representation.
src/main/java/me/tongfei/progressbar/ProgressBarRenderer.java - Default renderer · Standard textual rendering implementation.
src/main/java/me/tongfei/progressbar/DefaultProgressBarRenderer.java - Style · Defines the bar's textual appearance and glyph choices.
src/main/java/me/tongfei/progressbar/ProgressBarStyle.java - Text width · Handles display width and alignment for wide or complex glyphs.
src/main/java/me/tongfei/progressbar/StringDisplayUtils.java
Console Output
Consumer abstractions and terminal-aware console targets.
- Consumer · Abstracts where rendered progress updates are written.
src/main/java/me/tongfei/progressbar/ProgressBarConsumer.java - Delegating consumer · Composes or adapts another consumer.
src/main/java/me/tongfei/progressbar/DelegatingProgressBarConsumer.java - Console consumer · Concrete non-interactive console target.
src/main/java/me/tongfei/progressbar/ConsoleProgressBarConsumer.java - Interactive console · Terminal-aware consumer for live redraws and line management.
src/main/java/me/tongfei/progressbar/InteractiveConsoleProgressBarConsumer.java - Terminal utils · Detects terminal behavior and supports redraw decisions.
src/main/java/me/tongfei/progressbar/TerminalUtils.java
Wrappers
Declarative adapters that track progress while iterating or streaming.
- Iterable wrapper · Advances progress while iterating collections.
src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedIterable.java - Iterator wrapper · Tracks progress for iterator consumption.
src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedIterator.java - Spliterator wrapper · Tracks progress for spliterator-based traversal.
src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedSpliterator.java - Input stream · Advances progress while reading bytes.
src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedInputStream.java - Output stream · Advances progress while writing bytes.
src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedOutputStream.java - Reader wrapper · Advances progress while reading characters.
src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedReader.java - Writer wrapper · Advances progress while writing characters.
src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedWriter.java
Platform
Module and runtime compatibility boundaries.
- JPMS module · Java 9 module descriptor for explicit module support.
src/main/java9/module-info.java - Terminal · Standard console or terminal output device.
Other components
- Client app · User code that performs work and advances progress.
Connections 26
- Client app → Bar builder: configure · Client code typically starts by configuring a bar.
- Bar builder → ProgressBar: create · Builder constructs the runtime progress bar.
- Client app → ProgressBar: step · Imperative usage advances progress directly.
- Client app → Iterable wrapper: wrap · Declarative usage can adapt existing sources.
- Client app → Input stream: wrap · I/O sources can be wrapped for automatic tracking.
- Iterable wrapper → Progress state: advance · Wrappers update shared progress state as data is consumed.
- Iterator wrapper → Progress state: advance · Iterator consumption mutates progress state.
- Spliterator wrapper → Progress state: advance · Spliterator traversal mutates progress state.
- Input stream → Progress state: advance · Read operations advance progress state.
- Output stream → Progress state: advance · Write operations advance progress state.
- Reader wrapper → Progress state: advance · Character reads advance progress state.
- Writer wrapper → Progress state: advance · Character writes advance progress state.
- ProgressBar → Progress state: mutate · Imperative API updates the central state.
- Progress state → Renderer: render · State is converted into a display string.
- Renderer → Default renderer: implements · Default renderer provides standard output formatting.
- Default renderer → Style: uses · Rendering depends on style settings and glyph choices.
- Style → Style builder: builds · Style builder configures the visual language.
- Renderer → Text width: measure · Renderer relies on display-width calculations.
- Progress state → Consumer: emit · Rendered updates are sent through a consumer abstraction.
- Consumer → Delegating consumer: compose · Consumers can be wrapped or adapted.
- Delegating consumer → Console consumer: delegate · Delegating consumer can forward to console output.
- Console consumer → Interactive console: variant · Interactive console is the live-redraw variant.
- Interactive console → Terminal utils: inspect · Interactive behavior depends on terminal capabilities.
- Console consumer → Terminal: write · Console consumers ultimately write to the terminal.
- Interactive console → Terminal: redraw · Interactive consumers redraw output on the terminal.
- JPMS module → ProgressBar: exports · JPMS descriptor exposes the public API as a module.