2.17.2: 2011-06-17

net.sf.basedb.core
Class PluginConfiguration

java.lang.Object
  extended by net.sf.basedb.core.BasicItem<D>
      extended by net.sf.basedb.core.OwnedItem<D>
          extended by net.sf.basedb.core.SharedItem<D>
              extended by net.sf.basedb.core.CommonItem<D>
                  extended by net.sf.basedb.core.AnnotatedItem<PluginConfigurationData>
                      extended by net.sf.basedb.core.PluginConfiguration
All Implemented Interfaces:
AccessControlled, Annotatable, AnnotatableProxy, Controlled, Identifiable, Nameable, Ownable, Registered, Removable, Shareable, Transactional

public class PluginConfiguration
extends AnnotatedItem<PluginConfigurationData>
implements Transactional, AnnotatableProxy, Registered

This class is used to configure a plugin. A plugin can have many configurations.

Version:
2.0
Author:
Nicklas, Samuel

Nested Class Summary
 
Nested classes/interfaces inherited from interface net.sf.basedb.core.Transactional
Transactional.Action
 
Field Summary
private  int newParameterVersion
           
static Item TYPE
          The type of item represented by this class.
 
Fields inherited from interface net.sf.basedb.core.Nameable
MAX_DESCRIPTION_LENGTH, MAX_NAME_LENGTH
 
Constructor Summary
PluginConfiguration(PluginConfigurationData pc)
           
 
Method Summary
 PluginConfigurationRequest configure()
          Start the configuration sequence for a plugin.
 void copyParametersFrom(PluginConfiguration copyFrom)
          Copy all parameter values from another plugin configuration.
 Set<Annotatable> getAnnotatableParents()
          Get all parents objects which are annotatable and the logged in user has read permission to.
 String getAnnotationMessage()
          Get a message explaining what the proxy does with the annotations.
 ItemQuery<AnnotationType> getAnnotationTypes()
          Get the annotation types that can be used by this configuration.
static PluginConfiguration getById(DbControl dc, int id)
          Get a PluginConfiguration item when you know the ID.
 Date getEntryDate()
          Get the date that the item was registered in the database.
 ItemQuery<Job> getJobs()
          Get a query that returns the jobs using this plugin configuration.
static PluginConfiguration getNew(DbControl dc, PluginDefinition pd)
          Create a new PluginConfiguration item.
private  int getNewParameterVersion()
          Increase the version number once per transaction.
 ParameterInfo getParameterInfo(String name)
          Get extra information about a parameter in the latest version.
 ParameterInfo getParameterInfo(String name, int version)
          Get extra information about a parameter in a specific version.
 Set<String> getParameterNames()
          Get the names of all configuration values in the latest version.
 Set<String> getParameterNames(int version)
          Get the names of all configuration values in a specific version.
 ParameterValues getParameterValues(int version)
          Get the configuration parameters as a ParameterValues object.
 List<?> getParameterValues(String name)
          Get the values of a configuration parameter in the latest version.
 List<?> getParameterValues(String name, int version)
          Get the values of a configuration parameter in a specific version.
(package private)  ParameterValuesImpl getParameterValuesImpl(int version)
          Get a write-protected ParameterValuesImpl object so a job can read the paremeters.
 int getParameterVersion()
          Get the latest version number of the parameters.
 PluginDefinition getPluginDefinition()
          Get the plugin definition for this configuration.
static ItemQuery<PluginConfiguration> getQuery()
          Get a query configured to retrieve plugin configurations.
static ItemQuery<PluginConfiguration> getQuery(GuiContext gc, String interfaceName)
          Get a query that returns all plugins configurations related to a specified GUI context and implementing a certain interface.
 Item getType()
          Get the type of item represented by the object.
 Set<ItemProxy> getUsingItems()
          Get all: Job:s using this configuration
 boolean isUsed()
          Check if: A Job is using this plugin configuration
 Job newJob()
          Deprecated. Use newJob(Experiment) instead
 Job newJob(Experiment experiment)
          Create a new Job for this plugin configuration.
(package private)  void onAfterCommit(Transactional.Action action)
          Reset parameter version so that adding new parameters will increase the version the next time.
 void setParameterValues(String name, ParameterType<?> parameterType, List<?> values)
          Set a configuration parameter.
 void setParameterValues(String name, String label, String description, ParameterType<?> parameterType, List<?> values)
          Set a configuration parameter.
(package private)  void setParameterValuesInternal(String name, String label, String description, ParameterType<?> parameterType, List<?> values, boolean validate)
          Set the values of a configuration parameter.
private  void setPluginDefinition(PluginDefinition pd)
          The definition cannot be changed.
 
Methods inherited from class net.sf.basedb.core.AnnotatedItem
getAnnotationSet, getProtocol, isAnnotated, removeAnnotations, toTransferable
 
Methods inherited from class net.sf.basedb.core.CommonItem
getDescription, getName, isRemoved, setDescription, setName, setRemoved, toTransferable
 
Methods inherited from class net.sf.basedb.core.SharedItem
getItemKey, getProjectKey, initPermissions, isShared, onBeforeCommit, setItemKey, setProjectKey, toTransferable
 
Methods inherited from class net.sf.basedb.core.OwnedItem
getOwner, isOwner, setOwner, takeOwnership, toTransferable
 
Methods inherited from class net.sf.basedb.core.BasicItem
addUsingItems, addUsingItems, checkPermission, equals, getData, getDbControl, getId, getPermissions, getPluginPermissions, getSessionControl, getVersion, hashCode, hasPermission, isDetached, isInDatabase, onAfterInsert, onRollback, setDbControl, setProjectDefaults, toString, toTransferable, validate
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface net.sf.basedb.core.Annotatable
getAnnotationSet, getProtocol, isAnnotated, removeAnnotations
 
Methods inherited from interface net.sf.basedb.core.Identifiable
getId, getVersion
 
Methods inherited from interface net.sf.basedb.core.AccessControlled
checkPermission, getPermissions, hasPermission
 
Methods inherited from interface net.sf.basedb.core.Ownable
getOwner, isOwner, setOwner, takeOwnership
 

Field Detail

TYPE

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

See Also:
Item.PLUGINCONFIGURATION, getType()

newParameterVersion

private int newParameterVersion
Constructor Detail

PluginConfiguration

PluginConfiguration(PluginConfigurationData pc)
Method Detail

getNew

public static PluginConfiguration getNew(DbControl dc,
                                         PluginDefinition pd)
                                  throws PermissionDeniedException,
                                         BaseException
Create a new PluginConfiguration item.

Parameters:
dc - The DbControl which will be used for permission checking and database access.
pd - PluginDefinition to create a configuration for.
Returns:
The new PluginConfiguration item
Throws:
InvalidDataException - If the plugin definition is null
PermissionDeniedException - If the logged in user doesn't have use permission for the plugin definition
BaseException - If there is an error

getById

public static PluginConfiguration getById(DbControl dc,
                                          int id)
                                   throws ItemNotFoundException,
                                          PermissionDeniedException,
                                          BaseException
Get a PluginConfiguration 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 PluginConfiguration 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

getQuery

public static ItemQuery<PluginConfiguration> getQuery()
Get a query configured to retrieve plugin configurations.

Returns:
An ItemQuery object

getQuery

public static ItemQuery<PluginConfiguration> getQuery(GuiContext gc,
                                                      String interfaceName)
Get a query that returns all plugins configurations related to a specified GUI context and implementing a certain interface. Ie. The PluginDefinition.isInContext(GuiContext) returns true for the specified item, and PluginDefinition.supports(PluginType) returns true for the specified interface.

Parameters:
gc - The item 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

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

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

isUsed

public boolean isUsed()
               throws BaseException
Check if:

Overrides:
isUsed in class BasicItem<PluginConfigurationData>
Returns:
TRUE if this item is used, FALSE otherwise
Throws:
BaseException - If not able to tell if item is used or not.
See Also:
BasicItem.getUsingItems()

getUsingItems

public Set<ItemProxy> getUsingItems()
Get all:

onAfterCommit

void onAfterCommit(Transactional.Action action)
Reset parameter version so that adding new parameters will increase the version the next time.

Overrides:
onAfterCommit in class BasicItem<PluginConfigurationData>
See Also:
Transactional, Core API overview - Transaction handling, Coding rules and guidelines for item classes

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.

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

getPluginDefinition

public PluginDefinition getPluginDefinition()
                                     throws PermissionDeniedException,
                                            BaseException
Get the plugin definition for this configuration.

Returns:
PluginDefinition object.
Throws:
PermissionDeniedException - This exception is thrown if the logged in user doesn't have READ permission to the items.
BaseException - If anything else fails.

setPluginDefinition

private void setPluginDefinition(PluginDefinition pd)
                          throws PermissionDeniedException,
                                 InvalidUseOfNullException
The definition cannot be changed. Used internally only.

Throws:
PermissionDeniedException
InvalidUseOfNullException

getParameterVersion

public int getParameterVersion()
Get the latest version number of the parameters.


getNewParameterVersion

private int getNewParameterVersion()
Increase the version number once per transaction.


getParameterNames

public Set<String> getParameterNames()
Get the names of all configuration values in the latest version.

Returns:
A Set containing the names of the configuration values or an empty set if no values has been defined
See Also:
getParameterNames(int)

getParameterNames

public Set<String> getParameterNames(int version)
Get the names of all configuration values in a specific version.

Parameters:
version - The version to get the configuration parameters for
Returns:
A Set containing the names of the configuration values or an empty set if no values has been defined
See Also:
getParameterNames()

getParameterValues

public List<?> getParameterValues(String name)
                           throws PermissionDeniedException,
                                  BaseException
Get the values of a configuration parameter in the latest version.

Parameters:
name - The name of the parameter
Returns:
The values, or null if no value has been set
Throws:
PermissionDeniedException - If the logged in user doesn't have read permission to all values
BaseException - If there is another error
See Also:
getParameterValues(String, int)

getParameterValues

public List<?> getParameterValues(String name,
                                  int version)
                           throws PermissionDeniedException,
                                  BaseException
Get the values of a configuration parameter in a specific version.

Parameters:
name - The name of the parameter
version - The version of the parameter
Returns:
The values, or null if no value has been set
Throws:
PermissionDeniedException - If the logged in user doesn't have read permission to all values
BaseException - If there is another error
See Also:
getParameterValues(String)

getParameterInfo

public ParameterInfo getParameterInfo(String name)
                               throws PermissionDeniedException,
                                      BaseException
Get extra information about a parameter in the latest version. The information includes the label, description and values of the parameter.

Parameters:
name - The name of the parameter
Returns:
A ParameterInfo object or null if no parameter with the specified name exists
Throws:
PermissionDeniedException - If the parameter contain values that the logged in user doesn't have read permission for
BaseException - If there is another error
See Also:
getParameterInfo(String, int)

getParameterInfo

public ParameterInfo getParameterInfo(String name,
                                      int version)
                               throws PermissionDeniedException,
                                      BaseException
Get extra information about a parameter in a specific version. The information includes the label, description and values of the parameter.

Parameters:
name - The name of the parameter
version - The version of the parameter
Returns:
A ParameterInfo object or null if no parameter with the specified name exists
Throws:
PermissionDeniedException - If the parameter contain values that the logged in user doesn't have read permission for
BaseException - If there is another error
See Also:
getParameterInfo(String)

getParameterValues

public ParameterValues getParameterValues(int version)
Get the configuration parameters as a ParameterValues object.

Parameters:
version - The version of the parameters
Returns:
A ParameterValues object
Since:
2.5
See Also:
getParameterVersion()

setParameterValues

public void setParameterValues(String name,
                               ParameterType<?> parameterType,
                               List<?> values)
                        throws InvalidDataException,
                               PermissionDeniedException,
                               BaseException
Set a configuration parameter. The parameter version number is increased by one when the values are committed to the database.

Parameters:
name - The name of the configuration parameter
parameterType - The type of the parameter
values - A list containing the new values, null or empty to remove the configuration values
Throws:
PermissionDeniedException - If the logged in user doesn't have write permission
InvalidDataException - If name is null or the new value doesn't validate against the parameter type
BaseException - If there is another error

setParameterValues

public void setParameterValues(String name,
                               String label,
                               String description,
                               ParameterType<?> parameterType,
                               List<?> values)
                        throws InvalidDataException,
                               PermissionDeniedException,
                               BaseException
Set a configuration parameter. The parameter version number is increased by one when the values are committed to the database.

Parameters:
name - The name of the configuration parameter
label - The label of the parameter (optional)
description - A description of the parameter (optional)
parameterType - The type of the parameter
values - A list containing the new values, null or empty to remove the configuration values
Throws:
PermissionDeniedException - If the logged in user doesn't have write permission
InvalidDataException - If name is null or the new value doesn't validate against the parameter type
BaseException - If there is another error

setParameterValuesInternal

void setParameterValuesInternal(String name,
                                String label,
                                String description,
                                ParameterType<?> parameterType,
                                List<?> values,
                                boolean validate)
                          throws InvalidDataException,
                                 PermissionDeniedException,
                                 BaseException
Set the values of a configuration parameter.

Parameters:
name - The name of the configuration parameter
label - The label of the parameter (optional)
description - A description of the parameter (optional)
parameterType - The type of the parameter
values - A list containing the new values, null or empty to remove the configuration values
validate - If validation by ParameterType.validate(String, List) is needed or not
Throws:
PermissionDeniedException - If the logged in user doesn't have write permission
InvalidDataException - If name is null or the new value doesn't validate against the parameter type
BaseException - If there is another error

copyParametersFrom

public void copyParametersFrom(PluginConfiguration copyFrom)
                        throws InvalidDataException,
                               PermissionDeniedException,
                               BaseException
Copy all parameter values from another plugin configuration. This method increases the parameter version number and saves the copied parameters in that version.

Parameters:
copyFrom - The configuration to copy parameters from
Throws:
InvalidDataException - If the copyFrom parameter is null
PermissionDeniedException - If the logged in user doesn't have write permission for this configuration
BaseException - If there is another error

configure

public PluginConfigurationRequest configure()
                                     throws PermissionDeniedException,
                                            BaseException
Start the configuration sequence for a plugin. See PluginRequest for more information. The parameters sent to the plugin are those from the latest version.

Returns:
A PluginRequest object
Throws:
PermissionDeniedException - If the logged in user doesn't have write permission
BaseException - If there is another error

newJob

public Job newJob()
           throws PermissionDeniedException,
                  BaseException
Deprecated. Use newJob(Experiment) instead

Create a new job.

Throws:
PermissionDeniedException
BaseException

newJob

public Job newJob(Experiment experiment)
           throws PermissionDeniedException,
                  BaseException
Create a new Job for this plugin configuration.

Parameters:
experiment - The experiment the job is part of, or null if the job is not part of an experiment
Returns:
The new Job item
Throws:
PermissionDeniedException - If the logged in user doesn't have use permission for this plugin definition
BaseException
Since:
2.7

getJobs

public ItemQuery<Job> getJobs()
Get a query that returns the jobs using this plugin configuration.

Returns:
An ItemQuery object

getParameterValuesImpl

ParameterValuesImpl getParameterValuesImpl(int version)
                                     throws BaseException
Get a write-protected ParameterValuesImpl object so a job can read the paremeters.

Throws:
BaseException

2.17.2: 2011-06-17