Class 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) $
    • 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
      • isInitialized

        public static boolean isInitialized()
        Is the extension system initialized?
        Since:
        3.8
      • 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 ActionExtensionsInvoker<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...)
      • 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
      • 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
      • 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
      • 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)
      • 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 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()