gh Add Mike Naberezny's commentary.

git-svn-id: http://www.lyonlabs.org/svn/trunk@5 9a5e7900-32cd-4ded-a25b-a9dc1bcb21d6

reference/mike_n/01-getting-started.txt

@@ -0,0 +1,55 @@
+Getting Started
+===============
+
+Create the database
+  1. mysql -uroot -e"create database clink"
+  2. mysql -uroot -e"grant all privileges on clink.* to 'clinkuser'@'localhost' \
+      identified by 'clink' with grant option"
+  3. mysql -uroot -e"flush privileges"
+  4. Change the working directory to /trunk.
+  5. mysql -uclinkuser -pclink clink < schema.sql
+  6. mysql -uclinkuser -pclink clink -e \
+     "CREATE TABLE room_log (room varchar(40), public_ind enum('N','Y'), seat int(11), \
+      handle varchar(40), action varchar(40), text text, timestamp datetime);"
+  7. mysql -uclinkuser -pclink clink -e \
+     "CREATE TABLE vendor_rooms (reference_id int(11), room varchar(40));"
+
+  Notes: 
+    The Java server source is hardcoded to use the database configuration above.
+
+    The CREATE TABLE statement is necessary because the `room_log` table is required 
+    by the server but is not found in the schema.sql load file.  Column types are best-guess.
+
+    The `audit_log` table in schema.sql appears to not be used and is not referenced
+    anywhere in the source code.
+
+    Another table, `vendor_rooms`, is referenced in the source code but not in schema.sql.
+    See 9-vendor-rooms.txt for more information on this table.
+
+Build the Java classes (*.class) from sources (*.java):
+
+  From Eclipse:
+    1. Import the project into Eclipse
+    2. Compile the project into /trunk/classes using Project > Build All
+
+  From Command Line:
+    1. Generate an Ant build file in Eclipse: 
+         File > Export > General > Ant Buildfiles
+         Select the project
+         File "build.xml" should be generated in /trunk
+    2. Change the working directory to /trunk.
+    3. Ensure a clean build with `rm -rf classes/*`
+    4. Run `ant` to build.
+
+Run the server
+
+  1. Change the working directory to /trunk.
+  2. Start the server:
+        java -cp lib/log4j-1.2.5.jar:lib/martyr.jar:lib/mysql-connector-java-3.1.10-bin.jar:classes \
+        org.jbrain.qlink.QLinkServer
+
+Test the server
+
+  Once the server starts, it should output log messages and wait for
+  connections on port 5190.  Running `telnet localhost 5190` should
+  connect and show "Incoming connection received" in the server log.

reference/mike_n/02-accounts-users.txt

@@ -0,0 +1,67 @@
+Accounts & Users
+================
+
+User has-many Accounts (`users` table, `accounts` table)
+
+  `users`
+    user_id           Primary key.  Auto-increments.
+    active            Is this user active?  (enum N/Y)
+    access_code       Access Code stored on QLink diskette
+    orig_account      ?
+    orig_code         ?
+    name              Full name (e.g. Mike Naberezny)
+    city              City (San Jose)
+    state             CA
+    country           USA
+    email             Always NULL.  not implemented?
+    create_date       Datetime
+    last_access       Datetime
+    last_update       Datetime
+
+  `accounts`
+    account_id        Primary key.  Auto-increments.
+    primary_ind       enum('Y','N') -- Primary Account?
+    staff_ind         enum('Y','N') -- Staff Account?
+    user_id           Foreign key to the `users` table
+    active            Account active/enabled?  (enum Y/N)
+                      Not clear what this is used for since removing
+                      an account actually deletes the row.
+    handle            User's handle (10 characters)
+    create_date       Datetime
+    last_access       Datetime
+    last_update       Datetime
+
+Primary Account
+  A User can have many Accounts.  When the user logs on to QLink,
+  a menu is presented, "Select user name to sign on with:".  If the user has
+  only one account, this menu is not presented.
+
+  Each User has one "Primary Account", indicated by `accounts`.`primary_ind`='Y'.  
+  Other accounts the User has are called "sub-accounts". This significance is
+  not yet understood.
+
+Staff Account
+  Accounts with `accounts`.`staff_ind`='Y' are QLink Staff Member accounts.
+  These accounts have privileges beyond those of normal accounts.  See
+  09-chat-room.txt for examples.
+
+Notes
+  On QLink, the user can modify his/her account information by
+  going to Customer Service -> Account/User Name Maintenance
+
+  A user can delete his/her accounts, but the user must always have
+  at least one account.
+
+  Certain handles are reserved and cannot be registered.  These are stored
+  in the `reserved_names` table.
+
+  The validation rules for a handle is stored by
+  state.AbstractAccountState.validateNewAccount().
+
+  Refer to UserManager.java
+
+Issues
+  There is not an easy way to tell if a user is logged in to QLink. The only
+  way currently is to try to actually connect to the QLink server using the
+  QLink protocol and attempt to login. This is problematic also because it
+  will update `users`.`last_access`.

reference/mike_n/03-bulletins.txt

@@ -0,0 +1,21 @@
+Bulletins
+=========
+
+Bulletins are displayed after the user logs in, before the main menu
+is displayed.
+
+  `bulletin`
+    bulletin_id     Primary key.  Auto-increments.
+    text            Text to display in the bulletin.
+    start_date      Datetime
+    end_date        Datetime
+    approved        enum('Y','N')
+
+This query finds the bulletin(s) to display (org.jbrain.qlink.state.MainMenu.java):
+
+  SELECT text from bulletin 
+  WHERE start_date<now() AND end_date>now() AND approved='Y' 
+  ORDER BY start_date DESC
+
+If there is more than one row returned by the query, the bulletin text for each 
+will be shown to the user in order.

reference/mike_n/04-email.txt

@@ -0,0 +1,37 @@
+Email
+=====
+
+Users can send email to each other (local to QLink).  These are stored in the
+`email` table.
+
+To send a message:
+  Enter People Connection and then press F7
+  Select "Q-Link Post Office"
+  Select "Send E-Mail to someone's mailbox"
+  Enter the recipient's username
+  Enter the message and then RETURN on a blank line to send.
+
+When a message is sent, a row is inserted into the `emails` table:
+
+  `email`
+    email_id        Primary key.  Auto-increments.
+    recipient_id    Foreign key to `accounts`.`account_id` of recipient
+    sender_id       Foreign key to `accounts`.`account_id` of sender
+    recipient       Always NULL. (?)
+    sender          Always NULL. (?)
+    subject         Always NULL. (?)
+    body            Body of the message.  Oddly, this includes the headers:
+                    """
+                    Mail From:  Mnaberez
+                    Date:  Wednesday 26-Dec-2007 17:21 PST
+                    Text entered by user here
+                    """
+    unread          enum(Y/N)
+    received_date   Datetime.  This is actually when the email was sent.
+
+In order to see if any email is waiting, the user must enter the 
+Q-Link Post Office and select "Read Waiting Mail".  When mail is read,
+the `unread` enum changed from 'Y' to 'N'.  
+
+There appears to be no way for a user to go back and read messages 
+already read, nor is there a way to delete email rows from the database.

reference/mike_n/05-menus.txt

@@ -0,0 +1,104 @@
+Menu Structure
+==============
+
+Menus are stored as a tree in the `toc` (Table of Contents) table.  For 
+every row in `toc`, there is a corresponding row in `entry_types`.  
+
+  `toc`
+    toc_id        Primary key.  Does not auto-increment.
+    menu_id       See note below.
+    reference_id  Self-reference key to parent item's menu_id
+    title         Title of the menu item
+    sort_order    Always '1'
+    active        Always 'Y'
+
+When the user selects a menu item, the method selectItem() of
+org.jbrain.qlink.state.DepartmentMenu determines how to handle the menu
+item from its entry_type.
+
+Notes:
+  The `menu_id` relates to how Q-Link used a 24 bit address space for any
+  "artifact" on the system. This is why the old QLink started losing stuff at
+  the end, it ran out of space. Message Base postings were just items, but
+  they had to live > 0x800000.  We must constraint the menu_id to < 0xFFFFFF.
+
+  There is a maximum number of items that can exist under a single menu.
+  Jim believes it is 11 items max.
+
+Entry Types
+===========
+
+The `toc` table is a tree of items in the QLink system hierarchy.  Each row
+in that table has an associated row in the `entry_types` table that identifies
+what kind of item it is.
+
+  `entry_types`
+    reference_id  Foreign key to menu_id in `toc` table
+    cost          enum('PREMIUM','NORMAL','NOCHARGE')
+    entry_type    See table below.
+    special       enum('Y','N') -- if special, a custom handler is used.
+
+A listing of entry_types is found in the class constants at the top of the 
+class org.jbrain.qlink.cmd.action.MenuItem:
+
+    Name             Hex     Dec     Implemented?    Description
+    -------------    ----    ----    ------------    -----------
+    HEADING          0x00    0       Y               Top-level item
+    MESSAGE_BASE     0x01    1       Y               Message Base
+    MESSAGE          0x02    2       Y               Message; display it.
+    MENU             0x81    129     Y               Menu; send new menu.
+    TEXT             0x82    130     Y               File; display it.
+    UNKNOWN_83       0x83    131
+    UNKNOWN_84       0x84    132
+    GATEWAY          0x85    133     Y               Gateway; connect to it
+    AREA_MENU        0x86    134
+    POST_OFFICE      0x87    135
+    MULTI_TEXT       0x88    136     Y               File; display it.
+    UNKNOWN_89       0x89    137
+    DOWNLOAD         0x8A    138     Y               Download; display text.
+    CHAT             0x8B    139     Y               Chat Room; enter it.
+    UNKNOWN_8C       0x8C    140
+    UPLOAD           0x8d    141
+    UNKNOWN_8E       0x8E    142
+    MENU_DATA        0x8F    143
+    FILE_DESC        0x90    144
+
+The entry_types, at least those from 0x80 up, are actually from the QLink 
+protocol.  They are described at the bottom of Keith Hendrickson's notes 
+about the protocol that can be found in /trunk/reference/protocol/qlinkfuncs.txt
+
+
+Special Entry Types
+===================
+
+When a row in the `entry_types` table has `special`='Y', it is a special entry
+type.  Rather than using the standard handler for its entry_type, it uses a
+special handler.  
+
+In this case, it will have an entry in the `reference_handlers` table:
+
+  `reference_handlers`
+    reference_id    Foreign key to reference_id in `entry_types` table
+    handler         Class name of the Java handler for this entry type
+
+
+Importing Menus from Text Files
+===============================
+
+  There is a utility (src/ImportMenus.java) that will read a hierarchical 
+  text file containing menu items and produce the SQL statements to insert
+  the items into the `toc` and `entry_types` tables in the database.
+
+  1. Change the working directory to /trunk
+  2. Run the utility: 
+        java -cp lib/mysql-connector-java-3.1.10-bin.jar:classes ImportMenus \
+        reference/sw-support.txt 9000
+
+  Arguments:
+    - Text file to read.  There are two text files with menus in 
+      /trunk/reference/: sw-support.txt and hw-support.txt
+    - The first menu_id for the INSERTs.  The database does not auto-increment
+      the menu_id column and it's not clear how this ID is chosen.
+
+  Notes:
+    All items in the hierarchy will be created with entry_type = 129 (MENU).

reference/mike_n/06-message-bases.txt

@@ -0,0 +1,35 @@
+Message Bases
+=============
+
+QLink users can send messages to each other on public message bases.  Each
+message base is represented by a row in the `toc` table, whose associated
+`entry_type` is 0x01 in the `entry_types` table.
+
+To find all of the message bases in QLink:
+
+  SELECT * FROM TOC WHERE REFERENCE_ID IN (
+    SELECT REFERENCE_ID FROM ENTRY_TYPES WHERE ENTRY_TYPE=1
+  );
+
+All messages for all message bases are stored in the `messages` table:
+
+  `messages`
+    message_id        Primary key.  Auto-increments.
+    reference_id      ?
+    parent_id         If this is a new thread, 0.
+                      If this is a reply, key to `messages`.`reference_id`
+                      of the parent message
+    base_id           Foreign key to the `toc`.`reference_id`
+    title             Title of the message
+    author            Author's handle (not ID)
+    text              Body of the message.  Oddly, this includes the headers:
+                      """
+                      SUBJ: test topic                       
+                      FROM: Mnaberez    12/26/2007 S# 534
+                      Text entered by user here
+                      """ 
+    date              Datetime created
+    replies           Number of replies to this message
+
+The reference_id is computed in org.jbrain.qlink.db.DBUtils but it's still
+not clear how this works.

reference/mike_n/07-articles.txt

@@ -0,0 +1,60 @@
+Articles
+========
+
+Articles are text blocks stored in the database.  When the user
+selects an article from a menu, the text is displayed to the user.
+
+Articles may be linked to other articles in the same table.  In 
+this case, pressing F7 gives the user the ability to navigate
+to the previous or next article.
+
+  `articles`
+    article_id      Primary key.  Does not auto-increment.  This is the
+                    same as the `reference_id` in the `toc` table.
+    next_id         Key to `article_id` of next article in this chain,
+                    or 0 if no next article.
+    prev_id         Key to `article_id` of previous article in this chain,
+                    or 0 if this is the first article in the chain.
+    data            ASCII text of the article that is displayed to the user.
+
+
+Adding an Article Chain (entry_type = MULTI_TEXT)
+
+  The first article (or only article) in an article chain must have a
+  row in the `toc` table.  That row must have an associated row in the
+  `entry_types` table, and the `entry_type` must be 136 (MULTI_TEXT).
+
+  Example:
+    Main Menu > Customer Service Center > What's New
+
+    "What's New" in the `toc` table:
+      toc_id:       235
+      menu_id:      4
+      title:        What's New
+      reference_id: 401
+
+    "What's New" in the `entry_types` table:
+      reference_id: 401
+      entry_type:   136 (MULTI_TEXT)
+      cost:         NORMAL
+      special:      N
+
+    First article of "What's New" chain in `articles` table:
+      article_id:   401
+      prev_id:      0
+      next_id:      1000006
+      data:         <text message>
+
+    Next article of "What's New" chain in `articles` table:
+      article_id:   1000006
+      prev_id:      401
+      next_id:      1000005 -- yes, its backwards(?)
+      data:         <text message>
+
+  Important:
+    The first article in an article chain has associated rows in the
+    `toc` and `entry_types` tables.  
+
+    Each successive article in the chain does not have a row in the
+    `toc` table.  However, it DOES have a row in the `entry_types` table.
+