net.sf.basedb.clients.web.extensions
Class ExtensionsControl

java.lang.Object
  net.sf.basedb.clients.web.extensions.ExtensionsControl

All Implemented Interfaces:

AccessControlled

public class ExtensionsControl
extends Object
implements AccessControlled

Controller class for the extension system in the web client. This is the main class to use when working with extensions from the JSP code.

To get all registered extensions for an extension point call useExtensions(JspContext, String...).

Use get(DbControl) to access the management API wich allows you to enable/disable extensions and change settings for the extension system.

Version:

2.7

Author:

nicklas

Last modified

$Date:2008-03-20 12:15:25 +0100 (Thu, 20 Mar 2008) $

Nested Class Summary

(package private) static class

ExtensionsControl.AutoInstallTask Task for starting an automatic check for new/updated/deleted extensions.

Field Summary

static EventType	AFTER_ENABLE This event is sent after an extension or extension point is enabled by enableExtensionPoint(String, boolean), enableExtension(String, boolean), or enableAllInFile(String, boolean).
private static TimerTask	autoInstallTask
static EventType	BEFORE_DISABLE This event is sent before an extension or extension point is disabled by enableExtensionPoint(String, boolean), enableExtension(String, boolean), or enableAllInFile(String, boolean).
static String	EXTENSIONS_URL The location where the extension system is looking for extensions.
private static ExtensionsDirectory	extensionsDir
private static boolean	initialised
private static ScanResults	lastScanResults
private static Logger	log
private static long	nextAutoScan
private Set<Permission>	permissions
private static Registry	registry
static String	RESOURCES_URL The location where the extensions resources are extracted.
static String	SERVLET_URL The location where extension servlets are registered.
private static ServletContext	servletContext
private static Settings	settings

Constructor Summary

private

ExtensionsControl(Set<Permission> permissions)

Method Summary

void	checkPermission(Permission permission) Check if the logged in user has the desired permission on the item, otherwise throw an exception.
private void	checkPermission(Permission permission, String what) For checking the permission and adding a custom message to the PermissionDeniedException if the required permission is missing.
static void	close() Shut down the extensions system.
static JspContext	createContext(DbControl dc, PageContext pageContext) Create a new JspContext object with an active DbControl.
static JspContext	createContext(DbControl dc, PageContext pageContext, GuiContext guiContext, Object currentItem) Create a new JspContext object with an active DbControl and a current GuiContext and item.
static JspContext	createContext(SessionControl sc, PageContext pageContext) Create a new JspContext object without an active DbControl.
void	enableAllInFile(String filename, boolean enable) Enable or disable all extensions and extension points in a file.
void	enableExtension(String extensionId, boolean enable) Enable/disable an extension.
void	enableExtensionPoint(String extensionPointId, boolean enable) Enable/disable an extension point.
static ExtensionsControl	get(DbControl dc) Get an extension control object for managing the installed extensions.
int	getAutoInstall() Get the auto-installation setting.
ErrorHandlerFactory<Action>	getDefaultErrorHandlerFactory() Get the default error handling factory.
Extension<?>	getExtension(String id) Get the extension with a given ID.
ExtensionPoint<?>	getExtensionPoint(String id) Get the extension point with a given ID.
Iterator<ExtensionPoint<?>>	getExtensionPoints() Get an iterator returning all registered extension points.
Iterator<Extension<?>>	getExtensions() Get an iterator returning all registered extensions.
Iterator<Extension<?>>	getExtensions(String id) Get an iterator returning all registered extensions for a specific extension point.
ExtensionsFile	getFile(String filename) Get information about an installed extensions file.
ExtensionsFile	getFileByExtensionId(String extensionId) Get information about the file a given extension or extension point is defined in.
Iterator<ExtensionsFile>	getFiles() Get an iterator returning all XML/JAR files which contains installed extensions.
static String	getHomeUrl(String extensionId) Get the URL to the home directory of extension with the given ID.
Throwable	getLastExtensionError(String id) Get information about the last error that happened when rendering an extension.
Throwable	getLastExtensionPointError(String id) Get information about the last error that happened when rendering an extension point.
ScanResults	getLastScanResults() Get the results of the last scan (manual or automatic).
long	getNextAutoScanTime() Get the next scheduled time for automatic scanning.
Set<Permission>	getPermissions() Get the logged in user's permissions on the item.
static String	getServletUrl(String extensionId, String servletName) Get the base URL for servlets in the extension with the given ID.
boolean	hasPermission(Permission permission) Check if the logged in user has the desired permission on the item.
static void	init(ExtensionsDirectory directory, ServletContext context) Initialise the extension system.
private static void	initAutoInstaller() Initialise the automatic installation task.
ScanResults	installAndUpdateExtensions(boolean forceUpdate) Perform a manual scan for new/updated/deleted extensions.
boolean	isEnabled(Extension extension) Check if an extension is enabled of disabled.
boolean	isEnabled(ExtensionPoint extensionPoint) Check if an extension point is enabled of disabled.
void	saveSettings() Save the settings.
void	setAutoInstall(int autoInstall) Change the auto-installation setting.
private static void	setLastScanResults(ScanResults scanResults)
static ExtensionsInvoker<?>	useExtensions(JspContext context, ExtensionsFilter filter, String... extensionPoints)
static ExtensionsInvoker<?>	useExtensions(JspContext context, String... extensionPoints) Use extensions from one or more extension points.

Methods inherited from class java.lang.Object

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

Field Detail

log

private static final Logger log

EXTENSIONS_URL

public static final String EXTENSIONS_URL

The location where the extension system is looking for extensions.

See Also:

Constant Field Values

RESOURCES_URL

public static final String RESOURCES_URL

The location where the extensions resources are extracted.

See Also:

Constant Field Values

SERVLET_URL

public static final String SERVLET_URL

The location where extension servlets are registered.

Since:

2.13

See Also:

Constant Field Values

BEFORE_DISABLE

public static final EventType BEFORE_DISABLE

This event is sent before an extension or extension point is disabled by enableExtensionPoint(String, boolean), enableExtension(String, boolean), or enableAllInFile(String, boolean).

AFTER_ENABLE

public static final EventType AFTER_ENABLE

This event is sent after an extension or extension point is enabled by enableExtensionPoint(String, boolean), enableExtension(String, boolean), or enableAllInFile(String, boolean).

initialised

private static boolean initialised

registry

private static Registry registry

extensionsDir

private static ExtensionsDirectory extensionsDir

settings

private static Settings settings

servletContext

private static ServletContext servletContext

autoInstallTask

private static TimerTask autoInstallTask

lastScanResults

private static ScanResults lastScanResults

nextAutoScan

private static long nextAutoScan

permissions

private final Set<Permission> permissions

Constructor Detail

ExtensionsControl

private ExtensionsControl(Set<Permission> permissions)

Method Detail

init

public static void init(ExtensionsDirectory directory,
                        ServletContext context)

Initialise the extension system. This method is called once from the ExtensionsServlet when the web server starts up.

close

public static void close()

Shut down the extensions system.

Since:

2.8

setLastScanResults

private static void setLastScanResults(ScanResults scanResults)

initAutoInstaller

private static void initAutoInstaller()

Initialise the automatic installation task. This method should be called whenever the getAutoInstall() settings has changed.

get

public static ExtensionsControl get(DbControl dc)

Get an extension control object for managing the installed extensions. Everybody has permission to read information. To update, WRITE permission for the web client application is needed.

Parameters:

dc - The DbControl to use for database access and permission checks, or null to only get read permission

Returns:

An extensions control instance

useExtensions

public static ExtensionsInvoker<?> useExtensions(JspContext context,
                                                 String... extensionPoints)

Use extensions from one or more extension points. This method will return an invoker object that allows the use and rendering of the extensions. The returned invoker will not reflect changes made to the registry by the same or other threads after this call has returned. Each use/invokation of an extension point should call this method to get a new invoker object.

Parameters:

context - The current context

extensionPoints - An array with the ID values of the extension points. Extension points that are not found are ignored.

Returns:

An invoker instance

See Also:

Registry.useExtensions(net.sf.basedb.util.extensions.ClientContext, net.sf.basedb.util.extensions.ExtensionsFilter, String...)

useExtensions

public static ExtensionsInvoker<?> useExtensions(JspContext context,
                                                 ExtensionsFilter filter,
                                                 String... extensionPoints)

createContext

public static JspContext createContext(SessionControl sc,
                                       PageContext pageContext)

Create a new JspContext object without an active DbControl. NOTE! Unless there is a very good reason we recommend that an active DbControl is always supplied. Use the createContext(DbControl, PageContext) method instead.

Parameters:

sc - The current session control

pageContext - Page context for the executing JSP page

See Also:

createContext(DbControl, PageContext)

createContext

public static JspContext createContext(DbControl dc,
                                       PageContext pageContext)

Create a new JspContext object with an active DbControl.

Parameters:

dc - An open DbControl

pageContext - Page context for the executing JSP page

createContext

public static JspContext createContext(DbControl dc,
                                       PageContext pageContext,
                                       GuiContext guiContext,
                                       Object currentItem)

Create a new JspContext object with an active DbControl and a current GuiContext and item.

Parameters:

dc - An open DbControl

pageContext - Page context for the executing JSP page

Since:

2.12

getHomeUrl

public static String getHomeUrl(String extensionId)

Get the URL to the home directory of extension with the given ID. The URL is a local absolute URL, eg. it includes the full path but not the protocol, server or port.

Parameters:

extensionId - The ID of a registered extension

Returns:

The local absolute URL to the home directory, or null if an extension with the given ID is not found

getServletUrl

public static String getServletUrl(String extensionId,
                                   String servletName)

Get the base URL for servlets in the extension with the given ID. The URL is a local absolute UTL, eg. it includes the full path but not the protocol, server or port. The URL is usually something like:

/extensions/servlet/[jar-file-name]/[servlet-name]

NOTE! Servlets can also be invoked by using the alternate path:

/extensions/[jar-file-name]/[servlet-name].servlet

Parameters:

extensionId - The ID of a registered extension

servletName - The name of the servlet

Returns:

The local absolute URL to the servlet, or null if an extension with the given ID is not found

Since:

2.13

checkPermission

public void checkPermission(Permission permission)
                     throws PermissionDeniedException

Description copied from interface: AccessControlled

Check if the logged in user has the desired permission on the item, otherwise throw an exception.

Specified by:

checkPermission in interface AccessControlled

Parameters:

permission - Permission the user should have.

Throws:

PermissionDeniedException - If the user doesn't have the requested permission

getPermissions

public Set<Permission> getPermissions()

Description copied from interface: AccessControlled

Get the logged in user's permissions on the item.

Specified by:

getPermissions in interface AccessControlled

hasPermission

public boolean hasPermission(Permission permission)

Description copied from interface: AccessControlled

Check if the logged in user has the desired permission on the item.

Specified by:

hasPermission in interface AccessControlled

Parameters:

permission - The permission to check if the user has.

Returns:

TRUE if the user has the permission, FALSE otherwise

checkPermission

private void checkPermission(Permission permission,
                             String what)
                      throws PermissionDeniedException

For checking the permission and adding a custom message to the PermissionDeniedException if the required permission is missing.

Throws:

PermissionDeniedException

installAndUpdateExtensions

public ScanResults installAndUpdateExtensions(boolean forceUpdate)

Perform a manual scan for new/updated/deleted extensions. If forceUpdate is TRUE all extensions are updated, which means that the definitions are re-loaded and resource files are extracted even if nothing has changed.

Parameters:

forceUpdate - TRUE to force an update for unmodified extensions, FALSE otherwise

Throws:

PermissionDeniedException - If the logged in user doesn't have WRITE permission

getAutoInstall

public int getAutoInstall()

Get the auto-installation setting. A value > 0 means that a background thread is checking for new/updated/deleted extensions every x seconds. If the value is 0 or negative automatic installation is disabled.

Returns:

The number of seconds between automatic checking

setAutoInstall

public void setAutoInstall(int autoInstall)

Change the auto-installation setting.

Parameters:

autoInstall - Number of seconds between automatic checks, or 0 or negative to disable

Throws:

PermissionDeniedException - If the logged in user doesn't have WRITE permission

See Also:

getAutoInstall()

getLastScanResults

public ScanResults getLastScanResults()

Get the results of the last scan (manual or automatic).

Returns:

A ScanResults object, or null if no scan has taken place

getNextAutoScanTime

public long getNextAutoScanTime()

Get the next scheduled time for automatic scanning. Note! It is not guaranteed that the next automatic scan will take place at exactly the returned time. Depending on timer resolution and other activity the scan may take place sooner or later.

Returns:

A time value in milliseconds or 0 if automatic scanning is disabled

See Also:

System.currentTimeMillis()

getDefaultErrorHandlerFactory

public ErrorHandlerFactory<Action> getDefaultErrorHandlerFactory()

Get the default error handling factory.

Since:

2.17

getExtensionPoints

public Iterator<ExtensionPoint<?>> getExtensionPoints()

Get an iterator returning all registered extension points.

See Also:

Registry.getExtensionPoints()

getExtensionPoint

public ExtensionPoint<?> getExtensionPoint(String id)

Get the extension point with a given ID.

Parameters:

id - The ID of the extension point

Returns:

An ExtensionPoint object or null if that extension point doesn't exists

See Also:

Registry.getExtensionPoint(String)

isEnabled

public boolean isEnabled(ExtensionPoint extensionPoint)

Check if an extension point is enabled of disabled.

Parameters:

extensionPoint - The extension point

Returns:

TRUE if the extension point is enabled, FALSE if it is disabled

See Also:

Settings.isEnabled(ExtensionPoint)

getLastExtensionPointError

public Throwable getLastExtensionPointError(String id)

Get information about the last error that happened when rendering an extension point.

Parameters:

id - The id of the extension point

Returns:

The error, or null if no error information is available

Since:

2.9

enableExtensionPoint

public void enableExtensionPoint(String extensionPointId,
                                 boolean enable)

Enable/disable an extension point.

Parameters:

extensionPointId - The ID of the extension point to enable/disable

enable - TRUE to enable the extension point, FALSE to disable it

Throws:

PermissionDeniedException - If the logged in user doesn't have WRITE permission

getExtensions

public Iterator<Extension<?>> getExtensions()

Get an iterator returning all registered extensions.

See Also:

Registry.getExtensions()

getExtensions

public Iterator<Extension<?>> getExtensions(String id)

Get an iterator returning all registered extensions for a specific extension point.

Parameters:

id - The ID of the extension point

See Also:

Registry.getExtensions(String)

getExtension

public Extension<?> getExtension(String id)

Get the extension with a given ID.

Parameters:

id - The ID of the extension point

Returns:

An Extension object or null if that extension doesn't exists

See Also:

Registry.getExtension(String)

getLastExtensionError

public Throwable getLastExtensionError(String id)

Get information about the last error that happened when rendering an extension.

Parameters:

id - The id of the extension

Returns:

The error, or null if no error information is available

Since:

2.9

isEnabled

public boolean isEnabled(Extension extension)

Check if an extension is enabled of disabled.

Parameters:

extension - The extension

Returns:

TRUE if the extension is enabled, FALSE if it is disabled

See Also:

Settings.isEnabled(Extension)

enableExtension

public void enableExtension(String extensionId,
                            boolean enable)

Enable/disable an extension.

Parameters:

extensionId - The ID of the extension to enable/disable

enable - TRUE to enable the extension, FALSE to disable it

Throws:

PermissionDeniedException - If the logged in user doesn't have WRITE permission

getFiles

public Iterator<ExtensionsFile> getFiles()

Get an iterator returning all XML/JAR files which contains installed extensions.

getFile

public ExtensionsFile getFile(String filename)

Get information about an installed extensions file.

Parameters:

filename - The filename of the file

Returns:

An ExtensionsFile object or null if the given file doesn't exists or isn't an extensions file

getFileByExtensionId

public ExtensionsFile getFileByExtensionId(String extensionId)

Get information about the file a given extension or extension point is defined in.

Parameters:

extensionId - The ID of an extension or extension point

Returns:

Information about the file the extension is defined in, or null if no extension with the given ID is found

enableAllInFile

public void enableAllInFile(String filename,
                            boolean enable)

Enable or disable all extensions and extension points in a file. If no file with the given name is found or if that file isn't an extensions file, nothing is done.

Parameters:

filename - The filename which contains the extensions

enable - TRUE to enable, FALSE to disable

saveSettings

public void saveSettings()

Save the settings. This method should be called when changes have been made to the settings. Otherwise, the settings are lost if the server is stopped.

Throws:

PermissionDeniedException - If the logged in user doesn't have WRITE permission

See Also:

Settings.save()