Controlling paths to ensure interoperability across environments

Use forward slashes

To ensure that paths work in all locations, use forward slashes ("/") wherever possible in configuration files and scripts. Windows and Unix environments both work well with forward slashes. The only exceptions are platform-specific scripts, such as Windows .bat files or Unix shell scripts.

Use relative paths in the pipeline

Using absolute paths in the Forge pipeline ties the application to a particular location in one environment. It is therefore better to use relative paths.

In record-adapters, paths are relative to [appdir]/data/processing, which contains the content of [appdir]/data/incoming before the pipeline is run. Therefore any files from [appdir]/data/incoming can be referenced directly by name, without specifying a directory.

Java manipulator paths are relative to [appdir]. This applies both to the manipulator's class path and to any files the Java code may try to access. Since these file names are often given as pass-throughs, keep such pass-through values relative to [appdir].

Use variables in scripts

You can specify relative paths in scripts, but keep in mind that scripts are not always invoked from the same directory. For example, there might be a script called crawl.sh in [appdir]/control. If this script uses paths relative to [appdir]/control, then it will only work correctly if it is invoked while stored in this directory. But if the script is invoked as/control/crawl.sh from [appdir], then the paths will be incorrect and the script may fail.

To avoid this problem, scripts can use preset variables to refer to a known directory without presuming any particular absolute path. In Windows batch files, the variable%~dp0 resolves to the directory containing the script. In Unix Bash scripts, the variable$0 resolves to the script name, and running the dirname command on it will give the script's directory. In BeanShell scripts for AppConfig.xml, the variable ${ENDECA_PROJECT_DIR} points to [appdir]. By using these variables, you can construct portable paths in location-independent scripts.

All the scripts generated by the Deployment Template use this technique and can serve as examples.

For Unix, the scripts generally start with the following lines:

WORKING_DIR=`dirname ${0} 2>/dev/null` 
. "${WORKING_DIR}/../config/script/set_environment.sh" 
		

This sets the WORKING_DIR variable to the directory containing the script being run, and then addresses the set_environment.sh file in a different directory by making the path relative to WORKING_DIR. Wherever the script is invoked, the path to set_environment.sh will always resolve correctly.

For Windows, the scripts usually start with the following line:

call %~dp0..\config\script\set_environment.bat 
		

This addresses set_environment.bat via a path relative to%~dp0. It ensures that the reference is correct wherever the script is invoked.