com.avian.birds.basebirds
Class AbstractBasicBird

java.lang.Object
  extended by javax.swing.SwingWorker<java.lang.String,java.lang.String>
      extended by 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 Class Summary
 
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
 

Field Detail

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.

Constructor Detail

AbstractBasicBird

public AbstractBasicBird()
Default constructor for the Basic Bird - it doesn't require any parameters to create a Basic Bird with reasonable initial values.

Method Detail

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.