[Rapforums-developer] release ReadMe0.9.txt,NONE,1.1

[Brad R. <br...@us...>]

Update of /cvsroot/rapforums/release
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv18037

Added Files:
	ReadMe0.9.txt 
Log Message:
no message

--- NEW FILE: ReadMe0.9.txt ---
RAPForums Channel for uPortal 2.x
Version 0.9

by Brad Rippe (br...@fu...) and Christopher Pereda (cp...@fu...)
----------------------------------------------------------------------------------------------------------------------
Directory Structure

classes 	{Compiled Java Classes}
docs		{JavaDocs/Screenshots}
lib		{required jars to compile/deploy channel} - JARS NEED TO BE IN YOUR {uPortal-Installation-Dir}/WEB-INF/lib
properties 	{tables.xml/data.xml/sqlScript.xml/server.xml}
release	{rapForums.jar/license}
sql		{sql scripts for DB tables - available scripts for Oracle, MySQL, and MSSQL}
src		{media/xsl/java}
-----------------------------------------PREREQUISITES-----------------------------------------------------------------

Ant is required to install this channel. For more information on Ant, please see http://ant.apache.org/.

-----------------------------------------INSTALLATION------------------------------------------------------------------

RAP FORUMS INSTALLATION:

MySQL Installation

1) Extract the Rap Forum's zip file
2) Configure the build.properties, change the deploy.home to property to point to your Application Server's webapps directory. 
   This should be similar to "c:/Tomcat_4-1-18/webapps/myFC" on a windows machine. There is also a test.home in case you have a test environment
   you would like to deploy to first.   
3) Set your classpath to include the following:
	./lib/log4j.jar
	./lib/jdom.jar
	./classes
	{$deploy.home}/WEB-INF/classes
	{$jdbcDriver.jar}

4) Run "ant db" to create the database tables. The data.xml file contains any categories, forums, threads, comments that you would like created initially. 
   This can also be achieved through the channel after it is installed with the initial data.
5) Run "ant deploy"
6) Restart your application server

MICROSOFT SQL SERVER INSTALLATION

1) Extract the Rap Forum's zip file
2) Configure the build.properties, change the deploy.home to property to point to your Application Server's webapps directory. 
   This should be similar to "c:/Tomcat_4-1-18/webapps/myFC" on a windows machine. There is also a test.home in case you have a test environment
   you would like to deploy to first.
   Change the jdbcDriver.jar in the build.properties to mssqlserver.jar, then uncomment 
   "<taskdef name="SQLTask" classname="edu.fullcoll.uportal.channels.rap.forum.tools.SQLTask"/>" before the compile task and 
   "<SQLTask scriptXML="properties/sqlScript.xml"/>" in the db task in the build.xml file.

3) Set your classpath to include the following:
	./lib/log4j.jar
	./lib/jdom.jar
	./classes
	{$deploy.home}/WEB-INF/classes
	{$jdbcDriver.jar}

4) Run "ant db" to create the database tables. The data.xml file contains any categories, forums, threads, comments that you would like created initially. 
   This can also be achieved through the channel after it is installed with the initial data.
5) Run "ant deploy"
6) Restart your application server

To add RAP Forum Administrators/Managers, you need to add the channel and view the forums first. The channel will then add RAP Forum Administrators 
and RAP Forum Managers to your portal groups.
**Default action places Portal Administrators as Forums Administrators.


INSTALLATION CONTINUED

PUBLISHING CHANNEL:

Channel Type -> Custom
Channel Title -> Rap Forums
Channel Name -> Rap Forums
Channel Description -> Forums
Channel Timeout -> 50000
Channel Class -> edu.fullcoll.uportal.channels.rap.forum.CForum

Parameters:
dbProduct = MSSQL - configure for SQL Server
	  = MYSQL - configure for MySQL
	  = ORACLE - configure for ORACLE

**If dbProduct is not set, the forums will use the MSSQL configuration by default.

Category -> Applications
Groups -> Everyone

Please note that the installation my vary depending on your particular environment. For the most part, there are sql scripts to create the database tables,
and an ant deployment task to deploy the channel to the portal.

----------------------------------------------------------------------------------------------------------------------
What are rap forums and how do they work?

Rap Forums is a discussion forum channel. The forums channel allows users to create forums, threads and post messages (comments) to the forums. 
Rap Forums currently supports three types of users:

RAP Users - anybody looged on to uportal and guests
RAP Forum Managers
RAP Forum Administrators
Uportal Administrators

All users can post comments and create threads.
Rap Users can create threads, and post messages (comments) to a thread.
Uportal Administrators, Rap Administrators and RAP Managers can create forums, threads, and comments. 
These groups will be used in later versions for more flexiblity and control over the forums. 
Currently, Admins and managers have the ability to create a forums, delete forums, add categories, and delete categories through the channel interface.


Implemented features

- Search (Bare Bones) 
Rap Forums currently implements a brute force search. Users can search for comments by title text, subject text, user, and category. The search returns results based on a paging parameter, 10, 15, or 30. The results are retrieved from the database with each page request.

- Comment Profanity Filtering
Rap Forums provide filtering for in appropriate words, phases or sentences. 

- Category Creation
The forums provide a user interface for category creation and deletion. Only Managers and Administrators are currently able to create/delete forum categories.

- Forum Creation
The forums provide a user interface for forum creation and deletion. Only Managers and Administrators are currently able to create/delete forums.


***** Future features *****
----------------------------------------------------------------------------------------------------------------------
- Search
	Cachable search results
	Search by dates
	Indexed search
	

- Administrator and Manager interface
	UI for Thread deletion
	UI for Comment deletion
	UI for filter management

	Managing Users
	Managing Forums managers		(Admin)
	Assigning Managers to forums		(Admin)
	Block guest account from posting

- Utilities
	Forum loader for populating RAP Forums with forum titles via a data source or xml file. The idea is to have pre-existing courses
	in a database and load them as forums. 		(Can be done with data.xml)
	Database Loader			       		(uPortal's DatabaseLoader)
	Paging support for multiple database systems	(Tested support for MS SQL and MySQL. Support for Oracle provided but not tested)

	
----------------------------------------------------------------------------------------------------------------------
SQL Scripts from provided in the "sql" directory. 
Scripts are provided:

rapForumsMSSQL.sql - 
This is the original MS 2000 sql script for the forums database. Current version of Rap Forums relies on the portal's DBLoader 
to create tables. Thus, table create should be generic. A custom Ant task, SQLTask, is used to set the database default values and create the 
stored procedures. SQLTask uses ./properties/sqlScript.xml to retrieve the sql statements. If you are using another database besides MS SQL 2000, 
you can modify the sql statements appropriately.

rapForumsMYSQLTables.sql - Rap Forums DB dump from MySQL.

rapForumsOracleTables.sql - Rap Forums DB dump from Oracle.


Stored Procedures (Paging Mechanism - only for MS SQL Server)
storedProcedures/sp_getSelectViewForums.sql - procedure used for paging forums, utilized by RapViewXML.java.
storedProcedures/sp_getSelectViewThreads.sql - procedure used for paging threads, utilized by RapViewXML.java.
storedProcedures/sp_getSelectViewThread.sql - procedure used for paging comments, utilized by RapViewXML.java.

Database connectivity is done through the Jakarta DBCP. We have provided a sample server.xml for connection pooling and it is located in the /properties/server.xml.

RAP Forum users need to provide a method for retrieval of user email addresses and it obtains this information via the PersonDirs.xml mechanism in uPortal.
Please see PersonDirs.xml for configuration for more information.

***** Updates from 0.8.3 to 0.9 *****
-The goal of this release was to provide security features to the forums. Access restriction to forums include:
	- Read
	- Post
	- Delete
	- Create
	- Assign Permissions
-Modified main display of forums
-Modified Administrator layout
-Added the ability to import forums from an xml file
-Added the ability to rename forums
-Added the ability to only display forums that users have rights to
-Added generation of PDFs for threaded discussions via Apache FOP
-Bug Fix - OracleViewXML.java queries with select * caused a NullPointerException
-Bug Fix - OracleViewXML.java queries in proper parameters caused no results from queries
-OracleViewXML.java was never tested in version 8.3, now its tested
----- CONTINUE DESCRIPTION -----

***** Updates from 0.8.2 to 0.8.3 *****
-The goal of this release was to provide a version of the forums that does not use database dependences like stored procedures, thus
 another configuration was created for users who use MySQL or other databases that do not support nested select statements or stored 
 procedures.
-RAPDBService getDBConnection() and getDBConnection(String dbName) now use the service provided by org.jasig.portal.RDBMServices to obtain DB connections.
-Bug fix with java.util.Date used in insertion where java.sql.Date was required.
-DB column names have been changed to all lowercase. forumID is now forumid and modifiedDate is now modifieddate. Since most database systems do not support
 column names of different case.
-XSL have been changed support the change in all column names.
-JDOM org.jdom.contrib.input.ResultSetBuilder has been modified to only return xml tags as all lowercase. If you are using an older version of the 
 jdom-contrib.jar and jdom.jar, please update to the version provided in the forums.
-All database dependent sql has been moved to associated classes in edu.fullcoll.uportal.channels.rap.forum.xml. See edu.fullcoll.uportal.channels.rap.forum.xml.RAPViewXML
 for more information.
-This version was tested on MySQL.


***** Updates from 0.8 to 0.8.2 *****
-Set the width of messages displayed to the user.
-Added generic database table creation from the ant build script
-Added custom ant task to create default table values and generate stored procedures for paging
-Added database load support from the ant script.
-Added deploy task to ant script.
-Removed poolman references and poolman.jar from the project.
-Removed two separate database for forums channel. Initially, the forums supported two separate databases, one for the   
 forums and one for user information, and one for the forums information. This has been combined into one database which  
 can reside in the uportal database. 
-Removed the use of rapUser.sql which contained user information. User information now comes from the portal framework via 
 PersonDir.xml


***** Updates from 0.2 to 0.8 *****
Added support for addition and deletion of forum categories and forums through an administration ui.
Updated code to display user's username if email address cannot be obtained through IPerson interface.


***** Updates from 0.1 to 0.2 *****
Modified the paging mechanism. Previous version used java code for forums paging. Version 0.2 uses Sql Server paging. Forums administrator must create stored procedures for current paging to work.