Interface ConfigurableService

All Superinterfaces:
ADEPT2Service
All Known Subinterfaces:
ActivityEventManager, CommunicationService<I1,O1,I2,O2>, EventManager, ExecutionManager, InstanceStartEventManager, LogManager, MappingCommService<I1,O1,I2,O2>, OrgModelManager, ProcessManager, RuntimeManager, RuntimeService, SubprocessManager, WorklistManager
All Known Implementing Classes:
AbstractConfigurableAuthenticatedService, AbstractConfigurableService, AbstractEventManager, DefaultEventManager

public interface ConfigurableService extends ADEPT2Service
This interface extends an ADEPT2Service by the means to retrieve and change the configuration. Not all services allow to change their configuration at runtime and not all of the configuration may be changed at all and not by all users. This is reflected in this interface.
  • Field Details

    • CONF_RUNTIME_CONF_PREFIX

      static final String CONF_RUNTIME_CONF_PREFIX
      A prefix for runtime configuration values that have defaults in the normal configuration to be overridden by the runtime configuration. The default and the runtime configuration values need to have different keys otherwise deleting a value will also delete the default value. The default value will reappear after the next reboot.
      See Also:
  • Method Details

    • getConfiguration

      Configuration getConfiguration(SessionToken session)
      Gets the configuration of this service for displaying it. It usually contains all configuration values of a service. Not all of them may be changed and not all of them by all users! Therefore filter the configuration appropriately based on the changeable keys. The returned configuration must not be changed directly since it usually is a copy of the configuration. Use setConfigurationValue(SessionToken, String, String) for changing configuration values.

      Note to implementors: As stated above return a copy of the configuration and not the configuration itself. Additionally make sure the returned configuration is serialisable since it may be transfered to a remote machine.

      Parameters:
      session - The session which is used to check for access rights on this method.
      Returns:
      The configuration of the service. Some of its values may be changed.
    • getConfigurationValue

      String getConfigurationValue(SessionToken session, String key)
      Gets the string representation of the configuration value for the designated key or null if the key does not exist or has no value.
      Parameters:
      session - The session which is used to check for access rights on this method.
      key - The key of the configuration value.
      Returns:
      The string representation of the configuration value of the designated key or null if the key does not exist or has no value.
    • getChangeableConfigurationKeys

      List<String> getChangeableConfigurationKeys(SessionToken session)
      Gets a list of configuration keys that may be changed by the owner of the designated session token. Note that these may contain keys that are not yet in the configuration, and that the service may accept further keys for setting configuration values, for instance keys containing a name which the user chooses.
      Parameters:
      session - The session which is used to check for access rights on this method and to determine which configuration keys can be changed by the designated user.
      Returns:
      A list of strings that represent the keys that may be changed by the user identified by the designated session token.
    • setConfigurationValue

      void setConfigurationValue(SessionToken session, String key, String value) throws ConfigurationException
      Sets the designated configuration value. Be sure to use a valid key. The keys are specified by the service, which may accept keys beyond the changeable keys. The value has to conform to the key, for instance, if the value is a list, the string has to reflect this appropriately. Use the empty string as value to delete the configuration.

      Note to implementors: Check the configuration value for validity and the session token for whether it is allowed to change the configuration.

      Parameters:
      session - The session which is used to check for access rights on this method.
      key - The key for the configuration value.
      value - The string representation of the configuration value to be set.
      Throws:
      ConfigurationException - If there are problems setting the designated value, for instance, the value does not conform to the designated key or is not a valid value at all, a ConfigurationException will be thrown.
      IllegalArgumentException - If the key or the value is too long for the runtime configuration of the service, an IllegalArgumentException will be thrown.
      ConfigurationRuntimeException - If the runtime configuration of the service fails to store the value, a ConfigurationRuntimeException will be thrown.
    • setConfigurationValues

      default void setConfigurationValues(SessionToken session, Map<String,String> values) throws ConfigurationException
      Sets the designated configuration values as one batch. The keys and values are as for setConfigurationValue(SessionToken, String, String), so the empty string as value deletes the configuration of its key.

      This default implementation sets the values one after the other through setConfigurationValue(SessionToken, String, String) in the iteration order of the designated map, so if setting a value fails, the values before it stay set and those after it are not set.

      Note to implementors: Check all values for validity and the session token for whether it is allowed to change the configuration before setting any value, and set either all values or none.

      Parameters:
      session - The session which is used to check for access rights on this method.
      values - The string representations of the configuration values to be set, mapped by their keys.
      Throws:
      ConfigurationException - If there are problems setting the designated values, for instance, a value does not conform to its key or the values do not conform to each other, a ConfigurationException will be thrown.
      IllegalArgumentException - If a key or a value is too long for the runtime configuration of the service, an IllegalArgumentException will be thrown.
      ConfigurationRuntimeException - If the runtime configuration of the service fails to store the values, a ConfigurationRuntimeException will be thrown.
    • copyConfiguration

      static SerialisableConfiguration copyConfiguration(Configuration conf)
      Creates a new serialisable configuration containing the values of the designated configuration. The values are copied under the read lock of the designated configuration, so that the copy contains a write through it either completely or not at all. The configuration of a component instance, which ConfigurationManager.initConfiguration initialised, provides this lock; a subset of it has no lock of its own, so a copy of a subset is consistent per key only. For a configuration whose Synchronizer does not lock, a change during the copy may cause a ConcurrentModificationException.
      Parameters:
      conf - The configuration which to copy to a new configuration.
      Returns:
      A serialisable copy of the designated configuration containing the same values.
    • copyConfiguration

      @Deprecated(since="18.0.0", forRemoval=true) static SerialisableConfiguration copyConfiguration(Configuration conf, int retries, Logger logger)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use copyConfiguration(Configuration), which copies under the read lock of the designated configuration without retrying.
      Creates a new serialisable configuration containing the values of the designated configuration. The values are copied under the read lock of the designated configuration as for copyConfiguration(Configuration). If a concurrent modification interrupts the copy, as it may for a configuration whose Synchronizer does not lock, the copy will be retried for the designated amount of retries. If they all fail, this will be logged and the incomplete copy will be returned.
      Parameters:
      conf - The configuration which to copy to a new configuration.
      retries - The amount of copying retries in case of a concurrent modification of the configuration.
      logger - The logger in which to log that there have been too many concurrent modifications and that an incomplete configuration will be returned.
      Returns:
      A serialisable copy of the designated configuration containing the same values unless copying the configuration under its read lock could not be completed several times due to concurrent modifications. In this case the returned configuration will be incomplete.