3.0.1: 2011-11-10

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

java.lang.Object
  extended by 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) $

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).
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).
private  DbControl dc
           
private static boolean initialised
           
private static ProcessResults lastScanResults
           
private static Logger log
           
private static ExtensionsManager manager
           
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(DbControl dc, 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 fileuri, 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.
 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.
 List<ExtensionPoint<?>> getExtensionPoints()
          Get an list returning all registered extension points.
 List<Extension<?>> getExtensions()
          Get a list returning all registered extensions.
 List<Extension<?>> getExtensions(String id)
          Get a list returning all registered extensions for a specific extension point.
 ExtensionsFile getFile(String fileuri)
          Get information about an installed extensions file.
 ExtensionsFile getFileByObjectKey(ObjectKey key)
          Find out which file the given object is defined in.
 List<ExtensionsFile> getFiles()
          Get an list 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.
 ProcessResults getLastScanResults()
          Get the results of the last scan (manual or automatic).
<O> O
getObjectForKey(ObjectKey<O> key)
          Get the object that was registered for the given key.
 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(ServletContext context)
          Initialise the extension system.
 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.
 ProcessResults performActions(HttpServletRequest request)
          Perform the requested actions (install/uninstall) as given in the request form.
 void saveSettings()
          Save the settings.
private static ProcessResults scan(DbControl dc, HttpServletRequest request)
           
 int scanForChanges()
          Scan the managed directories for new/updated/deleted extensions.
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

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

manager

private static ExtensionsManager manager

registry

private static Registry registry

settings

private static Settings settings

servletContext

private static ServletContext servletContext

lastScanResults

private static ProcessResults lastScanResults

dc

private final DbControl dc

permissions

private final Set<Permission> permissions
Constructor Detail

ExtensionsControl

private ExtensionsControl(DbControl dc,
                          Set<Permission> permissions)
Method Detail

init

public static void init(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

scan

private static ProcessResults scan(DbControl dc,
                                   HttpServletRequest request)

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 URL, 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

scanForChanges

public int scanForChanges()
Scan the managed directories for new/updated/deleted extensions. Call getFiles() to get an updated list of files.

Returns:
The combined number of new/modified/deleted files
Throws:
PermissionDeniedException - If the logged in user doesn't have WRITE permission
Since:
3.0

performActions

public ProcessResults performActions(HttpServletRequest request)
Perform the requested actions (install/uninstall) as given in the request form.

Parameters:
request - The HTTP request with parameters
Throws:
PermissionDeniedException - If the logged in user doesn't have WRITE permission
Since:
3.0

getLastScanResults

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

Returns:
A ProcessResults object, or null if no scan has taken place
Since:
3.0

getDefaultErrorHandlerFactory

public ErrorHandlerFactory<Action> getDefaultErrorHandlerFactory()
Get the default error handling factory.

Since:
2.17

getExtensionPoints

public List<ExtensionPoint<?>> getExtensionPoints()
Get an list returning all registered extension points.

Since:
3.0 (Returned an Iterator in BASE 2.x)
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 List<Extension<?>> getExtensions()
Get a list returning all registered extensions.

Since:
3.0 (Returned an Iterator in BASE 2.x)
See Also:
Registry.getExtensions()

getExtensions

public List<Extension<?>> getExtensions(String id)
Get a list returning all registered extensions for a specific extension point.

Parameters:
id - The ID of the extension point
Since:
3.0 (Returned an Iterator in BASE 2.x)
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 List<ExtensionsFile> getFiles()
Get an list returning all XML/JAR files which contains installed extensions.


getFile

public ExtensionsFile getFile(String fileuri)
Get information about an installed extensions file.

Parameters:
fileuri - The URI to the file
Returns:
An ExtensionsFile object or null if the given file doesn't exists or isn't an extensions file

getFileByObjectKey

public ExtensionsFile getFileByObjectKey(ObjectKey key)
Find out which file the given object is defined in.

Parameters:
key - An object key
Returns:
Information about the file, or null if the object can't be found
Since:
3.0

getObjectForKey

public <O> O getObjectForKey(ObjectKey<O> key)
Get the object that was registered for the given key.

Parameters:
key - An object key
Returns:
The object or null if no object was found
Since:
3.0

enableAllInFile

public void enableAllInFile(String fileuri,
                            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:
fileuri - The fileuri 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()

3.0.1: 2011-11-10