Package net.sf.basedb.core

Class PluginDefinition

java.lang.Object
net.sf.basedb.core.BasicItem
net.sf.basedb.core.OwnedItem
net.sf.basedb.core.SharedItem
net.sf.basedb.core.CommonItem
net.sf.basedb.core.PluginDefinition
All Implemented Interfaces:
AccessControlled, Annotatable, AnnotatableProxy, Identifiable, Nameable, Ownable, Registered, Removable, Shareable
public class PluginDefinition extends CommonItem implements AnnotatableProxy, Registered
A plugin definition represents the executable plugin. Ie. the class name of a class implementing the Plugin interface.
Version:
2.0
Author:
Nicklas, Samuel
Last modified
$Date$

  • Field Details

    • TYPE

      public static final Item TYPE
      The type of item represented by this class.
      See Also:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • info

      private PluginInfo info

  • Constructor Details

  • Method Details

    • 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

    • getById

      public static PluginDefinition getById(DbControl dc, int id) throws ItemNotFoundException, PermissionDeniedException, BaseException
      Get a PluginDefinition item when you know the ID.
      Parameters:
      dc - The DbControl which will be used for permission checking and database access.
      id - The ID of the item to load.
      Returns:
      The PluginDefinition item.
      Throws:
      ItemNotFoundException - If an item with the specified ID is not found.
      PermissionDeniedException - If the logged in user doesn't have READ permission for the item.
      BaseException - If there is another error.

    • getByClassName

      public static PluginDefinition getByClassName(DbControl dc, String className) throws ItemNotFoundException, PermissionDeniedException, BaseException
      Get a PluginDefinition item when you know the class name.
      Parameters:
      dc - The DbControl which will be used for permission checking and database access.
      className - The class name of the item to load.
      Returns:
      The PluginDefinition item.
      Throws:
      ItemNotFoundException - If an item with the specified class name is not found.
      PermissionDeniedException - If the logged in user doesn't have READ permission for the item.
      BaseException - If there is another error.

    • getQuery

      public static ItemQuery<PluginDefinition> getQuery()
      Get a query that returns plugin definitions.
      Returns:
      An ItemQuery object

    • 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

    • getData

      PluginDefinitionData getData()
      Description copied from class: BasicItem
      Get the BasicData object that holds all data for this item.
      Overrides:
      getData in class CommonItem

    • 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

    • setRemoved

      public void setRemoved(boolean removed) throws PermissionDeniedException
      Description copied from interface: Removable
      Set the removed flag for this item.
      Specified by:
      setRemoved in interface Removable
      Overrides:
      setRemoved in class CommonItem
      Parameters:
      removed - TRUE if the item should be flagged as removed, FALSE otherwise
      Throws:
      PermissionDeniedException - If the logged in user doesn't have Permission.DELETE permission for setting the flag to TRUE or Permission.WRITE permission for setting the flag to FALSE

    • 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

    • isUsed

      public boolean isUsed() throws BaseException
      Check if a PluginConfiguration is using this definition.
      Overrides:
      isUsed in class BasicItem
      Returns:
      TRUE if this item is used, FALSE otherwise
      Throws:
      BaseException - If not able to tell if item is used or not.
      See Also:

    • onAfterInsert

      void onAfterInsert() throws BaseException
      Description copied from class: BasicItem
      This method is called on all items directly after Hibernate has inserted it into the database. This method can be used in place of the BasicItem.onBeforeCommit(Transactional.Action) in case the id is needed. The id has not been generated when the onBeforeCommit is called.
      Overrides:
      onAfterInsert in class BasicItem
      Throws:
      BaseException - If there is an error
      See Also:

    • getUsingItems

      public Set<ItemProxy> getUsingItems()
      Get all:
      Overrides:
      getUsingItems in class BasicItem
      Returns:
      A set containing proxies for the items, or an empty set if no items are using this item
      Since:
      2.2
      See Also:

    • getAnnotationSet

      public AnnotationSet getAnnotationSet() throws PermissionDeniedException, BaseException
      Description copied from interface: Annotatable
      Get the annotation set containing the annotations for this item. If the item doesn't have any annotations a new annotation set is created and automatically saved to the database when DbControl.commit() is called. To check if an item has annotations without creating a new annotation set use the Annotatable.isAnnotated() method.
      Specified by:
      getAnnotationSet in interface Annotatable
      Returns:
      An AnnotationSet
      Throws:
      PermissionDeniedException - If the logged in user doesn't have enough permissions
      BaseException - If there is another error
      Since:
      2.5

    • 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

    • removeAnnotations

      public void removeAnnotations() throws PermissionDeniedException, BaseException
      Description copied from interface: Annotatable
      Remove all annotations from this item, by deleting the annotation set.
      Specified by:
      removeAnnotations in interface Annotatable
      Throws:
      PermissionDeniedException - If the logged in user doesn't have write permission
      BaseException - If there is another error
      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

    • getAnnotationTypes

      public ItemQuery<AnnotationType> getAnnotationTypes()
      Get the annotation types that can be used by this configuration. This method requires that the plug-in implements the AnnotationSetterPlugin interface.
      Specified by:
      getAnnotationTypes in interface AnnotatableProxy
      Returns:
      A query or null if this plug-in doesn't use annotations
      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

    • setClassName

      private void setClassName(String className) throws InvalidDataException
      The class name cannot be changed. Used internally only.
      Throws:
      InvalidDataException

    • 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.

    • setJarFile

      private void setJarFile(String jarFile) throws InvalidDataException
      The jar path cannot be changed. Used internally only.
      Throws:
      InvalidDataException

    • 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

    • setVersionString

      private void setVersionString(String version) throws InvalidDataException
      Update version information for this plug-in.
      Throws:
      InvalidDataException - If the version is too long
      Since:
      3.0

    • getCopyright

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

    • setCopyright

      private void setCopyright(String copyright) throws InvalidDataException
      Update copyright information about this plug-in.
      Throws:
      InvalidDataException - If the copyright is too long
      Since:
      3.0

    • getContact

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

    • setContact

      private void setContact(String contact) throws InvalidDataException
      Set contact information for this plug-in.
      Throws:
      InvalidDataException - If the contact is too long
      Since:
      3.0

    • 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

    • setEmail

      private void setEmail(String email) throws InvalidDataException
      Set the email address that can be used to contact the developer of the plug-in.
      Throws:
      InvalidDataException - If the email is too long
      Since:
      3.0

    • getUrl

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

    • setUrl

      public void setUrl(String url) throws InvalidDataException
      Set the URL to a web page with more information about the plug-in.
      Throws:
      InvalidDataException - If the url is too long
      Since:
      3.0

    • 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:

    • 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:

    • getMainType

      public Plugin.MainType getMainType()
      Get the type of plugin.
      Returns:
      A type code that is defined in the enum Plugin.MainType.

    • setMainType

      private void setMainType(Plugin.MainType type) throws InvalidDataException
      The type cannot be changed. Used internally only.
      Throws:
      InvalidDataException - If the type is null
      Developer info
      This value is initialised upon installation to: plugin.getMainType() See: loadPluginInformation(String, String, boolean)

    • 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:

    • 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:

    • 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.

    • newPluginConfiguration

      public PluginConfiguration newPluginConfiguration() throws PermissionDeniedException, BaseException
      Create a new PluginConfiguration for this plugin.
      Returns:
      The new PluginConfiguration item
      Throws:
      PermissionDeniedException - If the logged in user doesn't have use permission for this plugin definition
      BaseException - If there is another error

    • 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 Plugin newInstance() throws PermissionDeniedException, BaseException
      Get an unitialized instance of the plugin.
      Throws:
      PermissionDeniedException - If the logged in user doesn't have Permission.USE permission to the items.
      BaseException - If there is a problem creating an instance.

    • newInstance

      public <P extends Plugin> P newInstance(Class<P> clazz) throws PermissionDeniedException, BaseException
      Get an unitialized 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
      Returns:
      An uninitialised plugin instance
      Throws:
      PermissionDeniedException
      BaseException

    • 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.