Example Project: Families	Appendix  B
CONTENTS

About the Project

This Family Tree application creates and stores Individuals in a Family structure, which then make up a Family tree through links to other families.  These links can be traversed to create lists of Individuals and Families, and more importantly, the tree can be used to create a list of Ancestors or Descendants of specific Individuals.
 

Opening the project

• Start Together/J
• Choose File | Open Project...
• Navigate to the ./samples/Families/source directory
• Open the FamilyTree.tpr project file

The Class Diagram

Using this diagram you can navigate down and browse the other packages shown:

• Right-click on the package icon and choose 'Browse in a New Window' from the context menu.

• Right-clicking on the View package icon and choosing 'Browse in a New Window' from the context menu.

Hyperlinks

• FamilesApplication class - if you select this class, and in the Inspector pane select the Diagram tab followed by the HyperLink To tab, you will see that the class is linked to a URL web address.  By right clicking on this address you can choose open to go to that address (only if your system has access to an Internet connection)

Problem Domain Package - this package is linked to a Microsoft Power Point presentation, if your system has MS Power Point then opening this link will show these slides.

Human Interface Package - this package is linked to the State diagram that was created for FamilyFrame class.  Because this hyperlink is a diagram, when you right click, you can choose to Browse the diagram.

• Selecting the element you want to create the link for.
• Selecting the 'HyperLink To' tab in the Inspector.
• Right click on the 'HyperLink To' pane.
• Select Link Diagram or Add URL.

Problem Domain

This package contains the actual classes from the analysis and design stage of development, and models the real world problem.  This diagram shows the navigation on the links because it makes it more easier to visually see the relationship flow.
 
A description of the classes found in the Problem Domain

• Family - the main class in the Problem Domain, holds groups of Individuals; 1 husband, 1 wife, 0 or more children.

 
• Individual - there are only three types of Individual: husband, wife and child.  This class has the stereotype 'role' which is why it has dark purple shading.  This shading is the default colour, but can be changed through the editing of the config.properties, found in the installation bin directory.

 
• LifeEvent - this has four subclasses that represent events that happen through life.
• Birth - the cardinality for this class is 0..1, although every Individual has a Birth event you may not know the details
• Death
• Marriage
• Divorce

 
• Note - a class to store descriptions, places and dates of the specific types of LifeEvent

Human Interface

This package contains implementation classes.  These classes are the user level of the application.  It is through this level that the user can call and view the various lists.  It is the Human Interface - FamilyFrame class that controls the application and handles all events and messages.

A description of the classes found in Human Interface

• FamilyFrame - this is the main frame of the application, it also is the class that controls all the features of the Family Tree.

 
• Aboutbox - a simple dialog with about information.

 
• ListDialog - a simple dialog to show a list of Individuals, it has added functionality of checking for clicking on a list item, and also has a pop-up menu for list items.

 
• InEntry - a dialog where the user can create new Families, with new or existing Individuals or add children to existing Families.

 
• Search - a useful dialog to use when trying to locate Individuals in a large family tree.

 
• ErrorDialog - a simple dialog to allow error message to be displayed to the user.

 

Hyperlinks

The FamilyFrame class has several hyperlinks - the class name appears in blue and bold to indicate links for classes.  The class itself is linked to the state diagram, while two of its operations, getAncestors and newIndividual are also hi-lighted in blue to show they too have links:

• getAncestors links - getAncestors sequence diagram, details the sequence of messages that the application steps through in order to create the Ancestor list.  The collaboration diagram link shows a simple collaboration diagram based on the sequence diagram.

 
• newIndividual link - addIndividual sequence diagram, details the sequence of messages that the application steps through to create a new Individual.

 

Data Management

This package holds a simple model for the control of the data, i.e. the opening and saving of the data:

DMControl - the main data control class that knows what type of data it will read in, flat file (as in this example), database etc...

FamilyDM - knows how to set and store the family records that a read in from the data storage.

IndividualDM - knows how to set and store the family records that a read in from the data storage.

IFamiliesDM & IIndividualsDM are the interfaces that the DMControl class must implement in order to read in the data records.

FlatFile

The FlatFile package contains the FlatFile class that has the behaviour to store the Family Tree details out to a text file on the local system.  Other packages at a later date could be added to allow classes to be stored by other means i.e  RTF, Database etc...
 

View

This diagram is made up of all of the main classes that make up this application, in fact you can also import classes from different packages located on the class or source path of the project - File | Project Properties.  Changes can be made directly to these classes unless you have imported compiled or read-only classes.
 

Documentation

The Use Case Diagram

The Use Case diagram shows the use cases for:

•   Searching for an Individual
•   Entering an Individual
•   Updating Family information

The State Diagram

The State diagram in the Family project models the interactive GUI component class FamilyFrame.  It shows the various states of the class as various events are triggered.
 

Sequence Diagrams

The getAncestors Sequence diagram shows the sequence of events that leads to the creation of the Ancestors list for an Individual.  The recursive loops on the sequence diagram take the form of moving up each family branch above the Individual.  The first branch it takes is the Father's branch of the family, and then the Mother's branch of the tree.  Whenever it finds a Husband or Wife that have no Families above them, the recursion unwinds, taking other routes, until all the various branches above the Individual have been taken.

addIndividiual Sequence Diagram

The addIndividual Sequence diagram shows the sequence of events that leads to the creation of an Individual.  There are some data checks in the entryDlg object to make sure that all the required data has been entered before proceeding with the creation of the new record.  These missing fields or errors are reported back to the user via the ErrorDialog class.
 

Collaboration Diagrams

Collaboration

This shows the getAncestors collaboration.
 

Running the Application

By default the application creates a small example Family Tree ready for you to use.  With the use of the File | Save as and File | Open menu you can create and store you own Family Trees.  This simple version has no implementation for entry of Marriage, Birth, Death or Divorce details.  If you want to start from scratch, then select File | Close to close the auto-generated Family Tree.
 

NB: Families must be created with the Husband first.  The application will warn you if you try to create a new family with the Wife as the starting member.
 

To Start the Application:

1. Run command line or console
2. Change directory to ./samples/Families
3. Note that compiled classes are already available after installation in the ./samples/Families/classes subdirectory
4. Invoke your Java VM for the main class of the application FamiliesApplication located in the Application package. Below is the sample code assuming you are using Sun JRE for Windows:

jre -cp classes Application.FamiliesApplication
The concrete command you should invoke may very depending on your OS, JVM and environment.

Creating Families from Existing Children in the Tree

• Select Edit | New Individual.
• Click on 'Individual' to display a list of current Individuals who are not parents.
• Select a Husband from this list by double clicking.
• This displays the Husband's details on the Entry dialog.
• Click on Update to create a new family with the selected person as the Husband.

• Add a Wife to the new family:
• Select Edit | New Individual.
• Enter the first name of the Wife.
• Click on 'Married to' to display a list of families without Wives.
• Select the Individual by double clicking on the Individual in the list.
• This will set the Wife's parent of field.
• Enter F or f as sex.
• The Maiden name field will become available - enter the maiden name here.
• Click on OK.

• Select View | Descendants.
• The Wife should appear on the list.
• Click on her name once to highlight her name.
• Right click on Wife's name.
• Select View Family.
• This displays the family you have just created.

Creating a new Family with a New Individual

Creating Children for Families

• Select Edit | New Individual
• Enter a new Individual's details but do not fill in the Parent of field
• Click on 'Child Of' and choose a family for this child
• On double clicking on a family in the list, the child's details are updated
• Click on OK

Updating/Amending an Individuals Details

• Select Edit | New Individual.
• Click on the 'Individual' button and choose the Individual to change.
• Change/Update the details.
• Click on the Update button to accept these changes.

NB: While creating Families you can at the same time add a new Individual to an existing Family by using the 'Child Of' button when entering the details.

Viewing the Ancestor or Descendent list

View | Show Spouse (this is a checkable menu option, by default it is off) works only with the View | Descendants. It adds the father's name to each Individual displayed on the Descendants list to make a large list more readable.

 Topic links for this chapter

• About the Project
• Opening the Project
• The Class Diagram
• Hyperlinks to other documents
• Problem Domain
• Human Interface
• Data Management
• Flat File
• View
• Documentation
• The Use Case Diagram
• The State Diagram
• Sequence Diagrams
• Collaboration Diagrams
• Running the application
• To Start the Application:
• Creating Families from existing children in the tree
• Creating a new Family with a New Individual
• Creating Children for families
• Updating/Amending an Individuals Details
• Viewing the Ancestor or Descendent list

---