Package ome.api

Interface IConfig

  • All Superinterfaces:
    ServiceInterface
    public 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 Preferences. Also used as the main developer example for developing (stateless) ome.api interfaces. See source code documentation for more.
    Since:
    3.0-M3

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String VERSION_REGEX
      Defines how the omero.version Preference will be parsed into the form: Major.minor.patch for getVersion()

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      java.util.Map<java.lang.String,​java.lang.String> getClientConfigDefaults()
      reads the etc/omero.properties file and returns all the key/value pairs that are found there which match the prefix "omero.client".
      java.util.Map<java.lang.String,​java.lang.String> getClientConfigValues()
      retrieves configuration values like getConfigValues(String) but only those with the prefix "omero.client".
      java.util.Map<java.lang.String,​java.lang.String> getConfigDefaults()
      reads the etc/omero.properties file and returns all the key/value pairs that are found there.
      java.lang.String getConfigValue​(java.lang.String key)
      retrieve a configuration value from the backend store.
      java.util.Map<java.lang.String,​java.lang.String> getConfigValues​(java.lang.String keyRegex)
      retrieves configuration values from the backend store which match the given regex.
      java.util.Date getDatabaseTime()
      checks the database for its time using a SELECT statement.
      java.lang.String getDatabaseUuid()
      Provides the UUID for this OMERO (database) instance.
      java.util.Date getServerTime()
      checks the current server for its time.
      java.lang.String getVersion()
      Provides the release version.
      void setConfigValue​(java.lang.String key, java.lang.String value)
      set a configuration value in the backend store.
      boolean setConfigValueIfEquals​(java.lang.String key, java.lang.String value, java.lang.String test)
      Calls setConfigValue(String, String) if and only if the configuration property is currently equal to the test argument.

    • Method Detail

      • getServerTime

        java.util.Date getServerTime()
        checks the current server for its time. This value may be variant depending on whether the service is clustered or not.
        Returns:
        Non-null Date representation of the server's own time.

      • getDatabaseTime

        java.util.Date getDatabaseTime()
                        throws ome.conditions.InternalException
        checks the database for its time using a SELECT statement.
        Returns:
        Non-null Date representation of the database's time.
        Throws:
        ome.conditions.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.

      • getConfigValue

        java.lang.String getConfigValue​(java.lang.String key)
                         throws ome.conditions.ApiUsageException,
                                ome.conditions.SecurityViolation
        retrieve 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
        Returns:
        The String value linked to this key, possibly null if not set.
        Throws:
        ome.conditions.ApiUsageException - if the key is null or invalid.
        ome.conditions.SecurityViolation - if the value for the key is not readable.

      • getConfigValues

        java.util.Map<java.lang.String,​java.lang.String> getConfigValues​(java.lang.String keyRegex)
        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
        Returns:
        a Map from the found keys to the linked values.

      • getConfigDefaults

        java.util.Map<java.lang.String,​java.lang.String> getConfigDefaults()
        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.
        Returns:
        a Map from the found keys to the linked values.

      • getClientConfigValues

        java.util.Map<java.lang.String,​java.lang.String> getClientConfigValues()
        retrieves configuration values like getConfigValues(String) but only those with the prefix "omero.client".
        Returns:
        a Map from the found keys to the linked values.

      • getClientConfigDefaults

        java.util.Map<java.lang.String,​java.lang.String> getClientConfigDefaults()
        reads the etc/omero.properties file and returns all the key/value pairs that are found there which match the prefix "omero.client".
        Returns:
        a Map from the found keys to the linked values.

      • setConfigValue

        void setConfigValue​(java.lang.String key,
                    java.lang.String value)
             throws ome.conditions.ApiUsageException,
                    ome.conditions.SecurityViolation
        set 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 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.
        Throws:
        ome.conditions.ApiUsageException - if the key is null or invalid.
        ome.conditions.SecurityViolation - if the value is not writable.

      • setConfigValueIfEquals

        boolean setConfigValueIfEquals​(java.lang.String key,
                               java.lang.String value,
                               java.lang.String test)
                        throws ome.conditions.ApiUsageException,
                               ome.conditions.SecurityViolation
        Calls setConfigValue(String, String) 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:
        key -
        value -
        test -
        Returns:
        See above.
        Throws:
        ome.conditions.ApiUsageException
        ome.conditions.SecurityViolation
        See Also:
        setConfigValue(String, String)

      • getVersion

        java.lang.String getVersion()
        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 getVersion()
        Returns:
        Returns the release version
        See Also:
        VERSION_REGEX

      • getDatabaseUuid

        java.lang.String getDatabaseUuid()
        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"
        Returns:
        String not null.