org.dcm4che3.conf.core.api

Interface Configuration

All Superinterfaces:

BatchRunner

All Known Implementing Classes:

DefaultsAndNullFilterDecorator, DelegatingConfiguration, ExtensionMergingConfiguration, HashBasedOptimisticLockingConfiguration, InMemoryConfiguration, InMemoryReadOnlyConfiguration, ReferenceIndexingDecorator, SimpleCachingConfigurationDecorator, SingleJsonFileConfigurationStorage

public interface Configuration
extends BatchRunner

Denotes a configuration source. Can be used by BeanVitalizer that creates POJOs, or configuration administration app that provides UI to edit configuration.

The Configuration API operates on a tree data structure, where any subtree is referred to as a configuration node. A configuration node represents a JSON object. A configuration node is either

• a primitive wrapper/string (Number, Boolean, String)
• null
• a collection of nodes
• Map<String,Object> where each object is a configuration node (single map can have values of multiple types.

Formally, if such a node object is serialized into JSON and back without any transformations applied, the resulting object should be deep-equal to the original one.

A path is a valid XPath expression evaluated against the configuration tree. The usage of very advanced XPath expressions is not recommended, since it could lead to eager loading of configuration tree. Examples of paths can be found in org.dcm4che3.conf.dicom.DicomPath. A helper class org.dcm4che3.conf.core.util.PathPattern can be used to safely compose parametrized paths.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Configuration.ConfigStorageType
static class	Configuration.NodeFactory

Nested classes/interfaces inherited from interface org.dcm4che3.conf.core.api.BatchRunner

BatchRunner.Batch

Field Summary

Fields

Modifier and Type	Field and Description
static String	CONF_STORAGE_SYSTEM_PROP
static String	OLOCK_HASH_KEY A special property key that indicates that the containing node is a hash-based optimistic locking root and that this property contains the hash of this node.
static String	REFERENCE_BY_UUID_PATTERN
static String	REFERENCE_KEY A special property key that indicates that the container of this property is a reference to a node with uuid that equals to the property's value.
static String	UUID_KEY A special property key that indicates that this property is the referable uuid of the containing config node
static String	WEAK_REFERENCE_KEY

Method Summary

Modifier and Type	Method and Description
Object	getConfigurationNode(Path path, Class configurableClass) Loads a configuration node under the specified path.
Map<String,Object>	getConfigurationRoot() Return the root of the configuration tree.
Path	getPathByUUID(String uuid)
void	lock() Aquire a global pessimistic lock (cluster-aware implementations should ensure that only a single node can aquire the lock at a time) Subsequent calls from the same transaction should not block.
boolean	nodeExists(Path path) Tests if a node under the specified path exists.
void	persistNode(Path path, Map<String,Object> configNode, Class configurableClass) Persists the configuration node to the specified path.
void	refreshNode(Path path) Invalidates any present cached state for the node It is imperative that some other nodes might also be refreshed during the operation.
void	removeNode(Path path) Removes a configuration node under the specified path with all its children permanently
Iterator	search(String liteXPathExpression) Performs a search on the configuration tree and returns an iterator to configuration nodes that satisfy the search criteria.

Methods inherited from interface org.dcm4che3.conf.core.api.BatchRunner

runBatch

Field Detail

CONF_STORAGE_SYSTEM_PROP

static final String CONF_STORAGE_SYSTEM_PROP

See Also:

Constant Field Values

UUID_KEY

static final String UUID_KEY

A special property key that indicates that this property is the referable uuid of the containing config node

See Also:

Constant Field Values

OLOCK_HASH_KEY

static final String OLOCK_HASH_KEY

A special property key that indicates that the containing node is a hash-based optimistic locking root and that this property contains the hash of this node.

See Also:

Constant Field Values

REFERENCE_KEY

static final String REFERENCE_KEY

A special property key that indicates that the container of this property is a reference to a node with uuid that equals to the property's value. Additionally if WEAK_REFERENCE_KEY:true is defined in the container node, this reference is considered to be a weak reference (ConfigurableProperty.weakReference())

See Also:

Constant Field Values

WEAK_REFERENCE_KEY

static final String WEAK_REFERENCE_KEY

See Also:

Constant Field Values

REFERENCE_BY_UUID_PATTERN

static final String REFERENCE_BY_UUID_PATTERN

See Also:

Constant Field Values

Method Detail

getConfigurationRoot

Map<String,Object> getConfigurationRoot()
                                 throws ConfigurationException

Return the root of the configuration tree. The returned node should not be modified directly (only through persistNode/removeNode).

Returns:

configuration tree

Throws:

ConfigurationException

getConfigurationNode

Object getConfigurationNode(Path path,
                            Class configurableClass)
                     throws ConfigurationException

Loads a configuration node under the specified path.

Parameters:

path - A reference to a node

configurableClass -

Returns:

configuration node or null, if not found

Throws:

ConfigurationException

nodeExists

boolean nodeExists(Path path)
            throws ConfigurationException

Tests if a node under the specified path exists.

Parameters:

path -

Returns:

Throws:

ConfigurationException

persistNode

void persistNode(Path path,
                 Map<String,Object> configNode,
                 Class configurableClass)
          throws ConfigurationException

Persists the configuration node to the specified path. The path must exist (or at least all nodes but the last one). The property is created/fully overwritten, i.e. if there were any child nodes in the old root that are not present in the new node root, they will be deleted in the new tree.

Parameters:

path - path to the node

configNode - configuration node to persist

configurableClass - class annotated with ConfigurableClass, ConfigurableProperty annotations that corresponds to this node.

Throws:

ConfigurationException

refreshNode

void refreshNode(Path path)
          throws ConfigurationException

Invalidates any present cached state for the node It is imperative that some other nodes might also be refreshed during the operation. There is no guarantee whether the new version will be re-loaded lazily or eagerly

Parameters:

path -

Throws:

ConfigurationException

removeNode

void removeNode(Path path)
         throws ConfigurationException

Removes a configuration node under the specified path with all its children permanently

Parameters:

path -

Throws:

ConfigurationException

getPathByUUID

Path getPathByUUID(String uuid)

search

Iterator search(String liteXPathExpression)
         throws IllegalArgumentException,
                ConfigurationException

Performs a search on the configuration tree and returns an iterator to configuration nodes that satisfy the search criteria.

Parameters:

liteXPathExpression - Must be absolute path, no double slashes, no @attributes (only [attr=val] or [attr<>val])

Throws:

IllegalArgumentException

ConfigurationException

lock

void lock()

Aquire a global pessimistic lock (cluster-aware implementations should ensure that only a single node can aquire the lock at a time) Subsequent calls from the same transaction should not block. Should be auto-released on transaction commit/rollback.