DiGIR Portal

Installation Instructions

This document is provided as a guide to setting up a DiGIR Portal. The implementation discussed is the Java implementation currently under the CVS repository at SourceForge and containing the following packages:

org.calacademy.digir.util
org.calacademy.digir.common
org.calacademy.digir.engine
org.calacademy.digir.presentation

The instructions cover both the setup for simply running a portal as well as the setup for those interested in doing additional portal development work, although the primary focus is on the former.

You will want to be familiar with the overall portal architecture. In brief, the portal is made up of two layers: the presentation layer and the engine (which may be thought of as a dispatcher). Each of these layers runs as its own application, or in specific, each as its own web application under its own Tomcat instance. Communication between each layer is via HTTP and allows for someone to run only one layer, if he/she so chooses, and communicate with the "missing" layer running elsewhere. For further information, please visit the DiGIR Site hosted on SourceForge.

Now, down to business...

Software Setup

Download and install the latest version of Java 2. You must have at least version 1.4 of the JDK. At the time of writing, the version used in development and testing was Java 2 SDK 1.4.0. The portal has undergone additional development using and is deemed to be supported by Java 2 SDK 1.4.1 and Java 2 SDK 1.4.2_02.
Java 2 is available here.
Follow the instructions available for installing the downloaded package. Be sure to do the following:
- Set the JAVA_HOME environment variable to the location of your Java 2 install (e.g. C:\j2sdk1.4.x). This should be done in a permanent fashion.
- Modify your PATH environment varialbe to include the Java 2 bin directory (e.g. C:\j2sdk1.4.x\bin). Again, this should be done in a permanent fashion.
Download and install at least version 4.0.3 of Jakarta Tomcat. Do not install a version earlier than 4.x or you will definitely have compatibility issues. At the time of writing, the versions used in development and testing include 4.0.3 and 4.0.4. The portal has undergone additional development using and is deemed to be supported by Tomcat 4.0.5, 4.0.6 and 4.1.29. Tomcat 4.1.29 is Apache's current production quality release. At this time, Tomcat 5.x is still in beta and will not run the portal applications as released.
Jakarta Tomcat is available here.
Follow the instuctions available for installing the downloaded package. Be sure to do the following:
- Set the CATALINA_HOME environment variable to the location of the Tomcat install (e.g. C:\jakarta-tomcat-4.0.3). This should be done in a permanent fashion.

Download the DiGIR environment ZIP file. This file establishes a basic directory structure for DiGIR as well as provides you with a number of configuration files required for Tomcat.

The DiGIR environment ZIP is available here.

Once you have downloaded this file, unzip it, preferably at C:\, but this is not required. After unzipping, be sure to:

Set a DIGIR_HOME environment variable to the location of the install (e.g. C:\DiGIR). Again, this should be done in a permanent fashion.

A brief overview of the directory structure is as follows:

Directory Description

/DiGIR/docs Directory for documentation. Developers who generate the javadoc will find the generated API javadoc here.

/DiGIR/lib Directory containing .jar files of required libraries. These .jar files are provided in the ZIP file so as to maintain a notion of compatiblity for development. The libraries include, but are not limited to: servlet.jar, soap.jar, uddi4j.jar, xalan.jar, xerces.jar, xml-apis.jar, log4j-1.2.8.jar, commons-logging-api.jar, commons-logging.jar, commons-httpclient-2.0.jar.

/DiGIR/logs Directory where application logs are written (i.e. portal_services.log and presentation.log).

/DiGIR/src Directory in which a developer should establish their CVS repository and work with the code. Do not be concerned if the directory is empty and remains that way if you are not doing development.

/DiGIR/tcinstance Directory containing setup and configuration for running the various layers of the Portal. You will find at least and engine and pres subdirectory here, each containing a bin, conf, logs, webapps, work, and temp directory. The directory structure within each tcinstance directory, as well as the configuration files, are required by Tomcat for a Tomcat instance to run.

Download the latest web application archive (.war) files for the portal application. Each layer, as discussed above, is its own web application and therefore has its own archive. You may choose to run either the presentation layer, the engine, or (probably) both.
The released DiGIR Web Application archives (.war) files are available here.
After downloading the files, you may need to rename them appropriately back to *.war as an extension (likely .zip) may be appended upon download. This does not harm the file contents.
- If you have downloaded the engine archive (DiGIR_portal_engine.war), place the file in the following directory:
  %DIGIR_HOME%/tcinstance/engine/webapps
  Then unpack the file as follows:
  jar xvf DiGIR_Portal_Engine.war
  This will create a WEB-INF directory containing a directory of java classes and a directory of libraries. Navigating the tree should yield an install of the following packages:
  - org.calacademy.digir.common
  - org.calacademy.digir.engine
  - org.calacademy.digir.util
  You will need to remove the .war file from the webapps directory, otherwise it may interfere with the running web application.
- If you have downloaded the presentation layer archive (DiGIR_portal_pres.war), place the file in the following directory:
  %DIGIR_HOME%/tcinstance/pres/webapps
  Then unpack the file as follows:
  jar xvf DiGIR_Portal_Pres.war
  This will create a WEB-INF directory containing a directory of java classes and a directory of libraries. It will also create some miscellaneous front end files. Navigating the tree should yield an install of the following java packages:
  - org.calacademy.digir.common
  - org.calacademy.digir.presentation
  - org.calacademy.digir.util
  You will need to remove the .war file from the webapps directory, otherwise it may interfere with the running web application.
Because the configuration files are contained within the archives, they must be unpacked so that you can make configuration changes (as directed below).

Software Configuration

To configure the engine (if of concern), you will need to edit the portal.xml file located in the %DIGIR_HOME/tcinstance/engine/webapps/WEB-INF/classes/org/calacademy/digir/engine directory you unpacked above. Initially you need only be concerned with the registry and/or provider configuration and the contactEmail. A quick review of the configuration options for the engine:

Element Notes

version The version of the particular release. This value is important as it should be in sync with the released protocol schema version. You should not need to edit it.

http The element contains many subelements related to http connection pooling done within the engine. These items are for fine tuning and are explained as follows:

maxConnections - The maximum number of connections allowed at any given time. These connections are maintained by a connection manager and reused.

maxConnectionsPerHost - The maximum number of connections allowed per host at any given time. These connections are maintained by a connection manager and reused. The number should be based on the expected number of simultaneous users.

connectionWaitTime - Th maximum number of seconds to wait to obtain a connection in order to make a request.

connectionEstablishmentTimeout - The maximum number of seconds to wait for a request to be accepted.

connectionResponseTimeout - The maximum number of seconds to wait on a response once a request is accepted.

connectionRetries - The number of times to retry should a recoverable error occur. Defaults to 0 (no retries).

You should not need to change these elements initially but may need to address them when running a portal in production.

handlerPoolThreadMax The maximum thread pool size for a request handler. This value indicates the number of providers that can be simultaneously queried per request (user). It should be set based on the number of expected providers for your network, the average size of the user base, and the throughpu t of your system. Usage of a threadpool per request promotes concurrency within requests. It is not intended for this value to be equal to the # of providers within your network unless that is a very small number or you expect to have very few simulataneous users.

configRefreshInterval The number of seconds to wait before reloading the config. This value indicates the time for the configuration information to live. If a value is not provided, it defaults to 0, meaning to never refresh. Although this option is provided, it is currently not implemented.

providerCacheRefreshInterval The number of seconds to wait before refreshing the provider cahce. This value indicates the time for the provider cache to live. If a value is not provided, it defaults to 0, meaning to never refresh. A refresh of the cache involves requerying a registry, if being used, and requerying each provider for metadata.

registry These are UDDI parameters for provider discovery. The uddiServiceKey should be set for your particular DiGIR Network. It is not required that a portal query any registry therefore this is an optional element.

provider The way to configure the portal for a particular provider(s). It is an optional element.

providerFilter A ProviderFilter class which filters out providers. At present, Darwin2ProviderFilterer is really a placeholder and you can remove the element from the config if you like. One can have N filters.

xmlSchema The namespace and location of the xml schema document

protocolSchema The namespace and location of the protocol (DiGIR) schema document.

contactEmail An email address for the contact of this portal. This element may disappear soon.

For further detail about the configuration file, feel free to read the portal.xsd XML Schema file in the same directory.

To configure the presentation layer (if of concern), you will need to edit the presentation.xml file located in the %DIGIR_HOME/tcinstance/pres/webapps/WEB-INF/classes/org/calacademy/digir/presentation directory you unpacked above. Initially you need only be concerned with the dispatcher value and the contactEmail. A quick review of the configuration options for the presentation layer:

Element Notes

dispatcher The URL for the engine layer. In the least, you will need to change the IP and port to those of the dispatcher you are accessing, which may be on your same machine (localhost).

http Elements related to http connection pooling. Although these subelements may share the same names of those in the engine layer, they may differ slightly in meaning.

maxConnections - The maximum number of connections allowed at any given time. These connections are maintained by a connection manager and reused. This value is also used as the maxConnectionsPerHost since only one host (the dispatcher) is ever queried.

connectionWaitTime - The maximum number of seconds to wait to obtain a connection in order to make a request.

connectionEstablishmentTimeout - The maximum number of seconds to wait for a request to be accepted.

connectionResponseTimeout - The maximum number of seconds to wait on a response once a request is accepted.

connectionRetries - The number of times to retry should a recoverable error occur. Defaults to 0 (no retries).

configRefreshInterval The number of seconds to wait before reloading the config. This value indicates the time for the configuration information to live. If a value is not provided, it defaults to 0, meaning to never refresh. Although this option is provided, it is currently not implemented.

providerListRefreshInterval The number of seconds to wait before refreshing the provider list from the dispatcher. This value indicates the time for the provider list to live. If a value is not provided, it defaults to 0, meaning to never refresh.

maxUserSpecifiedProviderTimeout The maximum number of seconds to allow the user to enter as the Provider Timeout. It should be less than the httpConnectionResponseTimeout specified above.

display A color, title, image, link, intro, about, and footer for use on the front end pages.

schemas The namespace, location and handle for the xmlSchema and the protocol (DiGIR) schema.

informationDomains The namespace, location and handle for supported information domains.

contactEmail Email address to appear on the front end error page as the contact.

For further detail about the configuration file, feel free to read the presentation.xsd XML Schema file in the same directory.

Running the Software

To run the engine (after configuration is complete), follow these steps:
- cd %DIGIR_HOME%/tcinstance/engine/bin
- run startup_engine.bat. This can be done on Windows by typing startup_engine at the command prompt.
To test that the engine is running, follow these steps:
- open a web browser
- open http://YOUR.IP.OR.DOMAIN:8080/portal/PortalServlet?action=getProviders in your browser
- you might keep an eye on the logfiles, in specific %DIGIR_HOME%/logs/portal_services.log
- also, keep an eye on the console window that appears when you run the startup script and be on the lookout for errors/exceptions
To run the presentation layer (after configuration is complete), follow these steps:
- ensure the engine is running, see above
- cd %DIGIR_HOME%/tcinstance/pres/bin
- run startup_pres.bat. This can be done on Windows by typing startup_pres at the command prompt.
To test that the presentation layer is running, follow these steps:
- open a web browser
- open http://YOUR.IP.OR.DOMAIN:10080/pres/PresentationServlet?action=home in your browser
- you might keep an eye on the logfiles, in specific %DIGIR_HOME%/logs/presentation.log
- also, keep an eye on the console window that appears when you run the startup script and be on the lookout for errors/exceptions

Troubleshooting

Note for Java 2 SDK 1.4.2 Users
This version of the SDK packages a Xalan library within it that conflicts with the portal software (and many other applications freely available). Sun packaged Xerces and Xalan with the JDK to spread adoption but unfortunately they have not packaged the latest releases of such. Therfore, if you are using version 1.4.2 of the SDK (and perhaps other 1.4.x versions) you may need to do the following:

copy xalan.jar found in %DIGIR_HOME%/lib to %CATALINA_HOME%/common/endorsed

This "endorses" the more recent xalan.jar for the class loader when you run the portal applications. Older versions of Tomcat (pre 4.1.?) may not offer an endorsed directory, therefore if you are encountering problems and need to take this step, upgrade to a 4.1.x version of Tomcat. If it is unclear whether you need to take this step, it will become obvious when you attempt to make a query once your portal is up and running and you receive this error on an error page or in the presentation layer's application log (presentation.log):

Unexpected error. (org.apache.xml.utils.WrappedRuntimeException: The output format must have a '{http://xml.apache.org/xalan}content-handler' property!)

Log configuration
If you're not seeing any output in the portal_services.log file, check the property log4j.appender.F.File in:

%DIGIR_HOME%/tcinstance/engine/webapps/WEB-INF/classes/log4j.properties

Tomcat resource location
When testing the portal engine, if you're getting:

HTTP status 404 Apache Tomcat error: The requested resource (/portal/PortalServlet) is not available.

Then you may want to check the docBase attribute inside the Tomcat Root Context element in:

%DIGIR_HOME%/tcinstance/engine/conf/server.xml

If you did not install your portal directly under the root directory of your file system, then you'll probably need to change "/" by "" in the docBase attribute.

Directory	Description
/DiGIR/docs	Directory for documentation. Developers who generate the javadoc will find the generated API javadoc here.
/DiGIR/lib	Directory containing .jar files of required libraries. These .jar files are provided in the ZIP file so as to maintain a notion of compatiblity for development. The libraries include, but are not limited to: `servlet.jar, soap.jar, uddi4j.jar, xalan.jar, xerces.jar, xml-apis.jar, log4j-1.2.8.jar, commons-logging-api.jar, commons-logging.jar, commons-httpclient-2.0.jar`.
/DiGIR/logs	Directory where application logs are written (i.e. `portal_services.log` and `presentation.log`).
/DiGIR/src	Directory in which a developer should establish their CVS repository and work with the code. Do not be concerned if the directory is empty and remains that way if you are not doing development.
/DiGIR/tcinstance	Directory containing setup and configuration for running the various layers of the Portal. You will find at least and engine and pres subdirectory here, each containing a bin, conf, logs, webapps, work, and temp directory. The directory structure within each tcinstance directory, as well as the configuration files, are required by Tomcat for a Tomcat instance to run.

Element	Notes
version	The version of the particular release. This value is important as it should be in sync with the released protocol schema version. You should not need to edit it.
http	The element contains many subelements related to http connection pooling done within the engine. These items are for fine tuning and are explained as follows: maxConnections - The maximum number of connections allowed at any given time. These connections are maintained by a connection manager and reused. maxConnectionsPerHost - The maximum number of connections allowed per host at any given time. These connections are maintained by a connection manager and reused. The number should be based on the expected number of simultaneous users. connectionWaitTime - Th maximum number of seconds to wait to obtain a connection in order to make a request. connectionEstablishmentTimeout - The maximum number of seconds to wait for a request to be accepted. connectionResponseTimeout - The maximum number of seconds to wait on a response once a request is accepted. connectionRetries - The number of times to retry should a recoverable error occur. Defaults to 0 (no retries). You should not need to change these elements initially but may need to address them when running a portal in production.
handlerPoolThreadMax	The maximum thread pool size for a request handler. This value indicates the number of providers that can be simultaneously queried per request (user). It should be set based on the number of expected providers for your network, the average size of the user base, and the throughpu t of your system. Usage of a threadpool per request promotes concurrency within requests. It is not intended for this value to be equal to the # of providers within your network unless that is a very small number or you expect to have very few simulataneous users.
configRefreshInterval	The number of seconds to wait before reloading the config. This value indicates the time for the configuration information to live. If a value is not provided, it defaults to 0, meaning to never refresh. Although this option is provided, it is currently not implemented.
providerCacheRefreshInterval	The number of seconds to wait before refreshing the provider cahce. This value indicates the time for the provider cache to live. If a value is not provided, it defaults to 0, meaning to never refresh. A refresh of the cache involves requerying a registry, if being used, and requerying each provider for metadata.
registry	These are UDDI parameters for provider discovery. The uddiServiceKey should be set for your particular DiGIR Network. It is not required that a portal query any registry therefore this is an optional element.
provider	The way to configure the portal for a particular provider(s). It is an optional element.
providerFilter	A ProviderFilter class which filters out providers. At present, Darwin2ProviderFilterer is really a placeholder and you can remove the element from the config if you like. One can have N filters.
xmlSchema	The namespace and location of the xml schema document
protocolSchema	The namespace and location of the protocol (DiGIR) schema document.
contactEmail	An email address for the contact of this portal. This element may disappear soon.

Element	Notes
dispatcher	The URL for the engine layer. In the least, you will need to change the IP and port to those of the dispatcher you are accessing, which may be on your same machine (localhost).
http	Elements related to http connection pooling. Although these subelements may share the same names of those in the engine layer, they may differ slightly in meaning. maxConnections - The maximum number of connections allowed at any given time. These connections are maintained by a connection manager and reused. This value is also used as the maxConnectionsPerHost since only one host (the dispatcher) is ever queried. connectionWaitTime - The maximum number of seconds to wait to obtain a connection in order to make a request. connectionEstablishmentTimeout - The maximum number of seconds to wait for a request to be accepted. connectionResponseTimeout - The maximum number of seconds to wait on a response once a request is accepted. connectionRetries - The number of times to retry should a recoverable error occur. Defaults to 0 (no retries).
configRefreshInterval	The number of seconds to wait before reloading the config. This value indicates the time for the configuration information to live. If a value is not provided, it defaults to 0, meaning to never refresh. Although this option is provided, it is currently not implemented.
providerListRefreshInterval	The number of seconds to wait before refreshing the provider list from the dispatcher. This value indicates the time for the provider list to live. If a value is not provided, it defaults to 0, meaning to never refresh.
maxUserSpecifiedProviderTimeout	The maximum number of seconds to allow the user to enter as the Provider Timeout. It should be less than the httpConnectionResponseTimeout specified above.
display	A color, title, image, link, intro, about, and footer for use on the front end pages.
schemas	The namespace, location and handle for the xmlSchema and the protocol (DiGIR) schema.
informationDomains	The namespace, location and handle for supported information domains.
contactEmail	Email address to appear on the front end error page as the contact.