Add Rewrite Rule Plugin

This bundle plugin is an example of how add Tuckey rewrite rules using an OSGI bundle plugin. For more information about Tuckey rewrite rules, please see the URL Rewrite Rules documentation.

Implementation Steps #

This plugin is located in the com.dotcms.tuckey subdirectory in the examples directory (/dotCMS/docs/examples/osgi/com.dotcms.tuckey).

To implement the plugin, you must do the following:

Modify the following files:
- The MANIFEST file.
- Java classes in the Source folder.
Update the OSGI Exported Packages list.

MANIFEST File #

To be able to deploy the plugin, you must specify the following in the META-INF/MANIFEST.MF file (please see the template plugin for examples):

Parameter	Description
Bundle-Name	The name of your bundle.
Bundle-SymbolicName	A short an unique name for the bundle.
Bundle-Activator	Package and name of your Activator class (example: com.dotmarketing.osgi.tuckey.Activator).
DynamicImport-Package	Dynamically add required imports the plugin may need without add them explicitly.
Import-Package	This is a comma separated list of package's name./nList the packages that you are using inside the bundle plugin and that are exported by dotCMS.

Warning #

In order for the plugin to work inside the Apache Felix OSGI runtime, the import and export directives must be bidirectional.

Source Folder #

The src folder (/src/com/dotmarketing/osgi/tuckey/ in the plugin folder) contains the Java classes needed to create Tuckey rewrite Rules in dotCMS - Activator.java and HelloWorldServlet.java.

The bundle activator extends from com.dotmarketing.osgi.GenericBundleActivator and implements BundleActivator.start. It manually registers Tuckey Rewrite Rules, making use of the method addRewriteRule.

Important:

unregisterServices must be called in the stop method.
- This call is MANDATORY as it stops and removes the register Quartz Job when the plugin is undeployed.

HelloWorldServlet.java #

This is a simple and standard implementation of an HttpServlet used to test the added Tuckey Rewrite Rules.

Update Exported Packages #

Your OSGI plugins may access any dotCMS packages which have been exported. When you add the rewrite plugin, you must add the tuckey package to the list of exported packages to ensure your plugin has access to it.

You may update the list of exported packages either through the OSGI Plugins portlet or by manually editing the osgi-extra.conf file.

For more information, please see the Exported Packages section of the OSGI Plugins documentation.

Testing #

You can test the rewrite plugin in several different ways:

Access the simple test servlet built-in to your dotCMS instance:


http://localhost:8082/app/helloworld

Test the forward rule:


http://localhost:8082/example/url/forward

Test the redirect rule:


http://localhost:8082/example/url/redirect

Test the conditions:


http://localhost:8082/example/url/condition

Note: If you call this using google Chrome, it will display the message "from google Chrome." Otherwise it will do nothing (404 error).

Troubleshooting #

You can enable logging to help in troubleshooting any issues. To enable logging, add the following lines to the web.xml file :


<init-param>
    <param-name>logLevel</param-name>
    <param-value>DEBUG</param-value>
</init-param>

Note:

It is strongly recommended that all changes to the web.xml file be made through a properties file extension.
Enabling logging generates a large number of log messages.
- Logging should be used for testing and troubleshooting only.
- Logging should be disabled for production systems.

Fore more information on OSGI plugin logging, please see the OSGI Plugin Logging documentation.