Package 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) $

  • Field Details

  • Constructor Details

  • Method Details

    • 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

    • isInitialized

      public static boolean isInitialized()
      Is the extension system initialized?
      Since:
      3.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 <A extends Action> ExtensionsInvoker<A> 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 <A extends Action> ExtensionsInvoker<A> 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

    • getSetting

      public String getSetting​(String extensionId, String key)
      Get a configuration setting for an extension.
      Parameters:
      extensionId - The ID of the extension to save a setting for
      key - The name of the setting
      Returns:
      The value or null if it doesn't exists
      Since:
      3.4

    • setSetting

      public void setSetting​(String extensionId, String key, String value)
      Set a configuration setting for an extension. Do not forget to saveSettings().
      Parameters:
      extensionId - The ID of the extension to save a setting for
      key - The name of the setting
      value - The value of the setting, use null to remove
      Since:
      3.4

    • getFiles

      public List<ExtensionsFile> getFiles()
      Get an list returning all XML/JAR files which contains installed extensions.

    • getIgnoredFiles

      public List<File> getIgnoredFiles()
      Get files that are currently ignored.
      Since:
      3.10

    • 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

    • checkUnsafeScriptableUsage

      public List<Extension<?>> checkUnsafeScriptableUsage​(ExtensionsFile xtFile)
      Checks if the given extensions file contain any extensions that may violate the 'Content Security Policy' for the server. The following checks are made: ContentSecurityPolicyFilter.isUnsafeInlineScriptsAllowed() are called. If this method returns true, no further checks are made and an empty list is returned. For each Extension defined in the file, checkUnsafeScriptableUsage(Extension) is called and the extension is included in the list if TRUE.
      Since:
      3.3

    • checkUnsafeScriptableUsage

      public boolean checkUnsafeScriptableUsage​(Extension<?> ex)
      Checks if the given extension may violate the 'Content Security Policy' for the server. The following checks are made: ContentSecurityPolicyFilter.isUnsafeInlineScriptsAllowed() are called. If this method returns true, no further checks are made and false is returned. The extended ExtensionPoint is checked for the UnsafeScriptable annotation. If this annotation is not present, it is not possible for the extension to violate the policy. If this annotation is present, it is possible for the extensions to violate the security policy and final check is made: The About object for the extension is checked for attribute 'safe-scripts'. If this attribute is missing or set to a FALSE value the extension is considered 'unsafe' and are included in the returned list. If the attribute is set to TRUE, the extension 'promises' to not use any unsafe scripts.
      Since:
      3.3

    • checkUnsafeScriptableUsageInternal

      private boolean checkUnsafeScriptableUsageInternal​(Extension<?> ex)

    • 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()