OmeroBlitz API

omero::api::IConfig

Overview

[ "ami", "amd" ] interface IConfig extends ServiceInterface

Access to server configuration. These methods provide access to the state and configuration of the server and its components (e.g. the database). However, it should not be assumed that two subsequent calls to a proxy for this service will go to the same server due to clustering. Not all possible server configuration is available through this API. Some values (such as DB connection info, ports, etc.) must naturally be set before this service is accessible. Manages synchronization of the various configuration sources internally. It is therefore important that as far as possible all configuration changes take place via this interface and not, for example, directly via java.util.prefs.Preferences. Also used as the main developer example for developing (stateless) ome.api interfaces. See source code documentation for more.

Operation Index

getVersion

Provides the release version.

getConfigValue

Retrieves a configuration value from the backend store.

getConfigValues

Retrieves configuration values from the backend store which match the given regex.

getConfigDefaults

Reads the etc/omero.properties file and returns all the key/value pairs that are found there.

getClientConfigValues

Retrieves configuration values like {@code getConfigValues} but only those with the prefix omero.client.

getClientConfigDefaults

Reads the etc/omero.properties file and returns all the key/value pairs that are found there which match the prefix omero.client.

setConfigValue

Sets a configuration value in the backend store.

setConfigValueIfEquals

Calls {@code setConfigValue} if and only if the configuration property is currently equal to the test argument.

getDatabaseUuid

Provides the UUID for this OMERO (database) instance.

getDatabaseTime

Checks the database for its time using a SELECT statement.

getServerTime

Checks the current server for its time.

Operations

string getVersion() throws ServerError

Provides the release version. OMERO-internal values will be in the form Major.minor.patch, starting with the value 4.0.0 for the 4.0 release, Spring 2009. Customized values should begin with a alphabetic sequence followed by a hyphen: ACME-0.0.1 and any build information should follow the patch number also with a hyphen: 4.0.0-RC1. These values will be removed by {@code getVersion}

string getConfigValue(string key) throws ServerError

Retrieves a configuration value from the backend store. Permissions applied to the configuration value may cause a SecurityViolation to be thrown.

Parameters

key

The non-null name of the desired configuration value

Return Value

The string value linked to this key, possibly null if not set.

Exceptions

ApiUsageException

if the key is null or invalid.

SecurityViolation

if the value for the key is not readable.

StringStringMap getConfigValues(string keyRegex) throws ServerError

Retrieves configuration values from the backend store which match the given regex. Any configuration value which would throw an exception on being loaded is omitted.

Parameters

keyRegex

The non-null regex of the desired configuration values

Return Value

a map from the found keys to the linked values.

StringStringMap getConfigDefaults() throws ServerError

Reads the etc/omero.properties file and returns all the key/value pairs that are found there. Since this file is not to be edited its assumed that these values are in the public domain and so there's no need to protect them.

Return Value

a map from the found keys to the linked values.

StringStringMap getClientConfigValues() throws ServerError

Retrieves configuration values like {@code getConfigValues} but only those with the prefix omero.client.

Return Value

a map from the found keys to the linked values.

StringStringMap getClientConfigDefaults() throws ServerError

Reads the etc/omero.properties file and returns all the key/value pairs that are found there which match the prefix omero.client.

Return Value

a map from the found keys to the linked values.

void setConfigValue(string key, string value) throws ServerError

Sets a configuration value in the backend store. Permissions applied to the configuration value may cause a SecurityViolation to be thrown. If the value is null or empty, then the configuration will be removed in all writable configuration sources. If the configuration is set in a non-modifiable source (e.g. in a property file on the classpath), then a subsequent call to {@code getConfigValue} will return that value.

Parameters

key

The non-null name of the desired configuration value

value

The string value to assign to the given key.

Exceptions

ApiUsageException

if the key is null or invalid.

SecurityViolation

if the value is not writable.

bool setConfigValueIfEquals(string key, string value, string test) throws ServerError

Calls {@code setConfigValue} if and only if the configuration property is currently equal to the test argument. If the test is null or empty, then the configuration property will be set only if missing.

Parameters

Exceptions

See Also

setConfigValue

string getDatabaseUuid() throws ServerError

Provides the UUID for this OMERO (database) instance. To make imports and exports function properly, only one physical database should be active with a given instance UUID. All other copies of the database with that UUID are invalid as soon as one modification is made. This value is stored in the configuration table under the key omero.db.uuid.

Return Value

String not null.

RTime getDatabaseTime() throws ServerError

Checks the database for its time using a SELECT statement.

Return Value

Non-null RTime representation of the database time.

Exceptions

InternalException

though any call can throw an InternalException it is more likely that this can occur while contacting the DB. An exception here most likely means (A) a temporary issue with the DB or (B) a SQL dialect issue which must be corrected by the Omero team.

RTime getServerTime() throws ServerError

Checks the current server for its time. This value may be variant depending on whether the service is clustered or not.

Return Value

Non-null RTime representation of the server's own time.