The first step is to install the actual extension code on the web server. Extensions are always packaged as XML or JAR files. To install an extension put the XML or JAR file in the <base-dir>/www/WEB-INF/extensions folder. This is the only place were extensions can be installed.

Make sure the extensions folder is writable by Tomcat

The extension you are installing may include resources such as HTML files, JSP scripts, images, etc. that needs to be extracted to the web application path before they can be used. This extraction is automatically done by the extensions system, but you have to make sure that the user account Tomcat is running as has permission to create (and delete) new files in the <base-dir>/www/extensions directory.

If you have enabled automatic installation you just have to wait and the extensions will be installed and registered automatically. Otherwise, you have to do a manual scan, using the following instructions.

Go to Extensions → Manual scan...

Figure 23.1. Manual scan

Performs a manual scan for new, updated or deleted extensions. If Force update is checked, extensions that have not been modified will also be re-registered. Leave this option unchecked unless there is any problem with the extension system.

Click on Start to start the scan.

If everything goes well you should get a report of what happend. The new XML or JAR file is hopefully listed as Installed. Click on the + icons to show more details.

Figure 23.2. Scan results

Some extensions may want to use custom JSP files that also uses classes that are stored in the extension's JAR file. The problem with this is that Tomcat usually doesn't know to look for classes in the WEB-INF/extensions directory. To solve this problem BASE ships with a X-JSP compiler that can do this. This compiler has been mapped to files with a .xjsp extension, which are just regular JSP files with a different extension.

The X-JSP compiler must be installed into Tomcat's internal library folder ($CATALINA_HOME/lib) since this is the only place where Tomcat look for compilers. The installation is easy. Simply copy <base-dir>/bin/jar/base2-xjsp-compiler.jar to $CATALINA_HOME/lib and restart Tomcat.

	X-JSP is experimental
	This is an experimental feature that depends on functionality in Tomcat. It may or may not work with future versions of Tomcat. The compiler will most likely not work with other servlet containers.

Go to Extensions → Installed extensions to display an overview of all installed extensions.

Figure 23.3. Installed extensions

The left-hand side of the screen shows you a tree with all installed extensions, sorted by extension point and by file. Use the + and - icons to expand and collapse parts of the tree. Click on an item in the tree to display detailed information about it on the right-hand side of the screen.

23.3.1. Settings

Click on the Settings... button to display a popup dialog that allows you to changes some global settings.

Figure 23.4. Extension settings

Auto-installation interval

The number of seconds between each check by the automatic installer. Enter 0 to disable automatic installation. The automatic installation performs the same steps as a manual scan with the Force update option unchecked. The default setting is to have the automatic installation disabled and we don't recommend enabling it in a production environment.

Click on Save to save the settings.