Installation Manual for v2.1

Introduction

1. Introduction
2. For the impatient...
3. Planning your installation
4. Required components
5. Contents of hipergate package
6. Install and configure a sample web site
7. Installing libraries
8. Creating an empty database
9. Executing Setup Assistant
10. Configuring Security and WorkAreas
11. Checking connectivity
12. Configuring servlets
13. Using multiple hipergate instances on the same server
14. Known Incompatibilities
15. Additional Downloads
16. Administrative Tools
17. Appendix 1: hipergate.cnf properties
18. Appendix 2: Manually loading the datamodel
19. Appendix 3: Configuring Web Farms
20. Appendix 4: Third Party Libraries
21. Appendix 5: Debug Library
22. How to upgrade from v2.0 to v2.1
23. How to upgrade from v1.1 to v2.0
24. Trouble shooting

You can get a more printer-friendly version of this page getting the HTML source.

For the impatient...

1. You need to have pre-installed Java 1.4 (or later), Tomcat 5.x o WebLogic 8.1, PostgreSQL 7.3, Microsoft SQL Server 2000 or Oracle 9/10.
   An initial 30Mb database size is more than enought for development purposes.
2. Download and unzip hipergate-x.x.x-full-xx.zip anyware.
3. Copy all files from the /web-en or /web-es directory on your web server.
4. Copy the /storage directory anywhere outside the webserver document root.
5. Open page http://server:port/admin/setup.htm for starting-up the Setup Assistant.
6. Configure /WEB-INF/web.xml (may be done later but Virtual Disk and servlets for file download will not work until done)
7. (Optional) If hipergate has been installed at a directory that is not the root of the domain used then set value for config.BaseUrl at file /fckeditor/js/fck_config.js as needed.

Planning your installation

In order to get a working copy of hipergate you should install all JSP pages and .jar files to the proper location on your web server and launch the Setup Assistant.

hipergate requires Java 1.4, a servlet/JSP engine (Tomcat, Sun Web Server, WebSphere, etc), and either PostgreSQL 7.x, Oracle 9/10 or Miscrosft SQL Server 2000.

You should plan the location of the following files prior to install:

• Relational database (PostgreSQL, Oracle, SQL Server).
• .jar libraries so they don't collision with previously installed versions (by default on WEB-INF/lib).
• Dynamic pages (JSP).
• /storage and /web directories, where files not stored in the database are archived.

/storage and /web directories can grow indefinitely with the use of hipergate. Main differences between /storage and /web are than /storage doesn't need to be available through HTTP, as /web require. Both are visible through HTTP in the default installation process.

Required components

UNIX or Windows Operating System

Linux (any distro), Solaris or AIX are preferred. You may also use BSD as long as it has support for Java 1.4.

Java 1.4

hipergate has been tested with version 1.4.1 of Sun JDK in several platforms.
versions 1.x can run on Java 1.3, but Java 1.4 is requiered for running hipergate 2.0.

servlets/JSP Engine

Initial development of hipergate is based on Apache Tomcat, and has been tested in other servers (Sun Web Server, Pramati, WebLogic and IBM WebSphere).

Relational Database

hipergate supports natively PostgreSQL, Microsoft SQL Server 2000 and Oracle 9/10. Database portability is realy easy, as it is completly separated from main application. There is no support for MySQL 4.x, as this version cannot use stored procedures.

You can run hipergate with a non-priviledged user account.

There are some initial requirements for each database in order to load hipergate:

PostgreSQL

TCP/IP protocol must be enabled at server side.
You need the plpgsql language in the database where you will load hipergate. To do so, launch the following command as the database administrator user: createlang plpgsql your_db_name. You can check that the language has been loaded with the following SQL query: select lanname from pg_language;

Oracle

Oracle only admits 50 open cursors by connection by default. This parameter is not compatible with the installation procedure, who leaves a prepared cursor for each table. Before the database creation you should edit the instance configuration file (initXXXX.ora) and change the option: "open_cursors=100" (at least).

Microsoft SQL Server

TCP/IP protocol must be enabled at server side. Use SQL Server Client Network Utility for enabling it.
In some circumstances it is necessary to change the parameter ARITHABORT prior to load de DB. To do so, connect to the master database with the SQL Query Analyzer and launch the following sentence: ALTER DATABASE nombre_bbdd SET ARITHABORT ON. If you don't do this, the following error can appear while loading the database: "[SQLServer 2000 Driver for JDBC][SQLServer]INSERT failed because the following SET options have incorrect settings: 'ARITHABORT'".

Contents of hipergate package

hipergate releases are distributed in a ZIP compressed package with the following contents:

• bin: hipergate standard library.
• java: library's source code.
• web-XX: JSP pages.
• storage: Contents of the private storage area.
• doc: Supplemental documentation, licenses and API JavaDocs.
• database: Database binary dumps.

This diagram shows the contents of the web and storage direcotories:

Install and configure a sample web site

Placing your JSP files is the first task to be done in the installation process. A working servlet/JSP engine must be available, and you should take note of configuration parameters and URLs where you place JSP pages as you will need them later when using the Setup Assistant.

It is recommended that you put hipergate directly under a domain like http://localhost:8080/
If you want to place hipergate at another directory below the web server root then you have to edit file /fckeditor/js/fck_config.js and change config.BaseUrl value as needed.

Installing on Tomcat 4x/5x

You can install a copy of Apache Tomcat in /opt/tomcat/, and make it listen HTTP requests on port 8080 (default configuration). Check the following line in your $CATALINA_HOME/conf/server.xml file:

<Connector className="org.apache.coyote.tomcat4.CoyoteConnector" port="8080" ... />

You can create a new <Context> for hipergate or use an existing one. For example, you can move the web from hipergate's ZIP package to $CATALINA_HOME/webapps/hipergate and create a new <Context> in server.xml as follows:

<Server port="8005" shutdown="SHUTDOWN" debug="0">
  <Service name="Tomcat-Standalone">
    <Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
               port="8080" minProcessors="5" maxProcessors="75"
               enableLookups="true" redirectPort="8443"
               acceptCount="100" debug="0" connectionTimeout="20000"
               useURIValidationHack="false" disableUploadTimeout="true" />
      <Host name="localhost" debug="0" appBase="$CATALINA_HOME/webapps/hipergate"
            unpackWARs="true" autoDeploy="true">
        <Context path="" docBase="" debug="0"
                 reloadable="true" crossContext="true">
          <Logger className="org.apache.catalina.logger.FileLogger"
                  prefix="hipergate_log." suffix=".txt" timestamp="true"/>
        </Context>
      </Host>
    </Engine>
  </Service>
</Server>

Servlets

hipergate includes three servlets used to download files from the storage directory. directory. To retrieve file descriptors from the database you should configure the following parameters in web/WEB-INF/web.xml file.

For each servlet (HttpBinaryServlet, HttpBLOBServlet and HttpQueryServlet) you should include the following parameters:

jdbcDriverClassName

JDBC driver name, like driver in hipergate.cnf

jdbcURL

JDBC connection string, like dburl in hipergate.cnf

dbUserName/dbUserPassword

Database username and password, like dbuser/dbpassword in hipergate.cnf

Database connection parameters for servlets from package com.knowgate.http (HttpBinaryServlet, HttpBLOBServlet and HttpQueryServlet) may be set at /WEB-INF/web.xml file or at /etc/hipergate.cnf. Information from web.xml will be prioritaire over hipergate.cnf so if both are different web.xmlwill be used.

web.xml parameters may be left empty if only one instance of the application is running on the same server, but it is neccesary to fill them if several instances are running on the same server against different databases. If no connection parameters are found on web.xml the servlet will take those from hipergate.cnf, and not from other properties files such as real.cnf or portal.cnf.

Last, check that http://hostname:8080/login.html works propertly.

Installing libraries

Next you should install hipergate and all required libraries in a directory where the servlet/JSP engine can find them.
If you are uncertain about how to create a web application at your servlet container then refer to one of the following web server setup guides.
JAR libraries come by default at $CATALINA_HOME/webapps/hipergate/WEB-INF/lib directory. Usually there is no need to change them to another place.
Adding JAR libraries to CLASSPATH is not enought, as some servers use they own directory structure and class loaders to find JAR files.
Tomcat uses the directory $CATALINA_HOME/shared/lib for JAR files shared across all web applications. You can move JAR files from WEB-INF/lib to shared/lib if your WebApp cannot find them at WEB-INF/lib.

Creating an empty database

Oracle 9.x

1. Connect to Oracle with SQL*Plus, SQL*Worksheet or Server Manager and execute:
   CREATE TABLESPACE HIPERGATE2 DATAFILE 'C:\ORANT\DATABASE\HIPERGATE2.DBF' SIZE 30M;
   
   CREATE USER HIPERGATE IDENTIFIED BY HIPERGATE DEFAULT TABLESPACE HIPERGATE2 TEMPORARY TABLESPACE YOUR_TEMP_TABLESPACE QUOTA UNLIMITED ON HIPERGATE2 QUOTA 0 ON SYSTEM;
   
   GRANT CONNECT,CREATE SYNONYM,CREATE PUBLIC SYNONYM,DROP PUBLIC SYNONYM,CREATE PROCEDURE,CREATE VIEW,CREATE TABLE, CREATE TRIGGER TO HIPERGATE;
   

Microsoft SQL Server 2000

1. Ensure that server accepts native authentication (Enterprise Manager -> SQL Server Group -> (local) -> Properties -> Security).
2. Enable TCP/IP connectivity at server side using SQL Server Client Network Utility.
3. Create new database from SQL Server Enterprise Manager.
4. Open SQL Query Analyzer switch to master database and execute:
   ALTER DATABASE hipergate20 SET ARITHABORT ON

Notes on Microsoft SQL Server 2000 Desktop Engine
Although hipergate can run on MSDE 2000, it is not recommended for production environments.
However, MSDE is easy to install and configure for demos running on Windows 2000/XP.
Here is how to proceed:

• Get MSDE 2000 Release A from http://www.microsoft.com/sql/msde/downloads/default.asp.
• Read the README file included with MSDE to know how to install it. MSDE is not intended to be installed by a "human" user, so be aware of that.
• Quoting section 3.4.3 from MSDE README, simply run: setup SAPWD="AStrongPassword" INSTANCENAME="InstanceName" TARGETDIR="C:\MyInstanceFolder" DISABLENETWORKPROTOCOLS=1 SECURITYMODE=SQL. SAPWD is a password for db super user, the name for the instance could be HGOLTP2D and targetdir C:\MSSQL. The last two parameters enable TCP/IP connections (required for JDBC), and that authentication will be "Mixed Mode" (SQL+Windows Auth)
• MSDE does not include administrative tools, so you'll have to connect to this database server somehow in order to create the DB, you may either:
  - Install the client tools from the SQL Server 2000 Standard/Enterprise CDs. You'll only need the Enterprise Manager Snap-in for Microsoft Management Console. This is the easiest way, but not free. - or use a SQL tool like WinSQL
  - or if IIS is available and .NET SDK installed, you can use the Web Data Administrator.
  - or (truly experimental) maybe there is some command line tool to restore the .BAK file distributed with hipergate so you can restore the "default" database.
  Having all this installed, configure the hipergate.cnf file using the given SAPWD, 127.0.0.1 as host and 1433 as port. You can start/stop MSSQLServer Service using the "Control Panel/Administrative Tools/Services" snap-in or "NET START/STOP" command from a DOS window.

PostgreSQL 7.4

1. Connect to the database server console via SSH/Telnet, using the database administration user (postgres) and create a new database and user:
   
   # createdb -E UNICODE hgoltp2d
   # createuser knowgate
   # grant all on database hgoltp2d to knowgate
2. Configure PostgreSQL for listening TCP/IP requests by updating file postgresql.conf
   
   tcpip_socket = true
   virtual_host = '127.0.0.1'
   port = 5432
3. Activate PL/pgSQL language support. PL/pgSQL must be activated before running setup assistant or loading the datamodel manually.
   
   # createlang plpgsql hgoltp2d

Executing the setup Assistant

For starting-up hipergate there are three basic requisites :

1. Have all requiered libraries (JARs) in place (by default they are at WEB-INF/lib).
2. Configure hipergate.cnf properties file for stablishing connection with the database. hipergate.cnf is created by default at /etc (or C:\WINNT in Windows) but its location can be changed by putting the desired directory on KNOWGATE_PROFILES environment variable
3. Have the datamodel created

Configuring Security and WorkAreas

For creating new Domains, Users and WorkAreas read to the User Manual.

It is strongly recommended to protect directory /web/admin with additional web server basic authentication after finishing the setup process.

It is neccesary to grant write permissions to the operating system account executing the web server on /tmp or C:\TEMP or any other temporary directory set on hipergate.cnf.

Connection test and first login

Once database is loaded, check the following URL: http://myserver/admin/test_connect.jsp. If everything is OK you'll see a screen with the JDBC connection URL.

Login to hipergate with the following URL: http://myserver/login.html. When you load the database some example users are created.

hipergate creates two default domains with 5 users that must be kept, althought it is recommended to change their default passwords.

administrator@hipergate-system.com (password hipergate)

Full admin rights account. Controls domains, workareas and users.

administrator@hipergate-model.com (password model, lowercase)

Model domain admin account. This domain is used when creating (cloning) a domain.

superuser@hipergate-model.com (password model, lowercase)

Model domain power user account. This domain is used when creating (cloning) a domain.

user@hipergate-model.com (password model, lowercase)

Model domain user account. This domain is used when creating (cloning) a domain.

guest@hipergate-model.com (password model, lowercase)

Model domain guest user account. This domain is used when creating (cloning) a domain. This user cannot write in the database nor filesystem.

Aditionaly, the setup process generates three test domains with some users that can be used inmediately. Each domain (test, demo and real) can be used when testing some features of the application.

• [administrator|superuser|user|guest]@hipergate-test.com (password TEST, uppercase)
• [administrator|superuser|user|guest]@hipergate-demo.com (password DEMO, uppercase)
• [administrator|superuser|user|guest]@hipergate-real.com (password REAL, uppercase)

Configuring servlets

After running Setup Assistant it is convenient to check /WEB-INF/web.xml file.
It is neccesary to have the servlets: HttpBinaryServlet, HttpBlobServlet and HttpQueryServlet from package com.knowgate.http.
For doing so, add the following lines to web.xml:

  <servlet>
        <servlet-name>HttpBinaryServlet</servlet-name>
        <servlet-class>com.knowgate.http.HttpBinaryServlet</servlet-class>

        <init-param>
            <param-name>jdbcDriverClassName</param-name>
            <param-value></param-value>
        </init-param>
        <init-param>
            <param-name>jdbcURL</param-name>
            <param-value></param-value>
        </init-param>
        <init-param>
            <param-name>dbUserName</param-name>
            <param-value></param-value>
        </init-param>
        <init-param>
            <param-name>dbUserPassword</param-name>
            <param-value></param-value>
        </init-param>
        <init-param>
            <param-name>id_product</param-name>
            <param-value></param-value>
        </init-param>

        <init-param>
            <param-name>id_location</param-name>
            <param-value></param-value>
        </init-param>

        <init-param>
            <param-name>id_category</param-name>
            <param-value></param-value>
        </init-param>

        <init-param>
            <param-name>id_user</param-name>
            <param-value></param-value>
        </init-param>
    </servlet>

   <servlet>
        <servlet-name>HttpBLOBServlet</servlet-name>
        <servlet-class>com.knowgate.http.HttpBLOBServlet</servlet-class>

        <init-param>
            <param-name>jdbcDriverClassName</param-name>
            <param-value></param-value>
        </init-param>
        <init-param>
            <param-name>jdbcURL</param-name>
            <param-value></param-value>
        </init-param>
        <init-param>
            <param-name>dbUserName</param-name>
            <param-value></param-value>
        </init-param>
        <init-param>
            <param-name>dbUserPassword</param-name>
            <param-value></param-value>
        </init-param>
        <init-param>
            <param-name>nm_table</param-name>
            <param-value></param-value>
        </init-param>
        <init-param>
            <param-name>nm_field</param-name>
            <param-value></param-value>
        </init-param>
        <init-param>
            <param-name>pk_field</param-name>
            <param-value></param-value>
        </init-param>
        <init-param>
            <param-name>pk_value</param-name>
            <param-value></param-value>
        </init-param>
        <init-param>
            <param-name>bin_field</param-name>
            <param-value></param-value>
        </init-param>
    </servlet>

   <servlet>
        <servlet-name>HttpQueryServlet</servlet-name>
        <servlet-class>com.knowgate.http.HttpQueryServlet</servlet-class>

        <init-param>
            <param-name>jdbcDriverClassName</param-name>
            <param-value></param-value>
        </init-param>
        <init-param>
            <param-name>jdbcURL</param-name>
            <param-value></param-value>
        </init-param>
        <init-param>
            <param-name>dbUserName</param-name>
            <param-value></param-value>
        </init-param>
        <init-param>
            <param-name>dbUserPassword</param-name>
            <param-value></param-value>
        </init-param>
        <init-param>
            <param-name>queryspec</param-name>
            <param-value></param-value>
        </init-param>
        <init-param>
            <param-name>columnlist</param-name>
            <param-value>*</param-value>
        </init-param>
        <init-param>
            <param-name>where</param-name>
            <param-value></param-value>
        </init-param>
        <init-param>
            <param-name>orderby</param-name>
            <param-value></param-value>
        </init-param>
        <init-param>
            <param-name>showas</param-name>
            <param-value>XLS</param-value>
        </init-param>
    </servlet>
    
    <servlet-mapping>
        <servlet-name>HttpBinaryServlet</servlet-name>
        <url-pattern>/servlet/HttpBinaryServlet</url-pattern>
    </servlet-mapping>

    <servlet-mapping>
        <servlet-name>HttpBLOBServlet
        </servlet-name>
        <url-pattern>/servlet/HttpBLOBServlet</url-pattern>
    </servlet-mapping>

    <servlet-mapping>
        <servlet-name>HttpQueryServlet</servlet-name>
        <url-pattern>/servlet/HttpQueryServlet</url-pattern>
    </servlet-mapping>

Configuring multiple instances of hipergate on the same machine

All servlet default parameters may be left blank except when using several instances of hipergate running on the same machine.
In that case these parameters must be set explicitly for each instance:

Multiple instances of hipergate on the same server

It is possible to have several instances of hipergate running on the same server against different databases.
Each instance must have its own properties files like hipergate.cnf but with a different name.
All property files must be located at the same directory, /etc or C:\WINNT by default or the one set at KNOWGATE_PROFILES environment variable.
hipergate public version comes with 5 additional instances: demo.cnf, devel.cnf, portal.cnf, real.cnf y test.cnf.
For using a properties file other than hipergate.cnf JSP include /web/methods/dbbind.jsp must be edited.
It is neccesary to replace class com.knowgate.dataobjs.DBBind at dbbind.jsp with the proper subclass for each properties file:

Thus for using file test.cnf, the content of dbbind.jsp must be:
<jsp:useBean id="GlobalDBBind" scope="application" class="com.knowgate.dataobjs.DBTest"/>

Known Incompatibilities

Version 1.x

• Version 1.x only works with Microsoft Internet Explorer 5.0 or greater
• The PostgreSQL driver distributed with the build only works with PostgreSQL 7.3, it is neccesary to download a new driver for 7.4
• The driver and the Oracle dump that come with builds 1.x only work with Oracle Server 8.x
• hipergate does not work with Microsoft SQL Server 7.0
• hipergate does not work with MySQL 4.x

Version 2.x

• Initial Database creation using ModelManager does not work with Oracle 8. hipergate 2.0 may work with Oracle 8 but a binary dump must be used for loading the database.
• Java BeanShell 2.0b1 is not compatible with JBOSS 3.2.5. BeanShell is needed during initial database creation using ModelManager. hipergate can still be used with JBoss as long as the database is created using one of the binary dumps.

Additional Downloads

• JDBC drivers for PostgreSQL
• JDBC drivers for Oracle
• SQL Server 2000 Driver for JDBC Service Pack 3
• Cloudscape v10.0

Administrative Tools

SQL Query Tools

There is a direct SQL query tool at /admin/sql.htm.
This tool allows launching ad-hoc SQL command sets against the database or retrieving resultsets.
The utility connects by default to the database specified at hipergate.cnf and not any other properties file, so be carefull of not connecting to the wrong databse when running multiple hiperate instances on the same server.
It is strongly recommended to restrict access to SQL Query using basic web server authentication.

Connection pool status

May be seen by opening page /admin/connectionpool.jsp

Environment variables

Can be inspected by opening page /admin/environment.jsp

Session cookies

Can be readed by opening /admin/viewcookies.html

Appendix 1: hipergate.cnf properfies file

hipergate.cnf file contains the following parameters (WARNING, $CATALINA_HOME variables are not valid in this file, they are only place here for explaination purpouses):

# [Database]
# Database Parameters
driver=org.postgresql.Driver
dburl=jdbc:postgresql://192.168.1.30:5432/test
schema=
dbuser=postgres
dbpassword=postgres
poolsize=32
maxconnections=100

# [Files]
# Where to store temporal files
temp=/tmp

# How hipergate reads and writes files and directories
# File/Directory access mode (PUREJAVA=0, UNIX=1, WINDOWS = 2)
javamode=0

# Root URL to hipergate
webserver=http://hostname:8080
# optional Root to static images
imageserver=http://hostname:8080/images

# Protocol, hostname, username and password to access workareas and storage
fileprotocol=file://
fileserver=localhost
fileuser=
filepassword=

# Private storage directory
storage=$CATALINA_HOME/webapps/storage

# External shell commands to perform
shelldir=/tmp

# Public storage directory
workareasput=$CATALINA_HOME/webapps/hipergate/workareas
# Public storage URL
workareasget=http://hostname:8080/workareas

# Maximum file size (bytes)
maxfileupload=10485760

# [Misc]
# Validate XML documents?
setXMLValidation=1

# Task scheduler maximum running threads
maxschedulerthreads=1

# SMTP mail configuration
mail.transport.protocol=smtp
mail.store.protocol=pop3
mail.incoming=pop3.yourserver.com
mail.outgoing=smtp.yourserver.com
mail.user=

# LDAP
ldapconnect=ldap://127.0.0.1:389/dc=hipergate,dc=org
ldapuser=cn=Manager,dc=hipergate,dc=org
ldappassword=manager
ldapclass=com.knowgate.ldap.LDAPNovell

driver

Name for JDCB driver as used in a Class.forName call:

• org.postgresql.Driver
• com.microsoft.jdbc.sqlserver.SQLServerDriver
• oracle.jdbc.driver.OracleDriver

dburl

JDBC connection string:

• jdbc:postgresql://host:5432/dbname
• jdbc:microsoft:sqlserver://host:1433;SelectMethod=cursor;DatabaseName=dbname
• jdbc:oracle:thin:@host:1521:oracle_sid

schema

Database Schema. Can be the tables' owner.
Leave schema blank for PostgreSQL except if there are probllems accessing sql_features table, in that case set schema to public.

• dbo (SQL Server)
• HIPERGATE (Oracle)
• public (PostgreSQL)

dbuser/dbpassword

Username and password for database connection.

poolsize

Number of connections that will be kept open by the connection pool ready to be reused.
A connection may only be open and waiting for a maximum of five minutes.
After that period of inactivity it will be closed by the pool manager at the number of open connections will eventually go down to zero.
The default value is 32.

maxconnections

Absoluta maximum of connections that can be openend simultaneosly against the database.

temp

Temporal storage. Here come uploaded files before moved to final storage directory and some temp files.

• /tmp (UNIX)
• C:\\TEMP (Windows 2000)

javamode

This parameter controls how hipergate access files and directories. When using PUREJAVA mode (javamode=0), all call are made with the standard java APIs (java.io). With UNIX and WINDOWS modes (javamode=1/2), this tasks are performed with OS commands. While PUREJAVA mode keeps platform portability, native modes can make hipergate run faster.
You should use the PUREJAVA mode when using WebLogic on Windows 2000.

webserver

Complete URL to hipergate's JSP root directory. This parameter is utilized to compose relative and absolute URLs in each module.

• http://server:port/webapp
• http://myserver:8080/
• http://localhost:7001/hipergateWeb (WebLogic example)

imageserver

Complete URL to optional image server. All static images (icons, graphics, etc) can be placed in a separate web server, or left on a directory on the same server.

• http://images.mycompany.com/hipergate
• http://myserver:8080/images
• http://localhost:7001/hipergateWeb/images (WebLogic example)

fileprotocol

Access to file storage can be done in different ways: FTP, NFS or localy mounted filesystems. This parameter tells hipergate which protocol use.

• file:// (localy mounted filesystems)
• ftp:// (FTP)
• nfs:// (NFS, currently not supported)

fileserver

Name of file storage server. This option is only relevant when using remote storage.

• localhost (localy mounted filesystems)
• ftp-server.domain.com (FTP)

fileuser/fileuser

Username and password to access remote file storage. Currently only used with FTP.

storage

Root directory to private storage directory.

• $CATALINA_HOME/webapps/storage
• /vol/1/hipergate_storage
• C:\\bea\\weblogic81\\samples\\workshop\\hipergate\\storage (Windows 2000)

shelldir

Some servlet containers (mostly Tomcat) lock files and directories. If you want to delete a newsletter, website or account you should remove all directories related to this object, but Java prevents this deletion, so you must create a scheduled task to remove them from outside the servlet container. For each object to be removed, a line is added to a file called cleanup.txt with the full path of the directory to be deleted. You can run a wrapper script each time server is restarted, or add a cron job that tries to remove this files periodicaly.

• /tmp
• $CATALINA_HOME/webapps/shell
• C:\\BEA\\weblogic81\\samples\\workshop\\hipergate\\shell (Windows 2000)

workareasput

Root directory for public storage that should be available via HTTP.

• $CATALINA_HOME/webapps/hipergate/workareas
• /vol/1/hipergate_workareas
• C:\\BEA\\weblogic81\\samples\\workshop\\hipergate\\hipergateWeb\\workareas (Windows 2000)

workareasget

Absolute web URL to workareasput directory.

• /workareas
• /hipergateWeb/workareas

maxfileupload

Maximum file size (in bytes) of uploaded files.

setXMLValidation

Activate XML validations when rendering XSLT templates.

maxschedulerthreads

Maximum number of threads for the job scheduler.

mail.transport.protocol

JavaMail transport (default=smtp)

mail.store.protocol

JavaMail store (default=pop3)

mail.outgoing

SMTP JavaMail server for mail delivery (default=localhost)

mail.incoming

POP3 JavaMail server for mail storage (default=localhost)

Appendix 2: Manually loading the database

Creating the database by loading binary dumps

Instead of Setup Assistant, you can also use the binary database dumps provided with the hipergate package inside the database/ directory.

Oracle 9/10

1. From the command line type:
   IMP80 system/manager fromuser=HIPERGATE touser=HIPERGATE buffer=128000 commit=yes ignore=yes file=H21ORCL9.DMP
   

Microsoft SQL Server 2000

1. Copy HG2MSSQL.BAK to a local disk drive.
2. Right click on the new database,then choose All Tasks -> Restore Database, select From Device radio button, add H21SQL2K.BAK to the devices list and click OK.

PostgreSQL 7.4

1. Create a new Unicode database:
   # createdb -E UNICODE hgoltp2d
   Create a new user:
   # createuser knowgate
   # grant all on database hgoltp2d to knowgate
   Restore the database dump file HG1PGSQL.DUMP:
   
   # pg_restore -d hgoltp2d H21PGSQL.DUMP
   The database is created with user knowgate password knowgate.
   
   If you get a permissions problem using language c do:
   # update pq_language set lanpltrusted=true where lanname='c';
   # grant usage on language c to knowgate;

Creating the database with ModelManager Java class SQL-DDL scripts

To install the initial database using ModelManager Java class first check JDCB connectivity parameters in the hipergate.cnf file.

Database chosen with the dburl parameter must be created prior to installation. Database creation process will use the DBURL, username and password parameters from hipergate.cnf file.

Use the following command to load the default database objects (case sensitive):

java com.knowgate.hipergate.datamodel.ModelManager /etc/hipergate.cnf create database

WARNING: all required libraries must be available on your CLASSPATH.
The minimum set of libraries for ModelManager is: beanshell.bsh-2.0b1.jar, ibm.bsf-2.2.jar, jakarta-oro-2.0.8.jar, xmlParserAPIs.jar, xercesImpl.jar. The right JDBC driver must also be included.

The following script will help you in this task. It will search for JAR packages at /opt/tomcat/webapps/hipergate/WEB-INF/lib/ and add them to CLASSPATH (-cp) of the java invocation:

#!/bin/sh

cp=`ls -1 /opt/tomcat/webapps/hipergate/WEB-INF/lib/*.jar | tr '\n' ':'`
java -cp "$cp" com.knowgate.hipergate.datamodel.ModelManager $@

You can save this script at /usr/local/bin/modelmanager.sh and run modelmanager.sh create database.

Appendix 3: Configuring Distributed cache for Web Farms

Introduction

This configuration step is neccesary if and only if you have more than one web server running in parallel.

When the application runs on several machines in parallel, it is neccesary to enable the Distributed Cache Coordinator.

Each web server mantains a local cache of frecuently used information such as user passwords, lookups, menu options, etc.

If more than one server provides service, it exists the possibility that one server updates information on the database that is localy cached on another server. This is why it is neccesary to install a Cache Coordinator.

The coordinator itself does not store any actual information, but only acts as a ticket server for clients. It is not possible to pass information among client caches, if one of them modifies information on the database, that information become invalid on all othre nodes and has to be re-loaded from the database.

The cache coordinator is divided in two parts: client and server.

Client part is package com.knowgate.cache at hipergate.jar. This cliente is independent of the server side.

Server Side may be either of one of two types: HTTP based or EJB based.

An HTTP coordinator uses one Web Server for coordinating all the other ones. This is the simplest configuration.

An EJB coordinator uses an application server (such as JBoss or WebLogic) as a ticket server for client web servers.

Configuring coordinator over HTTP

Any node of a web farm can act as coordinator of all the other ones. There may be only one coordinator, if this machine fails, all the other will stop working.

For enabling an HTTP coordinator, open appserver.cnf on echa nodo and set properties:

threetiers=enabled
java.naming.provider.url=http://IP_ADDRESS:PORT/cache/server.jsp

Configuring coordinator over an EJB container

Installing the coordinator on an EJB container y more complex but it gives better performance, scalability and fault tolerance.

Client Side (Web Servers)

If you use JBoss 3.0, additional libraries must be installed on each web server:

• cachecoordinator-jboss30.jar
• apache.log4j.jar
• jboss-3.0.common-client.jar
• jboss-3.0.jnp-client.jar
• sun.jndi.jar

Server Side (JBoss)

Add the following to the standardjboss.xml file:

<container-configuration>
	<container-name>Singleton Stateless SessionBean</container-name>
	<call-logging>false</call-logging>
	<container-invoker>org.jboss.proxy.ejb.ProxyFactory</container-invoker>	
	<container-interceptors>
		<interceptor>org.jboss.ejb.plugins.LogInterceptor</interceptor>	
		<interceptor>org.jboss.ejb.plugins.SecurityInterceptor</interceptor>
			<!-- BMT -->
		<interceptor transaction = "Bean">
		  org.jboss.ejb.plugins.StatelessSessionInstanceInterceptor
		</interceptor>
		<interceptor transaction = "Bean">
		  org.jboss.ejb.plugins.TxInterceptorBMT
		</interceptor>
		<interceptor transaction = "Bean" metricsEnabled = "true">
		  org.jboss.ejb.plugins.MetricsInterceptor
		</interceptor>
		<interceptor>
		  org.jboss.resource.connectionmanager.CachedConnectionInterceptor
		</interceptor>	
	</container-interceptors>
	<client-interceptors>
	<home>
		<interceptor>org.jboss.proxy.ejb.HomeInterceptor</interceptor>
		<interceptor>org.jboss.proxy.SecurityInterceptor</interceptor>
		<interceptor>org.jboss.proxy.TransactionInterceptor</interceptor>
		<interceptor>org.jboss.invocation.InvokerInterceptor</interceptor>
	</home>	
	<bean>
		<interceptor>org.jboss.proxy.ejb.StatelessSessionInterceptor</interceptor>
		<interceptor>org.jboss.proxy.SecurityInterceptor</interceptor>
		<interceptor>org.jboss.proxy.TransactionInterceptor</interceptor>
		<interceptor>org.jboss.invocation.InvokerInterceptor</interceptor>
	</bean>	
	</client-interceptors>
	<instance-pool>org.jboss.ejb.plugins.StatelessSessionInstancePool</instance-pool>
	<instance-cache/>
	<persistence-manager/>
	<transaction-manager/>
	<container-pool-conf>
		<MaximumSize>1</MaximumSize>
		<MinimumSize>1</MinimumSize>
		<strictMaximumSize>true</strictMaximumSize>
	</container-pool-conf>
</container-configuration>

Start JBoss and deploy cachecoordinator-jboss30.jar. To do so:

• Copy the JAR file to jboss/server/all/deploy, jboss/server/default/deploy or jboss/server/minimal/deploy
• Open The JBoss Admin Console (http://servidor:8080/jmx-console/)
• Choose "MainDeployer" and deploy cachecoordinator-jboss30.jar (file://C:\jboss\server\all\deploy\cachecoordinator-jboss30.jar)

Appendix 4: Third Party Libraries

J2EE Client - 3.0

Contains J2EE classes required for hipergate distributed cache

Xerces2 Java Parser 2.6.2

XML parser from The Apache Foundation

Bean Scripting Framework - 2.3.0

A set of Java classes which provides scripting language support within Java applications.

Jakarta POI - Java API To Access Microsoft Format Files - 2.5

Pure Java ports of file formats based on Microsoft's OLE 2 Compound Document Format.

Jakarta Lucene - 1.4

Jakarta Lucene is a high-performance search engine library written in Java.

Java BeanShell - 2.0b1

BeanShell is a small, free, embeddable, Java source interpreter with object scripting language features, written in Java.

Jakarta ORO 2.0.8 (only from version 2.0)

The OROMatcher project was donated to The Apache Software Foundation and now is Jakarta ORO.

Sun JavaMail - 1.3.2

The JavaMail API provides a set of abstract classes that model a mail system.

Sun Java Advanced Imaging API - 1.1.2

This library provides image manipulation from Java without using AWT.

Novell LDAP classes for Java (only from version 2.1)

Novell LDAP Classes for Java enables to write applications that access Novell eDirectory™, OpenLDAP or other LDAP-aware directories.

Sun JSR-168 Portlet API 1.0 (only from version 2.1)

Retired libraries from v1.x

edtFTP Java Client Library - 1.2.2 (only for versions 1.x)

This is an entire FTP client library written in Java. From version 2.0 this library is included into hiprgate.jar.

OROMatcher - 1.1.0a (only for versions 1.x)

OROMatcher is a set of regular expression pattern matching and utility classes for Java.

Appendix 5: Debug libraries

Upgrading from v2.0 to v2.1

1. Make a backup copy of the database and the JSP pages from 2.0.
2. Download v2.1 package.
3. Copy JSP pages from 2.1 to a new location on your web server.
4. Point 2.1 instance to the same database as 2.0 by reusing hipergate.cnf.
5. Open Setup Assistant at http://servidor/admin/setup.htm. The setup assistant will detect v2.0 and automatically upgrade de datamodel.

Alternative manual upgrade

java [-cp ...] com.knowgate.hipergate.datamodel.ModelManager /etc/hipergate.cnf upgrade 200 210

Upgrading from v1.1 to v2.0

1. Make a backup copy of v1.1 database and JSP pages.
2. Download the compressed file for v2.0.
3. Create a new empty databse with Unicode character set.
4. Replace savarese.oromatcher-1.1.0a.jar with jakarta-oro-2.0.8.jar.
5. Add javaOTP.jar to your CLASSPATH or shared/lib directory
6. Remove enterprisedt.ftp-1.2.2.jar the FTP library is now included inside hipergate.jar
7. Replace hipergate.jar 1.1 with 2.0.
8. Replace 1.1 JSP pages with 2.0.
9. Open hipergate.cnf file.
10. Append a one ("1") after the name of properties dburl, schema, dbuser and dbpassword converting them into dburl1, schema1, dbuser1 y dbpassword1 with the same values that they had.
11. Set dburl, schema, dbuser y dbpassword to the new empty Unicode database.
    Example:
    # Database parameters
    driver=com.microsoft.jdbc.sqlserver.SQLServerDriver
    dburl1=jdbc:microsoft:sqlserver://localhost:1433;SelectMethod=cursor;DatabaseName=hipergate11
    schema1=dbo
    dbuser1=sa
    dbpassword1=xxxx
    dburl=jdbc:microsoft:sqlserver://localhost:1433;SelectMethod=cursor;DatabaseName=hipergate20
    schema=dbo
    dbuser=sa
    dbpassword=xxxx
12. Execute java [-cp ...] com.knowgate.hipergate.datamodel.ModelManager /etc/hipergate.cnf create database
13. Remove properties dburl1, schema1, dbuser1 and dbpassword1 from hipergate.cnf.
14. Restart your servlet runner.

Copying Data

Permissions

Trouble shooting

PostgreSQL