net.sf.basedb.core
Class PluginConfiguration

java.lang.Object
  net.sf.basedb.core.BasicItem<D>
      net.sf.basedb.core.OwnedItem<D>
          net.sf.basedb.core.SharedItem<D>
              net.sf.basedb.core.CommonItem<D>
                  net.sf.basedb.core.AnnotatedItem<PluginConfigurationData>
                      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.
private <T> ParameterType<T>	getParameterType(Class<T> parameterClass, List<?> values) Gets the ParameterType to use with a class.
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
private <T> List<T>	getValueList(Element parameter, Class<T> classType) Gets the list of values for a parameter from the XML-file.
boolean	isUsed() Check if: A Job is using this plugin configuration
static List<Element>	loadXmlFile(InputStream in, String fileName) Load a configurations xml file from the given stream.
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(List<Element> parameters) Sets parameters for a PluginConfiguration from the elements in a xml configurations file.
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

loadXmlFile

public static List<Element> loadXmlFile(InputStream in,
                                        String fileName)
                                 throws IOException,
                                        JDOMException

Load a configurations xml file from the given stream.

Parameters:

in - The input stream to read from

fileName - The name of the originating file (optional)

Returns:

A list with all <configuration> elements in the file

Throws:

IOException

JDOMException

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

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:

• A Job is using this plugin configuration

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:

• Job:s using this configuration

  Overrides:

  getUsingItems in class BasicItem<PluginConfigurationData>

  Returns:

  A set containing proxies for the items, or an empty set if no items are using this item

  Since:

  2.2

  See Also:

  BasicItem.addUsingItems(Set, Item, org.hibernate.Query)

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, Developer documentation: Transactions, Developer documentation: 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. 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

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

setParameterValues

public void setParameterValues(List<Element> parameters)
                        throws ClassNotFoundException

Sets parameters for a PluginConfiguration from the elements in a xml configurations file.

Parameters:

parameters - A list of the parameters that shall be set to the configuration

Throws:

ClassNotFoundException - If there is an error while trying to find the type of the parameters.

Since:

3.0

getValueList

private <T> List<T> getValueList(Element parameter,
                                 Class<T> classType)

Gets the list of values for a parameter from the XML-file. Returns a list with parameter values.

getParameterType

private <T> ParameterType<T> getParameterType(Class<T> parameterClass,
                                              List<?> values)

Gets the ParameterType to use with a class. Returns null if this importer doesn't support the class.