starmapper-core

Formerly known as StarmapperLib, this is a library of classes extracted from original Starmapper (version 1) so that other applications can use it. Currently it is somewhat in a state of flux, undergoing a redesign for version 3.

jezuch.utils.starmapper3

The core class of the core is the jezuch.utils.starmapper3.Starmapper∞ class. It does all the heavy lifting. You wrap it around a DataModel∞ and call drawImage()∞, giving it a Report∞, Config∞, Plotter∞ and a point in time (in your model's time scale). The report has to be prepared by your application, but fortunately CachedReport∞ is of great help here. The Config contains settings that affect the result (like image size, actual region of The Map to draw, whether to plot marks for nodes, etc.), which can also be used by other components, like the actual application, the Plotter and the Data Model. Plotter is the thing that turns calculated influences into pixels (see the link for some cool info).

Alternatively you can call startBatch()∞ and Starmapper will extract available reports from the Data Model, optionally filtered by a Predicate∞. See BatchMode for details.

The core tries to use many of the interfaces from Java Collections Framework∞, at least in some places. Report is a Set<NodeInfo>∞ with ability to lookup NodeInfos by Nodes, via a view Map<Node, NodeInfo>∞ (the Report implementation must ensure that there are no duplicate NodeInfo for any Node and must keep consistency between NodeInfo's Node and the mapping's key - you add/remove a NodeInfo to/from a Set<NodeInfo>∞ and the mapping is added/removed automatically; that's why it's not a Map<Node, NodeInfo>∞ itself). That means that you can use Iterators∞ and/or enhanced loops to get the contents (but see below).

There are of course some convenience classes, like the DefaultNodesLookup∞ class, which is of interest to implementers of custom Reports. It's an adapter class that can create a view of the Report as a Map<Node, NodeInfo> for lookup purposes. It's rather inefficient (its implementation is iterative) but can be handy.

jezuch.utils.starmapper3.model

This package consists of several interfaces that define a Data Model. The default Data Model is for Stars!, of course, in package jezuch.utils.starmapper3.model.stars :) There's also an (somewhat experimental) implementation for Thousand Parsec∞ which connects directly to the server and pulls nodes and regions data from there (in package jezuch.utils.starmapper3.model.tparsec).

jezuch.utils.starmapper3.model.common

This subpackage contains some useful tools that may be helpful when implementing a Data Model. These tools are an implementation of Validator∞ for files and directories (mostly useless, because of relative paths) and several implementations of Producer∞ interface that can be used to collect reports from a directory of files. There's also FileNamePattern∞ class, quite useful but with a cryptic syntax (and which is also used by starmapper-app-cli to generate names for image files).

jezuch.utils.starmapper3.event

Starmapper is a good citizen and it offers to give feedback via events. The events are simple: batch started, image started, image progress, image errored, image finished and batch finished. It's all implemented just like in AWT - there's a ProgressListener∞ interface and a ProgressEvent∞ class. There are addProgressListener∞ and removeProgressListener∞ methods in Starmapper class. The only difference is that event IDs are Java 5's enum, not integer constants, but that's just a detail.

The events are delivered synchronously. No funny business with AWT's Event Dispatch Thread and such. The usual remarks on long tasks in event handlers apply.

jezuch.utils.starmapper3.plotters

This package is a collection of more or less useful plotters. This is important thing to have, because the default one generates really flat and boring pictures :)

jezuch.utils.starmapper3.config

The last piece of puzzle is the unified configuration model, which is implemented in this package. See the link for details.

IO Iterators

There's one thing to beware: there's a utility class called ReportReaderReport∞ that extracts the NodeInfos from a Producer∞ of NodeInfos (created by Data Model). This means that you have to expect IOException∞s (and other exceptions), but Iterator and stuff have methods that don't declare any exceptions. ReportReaderReport handles that by wrapping these exceptions in a unchecked RuntimeException∞, which has to be caught and examined for the cause. The library handles this part, so you don't have to worry about this, but if there's a bug somewhere in the library or your code using this part of the library, it can cause problems. There's usually some native resource inside there (usually a Reader∞), and all Java programmers know that it has to be released as early as possible (if you don't know that, I won't call you Java programmer). If everything goes well, the library handles that and releases the resource when it finishes reading from it or if it throws an exception. If something else throws an exception during iteration - and the control escapes the loops - then you have an unreleased native resource object waiting to be finalized. That's not a tragedy, but can cause problems.