Installation Manual for v4.0

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. Installing on JBoss
18. Appendix 1: hipergate.cnf properties
19. Appendix 2: Manually loading the datamodel
20. Appendix 3: Configuring Web Farms
21. Appendix 4: Third Party Libraries
22. Appendix 5: Debug Library
23. Appendix 6: Notes for re-compiling source code
24. How to upgrade from v3.0 to v4.0
25. 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.6 (or later)
   • Tomcat 6.0.16 (or later)
   • PostgreSQL 8.x, Microsoft SQL Server 2005/DE or Oracle 10g/XE or MySQL 5.x.
   
   An initial 30Mb database size is more than enought for development purposes.
2. Download and unzip hipergate-4.0.x-aa.zip anywhere.
3. Copy all files from the /webapp directory to a subdirectory of your web server /webapps.
4. Copy the /storage directory anywhere outside the web server 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 4.x requires J2SE 1.6 or later, a servlet/JSP engine (Jakarta Tomcat, BEA WebLogic, Sun Web Server, WebSphere, etc), and either PostgreSQL 8.x, Oracle 10g/XE, MySQL 5.x or Miscrosoft SQL Server 2005/DE.

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

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

Main differences between /storage and /webapp are than /storage doesn't need to be available through HTTP, as /webapp require. Both are visible through HTTP in the default installation process.

Required components

Windows 2000/XP/Vista, Linux, BSD or other UNIX 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.

JRE 1.6

hipergate 4 has been tested with version 1.6 of Sun JDK in several platforms.

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 PostgreSQL 7.4/8.x, Microsoft SQL Server 2000/2055/DE and Oracle 10g/XE, MySQL 5.x. There is no support for MySQL 4.x.

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;
The database must be created with UNICODE character set or else a SQLException 42P01 ERROR: relation k_x_app_workarea does not exist will be raised.

Oracle 9

Oracle 9 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). This procedure is not necessary for Oracle 10g/XE as the open_cursors property has been raised to 300 by default.

Oracle XE

Oracle XE uses by default the same port 8080 as Tomcat. When running both Oracle and Tomcat on the same machine one of both applications must be changed to use another port.

Microsoft SQL Server

TCP/IP protocol must be enabled at server side. Use SQL Server Client Network Utility for enabling it.
It is also neccesary to activate SQL Server native security. Windows integrated security is not enought.
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 2005 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.
• webapp.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 webapp.xx and storage directories:

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 6.0

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 webapp.xx 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 webapp.xx/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 10g

1. Connect to Oracle with SQL*Plus, SQL*Worksheet or Server Manager and execute:
   CREATE TABLESPACE HIPERGATE4 DATAFILE 'C:\oraclexe\oradata\XE\hipergate4.dbf' SIZE 100M;
   
   CREATE USER HIPERGATE IDENTIFIED BY HIPERGATE DEFAULT TABLESPACE HIPERGATE4 QUOTA UNLIMITED ON HIPERGATE4 QUOTA 0 ON SYSTEM;
   
   GRANT CONNECT,CREATE SEQUENCE,CREATE SYNONYM,CREATE PUBLIC SYNONYM,DROP PUBLIC SYNONYM,CREATE PROCEDURE,CREATE VIEW,CREATE TABLE, CREATE TRIGGER TO HIPERGATE;
   

Microsoft SQL Server 2005

1. Ensure that server accepts native authentication.
2. Enable TCP/IP connectivity at server side.
3. Create new database from Microsoft SQL Server Management Studio.
4. Open SQL Query Analyzer, switch to master database and execute:
   ALTER DATABASE hipergate4 SET ARITHABORT ON

Notes on Microsoft SQL Server 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 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 8.x

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 hipergate4
   # createuser knowgate
   # grant all on database hipergate4 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. If you do not enable PL/pgSQL prior to creating the datamodel you will get an error message at k_sp_authenticate function and you will have to re-create the whole datamodel from scratch.
   
   # createlang plpgsql hipergate4

MySQL 5.x

1. Connect to server as root and execute:
   CREATE DATABASE hipergate4 CHARACTER SET utf8;
   CREATE USER knowgate IDENTIFIED BY 'knowgate';
   GRANT ALL PRIVILEGES ON *.* TO 'knowgate'@'%' IDENTIFIED BY 'knowgate';
   Note that the database must be created with UTF-8 character set and that it is not enought to do GRANT ALL PRIVILEGES ON knowgate.* because this will not grant to knowgate user the CREATE TRIGGER privilege needed by the initial data model creation process.

Executing the setup Assistant

For starting-up hipergate there are three basic requisites :

1. Have all third party 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?profile=hipergate. 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 4.0

• The PostgreSQL driver distributed with the build only works with PostgreSQL 8.3
• The Oracle driver distributed with the build only works with Oracle 11g
• The SQL Server driver distributed with the build only works with SQL Server 2005
• hipergate does not work with Microsoft SQL Server 7.0
• hipergate does not work with MySQL versions prior to 5.0
• Java BeanShell 2.0b1 is not compatible with JBOSS 4.0. 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
• MySQL Connector/J 5.0
• JDBC drivers for Oracle
• Oracle Instant Client
• Microsoft SQL Server 2000 JDBC Driver SP3
• Microsoft SQL Server 2005 JDBC Driver 1.1

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

Installing on JBoss

• Use arvhive labeled hipergate-xx-war.zip instead of hipergate-xx-src.zip
• Create the datamodel with a binary dump and NOT by running the Setup Assistant. Java BeanShell scripting used during the initial data loading does not run under JBoss 4.0
• Configure hipergate.cnf parameters manually
• Copy the required JDBC drivers and hipergate-x.x.xx.jar to %JBOSS_HOME%/server/default/lib/
• In %JBOSS_HOME%/server/default/deploy/ create a connection for JBoss
• Make a copy of hsql-ds.xml for the database that is going to be used. For example for PostgreSQL it could be postgre-ds.xml like:

  <local-tx-datasource> 
    <jndi-name>KnowgateDS</jndi-name> <connection-url>jdbc:postgresql://127.0.0.1:5432/hgoltp8t</connection-url> 
    <!-- The driver class --> 
    <driver-class>org.postgresql.Driver</driver-class> 
    <!-- The login and password --> 
    <user-name>knowgate</user-name> 
    <password>knowgate</password> 
    <security-domain>PostgreSqlDbRealm</security-domain> 
    <metadata> 
      <type-mapping>Postgre SQL</type-mapping>
    </metadata> 
  </local-tx-datasource> 

Note that a service, mbean or anything is not needed; just to make sure of modifying /default/conf/login-config.xml proprietary because the <security-domain> above is used.
• Copy hiperweb.war to /server/default/deploy
• Go to http://localhost/hiperweb/

Appendix 1: hipergate.cnf properties 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 Connection Parameters
driver=org.postgresql.Driver
dburl=jdbc:postgresql://192.168.1.30:5432/test
schema=
dbuser=postgres
dbpassword=postgres

# [Connection Pool] 
# Parameters governing com.knowgate.jdc connection pool behaviour
poolsize=32
maxconnections=100
logintimeout=20
connectiontimeout=60000
connectionreaperdelay=30000

# [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
# Protocol names must be lowercase
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 (PostgreSQL)
• com.mysql.jdbc.Driver (MySQL)
• oracle.jdbc.driver.OracleDriver (Oracle)
• com.microsoft.jdbc.sqlserver.SQLServerDriver (SQL Server 2000)
• com.microsoft.sqlserver.jdbc.SQLServerDriver (SQL Server 2005)

dburl

JDBC connection string:

• jdbc:postgresql://host_name:5432/db_name (PostgreSQL)
• jdbc:mysql://host_name/db_name (MySQL)
• jdbc:oracle:thin:@host_name:1521:oracle_sid (Oracle)
• jdbc:microsoft:sqlserver://host_name:1433;SelectMethod=cursor;DatabaseName=db_name (SQL Server 2000)
• jdbc:sqlserver://host_name:1433;SelectMethod=cursor;DatabaseName=db_name (SQL Server 2005)

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. Leave blank also for MySQL.

• 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.
If this parameter is zero to zero, then the pool is disabled and each connection to the database is obtained by directly calling java.sql.DriverManager.getConnection().

maxconnections

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

logintimeout

Maximum time (in seconds) to wait for obtaining a connection to the database.
The default value is 20.

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)

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)

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)

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 10g/XE

1. From the command line type:
   IMP system/manager fromuser=HIPERGATE touser=HIPERGATE buffer=128000 commit=yes ignore=yes file=h4orclxe.dmp
   

Microsoft SQL Server 2005

1. Copy h4mssql2005.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 h4mssql2005.bak to the devices list and click OK.

PostgreSQL 8.x

1. Create a new Unicode database:
   # createdb -E UNICODE hipergate4
   Create a new user:
   # createuser knowgate
   # grant all on database hipergate4 to knowgate
   Restore the database dump file H3PGSQL8.DUMP:
   
   # pg_restore -d hipergate4 h4pgsql83.backup
   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, 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.9.0

XML parser from The Apache Foundation

Bean Scripting Framework - 2.4.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 - 2.3.2

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

Java BeanShell - 2.0b4

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

Jakarta ORO 2.0.8

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

Sun JavaMail - 1.4.0

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

Sun Java Advanced Imaging API - 1.1.3

This library provides image manipulation from Java without using AWT.

Novell LDAP classes for Java

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

JiBX XML binding 1.1.5

JiBX is a framework for binding XML data to Java objects.

Appendix 5: Debug libraries

Appendix 6: Notes for compiling sources

Upgrading from version 3.0 to 4.0

1. First make a backup copy of both the database and the JSP pages and libraries of version 3.0.
2. Donwload ZIP file containing hipergate 3.0.
3. Copy JSP pages from /web directory to a new web application.
4. All libraries from /WEB-INF/lib and classes from /WEB-INF/classes must be the ones from the new version (except for the JDCB driver already in use).
5. Point the 4.0 source to the already existing 3.0 database by re-using the old hipergate.cnf file.
6. Start the setup assistant http://server/admin/setup.htm. The assistant will automatically detect the old version and upgrade de data model.

Alternative manual upgrade

java [-cp ...] com.knowgate.hipergate.datamodel.ModelManager /etc/hipergate.cnf upgrade 300 400

Trouble shooting

JavaMail

MySQL

PostgreSQL

SQL Server

General