Class PluginDefinition

    • Field Detail

      • MAX_CLASSNAME_LENGTH

        public static final int MAX_CLASSNAME_LENGTH
        The maximum length of the class name that can be stored in the database. Check the length against this value before calling the setClassName method to avoid exceptions.
        See Also:
        Constant Field Values
      • MAX_JARFILE_LENGTH

        public static final int MAX_JARFILE_LENGTH
        The maximum length of the jar path name that can be stored in the database.
        Since:
        3.0
        See Also:
        Constant Field Values
      • MAX_NAME_LENGTH

        public static final int MAX_NAME_LENGTH
        The maximum length of the name that can be stored in the database.
        See Also:
        Constant Field Values
      • MAX_VERSION_LENGTH

        public static final int MAX_VERSION_LENGTH
        The maximum length of the version that can be stored in the database.
        See Also:
        Constant Field Values
      • MAX_COPYRIGHT_LENGTH

        public static final int MAX_COPYRIGHT_LENGTH
        The maximum length of the copyright notice that can be stored in the database.
        See Also:
        Constant Field Values
      • MAX_CONTACT_LENGTH

        public static final int MAX_CONTACT_LENGTH
        The maximum length of the contact information that can be stored in the database.
        See Also:
        Constant Field Values
      • MAX_EMAIL_LENGTH

        public static final int MAX_EMAIL_LENGTH
        The maximum length of the email address that can be stored in the database.
        See Also:
        Constant Field Values
      • MAX_URL_LENGTH

        public static final int MAX_URL_LENGTH
        The maximum length of the url that can be stored in the database.
        See Also:
        Constant Field Values
    • Method Detail

      • getNew

        public static PluginDefinition getNew​(DbControl dc,
                                              String className,
                                              String jarFile,
                                              boolean useRequestedPermissions)
                                       throws BaseException
        Create a new PluginDefinition item.
        Parameters:
        dc - The DbControl which will be used for permission checking and database access.
        className - The name of the class that implements the plugin interface
        jarFile - Optional file name of the JAR file which contains the plugin class. The JAR file must be located in the plugins.dir directory. If not specified the plugin must be in the classpath
        useRequestedPermissions - If the permissions that are returned by the Plugin.getPermissions() method should be used or not. If not used the plugin uses the permissions from the logged in user
        Returns:
        The new PluginDefinition item
        Throws:
        BaseException - If there is an error
      • getQuery

        public static ItemQuery<PluginDefinition> getQuery​(GuiContext gc,
                                                           String interfaceName)
        Get a query that returns all plugins related to a specified GUI context and implementing a certain interface. Ie. The isInContext(GuiContext) returns true for the specified item, and supports(PluginType) returns true for the specified interface.
        Parameters:
        gc - The context the plugin should be related to, or null if this parameter is irrelevant
        interfaceName - The complete name of the interface that the plugin must implement, or null if this parameter is irrelevant
      • countPlugins

        public static Map<Plugin.MainType,​Integer> countPlugins​(DbControl dc,
                                                                      GuiContext gc)
                                                               throws BaseException
        Count the number of plugins that can be used in a given context.
        Parameters:
        dc - An open DbControl object
        gc - The context to count plugins for
        Returns:
        A map with the main type as the key and the number of plugins as the value
        Throws:
        BaseException - If the plugins could not be counted.
      • checkInstallation

        public static void checkInstallation​(DbControl dc,
                                             Collection<PluginInfo> plugins)
        Check the installation status of the given list of plug-ins.
        Parameters:
        dc - An optional DbControl (if null a new internal connection will be used)
        plugins - An array with plug-in information objects
        Since:
        3.0
      • installOrUpdate

        public static PluginDefinition installOrUpdate​(DbControl dc,
                                                       PluginInfo info,
                                                       String jarFile,
                                                       ItemKey shareToEveryone)
        Install or update the plug-in definition with information from the info object. Existing plug-ins will be updated and the disabled flag is cleared (unless it is deprecated). New plug-ins are configured with additional options from the info object:
        • max-memory: Maximum memory in bytes when the plug-in is executed as an external process by a job agent
        • immediate-execution: If the plug-in is allowed to bypass the job queue.
        • everyone-use: If the plug-in should be shared with USE permission to everyone.
        • deprecated: Disable the plug-in if it is already installed, do not install if it is missing
        Returns:
        The plugin definition or null if no plug-in was installed
        Since:
        3.0
      • getType

        public Item getType()
        Description copied from interface: Identifiable
        Get the type of item represented by the object. The returned value is one of the values defined in the Item enumeration.
        Specified by:
        getType in interface Identifiable
        Returns:
        A value indicating the type of item
      • isRemoved

        public boolean isRemoved()
        Description copied from interface: Removable
        Check if the removed flag is set for this item.
        Specified by:
        isRemoved in interface Removable
        Overrides:
        isRemoved in class CommonItem
        Returns:
        TRUE if the item is flagged as removed, FALSE otherwise
      • getEntryDate

        public Date getEntryDate()
        Description copied from interface: Registered
        Get the date that the item was registered in the database.
        Specified by:
        getEntryDate in interface Registered
        Returns:
        A date or null if this is not known
      • setEntryDate

        public void setEntryDate​(Date entryDate)
        Description copied from interface: Registered
        Set the date the entry was registered in the database. Implementations should only allow this property to be set before the item is first stored in the database. The intention of this method is to facilitate export/import of data between server.
        Specified by:
        setEntryDate in interface Registered
        Parameters:
        entryDate - A date or null to use today's date
      • isAnnotated

        public boolean isAnnotated()
        Description copied from interface: Annotatable
        Check if this item has an annotation set. The annotation set may be empty.
        Specified by:
        isAnnotated in interface Annotatable
        Returns:
        TRUE if an annotation set exists, FALSE otherwise
        Since:
        2.5
      • getProtocol

        public Protocol getProtocol()
        Description copied from interface: Annotatable
        A protcol used in the creation of an item that is used to attach annotations for the protocol parameters.
        Specified by:
        getProtocol in interface Annotatable
        Returns:
        Always null
        Since:
        2.5
      • getAnnotatableParents

        public Set<Annotatable> getAnnotatableParents()
        Description copied from interface: Annotatable
        Get all parents objects which are annotatable and the logged in user has read permission to. If the item doesn't have any annotatable parents, it may return null or an empty set. The method should only return the immediate parent(s), not parents to parents, etc. As of BASE 3.1 this method may also return child items if the child item is a Subtypable item that has a subtype with the ItemSubtype.getPushAnnotations() flag set.
        Specified by:
        getAnnotatableParents in interface Annotatable
        Returns:
        Always null
        Since:
        2.5
      • getAnnotationMessage

        public String getAnnotationMessage()
        Get a message explaining what the proxy does with the annotations.
        Specified by:
        getAnnotationMessage in interface AnnotatableProxy
        Returns:
        A message or null
        Since:
        2.5
      • getClassName

        public String getClassName()
        Get the class name of the Java class that implements this plugin. The specified class must implement the Plugin interface.
        Returns:
        The class name for this plugin
      • getJarPath

        public String getJarPath()
        Get the path to the JAR file that contains the plugin class file. If this value is null, the plugin must be on the classpath.
      • getJarFile

        public String getJarFile()
        Get the name of the JAR file that contains this plug-in. If this value is null, the plug-in must be on the classpath (eg. in WEB-INF/lib).
        Since:
        3.0
      • getVersionString

        public String getVersionString()
        Get the version of the plugin.
        Returns:
        A string with the version of the plugin, or null if not known
      • getCopyright

        public String getCopyright()
        Get a copyright notice for the plugin.
        Returns:
        A string with a copyright notice, or null if not known
      • getContact

        public String getContact()
        Get contact information for the plugin.
        Returns:
        A string with contact information, or null if not known
      • getEmail

        public String getEmail()
        Get an email address that can be used to get more information about the plugin.
        Returns:
        A string with the email address, or null if not known
      • getUrl

        public String getUrl()
        Get a URL with more information about the plugin.
        Returns:
        A string containing the URL, or null if not known
      • setAbout

        public void setAbout​(About about,
                             boolean force)
        Update the plug-in information with the information in the about object.
        Parameters:
        about - An About object
        force - If TRUE all values are updated, if FALSE only non-null values
        Since:
        3.0
      • isDisabled

        public boolean isDisabled()
        Checks if this plugin is disabled or not. A disabled plugin can't be used.
        Since:
        3.0
      • setDisabled

        public void setDisabled​(boolean disabled)
        Disabled or enable this plugin.
        Since:
        3.0
      • isTrusted

        public boolean isTrusted()
        If this plugin is trusted or not. A trusted plugin is executed without any restrictions, an untrusted have restrictions similar to an applet in a web browser. NOTE!!! CURRENTLY NOT IMPLEMENTED.
        Returns:
        TRUE if the plugin is trusted, FALSE otherwise
      • setTrusted

        public void setTrusted​(boolean trusted)
        Set if this plugin should be trusted or not. NOTE!!! CURRENTLY NOT IMPLEMENTED.
        Throws:
        PermissionDeniedException - If the logged in user doesn't have write permission
        See Also:
        isTrusted()
      • getMaxMemory

        public Long getMaxMemory()
        Get the maximum amount of memory the plugins is allowed to use. The returned value is only a guideline to the job agent which may choose to use a lower setting due to the servers limitations. A null value means the job agent is free to choose any amount. Usually, it will select the default value as specified by the agent.maxMemory setting in it's configuration file.
        Returns:
        The maximum amount of memory to use, or null
      • setMaxMemory

        public void setMaxMemory​(Long maxMemory)
        Set the maximum amount of memory the plugin is allowed to use.
        Parameters:
        maxMemory - The maximum amount, or null if the job agent should decide
        Throws:
        PermissionDeniedException - If the logged in user doesn't have write permission
        See Also:
        getMaxMemory()
      • isInteractive

        public boolean isInteractive()
        Check if the plugin is interactive or not. An interactive plugin implements the InteractivePlugin interface and can be dynamically configured by telling the client application what configuration parameters it needs.
      • setInteractive

        private void setInteractive​(boolean interactive)
      • supportsConfigurations

        public boolean supportsConfigurations()
        Check if the plugin supports configurations or not when executing a job. Note! A false return value doesn't mean that the core stops anyone from creating a PluginConfiguration for this plugin. The return value should be used by client applications for better GUI.
      • setSupportsConfigurations

        private void setSupportsConfigurations​(boolean supportsConfigurations)
      • requiresConfiguration

        public boolean requiresConfiguration()
        Check if the plugin requires a configuration to execute a job. Note! The core will check the return value of this method when creating a job and throw an InvalidDataException if a configuration is required but isn't supplied.
      • setRequiresConfiguration

        private void setRequiresConfiguration​(boolean requiresConfiguration)
      • getUsePermissions

        public boolean getUsePermissions()
        Check if this plugin should execute with or without permissions. Note! The plugin will use the permissions of the logged in user if this is set to FALSE which could lead to this plugin not will be able to save/create files if the user doesn't have that permission. To be sure that the plugin will execute under certain permissions this should be set to TRUE.
        See Also:
        setPermissions(RoleKey, Set, Set)
      • setUsePermissions

        public void setUsePermissions​(boolean usePermissions)
      • getAllowImmediateExecution

        public boolean getAllowImmediateExecution()
        If immediate execution of jobs are allowed or if they always must go through the job queue. Immediate execution is needed by export plugins that want to use the immediate download feature.
        Returns:
        TRUE if immediate execition is allowed, FALSE it jobs must be added to the job queue
        Since:
        2.2
        See Also:
        ImmediateDownloadExporter
      • setAllowImmediateExecution

        public void setAllowImmediateExecution​(boolean allow)
      • getUseInternalJobQueue

        public boolean getUseInternalJobQueue()
        If this plug-in can be executed by the internal job queue or not. If not, the plug-in must be configured to be executed by a job agent. NOTE! The plug-in can always be excuted by job agents, they ignore this value.
        Returns:
        TRUE if the internal job queue is used, FALSE if not
        Since:
        2.5
      • setUseInternalJobQueue

        public void setUseInternalJobQueue​(boolean use)
        Set if the plug-in can use the internal job queue or not.
        Parameters:
        use - TRUE to use the internal job queue, FALSE to only use job agents
        Since:
        2.5
      • isInContext

        public boolean isInContext​(GuiContext context)
        Check if it makes sense to use this plugin in the context of the specified item. For example, a plugin that imports reporters would return true if passed Item.REPORTER.
        Parameters:
        context - The GuiContext type
        Returns:
        TRUE if the plugin handles the item, FALSE otherwise
      • getGuiContexts

        public Set<GuiContext> getGuiContexts()
        Get the Item types where it makes sense to use this plugin for a client application. For example, a plugin that imports reporters would return a set containing Item.REPORTER.
        Returns:
        A Set of Item:s or an empty set if the plugin is not concerned about items
      • setGuiContexts

        private void setGuiContexts​(Set<GuiContext> pluginContexts)
        Set the contexts where this plugin can be used.
      • getPluginConfigurations

        public ItemQuery<PluginConfiguration> getPluginConfigurations()
        Get a query that returns the configurations for this plugin definition.
        Returns:
        An ItemQuery object
      • getPluginTypes

        public ItemQuery<PluginType> getPluginTypes()
        Get a query that returns the plugin types for this plugin definition.
        Returns:
        An ItemQuery object
      • supports

        public boolean supports​(PluginType pluginType)
        Check if a plugin implements the interface specified by the plugin type.
        Parameters:
        pluginType - The pluginType to check
        Returns:
        TRUE if the plugin implements the specified interface, FALSE otherwise
      • supports

        public boolean supports​(String interfaceName)
        Check if a plugin implements the interface specified by the plugin type.
        Parameters:
        interfaceName - The pluginType to check
        Returns:
        TRUE if the plugin implements the specified interface, FALSE otherwise
      • newInstance

        public <P extends Plugin> P newInstance​(Class<P> clazz,
                                                SessionControl sc,
                                                PluginConfiguration configuration,
                                                Job job)
                                         throws PermissionDeniedException,
                                                BaseException
        Get an initialized instance of the plugin implementation.
        Type Parameters:
        P - The kind of returned object that extends Plugin.
        Parameters:
        clazz - The class of the plugin which must be a subclass of Plugin
        sc - The session control to initialise the plugin with
        configuration - The configuration parameters to initialise the plugin with, or null if no configuration exists
        job - The job parameters to intialise the plugin with, or null if no job exists
        Returns:
        An initialised plugin instance
        Throws:
        PermissionDeniedException
        BaseException
      • newInstance

        private Plugin newInstance​(String jarPath,
                                   String className,
                                   ClassLoader alternateClassLoader,
                                   boolean unloadBefore)
                            throws BaseException
        Create a new object instance of the given class.
        Parameters:
        jarPath - The full path to the JAR file
        className - The class to create
        unloadBefore - If the class definition should be unloaded before the new instance is created, unloading may not work if a client program holds a reference to an instance of the class
        Returns:
        The created instance
        Throws:
        BaseException
      • setPermissions

        public void setPermissions​(RoleKey roleKey,
                                   Set<Permission> granted,
                                   Set<Permission> denied)
                            throws PermissionDeniedException,
                                   InvalidUseOfNullException
        Sets the permissions for this plugin. It is not possible to give the plugin more permissions than the logged in user have. Permissions that are neither granted nor denied are checked against the permissions for the user that is running the plugin.

        NOTE! The granted permissions are always granted, regardless of the logged in user's permissions. The denied permissions are always denied regardless of the logged in user's permissions. This applies even to the root user account.

        If the granted permissions is null or empty and the denied permissions is null or contains the same set of permissions as defined by the item type the permissions are removed from the database, which means that only those permissions which differs from the defaults are stored in the database.

        Parameters:
        roleKey - The rolekey for this plugin
        granted - The permission to grant to the plugin
        denied - The permissions to deny the plugin
        Throws:
        PermissionDeniedException - If the logged in user doesn't have Permission.SET_PERMISSION for this PluginDefinition or trying to grant the plugin more permission then the logged in user
        InvalidUseOfNullException - If the rolekey is null
      • getGranted

        public Set<Permission> getGranted​(RoleKey roleKey)
                                   throws InvalidUseOfNullException
        Get the permissions that have been granted to this plugin.
        Parameters:
        roleKey - The role key to get the permission for
        Returns:
        A set containing the granted permissions for this plugin, the set is empty if no permissions has been granted
        Throws:
        InvalidUseOfNullException - If the role key is null
      • getDenied

        public Set<Permission> getDenied​(RoleKey roleKey)
                                  throws InvalidUseOfNullException
        Get the permissions that have been denied to this plugin.
        Parameters:
        roleKey - The role key to get the permission for
        Returns:
        A set containing the denied permissions for this plugin, the set is empty if no permissions has been denied
        Throws:
        InvalidUseOfNullException - If the role key is null
      • loadPluginInformation

        public void loadPluginInformation​(String jarFile,
                                          String className,
                                          boolean useRequstedPermissions)
                                   throws PermissionDeniedException,
                                          InvalidDataException,
                                          BaseException
        Load a plugin and copy information to the internal data structure.
        Parameters:
        jarFile - File name of the jar file containing the plug-in. The JAR file must be located in the directory spercified by 'plugins.dir' setting in base.config. Null is allowed if plugin is located in the classpath (eg. WEB-INF/lib).
        className - Full class name of the plugin's main class.
        useRequstedPermissions - TRUE if plugin should use the permissions it requests.
        Throws:
        PermissionDeniedException - If logged in user doesn't have write permission to this item.
        InvalidDataException - If any of the arguments is malformed or if setting the plugin's properties fails.
        BaseException - If something else fails.