com.avian.birds.basebirds
Class AbstractBasicBird
java.lang.Object
javax.swing.SwingWorker<java.lang.String,java.lang.String>
com.avian.birds.basebirds.AbstractBasicBird
- All Implemented Interfaces:
- java.lang.Runnable, java.util.concurrent.Future<java.lang.String>, java.util.concurrent.RunnableFuture<java.lang.String>
- Direct Known Subclasses:
- StdBird
public abstract class AbstractBasicBird
- extends javax.swing.SwingWorker<java.lang.String,java.lang.String>
Provides the standard functionality of a Basic Bird, which is eating, digesting,
storing food, napping, and Return to Egg (RTE or death).
Nested classes/interfaces inherited from class javax.swing.SwingWorker |
javax.swing.SwingWorker.StateValue |
Field Summary |
protected BirdHistoryFile |
bhf
A utility object that wraps (and hides) all of the messy code needed to open and
write to an output file. |
protected BirdInputFile |
bif
A utility object that wraps (and hides) all of the messy code needed to open and
read from an input file. |
protected java.lang.String |
birdDesc
Brief description of the bird but is primarily a convenience for developers |
protected java.lang.String |
birdHistory
String that records every event this individual bird encounters. |
protected java.lang.String |
birdName
Name of the bird but is intended primarily a convenience for the developers
so they can see which bird is responsible for which events |
protected BirdOutputFile |
bof
A utility object that wraps (and hides) all of the messy code needed to open and
write to an output file. |
protected java.lang.String |
eatsFood
Name of the food that this bird eats. |
protected long |
hatchTime
Time when the bird was hatched (launched by the Aviary). |
protected java.lang.String |
historyFileName
Name of the path and file that will be used if the bird's history should be
saved. |
protected java.lang.String |
inputFileName
Name of the path and file that will be used to open and read the input file. |
protected long |
lastAte
Time when the bird last ate, in milliseconds, based on the System time. |
protected int |
levelOfInfo
Provides a way to control the amount of information that is generated when the
bird is running. |
protected long |
lifeTime
Duration of this bird's life, measured in milliseconds. |
protected long |
napLength
Defines how long the bird will "nap" after digesting and storing its food. |
protected java.lang.String |
outputFileName
Name of the path and file that will be used to open and write to the output file. |
protected long |
stamina
Defines how long the bird can go without eating, in milliseconds. |
protected boolean |
stopNow
Controls when the bird stops running. |
protected java.lang.String |
storesFood
Name of the food that this bird stores. |
Constructor Summary |
AbstractBasicBird()
Default constructor for the Basic Bird - it doesn't require any
parameters to create a Basic Bird with reasonable initial values. |
Method Summary |
void |
addToBirdHistory(java.lang.String historicalEvent)
Adds the historical event to the bird's history. |
java.lang.String |
doInBackground()
The heart of the Basic Bird comes from this method - it eats, digests,
stores food, naps, and then checks its age until stopNow is true or
it has outlived its lifeTime. |
java.lang.String |
getAuxFood()
Returns a null String in AbstractBasicBird. |
java.lang.String |
getBirdDescription()
Returns the description of this bird as a string. |
java.lang.String |
getBirdHistory()
Returns the bird's personal history, which is all the events in which the bird
participated, such as eating and storing food, napping, etc. |
java.lang.String |
getBirdName()
Returns the name of this bird as a String. |
java.lang.String |
getEatsFood()
Returns the name of the food that this bird eats. |
long |
getHatchTime()
Retrieves the time that this bird was hatched (launched). |
java.lang.String |
getHistoryFileName()
Retrieves the name of the history file that is used to record the history of this bird. |
java.lang.String |
getInputFileName()
Retrieves the name of the input file
The presence (and absence) of this (file) name is used to determine bird behavior. |
long |
getLastAte()
Retrieves the last time that this bird successfully ate, based on the System
time, in milliseconds. |
int |
getLevelOfInfo()
Returns the current level of information recording within the bird. |
long |
getLifeTime()
Retrieves the length of time that this bird should live, in milliseconds. |
java.lang.String |
getNameOfFoodToStore()
Returns the String name of the food that this bird stores. |
long |
getNapLength()
Retrieves the length of time (in milliseconds) that this bird should nap after
eating and digesting and storing its food. |
java.lang.String |
getOutputFileName()
Retrieves the name of the output file. |
long |
getStamina()
Retrieves the amount of stamina a bird was initally assigned, in milliseconds. |
boolean |
isStopNow()
Returns the value of the stopNow variable as a Boolean. |
void |
setBhf(BirdHistoryFile bhf)
A utility object that encapsulates all the long and tedious code that is necessary
to open and write the bird's history to a file. |
void |
setBif(BirdInputFile bif)
A utility object that encapsulates all the long and tedious code that is necessary
to open and read an input file. |
void |
setBirdDesc(java.lang.String birdDesc)
Sets the description of this bird to the String that is passed in. |
void |
setBirdHistory(java.lang.String birdHistory)
Sets (or replaces) the bird history to some String value. |
void |
setBirdName(java.lang.String birdName)
Sets the name of the bird. |
void |
setBof(BirdOutputFile bof)
A utility object that encapsulates all the long and tedious code that is necessary
to open and write to an output file. |
void |
setEatsFood(java.lang.String nameOfFoodItEats)
Sets the name of the food (work packets) that this bird will eat. |
void |
setHatchTime(long hatchTime)
Sets the hatch time for this bird. |
void |
setHistoryFileName(java.lang.String fileName)
Set's the path and file name that is used to record the history of this bird. |
void |
setInputFileName(java.lang.String fileName)
Sets the name of the input file that will be read |
void |
setLevelOfInfo(int levelOfInfo)
Sets the level of info AS AN INT that this bird should use for recording its personal
history, the events that this bird has participated in, such as eating
and storing food, napping, etc. |
void |
setLevelOfInfo(java.lang.String levelOfInfo)
Sets the level of info AS A STRING that this bird should use for recording its personal
history, the events that this bird has participated in, such as eating
and storing food, napping, etc. |
void |
setLifeTime(long lifeTime)
Sets the length of time that this bird should live, in milliseconds. |
void |
setNapLength(long napLength)
Sets the length of time that this bird will nap, in milliseconds. |
void |
setOutputFileName(java.lang.String outputFileName)
Sets the name of the output file. |
void |
setStamina(long stamina)
Sets the length of time, in milliseconds, that this bird can exist without a
successful eating event. |
void |
setStopNow(boolean stopNow)
Sets the value of the stopNow variable. |
void |
setStoresFood(java.lang.String nameOfFoodItStores)
Sets the name of the food that this bird stores. |
Methods inherited from class javax.swing.SwingWorker |
addPropertyChangeListener, cancel, done, execute, firePropertyChange, get, get, getProgress, getPropertyChangeSupport, getState, isCancelled, isDone, process, publish, removePropertyChangeListener, run, setProgress |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
stopNow
protected boolean stopNow
- Controls when the bird stops running. If it is false, the bird continues
to run. If it is true, then the bird finishes its lifecycle and RTE.
birdName
protected java.lang.String birdName
- Name of the bird but is intended primarily a convenience for the developers
so they can see which bird is responsible for which events
birdDesc
protected java.lang.String birdDesc
- Brief description of the bird but is primarily a convenience for developers
eatsFood
protected java.lang.String eatsFood
- Name of the food that this bird eats. This is the input name. This is
the name that is used in the get method to retrieve the next chunk to work on.
storesFood
protected java.lang.String storesFood
- Name of the food that this bird stores. This is the output name. This is the
name that is used in the put method to output this chunk of data.
levelOfInfo
protected int levelOfInfo
- Provides a way to control the amount of information that is generated when the
bird is running. The range is 1 to 5, with the smallest number providing info
about the smallest details (most info) while the largest number provides info
about only the largest (or most important) details. Catastrophic events or
runtime errors/exceptions are level 5. Level 1 records stuff like when field
settings are changed or when a get starts & stops or when a put starts & stops.
birdHistory
protected java.lang.String birdHistory
- String that records every event this individual bird encounters. This is a log
file of everything that this bird does (or doesn't) do.
historyFileName
protected java.lang.String historyFileName
- Name of the path and file that will be used if the bird's history should be
saved. If historyFileName is blank, the bird's history will NOT be saved.
If the historyFileName in NOT blank, the bird will try to save its history
to this file name. Be sure to escape backslashes ("\\") or the backslash will
be interpreted as the escape character and the write will fail.
inputFileName
protected java.lang.String inputFileName
- Name of the path and file that will be used to open and read the input file. If
the inputFileName is blank, the bird will NOT try to read from an input file. If
the inputFileName is NOT blank, the bird will try to open and read the file
specified in this String. Be sure to escape the backslashes ("\\") or the backslash
will be interpreted as the escape character and the open & read will fail. Note that
the read is done one LINE at a time and not character by character. One line is
read each time thru the lifecycle loop in the eat method.
outputFileName
protected java.lang.String outputFileName
- Name of the path and file that will be used to open and write to the output file. If
the outputFileName is blank, the bird will NOT try to write to an output file. If
the outputFileName is NOT blank, the bird will try to open and write to the file
specified in this String. Be sure to escape the backslashes ("\\") or the backslash
will be interpreted as the escape character and the open will fail. Note that
the writing is done one food object at a time. Whatever that food object contains
as it's Dinner (work object) that will be output to the file, whether it is 1
character or 1000 lines.
hatchTime
protected long hatchTime
- Time when the bird was hatched (launched by the Aviary). This value is used to
calculate how long the bird has been alive and therefore how much longer it
should keep running. Note that if you stop the bird before it reaches the end
of its lifetime and inspect its values and piddle around with it, the hatch time
does NOT start over if you choose to continue. So by the time you click on continue,
its lifetime may have already been completed.
lifeTime
protected long lifeTime
- Duration of this bird's life, measured in milliseconds. The duration is calculated
by subtracting the hatch time from the current time, and if the result is larger
than this value, stopNow is set to true and the lifecycle loop is terminated.
lastAte
protected long lastAte
- Time when the bird last ate, in milliseconds, based on the System time. Every time
the bird successfully "gets" a chunk of info, the lastAte variable is updated with
the current time. The lastAte time is used to calculate how "hungry" the bird is,
which (eventually) will be used to adjust the aggressiveness of the bird.
stamina
protected long stamina
- Defines how long the bird can go without eating, in milliseconds. The larger the
stamina, the longer the bird can live without eating. If the bird doesn't eat
before its stamina is exceeded, then it sets stopNow to true and the bird does
a RTE (return to egg).
napLength
protected long napLength
- Defines how long the bird will "nap" after digesting and storing its food. The nap
is a built in mechanism to yield the CPU to other birds. Eventually, hungry birds
will be able to adjust their own nap lengths so that they can become more aggressive.
bhf
protected BirdHistoryFile bhf
- A utility object that wraps (and hides) all of the messy code needed to open and
write to an output file. This utility file receives the contents of this bird's
own personal history and saves it.
bif
protected BirdInputFile bif
- A utility object that wraps (and hides) all of the messy code needed to open and
read from an input file. Currently only one bird should read from an input file
at a time. You could have all 10 birds reading from 10 DIFFERENT files, that
should be fine, but currently only ONE bird should read an input file at a time.
bof
protected BirdOutputFile bof
- A utility object that wraps (and hides) all of the messy code needed to open and
write to an output file. Currently only one bird should write to an output file
at a time. You could have all 10 birds writing to 10 DIFFERENT files, that
should be fine, but currently only ONE bird should write to an output file at a time.
AbstractBasicBird
public AbstractBasicBird()
- Default constructor for the Basic Bird - it doesn't require any
parameters to create a Basic Bird with reasonable initial values.
doInBackground
public java.lang.String doInBackground()
- The heart of the Basic Bird comes from this method - it eats, digests,
stores food, naps, and then checks its age until stopNow is true or
it has outlived its lifeTime.
Before starting its lifecycle loop, it checks to see if the Bird Input File
(bif) was created by the calling method in the Aviary. If bif is non-null,
it assumes that it is reading from the input file and opens the input file.
After completing its lifecycle loop (StopNow = True), it reports that it stopped
running and reports its Hatched at time & Last Ate Time. It then checks to see if
the Bird Input File (bif) was created by the calling method in the Aviary. If
bif is non-null, it closes bif. It then checks the Bird History File (bhf) to
see if it is null. If bhf is null, it means the history file should just be
displayed to that bird's History Text Area. If bhf is non-null, it means that
the Aviary had a file name defined in the gui. The bhf opens that file name
(if it can) and writes the bird history file to that file.
- Specified by:
doInBackground
in class javax.swing.SwingWorker<java.lang.String,java.lang.String>
isStopNow
public boolean isStopNow()
- Returns the value of the stopNow variable as a Boolean. When true,
the stopNow variable ends the run method, terminating this Basic Bird.
- Returns:
- Returns a Boolean that represents the current setting of the
stopNow variable
setStopNow
public void setStopNow(boolean stopNow)
- Sets the value of the stopNow variable. When true, the stopNow variable
ends the run method, terminating this Basic Bird. Conversely, when
false, the Basic Bird continues running until its lifeTime is exceeded
or some external condition needs this bird to stop. Except when initializing
the bird, it doesn't make sense to set stopNow to false, since it is
already false if the bird is running. On the other hand, if you set it
to false repeated, there is no harm done, so if the logic is easier
then it should be OK to set to false as many times as desired.
- Parameters:
stopNow
- Boolean that is set to true when this bird should be stopped
getBirdName
public java.lang.String getBirdName()
- Returns the name of this bird as a String. The bird's name has no computational
value and is merely provided as a convenience for the bird user to make
it easier to manage the birds.
- Returns:
- Returns the name of this bird as a String
setBirdName
public void setBirdName(java.lang.String birdName)
- Sets the name of the bird. Normally used only during initialization of
the bird but is available if needed.
- Parameters:
birdName
- String identifier for this bird
getBirdDescription
public java.lang.String getBirdDescription()
- Returns the description of this bird as a string. The description has
no computational value and is merely provided as a convenience for the
bird user to help keep track of what this bird is supposed to do.
- Returns:
- String description of what this bird is supposed to do
setBirdDesc
public void setBirdDesc(java.lang.String birdDesc)
- Sets the description of this bird to the String that is passed in. The
description is meant as a convenience for the user to help keep track
of what this bird is supposed to be doing. This method is normally
only used during the initialization phase since each bird is expected to
do only one thing, so there isn't much need to change the description
- Parameters:
birdDesc
- String description of what this bird is supposed to do
getEatsFood
public java.lang.String getEatsFood()
- Returns the name of the food that this bird eats. This food is the key that
will be used to retrieve work packets, in the Linda world, when a get
operation is performed.
- Returns:
- Returns a String that is the name of the food that this bird eats
setEatsFood
public void setEatsFood(java.lang.String nameOfFoodItEats)
- Sets the name of the food (work packets) that this bird will eat. This method is
normally only used during initialization phase since each bird is
expected to do only one thing and then Return to Egg when it exceeds
its lifeTime.
- Parameters:
nameOfFoodItEats
- String name of the food that this bird will eat
getNameOfFoodToStore
public java.lang.String getNameOfFoodToStore()
- Returns the String name of the food that this bird stores. This is
the name of the food that some other bird(s) eats. The names must
match exactly or the other birds will starve. In the Linda world,
the storeFood name is the key used when a tuple is put out there.
- Returns:
- String name of the food that this bird stores
setStoresFood
public void setStoresFood(java.lang.String nameOfFoodItStores)
- Sets the name of the food that this bird stores. This method is used primarily during
the initialization phase since each bird will typically do only one thing
before RTE. Its easier and clearer to just create more birds that it is
to change names mid-flight.
- Parameters:
nameOfFoodItStores
- String value that is used when this bird stores
its food (outputs its work packet)
getAuxFood
public java.lang.String getAuxFood()
- Returns a null String in AbstractBasicBird. Override this method in any
Bird that wants to use the auxFood Xmv field for updating a third progress
bar by that Bird
- Returns:
- null String in AbstractBasicBird. Birds that need to eat an aux food
need to override this method and return the appropriate String name of food.
getLevelOfInfo
public int getLevelOfInfo()
- Returns the current level of information recording within the bird.
Info recording is similar to using log files, except each bird maintains
its own information, its personal history of events that it has encountered.
Each bird can have its own level of info recording, depending on the
needs of the user. The standard values are from 1 to 5, where 1 represents
the smallest details and 5 represents the highest level of info. A typical
level 1 piece of info would capture events like changing the name of a
bird or its description, or when a storeFood event started and when it
finished. A typical level 5 piece of info is when the bird started and
when it terminated and any unusual events, such as unexpected exceptions.
The default level for a bird is level 3, which captures a lot of info
about the eating and storing that the bird has done.
- Returns:
- An int between 1 and 5 representing the smallest details (1)
to the highest level of info (5)
setLevelOfInfo
public void setLevelOfInfo(int levelOfInfo)
- Sets the level of info AS AN INT that this bird should use for recording its personal
history, the events that this bird has participated in, such as eating
and storing food, napping, etc. The higher the info level number, the
higher importance of the event must be to be recorded. The range is from
1 to 5, with 5 being reserved for unexpected exceptions and terminal
events. Level 1 is for the lowest level events, such as when a bird was
renamed or when eating started and then finished.
- Parameters:
levelOfInfo
- int value that represents the amount of info that
should be recorded in the personal history of this bird
setLevelOfInfo
public void setLevelOfInfo(java.lang.String levelOfInfo)
- Sets the level of info AS A STRING that this bird should use for recording its personal
history, the events that this bird has participated in, such as eating
and storing food, napping, etc. The higher the info level number, the
higher importance of the event must be to be recorded. The range is from
1 to 5, with 5 being reserved for unexpected exceptions and terminal
events. Level 1 is for the lowest level events, such as when a bird was
renamed or when eating started and then finished.
Note that if you pass a non-numeric string (such as "Q" or "Tom"), a number
format exception is thrown and the info Level is defaulted to level 3.
- Parameters:
levelOfInfo
- String value representing the int that represents the amount
of info that should be recorded about this bird's personal info
getBirdHistory
public java.lang.String getBirdHistory()
- Returns the bird's personal history, which is all the events in which the bird
participated, such as eating and storing food, napping, etc.
- Returns:
- birdHistory String that includes every event that is worth recording
(based on the LevelOfInfo variable).
setBirdHistory
public void setBirdHistory(java.lang.String birdHistory)
- Sets (or replaces) the bird history to some String value. This should not normally be needed
but if Continue button is pressed, the history of this bird before the stop
button was pressed needs to be preserved by setting the new bird's history
to whatever was recorded before the stop button was pressed.
- Parameters:
birdHistory
- String that contains the history of events that this bird encountered.
addToBirdHistory
public void addToBirdHistory(java.lang.String historicalEvent)
- Adds the historical event to the bird's history. The time of the event is automatically
recorded, along with the bird's name. The history is written in comma separated value
("CSV") format, more or less. Technically any value that could contain a comma should
have be enclosed in double-quotes, but this CSV format isn't that formal. If events of
interest are added to the bird's history, they should NOT contain comma's unless the
comma is meant to separate values (fields). The CSV format was chosen so the history
events can be read into a spreadsheet or a database and then sorted by time.
- Parameters:
historicalEvent
- String that contains an event of interest
getHistoryFileName
public java.lang.String getHistoryFileName()
- Retrieves the name of the history file that is used to record the history of this bird.
The presence (and absence) of this (file) name is used to determine bird behavior.
Many times this field is checked and if it is empty, the assumption is that the
bird is not saving its history to a file and does some different behavior.
- Returns:
- String that represents the bird's history file name
setHistoryFileName
public void setHistoryFileName(java.lang.String fileName)
- Set's the path and file name that is used to record the history of this bird. Note
that if no path info is provided, the file will be saved in the current working
directory. If a path is included, any backslashes in the path must be doubled (escaped)
("\\") or else single backslashes will be interpreted as the escape command and then
most likely fail because the following character will not be a valid escape command.
Or worse, it will form a valid escape sequence and do something crazy.
- Parameters:
fileName
- String that contains the path and file name that will be used
to save the bird's history
setBhf
public void setBhf(BirdHistoryFile bhf)
- A utility object that encapsulates all the long and tedious code that is necessary
to open and write the bird's history to a file.
- Parameters:
bhf
- BirdHistoryFile object that encapsulates all the code needed to open
and write this bird's history to a file.
setBif
public void setBif(BirdInputFile bif)
- A utility object that encapsulates all the long and tedious code that is necessary
to open and read an input file.
- Parameters:
bif
- BirdInputFile object that encapsulates all the code needed to open
and read from an input file.
setBof
public void setBof(BirdOutputFile bof)
- A utility object that encapsulates all the long and tedious code that is necessary
to open and write to an output file.
- Parameters:
bof
- BirdOutputFile object that encapsulates all the code needed to open
and write to an output file.
getInputFileName
public java.lang.String getInputFileName()
- Retrieves the name of the input file
The presence (and absence) of this (file) name is used to determine bird behavior.
Many times this field is checked and if it is empty, the assumption is that the
bird is not reading from a file and does some different behavior.
- Returns:
- String that represents the name of the input file that will be read
setInputFileName
public void setInputFileName(java.lang.String fileName)
- Sets the name of the input file that will be read
- Parameters:
fileName
- String that contains the path and file name that should
be ready by this bird
getOutputFileName
public java.lang.String getOutputFileName()
- Retrieves the name of the output file.
The presence (and absence) of this (file) name is used to determine bird behavior.
Many times this field is checked and if it is empty, the assumption is that the
bird is not writing to a file and does some different behavior.
- Returns:
- String that represents the name of the output file that will be written to
setOutputFileName
public void setOutputFileName(java.lang.String outputFileName)
- Sets the name of the output file. The presence (and absence) of this (file) name
is used to determin bird behavior. Many times this field is check and if it is
empty, the assumption is that the bird is not writing to a file and does something
different.
- Parameters:
outputFileName
-
getHatchTime
public long getHatchTime()
- Retrieves the time that this bird was hatched (launched).
- Returns:
- long value that represents the System time millisecond that the bird was hatched.
setHatchTime
public void setHatchTime(long hatchTime)
- Sets the hatch time for this bird. This is not normally used, but it is needed
when a bird is stopped before it has outlived it's life time AND THEN the continue
button is pressed. Otherwise this method shouldn't be used.
- Parameters:
hatchTime
- long value that represents the System time (in milliseconds) that
this bird was hatched
getLifeTime
public long getLifeTime()
- Retrieves the length of time that this bird should live, in milliseconds.
- Returns:
- long value that represents the number of milliseconds that this bird should live
setLifeTime
public void setLifeTime(long lifeTime)
- Sets the length of time that this bird should live, in milliseconds. This is normally
only used during initialization of this bird.
- Parameters:
lifeTime
- long value that defines this bird's lifetime, in milliseconds
getLastAte
public long getLastAte()
- Retrieves the last time that this bird successfully ate, based on the System
time, in milliseconds. This value is used in the calculation of how much stamina
a bird has remaining. If one really wanted to, this time could be converted into
a standard calendar date and time.
- Returns:
- long value that represents the last time that the bird ate, based on
System time, in milliseconds.
getStamina
public long getStamina()
- Retrieves the amount of stamina a bird was initally assigned, in milliseconds.
In future versions, this value might be adjusted by the bird to help control
how long the bird will last before it RTE's.
- Returns:
- long value that represents how many milliseconds this bird can live
without successfully eating (retrieveing a chunk of data to work on)
setStamina
public void setStamina(long stamina)
- Sets the length of time, in milliseconds, that this bird can exist without a
successful eating event. This method is normally only used during the initialization
of the bird. When the stamina value is exceeded, stopNow is set to true and the
bird does a RTE.
- Parameters:
stamina
- long value that represents the number of milliseconds this bird
should live without being able to successfully eat.
getNapLength
public long getNapLength()
- Retrieves the length of time (in milliseconds) that this bird should nap after
eating and digesting and storing its food. Napping is a way of forcing every
bird to yield to other threads periodically. Future versions may adjust the
length of time a bird naps to help it become more aggressive when it gets hungry.
- Returns:
- long value that represents how many milliseconds this bird should nap
setNapLength
public void setNapLength(long napLength)
- Sets the length of time that this bird will nap, in milliseconds. Future versions
may use the nap length to adjust the aggressiveness of a bird to fit its level
of hunger.
- Parameters:
napLength
- long value that sets the length of time this bird will nap, in
milliseconds.