org.ceryle.wiki
Class WikiUtils

java.lang.Object
  org.ceryle.wiki.WikiUtils

public class WikiUtils
extends Object

Provides a utility shell for managing an instance of JSPWiki engine. For convenience' sake, the class itself provides all application services so that no methods are static.

Wiki Installations

There are three wiki configuration types possible in Ceryle. Only the first and third types are managed by this utility.

1. the Ceryle wiki: this is the documentation wiki for Ceryle itself. This wiki must exist in a $CERYLE_HOME/resource/webapps/CeryleWiki/ directory and its application name must be "CeryleWiki".
2. any collection-based wikis: if upon opening any wiki in the $CERYLE_HOME/resource/webapps/ directory via its URL being called by the web application (JSP servlet) engine in Jetty (the embedded HTTP server), if the wiki's application name matches an existing XNodeCollection ID it will use an XNodeProvider to provide wiki pages based on that collection. The rest of the wiki's settings (including all references to local file system locations) must be supplied in the specific wiki's $CERYLE_HOME/resource/webapps/$WIKI_HOME/WEB-INF/jspwiki.properties. As noted in setWikiProperties(WikiEngine), if you want a wiki to be untouched by this utility, just deliberately mismatch its directory name and the appname specified in its WEB-INF/jspwiki.properties. This wiki type is meant for those willing to hack the jspwiki.properties file, generally comfortable with such things.

Earlier versions used a concept of a "default wiki", and there may be remnants of that in the documentation. Now, all wikis installed in the webapps directory (except for the CeryleWiki) are treated the same, and have their individual settings set by a combination of the UI Prefs dialog and their own WEB-INF/jspwiki.properties file.

WikiEventManager

While the WikiEventManager was written as a singleton, because the servlet environment (e.g., Jetty) may create multiple JVMs multiple managers may actually exist. To avoid issues with this the first WikiEventManager returned by getInstance() is captured and available via getWikiEventManager().

WikiEventListeners

There is a WikiEventListener created each time getWikiEventListener() is called. Since each listener calls the same wikiStateChanged(WikiEngine,WikiEvent) method it this might seem unnecessary to use multiple listeners, but given that each WikiEngine runs independently there's little rationale to tying them together by a listener.

Template Preference

If the wiki being opened is identified as the Ceryle wiki, its settings are set according to the defaults for the Ceryle wiki. Otherwise, the template is determined according to this preference selection order:

1. The wiki has a specified templateDir. If the directory exists, use it.
2. If Ceryle preference directory exists, use it.
3. Don't change anything (use the 'default' template).

Version:

$Id: WikiUtils.java,v 1.8 2007-06-20 01:28:35 altheim Exp $

Author:

Murray Altheim

Field Summary

protected boolean	harvestAssertions When true, enables the WikiMapManager to perform an assertion harvest.
protected boolean	listenToChat When true, enables the WikiChatManager to listen to chat events.
static String	LOC_COLLECTION An enumerated String constant indicating that wiki pages are provided from an XNodeStore collection.
static String	LOC_CUSTOM An enumerated String constant indicating that wiki pages are provided from a custom, user-selected directory.
static String	LOC_DEFAULT An enumerated String constant indicating that wiki pages are provided from the default directory.
static String	PROPERTY_FACTORY_ENABLED The Ceryle property name of the property enabling or disabling creation of AssertionHandlers.
static String	PROPERTY_USECACHE The Ceryle property name of the property enabling or disabling caching by the TagManager (actually, TagManagerImpl).
static String	PROPERTY_WIKIMAP_ENABLED The Ceryle property name of the property enabling or disabling usurpation of a AssertionHandler by WikiMapManager.
static File	webappsDir The default webapps directory.

Constructor Summary

WikiUtils()

Method Summary

protected void	configureEngine(WikiEngine engine) Configures the engine by adding any listeners or filters.
WikiEngine	getEngine(String appname) Returns the WikiEngine whose wiki application name matches appname, or null if there is no match.
Set	getEngines() Returns the Set of WikiEngines.
static File	getWebappsDirectory() Returns the webapps directory, the base directory for any installed wiki applications.
String	getWikiBaseURL(String appname, boolean isCeryleWiki) Return the base URL of the WikiEngine installation with application name appname.
static File[]	getWikiDirectories() Returns an array of Files, each the root of a wiki installation.
WikiEventListener	getWikiEventListener() Returns a new WikiEventListener.
WikiEventManager	getWikiEventManager() Returns the WikiEventManager being used.
static boolean	hasWikiInstallation() Returns true if there is a JSPWiki installation directory, either the Ceryle wiki or a directory in the $CERYLE_HOME/resource/webapps/[name] directory containing a file named "Wiki.jsp", indicating availability of the default service.
static boolean	hasWikiInstallation(String name) Returns true if there is a JSPWiki installation directory matching the supplied wiki name (which will be tested against the name of the directory, as in $CERYLE_HOME/resource/webapps/[name], indicating availability of a wiki service and the file "Wiki.jsp" from that directory.
void	openWiki(String name) Attempts to start the default wiki by opening its base URL within the default web browser.
void	presetWikiProperties() Presets wiki properties prior to firing up the WikiEngine.
void	removeWikiEventListeners() Removes all WikiListeners from the WikiEventManager.
protected void	setWikiProperties(WikiEngine engine) Sets the properties of the WikiEngine based on application settings.
void	shutdown() Can be used to externally signal to any listeners that the Wiki is being shut down.
void	wikiStateChanged(WikiEngine engine, WikiEvent event) Process a state change from the wiki.
protected void	writeCascadeProperties(int index, File wikihome, Properties props) Writes the cascading properties of the WikiEngine based on application settings.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROPERTY_FACTORY_ENABLED

public static final String PROPERTY_FACTORY_ENABLED

The Ceryle property name of the property enabling or disabling creation of AssertionHandlers. The value is "http://purl.org/ceryle/prop/#wiki-ceryle.assertionhandler.factory.enabled".

See Also:

Constant Field Values

PROPERTY_WIKIMAP_ENABLED

public static final String PROPERTY_WIKIMAP_ENABLED

The Ceryle property name of the property enabling or disabling usurpation of a AssertionHandler by WikiMapManager. The value is "http://purl.org/ceryle/prop/#wiki-ceryle.wikimapmanager.enabled".

See Also:

Constant Field Values

PROPERTY_USECACHE

public static final String PROPERTY_USECACHE

The Ceryle property name of the property enabling or disabling caching by the TagManager (actually, TagManagerImpl). The value is "http://purl.org/ceryle/prop/#wiki-ceryle.tagmanager.usecache".

See Also:

Constant Field Values

LOC_DEFAULT

public static final String LOC_DEFAULT

An enumerated String constant indicating that wiki pages are provided from the default directory.

See Also:

Constant Field Values

LOC_COLLECTION

public static final String LOC_COLLECTION

An enumerated String constant indicating that wiki pages are provided from an XNodeStore collection.

See Also:

Constant Field Values

LOC_CUSTOM

public static final String LOC_CUSTOM

An enumerated String constant indicating that wiki pages are provided from a custom, user-selected directory.

See Also:

Constant Field Values

webappsDir

public static File webappsDir

The default webapps directory. The default value is "./resource/webapps/".

harvestAssertions

protected boolean harvestAssertions

When true, enables the WikiMapManager to perform an assertion harvest.

listenToChat

protected boolean listenToChat

When true, enables the WikiChatManager to listen to chat events.

Constructor Detail

WikiUtils

public WikiUtils()

Method Detail

hasWikiInstallation

public static boolean hasWikiInstallation()

Returns true if there is a JSPWiki installation directory, either the Ceryle wiki or a directory in the $CERYLE_HOME/resource/webapps/[name] directory containing a file named "Wiki.jsp", indicating availability of the default service.

hasWikiInstallation

public static boolean hasWikiInstallation(String name)

Returns true if there is a JSPWiki installation directory matching the supplied wiki name (which will be tested against the name of the directory, as in $CERYLE_HOME/resource/webapps/[name], indicating availability of a wiki service and the file "Wiki.jsp" from that directory.

This will return false if name is null or if it is "root" (as that is already used as the name of the HTTP installation) or "CVS".

getWebappsDirectory

public static File getWebappsDirectory()

Returns the webapps directory, the base directory for any installed wiki applications.

getWikiEventManager

public WikiEventManager getWikiEventManager()

Returns the WikiEventManager being used.

getWikiEventListener

public WikiEventListener getWikiEventListener()

Returns a new WikiEventListener.

presetWikiProperties

public void presetWikiProperties()

Presets wiki properties prior to firing up the WikiEngine.

writeCascadeProperties

protected void writeCascadeProperties(int index,
                                      File wikihome,
                                      Properties props)

Writes the cascading properties of the WikiEngine based on application settings. If this method notes that the wiki appname specified in WEB-INF/jspwiki.properties matches the wiki base directory name, then we allow modification of properties. This means that if you want a wiki to be untouched by this method, just deliberately mismatch its directory name and the appname specified in its WEB-INF/jspwiki.properties.

Parameters:

index - the property file index (1,2,3, etc.) Note that the index starts with 1, not 0.

wikihome - the wiki home directory

props - the Properties object to be modified

getWikiDirectories

public static File[] getWikiDirectories()

Returns an array of Files, each the root of a wiki installation. This ignores the 'root' directory. This returns an empty array rather than null, unless the webapps directory is not set or there is an error.

removeWikiEventListeners

public void removeWikiEventListeners()

Removes all WikiListeners from the WikiEventManager.

shutdown

public void shutdown()

Can be used to externally signal to any listeners that the Wiki is being shut down. This is generally sent as a message from the HTTPServer.

getEngines

public Set getEngines()

Returns the Set of WikiEngines. This Set may include nulls, as any engine may go offline at any time. This returns an empty Set if no WikiEngine is available rather than a null.

getEngine

public WikiEngine getEngine(String appname)

Returns the WikiEngine whose wiki application name matches appname, or null if there is no match. Note that an engine may go offline at any time.

wikiStateChanged

public void wikiStateChanged(WikiEngine engine,
                             WikiEvent event)

Process a state change from the wiki.

setWikiProperties

protected void setWikiProperties(WikiEngine engine)

Sets the properties of the WikiEngine based on application settings. If this method notes that the wiki appname specified in WEB-INF/jspwiki.properties matches the wiki base directory name, then we allow modification of properties. This means that if you want a wiki to be untouched by this method, just deliberately mismatch its directory name and the appname specified in its WEB-INF/jspwiki.properties.

getWikiBaseURL

public String getWikiBaseURL(String appname,
                             boolean isCeryleWiki)

Return the base URL of the WikiEngine installation with application name appname. If isCeryleWiki is true, the parameter is ignored, returning the base URL of the Ceryle Wiki; if false it is required, returning the wiki path for the specified application. This returns null if the HTTP host value property is not set or a null parameter is provided with a false boolean value.

openWiki

public void openWiki(String name)
              throws IOException

Attempts to start the default wiki by opening its base URL within the default web browser. This will fail if the browser is not set or configured correctly. If the wiki is not yet running, will call the default browser to open it with the included the page request. If the provided page name is null, opens the default 'Main' page, otherwise attempts to open the specified WikiPage.

Throws:

IOException - if the HTTP server is not already running

configureEngine

protected void configureEngine(WikiEngine engine)

Configures the engine by adding any listeners or filters.