jezuch.utils.starmapper2
Class Starmapper

java.lang.Object
  |
  +--jezuch.utils.starmapper2.Starmapper
All Implemented Interfaces:
java.io.Serializable

public class Starmapper
extends java.lang.Object
implements java.io.Serializable

The core class of Starmapper2 Library. Objects if this class are the central point of map drawing process. They are given a Stars! MAP (on creation), a set of reports and drawing instructions (image parameters) and draw maps for a specified year. Starmapper implements the Listener pattern; there are two kinds of listeners it can handle: ProgressListener and ImageProgressListener, and both fire ImageEvents. The former fires events on start, on end and on error of drawing process. The latter fires once in a while while Starmapper is drawing the image.

Important: Starmapper and all accompanying classes are not thread-safe. You should implement synchronization yourself if you need it.

Note: the jezuch.utils.starmapper.encoders package is not a part of Starmapper2 itself; it's a part of StarmapperApp and StarmapperGUI, that are (sample?) applications based on StarmapperLib. But the encoders package can be used to develop other applications.

Since:
1.0
Version:
2.0
Author:
Krzysztof Sobolewski
See Also:
StarsMap, StarsMap.StarsPla, StarsPlaReader, addPla(StarsMap.StarsPla), addPla(StarsMap.StarsPla, Player), addPla(StarsPlaReader, int), addPla(StarsPlaReader, int, Player), reset(), ProgressListener, ImageProgressListener, Serialized Form

Constructor Summary
Starmapper(StarsMap map)
          Creates a Starmapper instance based on a given Stars!
 
Method Summary
 void addImageProgressListener(ImageProgressListener l)
          Adds a ImageProgressListener to a list of listeners interested in drawing progress events.
 void addPla(StarsMap.StarsPla pla)
          Adds another report to information collected in this Starmapper.
 void addPla(StarsMap.StarsPla pla, Player byPlayer)
          Adds another report to information collected in this Starmapper.
 void addPla(StarsPlaReader plareader, int fromYear)
          Adds another report to information collected in this Starmapper.
 void addPla(StarsPlaReader plareader, int fromYear, Player byPlayer)
          Adds another report to information collected in this Starmapper.
 void addProgressListener(ProgressListener l)
          Adds a ProgressListener to a list of listeners interested in progress events.
 void dispatchEvent(ImageEvent event)
          Dispatches an ImageEvent.
 RawImage drawMap(int year)
          Request Starmapper to draw a map from a given year with default image parameters.
 RawImage drawMap(int year, ImageParameters params)
          Requests Starmapper to draw a map from a given year and custom image parameters.
static java.awt.Color[] getDefaultColors()
           
 StarsMap getMap()
           
static StarsMap parseMap(java.io.File basein, java.lang.String signature)
          Parses a Stars!
static StarsMap parseMap(java.io.Reader basein, java.lang.String signature)
          Parses a Stars!
static StarsMap parseMap(java.lang.String basein, java.lang.String signature)
          Parses a Stars!
static StarsMap parseMap(java.net.URL basein, java.lang.String signature)
          Parses a Stars!
static StarsMap.StarsPla parsePla(java.io.File basein, StarsMap map, int year)
          Parses a Stars!
static StarsMap.StarsPla parsePla(java.io.File basein, StarsMap map, int year, boolean addPlayers)
          Parses a Stars!
static StarsMap.StarsPla parsePla(java.io.Reader basein, StarsMap map, int year)
          Parses a Stars!
static StarsMap.StarsPla parsePla(java.io.Reader basein, StarsMap map, int year, boolean addPlayers)
          Parses a Stars!
static StarsMap.StarsPla parsePla(java.lang.String basein, StarsMap map, int year)
          Parses a Stars!
static StarsMap.StarsPla parsePla(java.lang.String basein, StarsMap map, int year, boolean addPlayers)
          Parses a Stars!
static StarsMap.StarsPla parsePla(java.net.URL basein, StarsMap map, int year)
          Parses a Stars!
static StarsMap.StarsPla parsePla(java.net.URL basein, StarsMap map, int year, boolean addPlayers)
          Parses a Stars!
 void removeImageProgressListener(ImageProgressListener l)
          Removes a ImageProgressListener from a list of listeners interested in drawing progress events.
 void removeProgressListener(ProgressListener l)
          Removes a ProgressListener from a list of listeners interested in progress events.
 void reset()
          Clears all planet information collected in this Starmapper.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Starmapper

public Starmapper(StarsMap map)
Creates a Starmapper instance based on a given Stars! MAP.

Parameters:
map - a Stars! "universe" that is used to draw maps; it can't be changed after Starmapper is created
See Also:
StarsMap
Method Detail

addImageProgressListener

public void addImageProgressListener(ImageProgressListener l)
Adds a ImageProgressListener to a list of listeners interested in drawing progress events. Image progress listeners receive notifications once in a while during drawing process.

Parameters:
l - listener to be added
See Also:
ImageProgressListener, removeImageProgressListener(ImageProgressListener)

addPla

public void addPla(StarsMap.StarsPla pla)
Adds another report to information collected in this Starmapper. Reports are "swallowed" by Starmapper - they are merged with data already collected and can't be reconstructed or removed afterwards. Only information that really matter are used; this is done on per-planet basis - "valuable" report are: if the report is the first one referring to a planet or if it is from later year than reports previously collected. Other overloads of this method can force additional checks.

Parameters:
pla - a Stars! PLA to be added
See Also:
addPla(StarsMap.StarsPla, Player), StarsMap.StarsPla

addPla

public void addPla(StarsMap.StarsPla pla,
                   Player byPlayer)
Adds another report to information collected in this Starmapper. This method does similar job as addPla(StarsMap.StarsPla) but also checks if owner of this report is also owner of the planet if the report and latest previously collected report are from the same year.

Parameters:
pla - a Stars! PLA to be added
byPlayer - owner of the report; ignored if null
See Also:
addPla(StarsMap.StarsPla), StarsMap.StarsPla

addPla

public void addPla(StarsPlaReader plareader,
                   int fromYear)
            throws java.io.IOException,
                   java.text.ParseException
Adds another report to information collected in this Starmapper. Report is read from a StarsPlaReader and doesn't contain information about a year that it's from, so it also needs to be supplied. This method does exactly the same job as addPla(StarsMap.StarsPla)

Parameters:
plareader - StarsPlaReader that the report is read from
fromYear - a year that the reports is from
Throws:
java.io.IOException - if an I/O error occurs
java.text.ParseException - if the PLA format is invalid
See Also:
addPla(StarsMap.StarsPla), StarsPlaReader

addPla

public void addPla(StarsPlaReader plareader,
                   int fromYear,
                   Player byPlayer)
            throws java.io.IOException,
                   java.text.ParseException
Adds another report to information collected in this Starmapper. Report is read from a StarsPlaReader and doesn't contain information about a year that it's from, so it also needs to be supplied. This method does exactly the same job as addPla(StarsMap.StarsPla, Player)

Parameters:
plareader - StarsPlaReader that the report is read from
fromYear - a year that the reports is from
byPlayer - owner of the report; ignored if null
Throws:
java.io.IOException - if an I/O error occurs
java.text.ParseException - if the PLA format is invalid
See Also:
addPla(StarsMap.StarsPla, Player), StarsPlaReader

addProgressListener

public void addProgressListener(ProgressListener l)
Adds a ProgressListener to a list of listeners interested in progress events. Progress listeners receive notification on start and end of drawing process and on errors.

Parameters:
l - listener to be added
See Also:
ProgressListener, removeProgressListener(ProgressListener)

dispatchEvent

public void dispatchEvent(ImageEvent event)
Dispatches an ImageEvent. This method sould not be called directly; it's intended to be called only be event dispatching thread (indirectly via ImageEvent.dispatch()) in response to Starmapper's methods that fire events.

Parameters:
event - event to be dispatched
See Also:
ImageEvent, ImageEvent.dispatch()

drawMap

public RawImage drawMap(int year)
Request Starmapper to draw a map from a given year with default image parameters. Starmapper will block until entire image has been produced and fires events notifying of the progress. Event fired on end of process might be dispatched after exit from this method.
Starmapper will ignore all reports that are from years later that the specified year (planets referenced by these reports will be reported as empty, because Starmapper holds only latest reports for planets).

Parameters:
year - a Stars! year that Starmapper should draw map for
Returns:
RawImage containing image data (as array of raw pixels)
See Also:
RawImage

drawMap

public RawImage drawMap(int year,
                        ImageParameters params)
Requests Starmapper to draw a map from a given year and custom image parameters. See drawMap(int) for details. Image parameters can be such as image size, map clip, etc.

Parameters:
year - a Stars! year that Starmapper should draw map for
params - image parameters that customize Starmapper's behavior
Returns:
RawImage containing image data (as array of raw pixels)
See Also:
RawImage, ImageParameters

getDefaultColors

public static java.awt.Color[] getDefaultColors()
Returns:
a copy of local table of default Player colors, so that clients can't modify it

getMap

public StarsMap getMap()
Returns:
a Stars! MAP that was used to create this Starmapper instance
See Also:
StarsMap

parseMap

public static StarsMap parseMap(java.io.File basein,
                                java.lang.String signature)
                         throws java.io.IOException,
                                java.text.ParseException
Parses a Stars! MAP reading contents from a given File.

Parameters:
basein - File to read from
signature - Stars! game's signature (a.k.a. prefix)
Returns:
parsed MAP as an instance of StarsMap
Throws:
java.io.IOException - if an I/O error occurs
java.text.ParseException - if an error during parsing occurs

parseMap

public static StarsMap parseMap(java.io.Reader basein,
                                java.lang.String signature)
                         throws java.io.IOException,
                                java.text.ParseException
Parses a Stars! MAP reading contents from a given Reader.

Parameters:
basein - Reader to read from
signature - Stars! game's signature (a.k.a. prefix)
Returns:
parsed MAP as an instance of StarsMap
Throws:
java.io.IOException - if an I/O error occurs
java.text.ParseException - if an error during parsing occurs

parseMap

public static StarsMap parseMap(java.lang.String basein,
                                java.lang.String signature)
                         throws java.io.IOException,
                                java.text.ParseException
Parses a Stars! MAP reading contents from a file with given name.

Parameters:
basein - name of the file to read from
signature - Stars! game's signature (a.k.a. prefix)
Returns:
parsed MAP as an instance of StarsMap
Throws:
java.io.IOException - if an I/O error occurs
java.text.ParseException - if an error during parsing occurs

parseMap

public static StarsMap parseMap(java.net.URL basein,
                                java.lang.String signature)
                         throws java.io.IOException,
                                java.text.ParseException
Parses a Stars! MAP reading contents from a given URL.

Parameters:
basein - URL to read from
signature - Stars! game's signature (a.k.a. prefix)
Returns:
parsed MAP as instance of StarsMap
Throws:
java.io.IOException - if an I/O error occurs
java.text.ParseException - if an error during parsing occurs

parsePla

public static StarsMap.StarsPla parsePla(java.io.File basein,
                                         StarsMap map,
                                         int year)
                                  throws java.io.IOException,
                                         java.text.ParseException
Parses a Stars! PLA file reading contents from a given File and attaches it to a given StarsMap at a given year.

Parameters:
basein - File to read from
map - Stars! MAP that this PLA belongs to
year - Stars! year that this PLA comes from
Returns:
parsed PLA as an instance of StarsMap.StarsPla
Throws:
java.io.IOException - if an I/O error occurs
java.text.ParseException - if an error during parsing occurs

parsePla

public static StarsMap.StarsPla parsePla(java.io.File basein,
                                         StarsMap map,
                                         int year,
                                         boolean addPlayers)
                                  throws java.io.IOException,
                                         java.text.ParseException
Parses a Stars! PLA file reading contents from a given File and attaches it to a given StarsMap at a given year and adds encountered unknown players if addPlayers is true.

Parameters:
basein - File to read from
map - Stars! MAP that this PLA belongs to
year - Stars! year that this PLA comes from
addPlayers - if true, Starmapper will automatically add unknown players to the map
Returns:
parsed PLA as an instance of StarsMap.StarsPla
Throws:
java.io.IOException - if an I/O error occurs
java.text.ParseException - if an error during parsing occurs

parsePla

public static StarsMap.StarsPla parsePla(java.io.Reader basein,
                                         StarsMap map,
                                         int year)
                                  throws java.io.IOException,
                                         java.text.ParseException
Parses a Stars! PLA file reading contents from a given Reader and attaches it to a given StarsMap at a given year.

Parameters:
basein - Reader to read from
map - Stars! MAP that this PLA belongs to
year - Stars! year that this PLA comes from
Returns:
parsed PLA as an instance of StarsMap.StarsPla
Throws:
java.io.IOException - if an I/O error occurs
java.text.ParseException - if an error during parsing occurs

parsePla

public static StarsMap.StarsPla parsePla(java.io.Reader basein,
                                         StarsMap map,
                                         int year,
                                         boolean addPlayers)
                                  throws java.io.IOException,
                                         java.text.ParseException
Parses a Stars! PLA file reading contents from a given Reader and attaches it to a given StarsMap at a given year and adds encountered unknown players if addPlayers is true.

Parameters:
basein - Reader to read from
map - Stars! MAP that this PLA belongs to
year - Stars! year that this PLA comes from
addPlayers - if true, Starmapper will automatically add unknown players to the map
Returns:
parsed PLA as an instance of StarsMap.StarsPla
Throws:
java.io.IOException - if an I/O error occurs
java.text.ParseException - if an error during parsing occurs

parsePla

public static StarsMap.StarsPla parsePla(java.lang.String basein,
                                         StarsMap map,
                                         int year)
                                  throws java.io.IOException,
                                         java.text.ParseException
Parses a Stars! PLA file reading contents from a file with given name and attaches it to a given StarsMap at a given year.

Parameters:
basein - name of the file to read from
map - Stars! MAP that this PLA belongs to
year - Stars! year that this PLA comes from
Returns:
parsed PLA as an instance of StarsMap.StarsPla
Throws:
java.io.IOException - if an I/O error occurs
java.text.ParseException - if an error during parsing occurs

parsePla

public static StarsMap.StarsPla parsePla(java.lang.String basein,
                                         StarsMap map,
                                         int year,
                                         boolean addPlayers)
                                  throws java.io.IOException,
                                         java.text.ParseException
Parses a Stars! PLA file reading contents from a file with given name and attaches it to a given StarsMap at a given year and adds encountered unknown players if addPlayers is true.

Parameters:
basein - name of the file to read from
map - Stars! MAP that this PLA belongs to
year - Stars! year that this PLA comes from
addPlayers - if true, Starmapper will automatically add unknown players to the map
Returns:
parsed PLA as an instance of StarsMap.StarsPla
Throws:
java.io.IOException - if an I/O error occurs
java.text.ParseException - if an error during parsing occurs

parsePla

public static StarsMap.StarsPla parsePla(java.net.URL basein,
                                         StarsMap map,
                                         int year)
                                  throws java.io.IOException,
                                         java.text.ParseException
Parses a Stars! PLA file reading contents from a given URL and attaches it to a given StarsMap at a given year.

Parameters:
basein - URL to read from
map - Stars! MAP that this PLA belongs to
year - Stars! year that this PLA comes from
Returns:
parsed PLA as an instance of StarsMap.StarsPla
Throws:
java.io.IOException - if an I/O error occurs
java.text.ParseException - if an error during parsing occurs

parsePla

public static StarsMap.StarsPla parsePla(java.net.URL basein,
                                         StarsMap map,
                                         int year,
                                         boolean addPlayers)
                                  throws java.io.IOException,
                                         java.text.ParseException
Parses a Stars! PLA file reading contents from a given URL and attaches it to a given StarsMap at a given year and adds encountered unknown players if addPlayers is true.

Parameters:
basein - URL to read from
map - Stars! MAP that this PLA belongs to
year - Stars! year that this PLA comes from
addPlayers - if true, Starmapper will automatically add unknown players to the map
Returns:
parsed PLA as an instance of StarsMap.StarsPla
Throws:
java.io.IOException - if an I/O error occurs
java.text.ParseException - if an error during parsing occurs

removeImageProgressListener

public void removeImageProgressListener(ImageProgressListener l)
Removes a ImageProgressListener from a list of listeners interested in drawing progress events.

Parameters:
l - the listener to be removed
See Also:
ImageProgressListener, addImageProgressListener(ImageProgressListener)

removeProgressListener

public void removeProgressListener(ProgressListener l)
Removes a ProgressListener from a list of listeners interested in progress events.

Parameters:
l - the listener to be removed
See Also:
ProgressListener, addProgressListener(ProgressListener)

reset

public void reset()
Clears all planet information collected in this Starmapper.