CIS705/805 Class Notes

=Collaboration=

Version control
A version control system (also known as revision control or source control) is a software that manages changes to a collection of source code files. This software is essential when a software system is developed by a team of developers, all sharing the same code base.

A version control system keeps track of
 * all successive versions of a source code file
 * authors of all versions and
 * time stamps of authored changes.

The version control system we use in this course is Subversion (SVN). SVN uses a centralized system with working copies that developers checkout as clients of the central repository.This is different from the distributed system that is used by Mercurial, Bazaar, or Git, where there is no reference code base by default, but only working copies. In a distributed system the working copies work like peers and function as remote backups of the code base.

Note: The CIS lab software decisions must be made way in advance of the beginning of the semester. Unfortunately, we cannot switch now from Subversion to Mercurial, but Mercurial is definitely a direction will take.

The client application we use in this course to communicate with the Subversion server is TortoiseSVN. See the opencomputing wiki article on TortoiseSVN. TortoiseSVN is for Windows only. Again, our wishlist has Linux as the best candidate for the development platform of FOSS projects.

Project hosting: Google Code
A version control system is usually part of a project hosting service. The project hosting service we use in this course is Google Code. This service provides: The service is available and free for all OSI-approved Open Source projects (as of 2010, it is strongly recommended but no longer required to use one of the nine well-known open source licenses: Apache, Artistic, BSD, GPLv2, GPLv3, LGPL, MIT, MPL and EPL). The site limits the number of projects one person can have to 25. Additionally, there is a limit as to the number of projects that may be created in one day.
 * Subversion and Mercurial repository,
 * project member controls
 * an issue tracker,
 * a wiki for documentation,
 * a file download feature.

See Google Code's Project Hosting wiki for more information.

Working with a Google Code hosted project involves:
 * 1) Customizing your project (use the Project Summary, Project Members, Source, and Administer tabs)
 * 2) Working with your source repository (use the Source tab)
 * 3) Documenting your project (use the Wiki tab)
 * 4) Tracking project tasks (use the Issues tab)
 * 5) Sharing releases (use the Downloads tab)

All the class projects must use Google Code hosting. The following requirements should apply to all hosted projects:
 * Project configuration manager and course instructor are owners of the project
 * The rest of the current team working on the project have commit privileges
 * Project summary is first drafted by the configuration manger, who sets up or reviews project hosting. Project summary is then the responsibility of the team leader.
 * Mailing lists must be set up as shown in Customizing your project on the Google Code's Project Hosting wiki (see steps 1 to 7)
 * Project documentation is done on the wiki that is maintained by our program.

Your password for committing to Subversion is not the same as the password that you use to access your project on the web (which is a Google Account password). Instead, it is a temporary password sent via email. Google believes that a Google Account password is too valuable to get exposed by being cached on your local disk. That is why a temporary password is used for committing operations. To find this password, look at your "Settings" tab of your profile page on the Google Code site. It will display your googlecode.com password. this password is used for access to your project's Subversion repository and for command-line file uploads to your project's Downloads area.

Code base organization with Subversion
Subversion community recommends that a repository location is chosen for each project root - the "topmost" directory that contains data related to that project. A comprehensive reference on Subversion (version 1.5) is the "Subversion red book" (see References).

In the case of the CIS705/805 projects this semester, the location of the DONATE project is cis605-donate (historical reasons!). If the configuration manager can change the name to unhm-donate, for example, that will be much better!

Projects developed previously are located at internship2career and dv-unit.

The following three subdirectories must exist beneath a project root:
 * trunk - directory under which the main project development occurs
 * branches - directory for various named branches of the main development line
 * tags - directory of tree snapshots that are created, and perhaps destroyed, but never changed.

The nature of our projects this semester suggests that a good layout of the trunk directory is, as we discussed in class, the following:
 * php - has all the PHP code and is further organized into:
 * model - has Xxxx.php application domain PHP classes, such as Person.php
 * db-control - has dbXxxx.php modules that have  CRUD functions for their respective tables in the database. An example of such module is dbPerson.php
 * view-control - has PHP modules that implement user interactions by requesting services from functions in the model and db-control directories. An example of such module is editPerson.php.
 * sql - has SQL scripts, including database backups. The SQL scripts are different than the database backup. A database backup is obtained from running mysqldump utility. It makes sense to get a backup AFTER the database has been created and populated by running SQL scripts that create a database and a user, creates tables for the system's application domain classes, and populates those tables with sample data.
 * docs - has code documentation files that are generated by Doxygen.
 * user-docs - has README, INSTALL and other deployment documents in TXT format.
 * mock-ups - has PNG files of Balsamiq "wireframes" that show user interface mock-ups.
 *  devel-docs  - has files that are used for writing system development documents (Requirement Analysis Document and System Design Document). These files need to be under version control and are organized in two subdirectories:
 * uml - has PNG and class.violet files for UML diagrams created with the Violet UML editor.
 * tests - has testXxxx.php unit test files, such as testPerson.php or testDBPerson.php
 * images - has graphics files referenced from the user interface modules.
 * html - has .html files whose content ends up being embedded in the PHP code
 * css - has .css files that the system uses to render dynamic pages whose HTML code is in the view-control directory.
 * js - has .js files, if any is needed.

When this structure is first time set up for the trunk, a local directory with subdirectories as listed above are "checked into" the repository by using the SVN import command. I know, the name of the command sounds counterintuitive, but that's the name! Note that this is done once, when the project is first set up.

Any additional restructuring is done on a local copy that's first "checked out" from the repository. Changed to the local copy, such relocate, rename, delete file/folder, etc. are done with TortoiseSVN. The local copy is then committed to the repository.

=Documentation= Project documentation includes:
 * wiki articles
 * analysis and design models, such as UML use case and class diagrams
 * other diagrams, such as a relational data models (using UML class diagram)
 * user manuals
 * developer manuals
 * source code comments and documentation that is automatically generated with Doxygen
 * formal documents that describe artifacts and explain development decisions, such as
 * Requirements and Analysis Document (RAD)
 * System Design Document (SDD)
 * project management documentation, such as meeting agendas and minutes

Project Wiki
OpenITWare wiki lists DONATE among other projects that have been part of various courses. More on how to write and maintain project wiki documentation can be found at http://openitware.org/wiki/index.php/Help:Project_wiki_documentation (also listed in the Guidelines box on the sidebar).

DONATE project wiki is organized as follows:
 * Home page has History, Description, Activities and Artifacts, and Events sections.
 * Home page must have the category Project. Insert at the end of the home page. VERY IMPORTANT!
 * All the other pages must have a category that names your particular project. For exaxmple is the category inserted at the end of each DONATE page, except for the Home page.
 * Wiki pages that document project management are separated from wiki pages that document system development. Activities and Artifacts section has interlinks to System Development and Project Management pages.
 * Project Management page has information about Team Members, their Roles and Responsibilities, and Team Meetings.
 * System Development page has interlinks to the Requirements and Analysis Document and System Design Document. Other information or links that pertain to the system development artifacts are included here.
 * History section on the home page indicates the most recent term and has an interlink to the previous term. These updates are made by each time a new team joins the project for a new term.

Content of some of the pages evolves with the project. New pages are created as the project progresses.

Except for the home page of the most recent project term, all pages must start with the "year term" and is followed by the name of the page. For example, the System Development page of this term (Spring 2012) for the DONATE project is named: "DONATE:2012 Spring System Development". The name of the current home page is "DONATE:Home". All project pages must have the prefix "DONATE", which is followed by colon ":". This is to place all project pages, including the home page, in a separate MediaWiki namespace.

The project wiki editor must study carefully the guidelines for writing project wiki documentation.

Requirements and Analysis Document (RAD)
A  requirements and analysis document (RAD)  describes and models all the aspects of the system under development from the user's point of view. This includes:
 * user roles or actors - roles of people who will use the delivered system
 * physical environment in which the system will run
 * work processes that the system automates
 * functional requirements or features that system must have
 * non-functional requirements or constraints on the system that are not directly to the system functionality
 * user cases - descriptions of system functions in terms of sequences of interactions between a user roles and the system
 * use case diagram - UML notation to represent actors, use cases, and their relationships
 * application domain concepts or classes that the system manipulates
 * application domain class diagram - UML notation to represent the application domain classes and their relationships.

RAD Template
The RAD template for your team project's RAD is organized in five sections. Use this template when you prepare this document. Explanations of what each section is follows.
 * 1) Overview
 * 2) Client profile
 * 3) Problem description - what problem does the proposed system solve and why is that important
 * 4) System objectives - what will the system achieve and who the end-users are
 * 5) Current system - how tasks that will be supported by the new system are accomplished right now
 * 6) Proposed system
 * 7) Functional requirements - high level functionality of the system
 * 8) Analysis models
 * 9) User stories (if any)
 * 10) Use case model - with actor definitions, use case full descriptions, and use case diagram.
 * 11) Analysis object model (also known as application domain model) - with entity (domain) class definitions and entity class diagram
 * 12) User interface mock-ups
 * 13) Non-functional requirements - user-level requirements not directly related to functionality. Licensing issues must be included here.
 * 14) Target environment - what computing resources (operating system, bundled software, server applications and client software tools) the proposed system will use.
 * 15) Glossary - definitions of frequently used terms that describe the application domain, user interactions, and system features.

Overview
The client profile describes the project's sponsor: type of organization, mission, customers or constituent base, etc. The problem that the project addresses and its importance set the stage for listing the project's objectives.

Current system
This description details the current processes that the system under development will make more efficient. Forms, documents, other systems, and roles of personnel that carry out current tasks are spell out.

Functional requirements
List the the high-level interactions between the system and its environment (users or other external systems, if that's the case). The description of these interactions is independent of actual implementation of the system. These interactions are features that the system must have, from the user's point of view (not developer's view).

The list of functional requirements provides names for the use cases.

Use case stories
User stories are an agile approach to requirements that help shift the focus from writing about requirements to talking about them (Mike Cohn). Read more at http://www.mountaingoatsoftware.com/topics/user-stories.

Use case model
The model has
 * Definitions of the actors that interact with the system
 * Full descriptions of each use case. Use cases are consistent with the high-level functional requirements
 * Use case diagram.

The following examples have been adapted from the Ronald McDonald Homebase (RMH) case study presented in Tucker, Morelli, and De Silva's book, Software development: An open source approach, CRC Press, 2011.

has selected "view all Applicants". (odd-numbered steps are done the actor, even-numbered steps are done by the system)
 * Name: UpdateApplicantList
 * Description: The House Manager tracks an Applicant by arranging for the Applicant to shadow another Volunteer working at the House to learn about the duties s/he will perform. This use case provides a way to record an Applicant's progress and add him/her to the Volunteer list or the Substitute Call list at the end of the tracking process.
 * Types of users: HouseManager
 * Goals: To keep the Applicant list, Substitute list, and Volunteer list up to date.
 * Entry conditions:
 * 1) An Applicant's application has been received.
 * 2) The Applicant has been interviewed and background-checked.
 * 3) The HouseManager is logged into the system and has the Applicant's information.
 * Exit conditions:
 * 1) The Applicant's information is entered or updated in the Applicant list.
 * 2) If the Applicant's tracking is complete, s/he is added to the Substitute list or the Volunteer list.
 * Steps:
 * 1) HouseManager views the status of the Applicant (use case ViewAList)
 * 2) The system performs the search and lists results.
 * 3) If the Applicant is not listed, the HouseManager adds him/her to the list. Otherwise, the HouseManager makes updates.
 * 4) The system performs the changes and displays results.
 * 5) If the Applicant finished tracking a Volunteer, HouseManager adds Applicant to the Substitute Call list (use cases UpdateSubList) and/or to the Volunteer list (use case UpdateVolunteerList), and removes Applicant from Applicant list.
 * 6) The system performs the changes.


 * Name: ViewAList
 * Description: In updating a list, schedule, or calendar, the HouseManager or Volunteer needs to know who meets certain conditions, such as availability for a particular shift or having a particular skill. That information is specified along with the list to be searched, and the system provides the names and phones of all persons satisfying those conditions.
 * Types of users: HouseManager, Volunteer
 * Goals: To view entries in the Applicant list, Volunteer list, Substitute list, a Schedule, or a Calendar. Various selections should be possible.
 * Entry conditions: HouseManager or Volunteer knows the list s/he will look up and the search criteria s/he will use.
 * Exit conditions: All persons on the specified list who satisfy the specified criteria are displayed.
 * Steps:
 * 1) HouseManager or Volunteer selects the people's list, a schedule, or a calendar.
 * 2) The system presents the search form.
 * 3) HouseManager or Volunteer enters the search criteria.
 * 4) The system performs the search and lists results.

Use the following guidelines when you write full descriptions of use cases:
 * Use cases are named with verb phrases. The name of the use case should indicate what the user is trying to accomplish. Examples: ViewAList, ChangeASchedule, GenerateReminders.
 * Use cases are initiated by types of users, called actors. Types of users are named with noun phrases. Examples: HouseManager, Volunteer.
 * A use case should describe a complete sequence of interactions (or steps) between the actor and the system. This sequence of interactions, called steps or flow of events, is part of the use case description. All steps are numbered.
 * The steps in the sequence of interactions should be phrased in the active voice. Example: HouseManager fills out the search form. The system performs the search and lists results.
 * A step performed by the actor is always followed by a step performed by the system. Because an actor initiates a use case, actor's steps are odd-numbered, while system's steps are even-numbered.
 * A use case should not exceed a page in length.
 * Entry conditions (or preconditions) describe the situation in which the actor and system are just before the use case can be started.
 * Exit conditions (or postconditions) describe the status of the system reached after the completion of the use case.
 * A use case can include another use case at any of its steps. Included use cases factor out sequence of interactions that may be initiated from other use cases. Example: ViewAList use case is included at the first step in the UpdateApplicantList use case. UpdateSubList (or UpdateVolunteerList) use case is included at step 5 in the UpdateApplicantList.

(Adapted from Object-Oriented Software Engineering - Using UML, Patterns, and Java by Bruegge and Dutoit, 3rd edition, Prentice Hall, 2010, page 137).

The use case diagram is a UML diagram that shows the top-level use cases and types of actors that interact with these use cases.
 * Upload the png file that has the diagram.
 * Include the png with caption and brief explanation.

This use case UML diagram, like all UML diagrams in this course, are created with the Violet UML editor. Both class.violet and png files obtained with Violet must become part of the project's code base and be under version control.
 * Use uml directory in the code base to save all UML diagrams, both class.violet and png files.

Analysis object model
This model represents the structure of the system in terms of application domain concepts and their relationships. These are entities (or concepts) of interest in the application domain. Their objects represent persistent data that the system keeps track of and stores in some database.

It is important that we have clear definitions of the application domain concepts for which data is collected. These definitions also go in the Glossary.

To show the relationships between application domain concepts for which data is collected, we draw a class diagram:
 * Include the png file of the diagram in the RAD document and provide a caption.
 * The associations should have labels and maximum cardinality values.
 * Associations that represent inheritance relationships use a triangle arrow head and do NOT show maximum cardinality values (unless they are different than one-to-one - which is not the case of our projects).
 * Associations that represent aggregation relationships use a diamond arrow head (not present in our projects).
 * Other associations that are not inheritance or aggregation use solid lines with no arrow heads.
 * Do not list the class attributes at this step. A class is simply a rectangle with the class name in it.

This UML class diagram, like all UML diagrams in this course, are created with Violet UML editor. Both class.violet and png files obtained with Violet must become part of the project's code base and be under version control.
 * Use uml subdirectory of devel-docs directory in the code base to save all UML diagrams, both class.violet and png files.

User interface mock-ups
These mock-ups are not the final dynamic web pages the system's user interface has to support user interactions. They are preliminary interface designs or visuals that must accompany the use case descriptions. Use cases and user interface mock-ups facilitate the on-going conversation between developers and users about the functional requirements that the system must have. The user interactions that are captured by these analysis artifacts must be consistently represented in the textual description of the use cases and the visual illustration of the mock-ups.

The mock-ups of interest include the most representative features of the system. Mock-ups can be created with Balsamiq or can be written in HTML/CSS. In either case, a PNG file of the mock-up should be included in RAD. Mock-up HTML/CSS files and Balsamiq PNGs must be maintained in the project central repository.

Nonfunctional requirements
Notes from Breugge and Dutoit's book (pages 126-127 and 250-252).

Non-functional requirements describe aspects of the system that are not directly related to the sequence of interactions between users and the system. They fall into two broad categories: List the quality requirements in the  System Design Document (SDD), in the Design Goals subsection (under Introduction).
 *  Quality requirements  of the system deal with qualities that the system should have. These qualities become the system design criteria and fall into:
 * Performance criteria include the speed (response time) and space (memory usage) requirements imposed by the system.
 * Dependability criteria include robustness, reliability, availability, fault tolerance, security.
 * Cost criteria include the cost to develop the system, deploy (installation and user training), administer, upgrade, and maintain it.
 * Maintenance criteria include extensibility, modifiability, adaptability, portability, readability.
 * End user criteria include qualities that are desirable from a user's point of view and have not been covered by the performance and dependability criteria. Two criteria are of interest here:
 * Utility: how well the system supports the work of the user
 * Usability: how easy it is for the user to use the system

List the constraint requirements in the  Requirements and Analysis Document (RAD), in the Nonfunctional Requirements section.
 *  Constraint requirements  fall into:
 * Implementation requirements, including the use of specific tools, programming languages, or hardware platforms.
 * Interface requirements
 * Operations requirements are constraints on the administration and management of the system in the operational setting.
 * Packaging requirements are constraints on the actual delivery of the system
 * Legal requirements are concerned with licensing.

Target environment
This section describes what computing resources (operating system, bundled software, server applications and client software tools) the proposed system will use.

System Design Document (SDD)
A  system design document (SDD)  describes the system design model. This model includes:
 * Design goals of the project
 * System architecture - that is the decomposition of the system in smaller subsystems that can be realized by individual teams or single developers.
 * System services - what services the storage subsystem provides to the application logic subsystem, and what services the application logic subsystem provides to the user interface subsystem.
 * System infrastructure - that is selection of the hardware and software components on which the system will run, including data management components.

While an analysis model describes the application domain and all system's aspects from the user point of view, the system design model describes the solution domain and development decisions made by developers to allow teams members to work concurrently and collaboratively.

SDD Template
A SDD template has the following organization:
 * 1) Design goals
 * 2) System architecture
 * 3) System services
 * 4) System infrastructure

Design goals
See the  quality requirements list.

System architecture
This is a UML component diagram, where each component corresponds to a source code file or package of source code files. The relationships between subsystem components are dependency relationships, shown with dashed lines with arrows that point to the target component (used by or dependent-on by the source component). The meaning is that the source component has calls to the target component (which have functions/methods that satisfy the calls).

Figure 4-3 on page 91 in the textbook shows the RMH Homebase a detailed subsystem decomposition. This hierarchical decomposition uses a layered architecture. Layers are ordered: each layer depends on lower-level layers. A subset from a layer decomposition that has at least one subsystem from each layer is called a vertical slice.

Our projects also use a layered architecture that has the following layers: view-control, db-control, and model:
 * view-control subsystem depends on the db-control and model subsystems and is responsible for implementing user interactions.
 * model subsystem is responsible for representing concepts of the business and business rules.
 * db-control subsystem depends on the model subsystem.

The user interacts only with the ui subsystem. The database is accessed by and returns information only to the db-control subsystem.

To describe the high-level decomposition of the system of your project:
 * Create a UML component diagram (with the UML Violet editor) to describe the layered architecture of your system.
 * Upload the png file to the project's wiki and include it in the SDD document (in the "Subsystem decomposition" section).
 * The diagram has a caption and a brief explanation.

Additional UML component diagrams show in more detail the structure of a vertical slice. A vertical slice corresponds to a use case.

To describe the system design structure in more detail, for each representative use case:
 * Create a UML diagram that shows dependencies among components that are used to implement a particular use case.
 * The diagram's components are labeled with the PHP file names.
 * Upload the png file and include it in the SDD document (in the "Subsystem decomposition").
 * The diagram has a caption and a brief explanation.

These UML component diagrams, like all UML diagrams in this course, are created with the Violet UML editor. Both class.violet and png files obtained with Violet must become part of the project's code base and be under version control.
 * Use uml subdirectory of devel-docs directory in the code base to save all UML diagrams, both class.violet and png files.

Storage subsystem
Models and descriptions that are useful to developers and pertain to the database design and implementation go in this section.
 * Database design diagram obtained from MySQL Workbench (or from a UML editor) are exported to a png file and included here (with a caption and brief narrative).
 * Dependency graphs that explain the order in which the tables must be dropped and created are another example of an artifact that belongs to this section.

To describe a database design:
 * Name the database and describe its purpose.
 * Name all its tables along with brief descriptions of what each table represents, what attributes it has, which is the primary key, and any other special characteristics (such as whether the table is an intersection table).
 * Describe all relationships and explain cardinality values.
 * Include the database design diagram. This is a UML class diagram or entity-relationship diagram obtained from SQL IDE's, such as MySQL Workbench.

A dependency graph shows 'child of' and 'parent of' dependencies among the database tables. These graphs show in which order the database tables are dropped and in which order they are created (ordering is not the same for dropping and creating tables!).

All drop table statements are written at the beginning of the SQL script that creates the tables and their constraints. The order in which these statements are written corresponds to the order of layers in the 'child-of' dependency graph.

All create table statements are written after the drop table statements and in the order imposed by the referential integrity constraints. This order corresponds to the order of layers in the 'parent-of' dependency graph.

Guidelines to create a dependency graph and use it in the SDD document:
 * Use the Violet UML editor to draw a class diagram that shows dependency relationships.
 * Annotate the dependency relationships with either 'parent-of' or 'child-of' labels.
 * Export the UML diagram to a PNG file.
 * Upload the PNG file to the project's wiki and include it in the SDD document in the "Persistent data management" section.
 * Add a caption and a brief explanation.

The database design diagram and dependency graphs must become part of the project's code base and be under version control.
 * Use uml subdirectory of devel-docs directory in the code base to save all diagrams and graphs. If Violet UML editor is used to create a diagram, then both class.violet and png files are saved in the uml directory.

Example of database design
A sales database manages invoices made by customers who buy items. The relational model of this database has the following tables:
 * customer: A customer has a last name and first name. The primary key is customerID. Primary key values are generated by the database server.
 * invoice: An invoice has the date when the invoice was made, the ID of the customer who placed the invoice, and a primary key, invoiceID. Primary key values are generated by the database server.
 * item: An item has name, description, and quantity on hand (how many items of that particular name are on stock). The primary key is itemID. Primary key values are generated by the database server.
 * invoice_item: An invoice_item associates an invoice ID with an item ID and has additional information about the quantity of a particular item sold with a particular invoice, and sale price for that particular item. The primary key is a composite key of invoiceID and itemID columns. This table is an intersection table.



All relationships are one-to-many:
 * customer-invoice: A customer object can be linked to many invoice objects. An invoice object is linked to exactly one customer object.
 * invoice-invoice_item: An invoice object is linked to at least one invoice_item object. An invoice_item object is linked to exactly one invoice object.
 * item-invoice_item: An item object can be linked to many invoice_item objects. An invoice_item object is linked to exactly one item object.

Examples of dependency graphs
Child tables in the sales database are invoice and invoice_item. See "Child-of" dependencies in the Sales database (UML class diagram). Parent tables are: customer, invoice, and item. See "Parent-of" dependencies in the Sales database (UML class diagram).



The SQL script sales_create_db.sql drops the tables in a top-down order following the "child-of" dependencies, and creates the tables in a top-down order following the "parent-of" dependencies.

System infrastructure
This section is necessary if more technical information is provided in addition to the RAD's section, Target environment.

Object Design Document (ODD)
During object design developers produce the actual implementation of the subsystems designed during system design. Therefore, object design document (ODD) is tightly linked to the source code and generated with code documentation generators, such as Doxygen.
 * See opencomputing wiki article Doxygen for examples of block comments you must write for each file, class, and function.
 * Include the copyright notice in each file block comment.
 * Use /** .... */ comment notation that Doxygen requires to generate software documentation.

Coding standards
Besides the source code generated documentation, ODD should include a section with coding standards. These coding standards are rules that developers should use when writing code.

We will start writing these rules here. When the list is to long, we'll move it to a separate page.


 * Line length: Limit each line of code to 80 characters.

function addTwoNumbers($firstNumber, $secondNumber) { $sum = $firstNumber + $secondNumber; return $sum; }
 * PHP function and variable names: Use "camel case" for function and variable names. For example:


 * PHP class names: Class names are capitalized.


 * Indentation: DO NOT use TABs in NetBeans or Eclipes. Change tabs to TWO spaces.

=Implementation= We use Tucker, Morelli, and De Silva textbook, Software Development - An Open Source Approach (see References), and the Ronald McDonald House (RMH) case studies: RMH Homebase 1.5, RMH Homebase 2.0, and RMH Homeroom, to learn how to implement your team projects.

The implementation of the web application is written in PHP. The implementation of the database is written in SQL. The PHP modules that implement the application user interface use HTML and CSS.

PHP application domain classes
The model folder has PHP classes that describe application domain concepts. These application domain concepts model persistent data stored in a database. Therefore, each class has a corresponding database table.
 * Use the same name for both the application domain class and the table.
 * For each class, define instance variables that correspond to table columns.
 * Use the same name for the class' instance variables and table's columns.
 * Write setters and getters for the class instance variables.
 * Instance variables that correspond to primary auto-increment keys should not have setters.
 * Write a constructor that has as many parameters as instance variables and assign parameter values to the instance variables.

Example of creating an application domain object
Note that many of the database tables have surrogate keys whose values are automatically generated by the MySQL server. The data type of these primary keys is auto_increment. That is why the constructor of an application domain object has parameters for all the instance variables except for the instance variable that corresponds to a surrogate key. The constructor assigns "null" value to that instance variable. All the other instance variables are set by the parameter values.

For example, when you define a variable $c whose value is an object of type Customer as defined in class Customer above, you write: $c = new Customer("Smith", "Ben", ...);

PHP database modules
The db-control folder has PHP modules that:
 * Control the interaction between the system and the database
 * Assist with database management operations:
 * set up all the database tables with no data in them (dbInstall.php)
 * populate the database with sample data (dbInstallSandbox.php

The naming convention for these db-control modules uses the prefix "db" followed by the name of the table. For example, dbPerson.php is the db-control module that provide services for creating, accessing, and manipulating data in the Person table.

The services of a db-control module that implements the interaction between the system and the database are:
 * create a table
 * delete a table
 * insert, delete, and update data in a table
 * retrieve certain data from a table.

Important Note: The interaction between the system and the database is carried out by mysql_query calls. To improve the system's performance, each mysql_query call must be have two "book ends": Do not keep a connection open for more than one mysql_query operation at a time.
 * A call that connects the system to the database just before mysql_query call, and
 * A call that closes the connection using mysql_close calls just after mysql_query call.

Create table service example
This function is called in dbInstall.php module to create a table that corresponds to an application domain class.

Note that there is no DROP TABLE statement executed before the table is created. This is because the order in which tables are created is different from the order in which tables can be dropped. In the dbInstall.php module, all drop statements are executed prior to executing the create table statements. Use the xxx_create_tables.sql script as a guide for implementing dbInstall.sql module.

Insert data service example
This function is called in the dbInstallSandbox.php module. Here is an example:

SQL scripts
There are three SQL scripts that has the SQL code to:
 * 1) Create the database and a user for it. Call this script xxx_create_db_user.sql, where xxx stands for the name of your project's database (e.g. donate, i2c, and dv-unit).
 * 2) Create the tables in the database and its constraints. Call this script xxx_create_tables.sql.
 * 3) Populate the database with data. Call this script xxx_insert_data.sql.

Common mistakes when you write your SQL scripts

 * Name a column or a table with a MySQL keyword. Avoid using date, name, state, or user. Instead:
 * use xxxDate and xxxName, where xxx is the name of the table that has xxxDate or xxxName column.
 * replace state with stateName for a column that stores state name values.
 * replace user with sysuser or user-profile for a table that store user accounts for the system you develop.
 * Mispelled auto_increment. Search for "auto" (unless that's misspelled, too!) and verify that increment is spelled correctly.
 * Missing _ in auto_increment. Again, search for "auto" and verify that there is a _ between "auto" and "increment".
 * Missing , between clauses in the create table statements. Descriptions of table columns and constraints must be separated by ,, unless the clause is the last one in the table.

Create a database and a user account with database scope privileges
To run the script that creates the database and a user for it, you must login to the MySQL server with an account that has global privileges. You have access to such account on your local MySQL server. However, you cannot login to the MySQL server on the staging server with an account that has global privileges. Send your xxx_create_db_and_user.sql script to Chris, who'll run it for you.

See  Example of SQL script to create a database and a database user.

Create the database tables and their constraints
See Example of SQL script to create the database tables and their constraints.

Populate the database with sample data
See Example of SQL script to populate a database with sample data.

Database backup

 * To backup the database that was correctly created and populated, use mysqldump utility.
 * To recover the database from the backup file, use the source command in mysql utility.

See Example of database backup from mysqldump.

Example of SQL script to create a database and a database user
The user you create must have the privileges to do anything in the database s/he designs and manipulates. These are called database scope privileges. We use the command to assign database scope privileges to the user 'sales'.

For more information about how to manage users in MySQL see Manage Users Tutorial. I'm including an important note on the GRANT OPTION privilege.

Note on the GRANT OPTION Privilege
A special privilege provides users with the ability to grant privileges to other users. If the GRANT statement is issued with the WITH GRANT OPTION clause, it means that the user has the special privilege to grant other users the same privileges they have.


 * Warning: There are very few reasons to have users with WITH GRANT OPTION clause. It is a security headache and user privileges should be granted by very few individuals, preferably only one. This ensures consistency and conformity with regard to security policies.

The following script has the code for creating a user with database-scope privileges.

To verify that the user has been created, check user name and password in the metadata table user in the metadata database myslq: The output of this command should be something like: ++---+ ++---+ ++---+
 * user  | password                                  |
 * sales | *FE78AD5B78723763A568B1EE4FD44324EEF2A87A |

Example of database backup from mysqldump
A database backup file is obtained from mysqldump utility. A backup file is generated ONLY AFTER the database:
 * has been correctly created,
 * has correctly implemented tables with named primary and foreign key constraints, and
 * has been correctly populated with data.

These steps require that you have created and executed successfully the SQL scripts:
 * xxx_create_db_and_user.sql - creates the database and a user with database scope privileges
 * xxx_create_tables.sql - creates the database tables and their primary and foreign key constraints
 * xxx_insert_data.sql - populates the database with sample data.

=References=
 * 1) Google Code Project Hosting - Getting Started. Code.google.com. Retrieved 2011-02-06.
 * 2)  Manage Users Tutorial. Webeucator, Inc. Retrieved March 1, 2011.
 * 3) Version Control with Subversion (for Subversion 1.5), by Ben Collins-Sussman, Brian W. Fitzpatrick, C. Michael Pilato. Retrieved 2011-02-06.
 * 4) Subversion FAQ. Code.google.com. Retrieved 2011-02-06.
 * 5) Tucker, A., Morelli, R., and De Silva, C. (2011). Software Development - An Open Source Approach. CRC Press.