//|---------------------------------------------------------------------
//|             |============================|	
//|             |   BERT v1.0                |
//|             |============================|
//|
//|         (BUSINESS ENVIRONMENT RESOURCE TRACKER)
//|
//|                           by Andrew Noske,
//|                              Cheryl Thomas &
//|                              Timothy Anderson
//|
//|                               28/10/2003
//|---------------------------------------------------------------------



|===================================|
|    INSTALLATION INSTRUCTIONS.     |
|===================================|

  NOTE:  If you have problems following these instructions
         email andrew.noske@jcu.edu.au


------------------------------------------------------------------------
ASSUMPTIONS:


1: Classpaths are correct & includes MySQL java database connector
   NOTE: Editing then executing "__change_class_paths.bat" should
         help you to do this quickly (if you know what your doing)

2: Your machine must be connected to JCU network in order for program to connect to manning.cs.jcu.edu.au, (the default database).

3: Sun ONE Studios 4 is installed, the update is installed, and the JUnit addon is installed. 

4: Tomcat is installed and working - (preferably the version of Tomcat which comes with SunStudios). 

------------------------------------------------------------------------
MySQL JAVA CONNECTOR SETUP:


Download the MySQL Java Connector from www.mysql.org. 
Unzip this into an appropriate directory (eg: "C:\mysql-connector-java-3.0.6-stable"). 
Add the connector JAR file ("mysql-connector-java-3.0.6-stable-bin.jar") to your currenly classpath 
Make a copy of the connector JAR to the classpath used by Sun Studios "C:\Program Files\s1studio_jdk\j2sdk1.4.1_02\jre\lib" (or else our JUnit testing won't work). 

------------------------------------------------------------------------
BERT SETUP/BUILD: 


#1) Download & unzip the install file (g50_bert_install.zip) to any directory (DONE)

#2) Run build_all.bat (In the first level of the unzipped directory). This will build all classes (including the gui classes).

You can try to run build_test, but it will probably fail since all tests were written using Sun Studios (with the JUnit addon). You have to the Sun Studios environment to compile and execute these tests.

------------------------------------------------------------------------
BERT JSP WEBSITE:


#1) Now all classes have been compiled copy the "bert" directory (with all the class files) to the "\classes" directory under tomcat. 

#2) Copy the "bert_jsp/bert" directory (with all the jsp files) to the "\webapps\ROOT" directory under tomcat. 
NOTE: Tomcat comes with Sun Studios, so we set that up to work, and used "D:\s1studio_jdk\s1studio\tomcat401\classes" and "D:\s1studio_jdk\s1studio\tomcat401\webapps\ROOT" respectively. 
I'm pretty sure is should work with any version of tomcat. 

#3) Start tomcat/catelina by executing "bin\startup.bat" under the tomcat directory. 
NOTE: If you have installed Tomcat as a stand alone, you will need to start an executable instead. 

#4) Open a web browser (preferrably Internet Explorer) and open the page "http://localhost:8080/bert/". You can start your navigation of the site at "http://localhost:8080/bert/login.jsp". Most, but not all senarios have been labelled in green. 
NOTE: the "make_employee.jsp" page demonstrates how JavaScript can detect incorrect field values (eg: letters in the phone number fields) at the gui level. 
NOTE: that none of the equipment booking is working at this stage. 
Try logging in as a Cheryl the superuser (details are provided), and then go back an log in as Andrew the normal user. Notice that each take you to a different page. Priveledged options are prevented for normal users.

------------------------------------------------------------------------


  //----------------------------------------------//
  //|  CHECKPOINT                                |//
  //|                                            |//
  //|     If you are only interested in getting  |//
  //|     the project to work (as a website on   |//
  //|     your machine) you may stop point.      |//
  //|                                            |//
  //|     All further instructions demonstrate   |//
  //|     the testing of, & (hopefully) the      |//
  //|     versatility of BERT                    |//
  //----------------------------------------------//


------------------------------------------------------------------------
BERT GUI AND ROBOT DEMONSTRATION:


#1) Execute run_gui.bat to execute BERT as a regular Java applicaiton. 
If an error message "jdbc drive not found" appears on startup, then you have not installed the MySQL Java Connector correctly.

#2) Run run_robot_demo.bat to see the robot testing of:
      entering an incorrect date and trying to view bookings (produces error message), 
      entering an correct date and viewing bookings (no error message this time), 
      attempting to book a room (will only work if there is no conflicting booking), and
      then view bookings again 
      All this JFrame/JPanel gui stuff was included only to demonstrate we
      understand JRobot. Our real objective was to get the program working
      as a jsp website.

------------------------------------------------------------------------
JUNIT TESTING:


#1) Open Sun Studios, and mount the directory you unzipped. Use the "filesystems" panel to navigate to "bert\control" and highlight/select all the use case tests classes (they all start with "UC"), open them and hit "build all" (Shift F11). Providing you installed the SunStudios JUnit addon correctly they should all compile without error.

#2) Open all the use case tests classes in SunStudios (as above) & execute them one at a time.

NOTE:
      Notice that all use case test require that the database is reset
      to its origional stage. For instance, "UC6_ManageEmployees_Test"
      adds a new employee called "dmitry" (hey - that's you!), & deletes
      the employee "benjamin" (which seems strangely appropriate). If this
      was run twice without reset database values the test would fail to add
      "dmitry" (since he already exists), and fail to delete "benjamin"
      (because he's already been deleted). I've written the method
      "clearAndPopulateAllTablesWithTestData()" in "DBSetupServices"
      to serve this purpose. All use cases call this method at the beginning
      of their execution.

------------------------------------------------------------------------
MYSQL DATABASE CHECKING: (optional)

(use this to view the database as you make changes to it via the jsp pages).

#1) Open a putty window and log onto manning (as yourself)

#2) Type/copy this:

      mysql -p -h manning.cs.jcu.edu.au -u g312_50 
      jrzCszB77 
      use g312_50db; 

#4) The following commands may also be useful:

      show tables;
      select * from room_bookings;

#5) If have changed the database & you want to revert to the origional database (with 4 rows populated in each table) then cut & paste the text from "bert_sql/bert.sql", or run "database/IDBConnection_Reset_DB".  //%%%%%%%%%%

------------------------------------------------------------------------
USING A DIFFERENT MYSQL DATABASE:

Currently, to use a different MySQL database you must go into "bert/common/Global" & change the values of dbHost, dbName, dbUser & dbPassword. Recompile it.

NOTE: We wanted to have these set automatically by reading in an XML file, but it wasn't worth the marks & ran out of time.

------------------------------------------------------------------------

  //----------------------------------------------//
  //|  CHECKPOINT                                |//
  //|                                            |//
  //|     I havent had time to check that the    |//
  //|     instructions below work perfectly      |//
  //|     with the JSP site. In theory they      |//
  //|     should work, but I wouldn't advise     |//
  //|     trying                                 |//
  //|                                            |//
  //----------------------------------------------//

------------------------------------------------------------------------
USING A MSACCESS DATABASE:


To use a Microsoft Access database (instead of MySQL), the process will be more involved.

First, open "bert/common/Global", change the value of dbType to "MSACCESS". Recompile it.

To make the Microsoft Access Database work in Windows XP or Windows NT you must register a DSN (Data Source Name) for "bert.mdb" to your system ODBC 
Administrator.

TO DO THIS YOU MUST:

1.  Go to the control panel->administrative tools.
2.  Double click on 'Data Sources (ODBC)' shortcut.
3.  Select the 'System DSN' tab.
4.  Click  'add'.
5.  Select 'Microsoft Access Driver' (*.mdb).
6.  Click  'finish'.
7.  Enter  "bert" in the Data Source Name textfield.
8.  Click  'select' button in the Database button group.
9.  Find the "bert.mdb" dbfile (in the same directory as this file).
10. Click  'ok' to close the open file dialog.
11. Click  'ok' to close the Data Sources (ODBC) dialog.

NOTE: if database is on another host, click the network button and folow the wizard.

It should now work (fingers crossed).

------------------------------------------------------------------------
