          WebPBC README
          -------------

INTRODUCTION
------------

WebPBC is a Web-based application that allows small to medium-sized
companies to do budget consolidation on their projects. It is
especially suitable for companies that coordinate projects
that are geographically distributed. The Web-based interface
allows managers, accountants and organizers from anywhere in the world
to access, update and report on budget data stored on a central server.


REQUIREMENTS
------------

The following are required for running WebPBC on the server.

JDK 1.4
MySQL 3.23.x (or any RDMS with JDBC 2 driver)
MySQL Connector/J 2.0.14 (or any JDBC 2 driver)
Jakarta OJB 0.9.9
Jakarta Struts 1.0.1
Jakarta Tomcat 4.0.4 (or similar servlet container)

To use WebPBC, you need one of the following browsers:

Netscape 6+
Mozilla 1+    *Recommended :)
Internet Explorer 5+


ARCHITECTURE
------------

WebPBC is actually composed of three CyberDemia modules:
- The Web interface module named WebPBC. This contains Struts
  actions, HTML, JSP, Javascripts, style-sheets, etc. It is
  the default implementation of a user-interface for PBC.
- The main PBC business-logic module, where the calculations
  and other interesting tasks are performed.
- The generic Core module that contains some useful
  utility code.

Build all these modules if you want a fully functional
WebPBC application. Build only the PBC and Core modules
if you intend to develop your own user-interface on top of PBC.

Each module comes with its own release notes.
It is located inside the doc subdirectory under the
module's directory, i.e.
WebPBC-1.3.2/devel/WebPBC/doc


BUILDING
--------

The following is also required for building WebPBC.
Jakarta Ant 1.4.1

This building instructions are based on the setup
as described in REQUIREMENTS, on a Linux machine.

1. Install all the required programs, then set the following
environment variables :

JAVA_HOME     : Set to JDK directory
TOMCAT_HOME   : Set to Jakarta Tomcat directory
OJB_HOME      : Set to Jakarta OJB directory
STRUTS_HOME   : Set to Jakarta Struts directory
JDBC_HOME     : Set to MySQL Connector/J directory

2. Add the directory containing the Jakarta ant executable
into your PATH.

3. Unpack the downloaded zip file. These instructions assume
that the zip file is unpacked into the /usr/local directory.
This will generate the following directory structure :

usr
|--local
   |--WebPBC-1.3.2
      |--devel
         |--WebPBC
         |--PBC
         |--Core

The Core directory contains the source for some generic classes.
The PBC directory contains the source for the PBC business logic.
The WebPBC directory contains the source for the Web interface.

4. The easiest way is to build everything, by simply running:

> cd /usr/local/WebPBC-1.3.2/devel/WebPBC
> ant all

This will build WebPBC, PBC and Core modules, deploy all the
resultant classes and jars, and also generate Javadocs.

If you just want to build PBC, e.g. for your own client interface,
just cd to the PBC directory and run "ant".


INSTALLING
----------

1. You can install directly from the downloaded binaries zip,
or from the built files.

2. The WebPBC deployment directory is named "deploy" and is created
parallel to "devel". So, the directory structure looks like:

usr
|--local
   |--WebPBC-1.3.2
      |--devel   
         |-- ...
      |--deploy
         |--webpbc
            |--auth
            |--WEB-INF
               |-- ...

3. You need to configure the Jakarta OJB with your own
database settings. Edit the repository_database.xml file found in
/usr/local/WebPBC-1.3.2/deploy/webpbc/WEB-INF/classes
to set the dbalias, username and password.

4. Next, startup MySQL and create a database named "ojb".
Set up a user (as specified in repository.xml) with
full access to this database. Then, initialize this database
using:
> cd /usr/local/WebPBC-1.3.2/devel/PBC/tool
> mysql -u (username) -p(password) ojb < initdb.mysql

5. Make sure that PBC is configured for the correct version of OJB.
Use a text editor to open the following file:
/usr/local/WebPBC-1.3.2/deploy/webpbc/WEB-INF/classes/repository.xml

The version attribute of the descriptor-repository tag should
match the OJB version you're using. If you're using OJB 0.9.9, 
it should be:
<descriptor-repository version="0.9.9" ...

If it doesn't match, try to get the correct version of OJB because
your OJB might not be compatible with the OJB that PBC expects.

6. The PBC can be configured at run time using an XML file.
You can use the sample-pbc.xml file located in
/usr/local/WebPBC-1.3.2/deploy/webpbc/WEB-INF/classes
as a guide to write your own. Just make a copy
of this file and rename it for your own configuration.

7. Add WebPBC as a servlet context to Tomcat, by inserting
the following into $TOMCAT_HOME/conf/server.xml :

    <Context path="/webpbc"
        docBase="/usr/local/WebPBC-1.3.2/deploy/webpbc"
        reloadable="false" >
        <Parameter name="pbc-config"
            value="/usr/local/WebPBC-1.3.2/deploy/webpbc/WEB-INF/classes/mypbc.xml" />
    </Context>

The "pbc-config" initialization parameter is needed to tell PBC
the location of the configuration file to use. Set it to
the location of your own configuration file.

8. WebPBC uses container managed security (Servlet Spec 2.3)
to authenticate its users. You can easily set this
up using Tomcat's MemoryRealm by editing
$TOMCAT_HOME/conf/tomcat-users.xml.

Please refer to the sample tomcat-users.xml in
/usr/local/WebPBC-1.3.2/devel/WebPBC
for instructions.

Alternatively, you can also do the same setup using
Tomcat's JDBCRealm or JNDIRealm.

9. WebPBC works a lot faster with more JVM memory,
especially for large hierarchies. If your hierarchy
is large and you have RAM to spare, you may want to
give the JVM more than its default 64Mb. You can
put something like
JAVA_OPTS="-Xmx256m"
into $TOMCAT_HOME/bin/catalina.sh.

10. Start Tomcat:
> $TOMCAT_HOME/bin/startup.sh

11. Finally, launch your browser and login to WebPBC.
For example, if browser is on the same machine, try:
http://localhost:8080/webpbc

12. For optimum performance, trying hooking Tomcat into
Apache to server static files. This is beyond the scope
of this README.


TROUBLESHOOTING
---------------

1. If your are using MySQL as the database, be aware that MySQL has a
default waiting timeout of 8 hours. That means that if the database
is not used for more than 8 hours, MySQL will quietly
close the connection that is held by PBC. When PBC next tries
to access the database, it will simply get an exception.
This might cause problems if your usage pattern involves
more than 8 hours stretch of inactivity, such as for a workplace
that is only active during office-hours and quiet at night.
To fix this, you can specify a longer timeout values when starting
the MySQL server. Refer to MySQL manual on how to set the
waiting_timeout and interactive_timeout settings.




RESOURCES
---------

Here is where you can download the programs that
WebPBC depends on:

JDK               : http://java.sun.com/j2se
MySQL             : http://www.mysql.com
MySQL Connector/J : http://www.mysql.com
Jakarta OJB       : http://jakarta.apache.org/ojb
Jakarta Struts    : http://jakarta.apache.org/struts
Jakarta Tomcat    : http://jakarta.apache.org/tomcat
Jakarta Ant       : http://jakarta.apache.org/ant
Mozilla browser   : http://www.mozilla.org


ENQUIRIES
---------

Please forward all enquiries and comments about WebPBC
to Alexander Yap at:

alex.yap@cyberdemia.com


