Last edited on
2007-11-28 09:20:39 by KrzysztofSobolewski
[Rewrite some stuff to reflect recent developments]
Additions:
The core class of the core is the [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/Starmapper.html jezuch.utils.starmapper3.Starmapper]] class. It does all the heavy lifting. You wrap it around a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/model/DataModel.html DataModel]] and call [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/Starmapper.html#drawImage(jezuch.utils.starmapper3.Report,%20jezuch.utils.starmapper3.config.Config,%20jezuch.utils.starmapper3.Plotter,%20int,%20java.net.URI,%20java.lang.String) drawImage()]], giving it a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/Report.html Report]], [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/config/Config.html Config]], [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/Plotter.html Plotter]] and a point in time (in your model's time scale). The report has to be prepared by your application, but fortunately [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/CachedReport.html 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 [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/Starmapper.html#startBatch(jezuch.utils.Predicate,%20jezuch.utils.starmapper3.config.Config,%20jezuch.utils.starmapper3.Plotter,%20java.net.URI,%20java.lang.String) startBatch()]] and Starmapper will extract available reports from the [[DataModel Data Model]], optionally filtered by a [[http://starmapper.sourceforge.net/api/jezuch-utils/trunk/jezuch/utils/Predicate.html Predicate]]. See [[BatchMode]] for details.
The core tries to use many of the interfaces from [[http://java.sun.com/j2se/1.5.0/docs/guide/collections/reference.html Java Collections Framework]], at least in some places. Report is a [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html Set]] with ability to lookup NodeInfos by Nodes, via a view [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html Map]] (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 [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html Set]] and the mapping is added/removed automatically; that's why it's not a [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html Map]] itself). That means that you can use [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Iterator.html Iterators]] and/or enhanced loops to get the contents (but see below).
There's one thing to beware: there's a utility class called [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/ReportReaderReport.html ReportReaderReport]] that extracts the NodeInfos from a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/model/Producer.html Producer]] of NodeInfos (created by Data Model). This means that you have to expect [[http://java.sun.com/j2se/1.5.0/docs/api/java/io/IOException.html 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 [[http://java.sun.com/j2se/1.5.0/docs/api/java/lang/RuntimeException.html 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 [[http://java.sun.com/j2se/1.5.0/docs/api/java/io/Reader.html 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.
Deletions:
The core class of the core is the [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/Starmapper.html jezuch.utils.starmapper3.Starmapper]] class. It does all the heavy lifting. You wrap it around a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/NodesMap.html NodesMap]] and call [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/Starmapper.html#drawImage(jezuch.utils.starmapper3.Report,%20jezuch.utils.starmapper3.config.Config,%20jezuch.utils.starmapper3.Plotter,%20int) drawImage]], giving it a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/Report.html Report]], [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/config/Config.html Config]], [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/Plotter.html Plotter]] and a point in time (in your model's time scale). The report has to be prepared by your application, but fortunately [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/CachedReport.html 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).
The whole core tries to use many of the interfaces from [[http://java.sun.com/j2se/1.5.0/docs/guide/collections/reference.html Java Collections Framework]]. NodesMap is a [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html Set]] with some additions (list of Regions as [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/SortedMap.html SortedMap]] and ability to lookup Nodes by their names via a view [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html Map]]). Report is a [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html Set]] with ability to lookup NodeInfos by Nodes, again via a view [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html Map]] (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 [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html Set]] and the mapping is added/removed automatically; that's why it's not a [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html Map]] itself).
All that means that you can use [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Iterator.html Iterators]] and/or enhanced loops to get the contents (but see below).
One thing to note is that NodesMap is a class, while Report is an interface, implemented among others by a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/CachedReport.html CachedReport]] (which caches its data in memory and automatically merges additions with existing entries) and [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/ReportReaderReport.html ReportReaderReport]] (which looks like a Report but is just a thin wrapper around an [[http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Iterable.html Iterable]] of NodeInfos. Why so much flexibility with Reports and so little with NodesMap? The answer is that with NodesMap it's not that much needed. NodesMap can construct itself from a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/model/DataModel.html DataModel]] and it remains static (thinking of that, it seems that more dynamism with nodes might be handy - as always, patches welcome!). Reports, on the other hand, are quite dynamic. CachedReport faciliates a handy "accumulator" for NodeInfos (the merging process is delegated to NodeInfos). It's just a Set, so you can use [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html#addAll(java.util.Collection) addAll()]] to add another Report (usually a ReportReaderReport), or whatever what looks like a Set, and don't worry about conflicts (OK, you have to worry, but while designing a [[DataModel Data Model]]).
The [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/ReportDescriptor.html ReportDescriptor]] class is of interest to users of [[BatchMode batch mode]].
There's one thing to beware: there's a utility class called [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/ReportReaderReport.html ReportReaderReport]] that extracts the NodeInfos from an [[http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Iterable.html Iterable]] of NodeInfos (created by Data Model). This means that you have to expect [[http://java.sun.com/j2se/1.5.0/docs/api/java/io/IOException.html IOException]]s, **but** Iterator and stuff have methods that don't declare any exceptions. ReportReaderReport (and actually all Iterables returned from Data Model) handles that by wrapping these exceptions in a unchecked [[http://java.sun.com/j2se/1.5.0/docs/api/java/lang/RuntimeException.html RuntimeException]], which has to be caught and examined. 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 [[http://java.sun.com/j2se/1.5.0/docs/api/java/io/Reader.html 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 IOException. 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.
**NOTE1**: normally there's no need t worry about that, this is an issue only if you have bugs [ok, there are always bugs, but...].
**NOTE2**: if you are going to implement Iterators doing IO, try to be nice and close the IO upon end and catch any expected exception and close the IO before rethrowing.
===Things to more or less possibly change===
Extend the notion of encoders. Actually what's in versions 3 and 2 is somewhat a step back from version 1 - originally I wanted it to make animated GIFs (they were extremely cool thing to watch after a long and exciting Stars! game), so I provided some hooks to plug in so-called "image encoders". But I didn't know at this time how to do proper plugin system, so it got lost somehow [the truth is, I still don't know how to do plugins ;)]. In version 3 the application takes care of encoding the images and it's a thing that each application duplicates, and that's not that good.
Additions:
This package consists of several interfaces that define a [[DataModel 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 [[http://www.thousandparsec.net/ 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 [[DataModel Data Model]]. These tools are an implementation of [[http://starmapper.sourceforge.net/api/jezuch-utils/trunk/jezuch/utils/parameters/Validator.html Validator]] for files and directories (mostly useless, because of relative paths) and several implementations of [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/model/Producer.html Producer]] interface that can be used to collect reports from a directory of files. There's also [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/model/common/FileNamePattern.html FileNamePattern]] class, quite useful but with a cryptic syntax (and which is also used by [[StarmapperAppCli starmapper-app-cli]] to generate names for image files).
Deletions:
This package consists of several interfaces that define a [[DataModel Data Model]]. The default Data Model is for Stars!, of course :) There's also an experimental implementation for [[http://www.thousandparsec.net/ Thousand Parsec]] which connects directly to the server and pulls nodes and regions data from there.
Additions:
The core class of the core is the [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/Starmapper.html jezuch.utils.starmapper3.Starmapper]] class. It does all the heavy lifting. You wrap it around a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/NodesMap.html NodesMap]] and call [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/Starmapper.html#drawImage(jezuch.utils.starmapper3.Report,%20jezuch.utils.starmapper3.config.Config,%20jezuch.utils.starmapper3.Plotter,%20int) drawImage]], giving it a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/Report.html Report]], [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/config/Config.html Config]], [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/Plotter.html Plotter]] and a point in time (in your model's time scale). The report has to be prepared by your application, but fortunately [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/CachedReport.html 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).
The whole core tries to use many of the interfaces from [[http://java.sun.com/j2se/1.5.0/docs/guide/collections/reference.html Java Collections Framework]]. NodesMap is a [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html Set]] with some additions (list of Regions as [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/SortedMap.html SortedMap]] and ability to lookup Nodes by their names via a view [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html Map]]). Report is a [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html Set]] with ability to lookup NodeInfos by Nodes, again via a view [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html Map]] (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 [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html Set]] and the mapping is added/removed automatically; that's why it's not a [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html Map]] itself).
One thing to note is that NodesMap is a class, while Report is an interface, implemented among others by a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/CachedReport.html CachedReport]] (which caches its data in memory and automatically merges additions with existing entries) and [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/ReportReaderReport.html ReportReaderReport]] (which looks like a Report but is just a thin wrapper around an [[http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Iterable.html Iterable]] of NodeInfos. Why so much flexibility with Reports and so little with NodesMap? The answer is that with NodesMap it's not that much needed. NodesMap can construct itself from a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/model/DataModel.html DataModel]] and it remains static (thinking of that, it seems that more dynamism with nodes might be handy - as always, patches welcome!). Reports, on the other hand, are quite dynamic. CachedReport faciliates a handy "accumulator" for NodeInfos (the merging process is delegated to NodeInfos). It's just a Set, so you can use [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html#addAll(java.util.Collection) addAll()]] to add another Report (usually a ReportReaderReport), or whatever what looks like a Set, and don't worry about conflicts (OK, you have to worry, but while designing a [[DataModel Data Model]]).
This package consists of several interfaces that define a [[DataModel Data Model]]. The default Data Model is for Stars!, of course :) There's also an experimental implementation for [[http://www.thousandparsec.net/ Thousand Parsec]] which connects directly to the server and pulls nodes and regions data from there.
There's one thing to beware: there's a utility class called [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/ReportReaderReport.html ReportReaderReport]] that extracts the NodeInfos from an [[http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Iterable.html Iterable]] of NodeInfos (created by Data Model). This means that you have to expect [[http://java.sun.com/j2se/1.5.0/docs/api/java/io/IOException.html IOException]]s, **but** Iterator and stuff have methods that don't declare any exceptions. ReportReaderReport (and actually all Iterables returned from Data Model) handles that by wrapping these exceptions in a unchecked [[http://java.sun.com/j2se/1.5.0/docs/api/java/lang/RuntimeException.html RuntimeException]], which has to be caught and examined. 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 [[http://java.sun.com/j2se/1.5.0/docs/api/java/io/Reader.html 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 IOException. 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.
**NOTE2**: if you are going to implement Iterators doing IO, try to be nice and close the IO upon end and catch any expected exception and close the IO before rethrowing.
Deletions:
The core class of the core is the [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/Starmapper.html jezuch.utils.starmapper3.Starmapper]] class. It does all the heavy lifting. You wrap it around a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/NodesMap.html NodesMap]] and call [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/Starmapper.html#drawImage(jezuch.utils.starmapper3.Report,%20jezuch.utils.starmapper3.config.Config,%20jezuch.utils.starmapper3.Plotter,%20int) drawImage]], giving it a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/Report.html Report]], [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/config/Config.html Config]], [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/Plotter.html Plotter]] and a point in time (in you model's time scale). The report has to be prepared by your application, buy fortunately [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/CachedReport.html CachedReport]] is of great help here. The Config describes some settings that affect the result (like image size, actual region of The Map to draw, whether to plot marks for nodes, etc.). [[Plotter]] is the thing that turns calculated influences into pixels (see the link for some cool info).
The whole core tries to use much of the interfaces from [[http://java.sun.com/j2se/1.5.0/docs/guide/collections/reference.html Java Collections Framework]]. NodesMap is a [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html Set]] with some additions (list of Regions as [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/SortedMap.html SortedMap]] and ability to lookup Nodes by their names via a view [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html Map]]). Report is a [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html Set]] with ability to lookup NodeInfos by Nodes, again via a view [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html Map]] (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 [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html Set]] and the mapping is added/removed automatically; that's why it's not a [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html Map]] itself).
One thing to note is that NodesMap is a class, while Report is an interface, implemented among others by a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/CachedReport.html CachedReport]] (which caches its data in memory and automatically merges additions with existing entries) and [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/ReaderSourceReport.html ReaderSourceReport]] (which looks like a Report but is just a thin wrapper around a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/model/ReportReader.html ReportReader]] and a [[http://starmapper.sourceforge.net/api/jezuch-utils/trunk/jezuch/utils/io/ReaderSource.html ReaderSource]]). Why so much flexibility with Reports and so little with NodesMap? The answer is that with NodesMap it's not that much needed. NodesMap can construct itself given a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/model/NodeReader.html NodeReader]] with a [[http://starmapper.sourceforge.net/api/jezuch-utils/trunk/jezuch/utils/io/ReaderSource.html ReaderSource]] and it remains static (thinking of that, it seems that more dynamism with nodes might be handy - as always, patches welcome!). Reports, on the other hand, are quite dynamic. CachedReport faciliates a handy "accumulator" for NodeInfos (the merging process is delegated to NodeInfos). It's just a Set, so you can [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html#addAll(java.util.Collection) addAll()]] another Report (usually a ReaderSourceReport), or whatever what looks like a Set, and don't worry about conflicts (OK, you have to worry, but while designing a [[DataModel Data Model]]).
This package consists of several interfaces that define a [[DataModel Data Model]]. The default Data Model is for Stars!, of course :)
There's one thing to beware: there's a utility class called [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/ReaderSourceReport.html ReaderSourceReport]] that extracts the NodeInfos from a [[http://java.sun.com/j2se/1.5.0/docs/api/java/io/Reader.html Reader]] (using Data Model's [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/model/ReportReader.html ReportReader]]). This means that you have to expect [[http://java.sun.com/j2se/1.5.0/docs/api/java/io/IOException.html IOException]]s, **but** Iterator and stuff have methods that don't declare any exceptions. ReaderSourceReport handles that by wrapping these exceptions in a unchecked [[http://java.sun.com/j2se/1.5.0/docs/api/java/lang/RuntimeException.html RuntimeException]], which has to be caught and examined. 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 a Reader inside there, and all Java programmers know that it has to be closed 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 closes the Reader if it finishes reading from it or if it throws an IOException. If **something else** throws an exception during iteration - and the control escapes the loop - then you have an unclosed Reader object waiting to be finalized. That's not a tragedy, but //can// cause problems.
**NOTE2**: if you are going to implement Iterators doing IO, try to be nice and catch any expected exception and close the IO before rethrowing.
Additions:
One thing to note is that NodesMap is a class, while Report is an interface, implemented among others by a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/CachedReport.html CachedReport]] (which caches its data in memory and automatically merges additions with existing entries) and [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/ReaderSourceReport.html ReaderSourceReport]] (which looks like a Report but is just a thin wrapper around a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/model/ReportReader.html ReportReader]] and a [[http://starmapper.sourceforge.net/api/jezuch-utils/trunk/jezuch/utils/io/ReaderSource.html ReaderSource]]). Why so much flexibility with Reports and so little with NodesMap? The answer is that with NodesMap it's not that much needed. NodesMap can construct itself given a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/model/NodeReader.html NodeReader]] with a [[http://starmapper.sourceforge.net/api/jezuch-utils/trunk/jezuch/utils/io/ReaderSource.html ReaderSource]] and it remains static (thinking of that, it seems that more dynamism with nodes might be handy - as always, patches welcome!). Reports, on the other hand, are quite dynamic. CachedReport faciliates a handy "accumulator" for NodeInfos (the merging process is delegated to NodeInfos). It's just a Set, so you can [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html#addAll(java.util.Collection) addAll()]] another Report (usually a ReaderSourceReport), or whatever what looks like a Set, and don't worry about conflicts (OK, you have to worry, but while designing a [[DataModel Data Model]]).
Deletions:
One thing to note is that NodesMap is a class, while Report is an interface, implemented among others by a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/CachedReport.html CachedReport]] (which caches its data in memory and automatically merges additions with existing entries) and [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/ReaderSourceReport.html ReaderSourceReport]] (which looks like a Report but is just a thin wrapper around a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/model/ReportReader.html ReportReader]] and a [[http://starmapper.sourceforge.net/api/jezuch-utils/jezuch/utils/io/ReaderSource.html ReaderSource]]). Why so much flexibility with Reports and so little with NodesMap? The answer is that with NodesMap it's not that much needed. NodesMap can construct itself given a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/model/NodeReader.html NodeReader]] with a [[http://starmapper.sourceforge.net/api/jezuch-utils/jezuch/utils/io/ReaderSource.html ReaderSource]] and it remains static (thinking of that, it seems that more dynamism with nodes might be handy - as always, patches welcome!). Reports, on the other hand, are quite dynamic. CachedReport faciliates a handy "accumulator" for NodeInfos (the merging process is delegated to NodeInfos). It's just a Set, so you can [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html#addAll(java.util.Collection) addAll()]] another Report (usually a ReaderSourceReport), or whatever what looks like a Set, and don't worry about conflicts (OK, you have to worry, but while designing a [[DataModel Data Model]]).
Additions:
The core class of the core is the [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/Starmapper.html jezuch.utils.starmapper3.Starmapper]] class. It does all the heavy lifting. You wrap it around a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/NodesMap.html NodesMap]] and call [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/Starmapper.html#drawImage(jezuch.utils.starmapper3.Report,%20jezuch.utils.starmapper3.config.Config,%20jezuch.utils.starmapper3.Plotter,%20int) drawImage]], giving it a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/Report.html Report]], [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/config/Config.html Config]], [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/Plotter.html Plotter]] and a point in time (in you model's time scale). The report has to be prepared by your application, buy fortunately [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/CachedReport.html CachedReport]] is of great help here. The Config describes some settings that affect the result (like image size, actual region of The Map to draw, whether to plot marks for nodes, etc.). [[Plotter]] is the thing that turns calculated influences into pixels (see the link for some cool info).
One thing to note is that NodesMap is a class, while Report is an interface, implemented among others by a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/CachedReport.html CachedReport]] (which caches its data in memory and automatically merges additions with existing entries) and [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/ReaderSourceReport.html ReaderSourceReport]] (which looks like a Report but is just a thin wrapper around a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/model/ReportReader.html ReportReader]] and a [[http://starmapper.sourceforge.net/api/jezuch-utils/jezuch/utils/io/ReaderSource.html ReaderSource]]). Why so much flexibility with Reports and so little with NodesMap? The answer is that with NodesMap it's not that much needed. NodesMap can construct itself given a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/model/NodeReader.html NodeReader]] with a [[http://starmapper.sourceforge.net/api/jezuch-utils/jezuch/utils/io/ReaderSource.html ReaderSource]] and it remains static (thinking of that, it seems that more dynamism with nodes might be handy - as always, patches welcome!). Reports, on the other hand, are quite dynamic. CachedReport faciliates a handy "accumulator" for NodeInfos (the merging process is delegated to NodeInfos). It's just a Set, so you can [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html#addAll(java.util.Collection) addAll()]] another Report (usually a ReaderSourceReport), or whatever what looks like a Set, and don't worry about conflicts (OK, you have to worry, but while designing a [[DataModel Data Model]]).
The [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/ReportDescriptor.html ReportDescriptor]] class is of interest to users of [[BatchMode batch mode]].
There are of course some convenience classes, like the [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/DefaultNodesLookup.html 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 for lookup purposes. It's rather inefficient (its implementation is iterative) but can be handy.
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 [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/event/ProgressListener.html ProgressListener]] interface and a [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/event/ProgressEvent.html ProgressEvent]] class. There are [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/Starmapper.html#addProgressListener(jezuch.utils.starmapper3.event.ProgressListener) addProgressListener]] and [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/Starmapper.html#removeProgressListener(jezuch.utils.starmapper3.event.ProgressListener) 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.
There's one thing to beware: there's a utility class called [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/ReaderSourceReport.html ReaderSourceReport]] that extracts the NodeInfos from a [[http://java.sun.com/j2se/1.5.0/docs/api/java/io/Reader.html Reader]] (using Data Model's [[http://starmapper.sourceforge.net/api/starmapper3/trunk/jezuch/utils/starmapper3/model/ReportReader.html ReportReader]]). This means that you have to expect [[http://java.sun.com/j2se/1.5.0/docs/api/java/io/IOException.html IOException]]s, **but** Iterator and stuff have methods that don't declare any exceptions. ReaderSourceReport handles that by wrapping these exceptions in a unchecked [[http://java.sun.com/j2se/1.5.0/docs/api/java/lang/RuntimeException.html RuntimeException]], which has to be caught and examined. 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 a Reader inside there, and all Java programmers know that it has to be closed 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 closes the Reader if it finishes reading from it or if it throws an IOException. If **something else** throws an exception during iteration - and the control escapes the loop - then you have an unclosed Reader object waiting to be finalized. That's not a tragedy, but //can// cause problems.
Deletions:
The core class of the core is the [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/Starmapper.html jezuch.utils.starmapper3.Starmapper]] class. It does all the heavy lifting. You wrap it around a [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/NodesMap.html NodesMap]] and call [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/Starmapper.html#drawImage(jezuch.utils.starmapper3.Report,%20jezuch.utils.starmapper3.config.Config,%20jezuch.utils.starmapper3.Plotter,%20int) drawImage]], giving it a [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/Report.html Report]], [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/config/Config.html Config]], [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/Plotter.html Plotter]] and a point in time (in you model's time scale). The report has to be prepared by your application, buy fortunately [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/CachedReport.html CachedReport]] is of great help here. The Config describes some settings that affect the result (like image size, actual region of The Map to draw, whether to plot marks for nodes, etc.). [[Plotter]] is the thing that turns calculated influences into pixels (see the link for some cool info).
One thing to note is that NodesMap is a class, while Report is an interface, implemented among others by a [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/CachedReport.html CachedReport]] (which caches its data in memory and automatically merges additions with existing entries) and [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/ReaderSourceReport.html ReaderSourceReport]] (which looks like a Report but is just a thin wrapper around a [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/model/ReportReader.html ReportReader]] and a [[http://starmapper.sourceforge.net/api/jezuch-utils/jezuch/utils/io/ReaderSource.html ReaderSource]]). Why so much flexibility with Reports and so little with NodesMap? The answer is that with NodesMap it's not that much needed. NodesMap can construct itself given a [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/model/NodeReader.html NodeReader]] with a [[http://starmapper.sourceforge.net/api/jezuch-utils/jezuch/utils/io/ReaderSource.html ReaderSource]] and it remains static (thinking of that, it seems that more dynamism with nodes might be handy - as always, patches welcome!). Reports, on the other hand, are quite dynamic. CachedReport faciliates a handy "accumulator" for NodeInfos (the merging process is delegated to NodeInfos). It's just a Set, so you can [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html#addAll(java.util.Collection) addAll()]] another Report (usually a ReaderSourceReport), or whatever what looks like a Set, and don't worry about conflicts (OK, you have to worry, but while designing a [[DataModel Data Model]]).
The [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/ReportDescriptor.html ReportDescriptor]] class is of interest to users of [[BatchMode batch mode]].
There are of course some convenience classes, like the [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/DefaultNodesLookup.html 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 for lookup purposes. It's rather inefficient (its implementation is iterative) but can be handy.
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 [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/event/ProgressListener.html ProgressListener]] interface and a [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/event/ProgressEvent.html ProgressEvent]] class. There are [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/Starmapper.html#addProgressListener(jezuch.utils.starmapper3.event.ProgressListener) addProgressListener]] and [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/Starmapper.html#removeProgressListener(jezuch.utils.starmapper3.event.ProgressListener) 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.
There's one thing to beware: there's a utility class called [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/ReaderSourceReport.html ReaderSourceReport]] that extracts the NodeInfos from a [[http://java.sun.com/j2se/1.5.0/docs/api/java/io/Reader.html Reader]] (using Data Model's [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/model/ReportReader.html ReportReader]]). This means that you have to expect [[http://java.sun.com/j2se/1.5.0/docs/api/java/io/IOException.html IOException]]s, **but** Iterator and stuff have methods that don't declare any exceptions. ReaderSourceReport handles that by wrapping these exceptions in a unchecked [[http://java.sun.com/j2se/1.5.0/docs/api/java/lang/RuntimeException.html RuntimeException]], which has to be caught and examined. 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 a Reader inside there, and all Java programmers know that it has to be closed 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 closes the Reader if it finishes reading from it or if it throws an IOException. If **something else** throws an exception during iteration - and the control escapes the loop - then you have an unclosed Reader object waiting to be finalized. That's not a tragedy, but //can// cause problems.
Additions:
The [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/ReportDescriptor.html ReportDescriptor]] class is of interest to users of [[BatchMode batch mode]].
There are of course some convenience classes, like the [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/DefaultNodesLookup.html 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 for lookup purposes. It's rather inefficient (its implementation is iterative) but can be handy.
==jezuch.utils.starmapper3.plotters==
This package is a collection of more or less useful [[Plotter plotters]]. This is important thing to have, because the default one generates really flat and boring pictures :)
===Things to more or less possibly change===
Extend the notion of encoders. Actually what's in versions 3 and 2 is somewhat a step back from version 1 - originally I wanted it to make animated GIFs (they were extremely cool thing to watch after a long and exciting Stars! game), so I provided some hooks to plug in so-called "image encoders". But I didn't know at this time how to do proper plugin system, so it got lost somehow [the truth is, I still don't know how to do plugins ;)]. In version 3 the application takes care of encoding the images and it's a thing that each application duplicates, and that's not that good.
Deletions:
There's last one utility class not mentioned yet. It's the [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/DefaultNodesLookup.html DefaultNodesLookup]] class, which is of interest to implementers of custom Report. It's an adapter class that can create a view of the Report as a Map for lookup purposes. It's rather inefficient (its implementation is iterative) but can be handy.
===Things to quite possibly change===
Right now it's very simple (from the outside; LOC count and various complexity measures for Starmapper class are a different thing), create an instance, add a listener and fire drawImage() with a Report. Re-crunch the Report and repeat. It places too much load on the application and it's the kind of load that each application wants to do almost the same thing with the Reports. So Starmapper should be more abstract and do these things itself. Most probably it should be something like "here's the pattern/list of input files, go hunt for the reports and give me back the images".
Another thing to do is to extend the notion of encoders. Actually what's in versions 3 and 2 is somewhat a stap back from version 1 - originally I wanted it to make animated GIFs (they were extremely cool thing to watch after a long and exciting Stars! game), so I provided some hooks to plug in so-called "image encoders". But I didn't know at this time how to do proper plugin system, so it got lost somehow [the truth is, I still don't know how to do plugins ;)]. In version 3 the application takes care of encoding the images and it's another thing that each application duplicates.
Additions:
There's last one utility class not mentioned yet. It's the [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/DefaultNodesLookup.html DefaultNodesLookup]] class, which is of interest to implementers of custom Report. It's an adapter class that can create a view of the Report as a Map for lookup purposes. It's rather inefficient (its implementation is iterative) but can be handy.
Additions:
==jezuch.utils.starmapper3.config==
The last piece of puzzle is the [[UnifiedConfigurationModel unified configuration model]], which is implemented in this package. See the link for details.
Additions:
==jezuch.utils.starmapper3==
==jezuch.utils.starmapper3.model==
This package consists of several interfaces that define a [[DataModel Data Model]]. The default Data Model is for Stars!, of course :)
==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 [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/event/ProgressListener.html ProgressListener]] interface and a [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/event/ProgressEvent.html ProgressEvent]] class. There are [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/Starmapper.html#addProgressListener(jezuch.utils.starmapper3.event.ProgressListener) addProgressListener]] and [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/Starmapper.html#removeProgressListener(jezuch.utils.starmapper3.event.ProgressListener) 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.
Additions:
One thing to note is that NodesMap is a class, while Report is an interface, implemented among others by a [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/CachedReport.html CachedReport]] (which caches its data in memory and automatically merges additions with existing entries) and [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/ReaderSourceReport.html ReaderSourceReport]] (which looks like a Report but is just a thin wrapper around a [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/model/ReportReader.html ReportReader]] and a [[http://starmapper.sourceforge.net/api/jezuch-utils/jezuch/utils/io/ReaderSource.html ReaderSource]]). Why so much flexibility with Reports and so little with NodesMap? The answer is that with NodesMap it's not that much needed. NodesMap can construct itself given a [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/model/NodeReader.html NodeReader]] with a [[http://starmapper.sourceforge.net/api/jezuch-utils/jezuch/utils/io/ReaderSource.html ReaderSource]] and it remains static (thinking of that, it seems that more dynamism with nodes might be handy - as always, patches welcome!). Reports, on the other hand, are quite dynamic. CachedReport faciliates a handy "accumulator" for NodeInfos (the merging process is delegated to NodeInfos). It's just a Set, so you can [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html#addAll(java.util.Collection) addAll()]] another Report (usually a ReaderSourceReport), or whatever what looks like a Set, and don't worry about conflicts (OK, you have to worry, but while designing a [[DataModel Data Model]]).
Additions:
The whole core tries to use much of the interfaces from [[http://java.sun.com/j2se/1.5.0/docs/guide/collections/reference.html Java Collections Framework]]. NodesMap is a [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html Set]] with some additions (list of Regions as [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/SortedMap.html SortedMap]] and ability to lookup Nodes by their names via a view [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html Map]]). Report is a [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html Set]] with ability to lookup NodeInfos by Nodes, again via a view [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html Map]] (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 [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html Set]] and the mapping is added/removed automatically; that's why it's not a [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html Map]] itself).
All that means that you can use [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Iterator.html Iterators]] and/or enhanced loops to get the contents (but see below).
Deletions:
The whole core tries to use much of the interfaces from [[http://java.sun.com/j2se/1.5.0/docs/guide/collections/reference.html]]. Report is a [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html Set]] of NodeInfos with additional method to return a view of the Report as a [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html Map]] of Node -> NodeInfo mappings (the Report implementation must ensure that there are no duplicate NodeInfo for any Node). [**NOTE**: why not change it to just Map?] That means that you can use [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Iterator.html Iterator]]s and/or enhanced loops to get the contents.
Additions:
There's one thing to beware: there's a utility class called [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/ReaderSourceReport.html ReaderSourceReport]] that extracts the NodeInfos from a [[http://java.sun.com/j2se/1.5.0/docs/api/java/io/Reader.html Reader]] (using Data Model's [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/model/ReportReader.html ReportReader]]). This means that you have to expect [[http://java.sun.com/j2se/1.5.0/docs/api/java/io/IOException.html IOException]]s, **but** Iterator and stuff have methods that don't declare any exceptions. ReaderSourceReport handles that by wrapping these exceptions in a unchecked [[http://java.sun.com/j2se/1.5.0/docs/api/java/lang/RuntimeException.html RuntimeException]], which has to be caught and examined. 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 a Reader inside there, and all Java programmers know that it has to be closed 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 closes the Reader if it finishes reading from it or if it throws an IOException. If **something else** throws an exception during iteration - and the control escapes the loop - then you have an unclosed Reader object waiting to be finalized. That's not a tragedy, but //can// cause problems.
**NOTE1**: normally there's no need t worry about that, this is an issue only if you have bugs [ok, there are always bugs, but...].
**NOTE2**: if you are going to implement Iterators doing IO, try to be nice and catch any expected exception and close the IO before rethrowing.
Deletions:
There's one thing to beware: there's a utility class called [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/ReaderSourceReport.html ReaderSourceReport]] that extracts the NodeInfos from a [[http://java.sun.com/j2se/1.5.0/docs/api/java/io/Reader.html Reader]] (using Data Model's [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/model/ReportReader.html ReportReader]]). This means that you have to expect [[http://java.sun.com/j2se/1.5.0/docs/api/java/io/IOException.html IOException]]s, **but** Iterator and stuff have methods that don't declare any exceptions. ReaderSourceReport handles that by wrapping these exceptions in a unchecked [[http://java.sun.com/j2se/1.5.0/docs/api/java/lang/RuntimeException.html RuntimeException]], which has to be caught and examined. 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 a Reader inside there, and all Java programmers know that it has to be closed 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 closes the Reader if it finishes reading from it or if it throws an IOException. If **something else** throws an exception during iteration - and the control escapes the loop - then you have an unclosed Reader object waiting to be finalized. That's not a tragedy, but //can// cause problems. **NOTE1**: normally there's no need t worry about that, this is an issue only if you have bugs [ok, there are always bugs, but...]; **NOTE2**: if you are going to implement Iterators doing IO, try to be nice and catch any expected exception and close the IO before rethrowing.
Additions:
The whole core tries to use much of the interfaces from [[http://java.sun.com/j2se/1.5.0/docs/guide/collections/reference.html]]. Report is a [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html Set]] of NodeInfos with additional method to return a view of the Report as a [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html Map]] of Node -> NodeInfo mappings (the Report implementation must ensure that there are no duplicate NodeInfo for any Node). [**NOTE**: why not change it to just Map?] That means that you can use [[http://java.sun.com/j2se/1.5.0/docs/api/java/util/Iterator.html Iterator]]s and/or enhanced loops to get the contents.
===IO Iterators===
There's one thing to beware: there's a utility class called [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/ReaderSourceReport.html ReaderSourceReport]] that extracts the NodeInfos from a [[http://java.sun.com/j2se/1.5.0/docs/api/java/io/Reader.html Reader]] (using Data Model's [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/model/ReportReader.html ReportReader]]). This means that you have to expect [[http://java.sun.com/j2se/1.5.0/docs/api/java/io/IOException.html IOException]]s, **but** Iterator and stuff have methods that don't declare any exceptions. ReaderSourceReport handles that by wrapping these exceptions in a unchecked [[http://java.sun.com/j2se/1.5.0/docs/api/java/lang/RuntimeException.html RuntimeException]], which has to be caught and examined. 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 a Reader inside there, and all Java programmers know that it has to be closed 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 closes the Reader if it finishes reading from it or if it throws an IOException. If **something else** throws an exception during iteration - and the control escapes the loop - then you have an unclosed Reader object waiting to be finalized. That's not a tragedy, but //can// cause problems. **NOTE1**: normally there's no need t worry about that, this is an issue only if you have bugs [ok, there are always bugs, but...]; **NOTE2**: if you are going to implement Iterators doing IO, try to be nice and catch any expected exception and close the IO before rethrowing.
Right now it's very simple (from the outside; LOC count and various complexity measures for Starmapper class are a different thing), create an instance, add a listener and fire drawImage() with a Report. Re-crunch the Report and repeat. It places too much load on the application and it's the kind of load that each application wants to do almost the same thing with the Reports. So Starmapper should be more abstract and do these things itself. Most probably it should be something like "here's the pattern/list of input files, go hunt for the reports and give me back the images".
Deletions:
Right now it's very simple (from he outside, LOC count and various complexity measures for Starmapper class are a different thing), create an instance, add a listener and fire drawImage() with a Report. Re-crunch the Report and repeat. It places too much load on the application and it's the kind of load that each application wants to do almost the same thing with the Reports. So Starmapper should be more abstract and do these things itself. Most probably it should be something like "here's the pattern/list of input files, go hunt for the reports and give me back the images".
Additions:
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.
The core class of the core is the [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/Starmapper.html jezuch.utils.starmapper3.Starmapper]] class. It does all the heavy lifting. You wrap it around a [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/NodesMap.html NodesMap]] and call [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/Starmapper.html#drawImage(jezuch.utils.starmapper3.Report,%20jezuch.utils.starmapper3.config.Config,%20jezuch.utils.starmapper3.Plotter,%20int) drawImage]], giving it a [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/Report.html Report]], [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/config/Config.html Config]], [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/Plotter.html Plotter]] and a point in time (in you model's time scale). The report has to be prepared by your application, buy fortunately [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/CachedReport.html CachedReport]] is of great help here. The Config describes some settings that affect the result (like image size, actual region of The Map to draw, whether to plot marks for nodes, etc.). [[Plotter]] is the thing that turns calculated influences into pixels (see the link for some cool info).
===Things to quite possibly change===
Right now it's very simple (from he outside, LOC count and various complexity measures for Starmapper class are a different thing), create an instance, add a listener and fire drawImage() with a Report. Re-crunch the Report and repeat. It places too much load on the application and it's the kind of load that each application wants to do almost the same thing with the Reports. So Starmapper should be more abstract and do these things itself. Most probably it should be something like "here's the pattern/list of input files, go hunt for the reports and give me back the images".
Another thing to do is to extend the notion of encoders. Actually what's in versions 3 and 2 is somewhat a stap back from version 1 - originally I wanted it to make animated GIFs (they were extremely cool thing to watch after a long and exciting Stars! game), so I provided some hooks to plug in so-called "image encoders". But I didn't know at this time how to do proper plugin system, so it got lost somehow [the truth is, I still don't know how to do plugins ;)]. In version 3 the application takes care of encoding the images and it's another thing that each application duplicates.
Deletions:
Formerly known as StarmapperLib, this is a library of classes etracted 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.
The core class of the core is the [[http://starmapper.sourceforge.net/api/starmapper3/jezuch/utils/starmapper3/Starmapper.html jezuch.utils.starmapper3.Starmapper]] class. [**FIXME**: write some more]