com.avian.birds.basebirds
Class StdBird

java.lang.Object
  extended by javax.swing.SwingWorker<java.lang.String,java.lang.String>
      extended by com.avian.birds.basebirds.AbstractBasicBird
          extended by com.avian.birds.basebirds.StdBird
All Implemented Interfaces:
java.lang.Runnable, java.util.concurrent.Future<java.lang.String>, java.util.concurrent.RunnableFuture<java.lang.String>
Direct Known Subclasses:
Add1Bird, Add2Bird, Add3Bird, Add4Bird, Add5Bird, CombineBird, DataBird, DbUpdateBird, FirstNameBoyBird, FirstNameGirlBird, FNameBBird, FNameGBird, LastNameBird, LNameBird, MathBird, Phil1, Phil2, TestErrBird, Waiter

public class StdBird
extends AbstractBasicBird

Concrete implementation of the AbstractBasicBird. The StdBird eats (gets) and stores (puts) every food packet (tuple) in a TupleTree (tuple space) so it is very Linda-like. The details of retrieving a food packet are contained in the eatFood method. The food packet is processed in the digest method. The food packet is put back into the TupleTree using the storeFood method. After storing the food, the bird needs a nap. This same cycle repeats (eating, digesting, storing, and napping) in the run method until it is told to stopNow, either because it's lifeTime has been exceeded or it has exceeded the length of time that it can live without eating, at which time it Returns to Egg (death being so ugly and final). One can also use the setStopNow method to terminate when desired the next time the run method gets to the statement where it test to see if it should continue running.


Nested Class Summary
 
Nested classes/interfaces inherited from class javax.swing.SwingWorker
javax.swing.SwingWorker.StateValue
 
Field Summary
protected  StdFood foodFromTree
          The StdBird always eats some kind of Manna from a TupleTree.
protected  java.lang.String healthStatus
          Initialized by the xxStartButton or xxContinueButton methods in the Aviary.
protected  javax.swing.JButton jbRefStart
          Initialized by the xxStartButton or xxContinueButton methods in the Aviary.
protected  javax.swing.JLabel jlRefLastAte
          Initialized by the xxStartButton or xxContinueButton methods in the Aviary.
protected  javax.swing.JTextArea jtaRefHistory
          Initialized by the xxStartButton or xxContinueButton methods in the Aviary.
protected  javax.swing.JTextField jtfRefHealth
          Initialized by the xxStartButton or xxContinueButton methods in the Aviary.
protected  MilliTimeString mts
          Utility object that knows how to convert a millisecond time (as a long) into a String object.
protected  BasicTupleTree myTupleTree
          This is a Google Collections ArrayListMultimap object that saves and retrieves key-value pairs, even when there are duplicate keys.
protected  NanoTimeString nts
          Utility object that knows how to convert a nanosecond time (as a long) into a String object.
 java.lang.String sampleXmv
          Externally managed variables (Xmv) work like command line parameters but for the GUI env.
protected  java.lang.String startButtonText
          Initialized by the xxStartButton or xxContinueButton methods in the Aviary.
 
Fields inherited from class com.avian.birds.basebirds.AbstractBasicBird
bhf, bif, birdDesc, birdHistory, birdName, bof, eatsFood, hatchTime, historyFileName, inputFileName, lastAte, levelOfInfo, lifeTime, napLength, outputFileName, stamina, stopNow, storesFood
 
Constructor Summary
StdBird()
          Constructor of StdBirds, using the default constructor of AbstractBasicBird It's internal tree isn't set to point to the BasicTupleTree so that must be done separately
StdBird(BasicTupleTree elm)
          Constructor of StdBirds, using the default constructor of AbstractBasicBird and then setting it's internal tree to the BasicTupleTree that was created when the GUI was initialized.
 
Method Summary
protected  void checkAge()
          Verifies the age of a Basic Bird and if it has exceeded its lifeTime, sets stopNow to true so that the run method will terminate.
 void digest()
          Provides the processing functionality for this StdBird.
protected  void done()
          Performs various clean up activities when this bird has gotten old and RTE's or has received the stopNow(true) message.
 void eatFood()
          Every Bird must eat food to stay alive and this method provides the instructions that the Basic Bird will follow to eat.
 void setHealthRef(javax.swing.JTextField jtf)
          Text field that holds a human-readable message describing the current status of this bird.
 void setHealthStatus(java.lang.String healthDesc)
          Allows the different objects and methods to update the healthDesc string that is displayed whenever the HealthRef field is updated.
 void setHistoryAreaRef(javax.swing.JTextArea jta)
          The on-screen display of the personal history of this bird.
 void setJlRefLastAte(javax.swing.JLabel refLastAte)
          The on-screen field that displays the last time that this bird ate.
 void setStartButtonRef(javax.swing.JButton jb)
          The Start button that was pressed by the user that created this bird.
 void setStartButtonText(java.lang.String buttonText)
          The text String that was on the Start button when the user pressed the button.
 void setTupleTree(BasicTupleTree tt)
          Sets the local TupleTree reference so this bird knows where to put objects and where to get objects.
 void storeFood()
          Puts the digested food out for other Birds to eat.
 
Methods inherited from class com.avian.birds.basebirds.AbstractBasicBird
addToBirdHistory, doInBackground, getAuxFood, getBirdDescription, getBirdHistory, getBirdName, getEatsFood, getHatchTime, getHistoryFileName, getInputFileName, getLastAte, getLevelOfInfo, getLifeTime, getNameOfFoodToStore, getNapLength, getOutputFileName, getStamina, isStopNow, setBhf, setBif, setBirdDesc, setBirdHistory, setBirdName, setBof, setEatsFood, setHatchTime, setHistoryFileName, setInputFileName, setLevelOfInfo, setLevelOfInfo, setLifeTime, setNapLength, setOutputFileName, setStamina, setStopNow, setStoresFood
 
Methods inherited from class javax.swing.SwingWorker
addPropertyChangeListener, cancel, 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

myTupleTree

protected BasicTupleTree myTupleTree
This is a Google Collections ArrayListMultimap object that saves and retrieves key-value pairs, even when there are duplicate keys. All of the birds share this same TupleTree, eating and storing to the same tree. When a bird eats a key, the TupleTree returns any of the objects that matches the key, with no order or sequence desired or maintained. It is critical that any object that is returned be equally valid for the bird that is eating it. If there is some order or sequence required, then it needs to handled as a different type of food that is eaten by a different bird. The key is always a string but the value is an Object, totally generic. You will typically cast the object into the class that you need to use.


foodFromTree

protected StdFood foodFromTree
The StdBird always eats some kind of Manna from a TupleTree. Manna is the basic food type for a StdBird, and all of the food objects in the avian.food folder are descended from Manna. The foodFromTree variable is declared here so that it can be used when eating, digesting, and storing.


jtaRefHistory

protected javax.swing.JTextArea jtaRefHistory
Initialized by the xxStartButton or xxContinueButton methods in the Aviary. This is the JTextArea that is used to display the history of this bird in the GUI and is used when the done method executes when the bird RTE's.


jbRefStart

protected javax.swing.JButton jbRefStart
Initialized by the xxStartButton or xxContinueButton methods in the Aviary. This is the JButton that was clicked to start this bird. It is used when the done method executes when the bird RTE's.


startButtonText

protected java.lang.String startButtonText
Initialized by the xxStartButton or xxContinueButton methods in the Aviary. This is the string that was on the start button whe that button was clicked to start this bird. It is used when the done method executes when the bird RTE's.


jlRefLastAte

protected javax.swing.JLabel jlRefLastAte
Initialized by the xxStartButton or xxContinueButton methods in the Aviary. This is the JLabel that is updated when the done method executes when the bird RTE's.


jtfRefHealth

protected javax.swing.JTextField jtfRefHealth
Initialized by the xxStartButton or xxContinueButton methods in the Aviary. This JTextField is updated when the done method executes when the bird RTE's to give an human-readable description of the bird's status. This field holds the name of the field to update but doesn't hold the update's value.


healthStatus

protected java.lang.String healthStatus
Initialized by the xxStartButton or xxContinueButton methods in the Aviary. This JTextField is updated when the done method executes when the bird RTE's to give an human-readable description of the bird's status. This field holds the human-readable description, but doesn't hold the name of the field to update.


mts

protected MilliTimeString mts
Utility object that knows how to convert a millisecond time (as a long) into a String object. Typically this would have been a static object that all objects would have shared, but because we expect every implementation to be a multi-threaded/multi-core project, we have to expect that static objects would either have to be synchronized or subject to erratic and non-reproducible behavior, depending on the exact conflicting conditions that the birds encountered. By providing a separate MilliTimeString object to every StdBird instance, the potential corruption of this insignificant value is avoided.


nts

protected NanoTimeString nts
Utility object that knows how to convert a nanosecond time (as a long) into a String object. Typically this would have been a static object that all objects would have shared, but because we expect every implementation to be a multi-threaded/multi-core project, we have to expect that static objects would either have to be synchronized or subject to erratic and non-reproducible behavior, depending on the exact conflicting conditions that the birds encountered. By providing a separate NanoTimeString object to every StdBird instance, the potential corruption of this insignificant value is avoided.


sampleXmv

public java.lang.String sampleXmv
Externally managed variables (Xmv) work like command line parameters but for the GUI env. Up to 7 Xmv's can be set on the Activity tab of the Aviary and they will be passed into your birds. This allows you to use the same type of Bird to have different behaviors. For example, instead of creating MySQL Birds and Oracle Birds and Derby Birds, you can create a Data Bird and pass in the proper db address & login & password & SQL commands, etc

Constructor Detail

StdBird

public StdBird()
Constructor of StdBirds, using the default constructor of AbstractBasicBird It's internal tree isn't set to point to the BasicTupleTree so that must be done separately


StdBird

public StdBird(BasicTupleTree elm)
Constructor of StdBirds, using the default constructor of AbstractBasicBird and then setting it's internal tree to the BasicTupleTree that was created when the GUI was initialized.

Parameters:
elm - BasicTupleTree object that manages the key-value pairs that are put and get'd. The BasicTupleTree is a Google Collections ArrayListMultimap because it handles multiple objects with duplicate keys.
Method Detail

setHistoryAreaRef

public void setHistoryAreaRef(javax.swing.JTextArea jta)
The on-screen display of the personal history of this bird. This field is initialized when the the Start or Continue button is pressed and is actually updated when the done method is called.

Parameters:
jta - JTextArea object that displays on-screen the history of the events that this bird encountered.

setStartButtonRef

public void setStartButtonRef(javax.swing.JButton jb)
The Start button that was pressed by the user that created this bird. The Start button is updated with the message that it is running by the Start button method and is updated with the "Start #x" message when the done method is called. The text on this button is used as a "trigger" that prevents multiple instances of the same bird from running.

Parameters:
jb - JButton object that was pressed by the user that started this bird running.

setStartButtonText

public void setStartButtonText(java.lang.String buttonText)
The text String that was on the Start button when the user pressed the button. In effect, each bird remembers which button was pushed to start it running and puts back the text that was on that button when it is finished running. The text on this button is used as a "trigger" that allows birds to start or prevents muliple instances of the same bird from running.

Parameters:
buttonText - String that was on the Start button when the user started the bird running.

setHealthRef

public void setHealthRef(javax.swing.JTextField jtf)
Text field that holds a human-readable message describing the current status of this bird. This field is updated and displayed when the done method of the StdBird is called.

Parameters:
jtf - JTextField object that holds the human-readable message that describe the status of this bird (Egg, Running, etc)

setHealthStatus

public void setHealthStatus(java.lang.String healthDesc)
Allows the different objects and methods to update the healthDesc string that is displayed whenever the HealthRef field is updated. This String is displayed in the HealthRef field when the done method is called.

Parameters:
healthDesc - String that represents the current status of this bird.

setJlRefLastAte

public void setJlRefLastAte(javax.swing.JLabel refLastAte)
The on-screen field that displays the last time that this bird ate. The LastAte time is used to help determine when the bird must RTE. This JLable is the on- screen label that displays the last time this bird ate in the done method.

Parameters:
refLastAte - JLable that displays the last time the bird ate - this label is only updated when the done method is called.

setTupleTree

public void setTupleTree(BasicTupleTree tt)
Sets the local TupleTree reference so this bird knows where to put objects and where to get objects. Future birds might have multiple TupleTrees that they refer to but currently the TupleSpace is limited to this single tree. This method was added because a default (no params) constructor was required there could be times where situations might require the birds to change the tupleTree that they interact with.

Parameters:
tt - BasicTupleTree reference that allows this bird to get and put objects in the TupleTree

eatFood

public void eatFood()
Every Bird must eat food to stay alive and this method provides the instructions that the Basic Bird will follow to eat. Eating is another way of saying that the Basic Bird is obtaining a package of data to work on. Each Basic Bird will eat only one type of food and will store one type of food. By correctly setting up the types of food that the Basic Birds in the flock eat and store, a producer-consumer stream can be defined, with as many steps as necessary to do the necessary work.

In the Linda world of tuples and tuplespaces, the eatFood method is a get operation, where the Basic Bird retrieves a work packet. The name of the food defined for this Basic Bird is the key value that is used to retrieve its tuple. Any tuple which matches the eat food name may be retrieved, with no order expected or implied. If there is some special need for a type or a sequence, then it probably needs to be a different kind of Basic Bird that eats a different food name.

Typically, eating involves getting food from a TupleTree. Right now, the TupleTree is implemented using Google Collections ArrayListMultimap because it allows multiple objects with the same key to be stored and retrieved, but there is no requirement that this be used. The eatFood method is defined as abstract in AbstractBasic Bird so that users can define whatever method they desire to retrieve the next packet to work on, such as SQL queries or X-path look ups.


storeFood

public void storeFood()
Puts the digested food out for other Birds to eat. The user is responsible for creating their own storeFood method, implementing their own method of saving the work packet for retrieval by a different Bird. The work packet is an object, either a std Java object or one that the user defines.

The name for the digested food comes from the storeFood variable, which is the "key" that will be used to store the work packet (object). This object is the "value" in a pair. The next Birds will eat (get) this food using the name used here.

In the real world, one bird will store (cache) some food for later eating (such as when a woodpecker puts a nut or a bug in a hole in the tree). Sometimes, however, a different bird will actually eat it.

In the Linda world, storeFood is the equivalent of the put operation. The StdBird is implemented using the TupleTree which is based on the Google Collections ArrayListMultimap because it allows multiple values to be stored using the same key, but there is no requirement that users do the same - they can implement any way of saving the info that they desire in the TupleTree of their own device.


digest

public void digest()
Provides the processing functionality for this StdBird. Whatever food (work packet) the StdBird has eaten, it applies the processing that is specified in this method to the food, modifying the food and preparing it for the next Bird to eat. The intent is that each bird do some discrete chunk of processing when it digests, some meaningful amount of processing that produces an interim result.

Every different kind of Bird can be expected to digest differently. That is the whole reason for making different Birds and having them eat different foods, to handle different situations outside of code logic. For example, consider a situation where you have a special condition that involves a lot of convoluted logic to correctly handle that special condition. Instead of coding it, store it as a different kind of food and then add a Bird that will eat just that special kind of food. Set that Bird's stamina high because it won't eat often, but when it does it, it handles the special condition without a lot of complicated logic or deeply nested if statements.


checkAge

protected void checkAge()
Verifies the age of a Basic Bird and if it has exceeded its lifeTime, sets stopNow to true so that the run method will terminate. This method ensures that no Basic Bird lives forever (unless you want it to, of course). If lifeTime is negative, it will never terminate because of old age. It will record its expected life and actual life durations if the levelOfInfo is <= 4


done

protected void done()
Performs various clean up activities when this bird has gotten old and RTE's or has received the stopNow(true) message. Because the Basic Bird is tightly tied to the Aviary, it's done activities all relate to updating the Aviary. This bird extends the AbstractBasicBird which extends the SwingWorker. When the doInBackground method finishes, the birdHistory is returned in the get method. This method overrides the SwingWorker done method and updates the Aviary with the appropriate status info.

Overrides:
done in class javax.swing.SwingWorker<java.lang.String,java.lang.String>