net.java.sip.communicator.service.configuration
Interface ConfigurationService

All Known Implementing Classes:

ConfigurationServiceImpl

public interface ConfigurationService

The configuration services provides a centralized approach of storing persistent configuration data.

Author:

Emil Ivov, Lyubomir Marinov, Dmitri Melnikov

Field Summary

static String	PNAME_CONFIGURATION_FILE_IS_READ_ONLY The name of the boolean system property which indicates whether the configuration file is to be considered read-only.
static String	PNAME_CONFIGURATION_FILE_NAME The name of the system property that stores the name of the configuration file.
static String	PNAME_SC_HOME_DIR_LOCATION The name of the property that indicates the location of the directory where SIP Communicator is to store user specific data such as configuration files, message and call history as well as is bundle repository.
static String	PNAME_SC_HOME_DIR_NAME The name of the property that indicates the name of the directory where SIP Communicator is to store user specific data such as configuration files, message and call history as well as is bundle repository.

Method Summary

void	addPropertyChangeListener(PropertyChangeListener listener) Adds a PropertyChangeListener to the listener list.
void	addPropertyChangeListener(String propertyName, PropertyChangeListener listener) Adds a PropertyChangeListener to the listener list for a specific property.
void	addVetoableChangeListener(ConfigVetoableChangeListener listener) Adds a VetoableChangeListener to the listener list.
void	addVetoableChangeListener(String propertyName, ConfigVetoableChangeListener listener) Adds a VetoableChangeListener to the listener list for a specific property.
List<String>	getAllPropertyNames() Returns a java.util.List of Strings containing all property names.
boolean	getBoolean(String propertyName, boolean defaultValue) Gets the value of a specific property as a boolean.
int	getInt(String propertyName, int defaultValue) Gets the value of a specific property as a signed decimal integer.
long	getLong(String propertyName, long defaultValue) Gets the value of a specific property as a signed decimal long integer.
Object	getProperty(String propertyName) Returns the value of the property with the specified name or null if no such property exists.
List<String>	getPropertyNamesByPrefix(String prefix, boolean exactPrefixMatch) Returns a java.util.List of Strings containing the all property names that have the specified prefix.
List<String>	getPropertyNamesBySuffix(String suffix) Returns a List of Strings containing the property names that have the specified suffix.
String	getScHomeDirLocation() Returns the location of the directory where SIP Communicator is to store user specific data such as configuration files, message and call history as well as is bundle repository.
String	getScHomeDirName() Returns the name of the directory where SIP Communicator is to store user specific data such as configuration files, message and call history as well as is bundle repository.
String	getString(String propertyName) Returns the String value of the specified property and null in case no property value was mapped against the specified propertyName, or in case the returned property string had zero length or contained whitespaces only.
String	getString(String propertyName, String defaultValue) Returns the String value of the specified property and null in case no property value was mapped against the specified propertyName, or in case the returned property string had zero length or contained whitespaces only.
void	purgeStoredConfiguration() Removes all locally stored properties leaving an empty configuration.
void	reloadConfiguration() Deletes the current configuration and reloads it from the configuration file.
void	removeProperty(String propertyName) Removes the property with the specified name.
void	removePropertyChangeListener(PropertyChangeListener listener) Removes a PropertyChangeListener from the listener list.
void	removePropertyChangeListener(String propertyName, PropertyChangeListener listener) Removes a PropertyChangeListener from the listener list for a specific property.
void	removeVetoableChangeListener(ConfigVetoableChangeListener listener) Removes a VetoableChangeListener from the listener list.
void	removeVetoableChangeListener(String propertyName, ConfigVetoableChangeListener listener) Removes a VetoableChangeListener from the listener list for a specific property.
void	setProperties(Map<String,Object> properties) Sets a set of specific properties to specific values as a batch operation meaning that first VetoableChangeListeners are asked to approve the modifications of the specified properties to the specified values, then the modifications are performed if no complaints have been raised in the form of PropetyVetoException and finally PropertyChangeListeners are notified about the changes of each of the specified properties.
void	setProperty(String propertyName, Object property) Sets the property with the specified name to the specified value.
void	setProperty(String propertyName, Object property, boolean isSystem) Sets the property with the specified name to the specified.
void	storeConfiguration() Store the current set of properties back to the configuration file.

Field Detail

PNAME_SC_HOME_DIR_NAME

static final String PNAME_SC_HOME_DIR_NAME

The name of the property that indicates the name of the directory where SIP Communicator is to store user specific data such as configuration files, message and call history as well as is bundle repository.

See Also:

Constant Field Values

PNAME_SC_HOME_DIR_LOCATION

static final String PNAME_SC_HOME_DIR_LOCATION

The name of the property that indicates the location of the directory where SIP Communicator is to store user specific data such as configuration files, message and call history as well as is bundle repository.

See Also:

Constant Field Values

PNAME_CONFIGURATION_FILE_IS_READ_ONLY

static final String PNAME_CONFIGURATION_FILE_IS_READ_ONLY

The name of the boolean system property which indicates whether the configuration file is to be considered read-only. The default value is false which means that the configuration file is considered writable.

See Also:

Constant Field Values

PNAME_CONFIGURATION_FILE_NAME

static final String PNAME_CONFIGURATION_FILE_NAME

The name of the system property that stores the name of the configuration file.

See Also:

Constant Field Values

Method Detail

setProperty

void setProperty(String propertyName,
                 Object property)

Sets the property with the specified name to the specified value. Calling this method would first trigger a PropertyChangeEvent that will be dispatched to all VetoableChangeListeners. In case no complaints (PropertyVetoException) have been received, the property will be actually changed and a PropertyChangeEvent will be dispatched.

Parameters:

propertyName - the name of the property to change.

property - the new value of the specified property.

Throws:

ConfigPropertyVetoException - in case the changed has been refused by at least one propertychange listener.

setProperty

void setProperty(String propertyName,
                 Object property,
                 boolean isSystem)

Sets the property with the specified name to the specified. Calling this method would first trigger a PropertyChangeEvent that will be dispatched to all VetoableChangeListeners. In case no complaints (PropertyVetoException) have been received, the property will be actually changed and a PropertyChangeEvent will be dispatched. This method also allows the caller to specify whether or not the specified property is a system one.

Parameters:

propertyName - the name of the property to change.

property - the new value of the specified property.

isSystem - specifies whether or not the property being is a System property and should be resolved against the system property set

Throws:

ConfigPropertyVetoException - in case the changed has been refused by at least one propertychange listener.

setProperties

void setProperties(Map<String,Object> properties)

Sets a set of specific properties to specific values as a batch operation meaning that first VetoableChangeListeners are asked to approve the modifications of the specified properties to the specified values, then the modifications are performed if no complaints have been raised in the form of PropetyVetoException and finally PropertyChangeListeners are notified about the changes of each of the specified properties. The batch operations allows the ConfigurationService implementations to optimize, for example, the saving of the configuration which in this case can be performed only once for the setting of multiple properties.

Parameters:

properties - a Map of property names to their new values to be set

Throws:

ConfigPropertyVetoException - if a change in at least one of the properties has been refused by at least one of the VetoableChangeListeners

getProperty

Object getProperty(String propertyName)

Returns the value of the property with the specified name or null if no such property exists.

Parameters:

propertyName - the name of the property that is being queried.

Returns:

the value of the property with the specified name.

removeProperty

void removeProperty(String propertyName)

Removes the property with the specified name. Calling this method would first trigger a PropertyChangeEvent that will be dispatched to all VetoableChangeListeners. In case no complaints (PropertyVetoException) have been received, the property will be actually changed and a PropertyChangeEvent will be dispatched. All properties with prefix propertyName will also be removed.

Parameters:

propertyName - the name of the property to change.

Throws:

ConfigPropertyVetoException - in case the changed has been refused by at least one propertychange listener.

getAllPropertyNames

List<String> getAllPropertyNames()

Returns a java.util.List of Strings containing all property names.

Returns:

a java.util.Listcontaining all property names

getPropertyNamesByPrefix

List<String> getPropertyNamesByPrefix(String prefix,
                                      boolean exactPrefixMatch)

Returns a java.util.List of Strings containing the all property names that have the specified prefix. Depending on the value of the exactPrefixMatch parameter the method will (when false) or will not (when exactPrefixMatch is true) include property names that have prefixes longer than the specified prefix param.

Example:

Imagine a configuration service instance containing 2 properties only:
net.java.sip.communicator.PROP1=value1
net.java.sip.communicator.service.protocol.PROP1=value2

A call to this method with a prefix="net.java.sip.communicator" and exactPrefixMatch=true would only return the first property - net.java.sip.communicator.PROP1, whereas the same call with exactPrefixMatch=false would return both properties as the second prefix includes the requested prefix string.

Parameters:

prefix - a String containing the prefix (the non dotted non-caps part of a property name) that we're looking for.

exactPrefixMatch - a boolean indicating whether the returned property names should all have a prefix that is an exact match of the the prefix param or whether properties with prefixes that contain it but are longer than it are also accepted.

Returns:

a java.util.Listcontaining all property name String-s matching the specified conditions.

getPropertyNamesBySuffix

List<String> getPropertyNamesBySuffix(String suffix)

Returns a List of Strings containing the property names that have the specified suffix. A suffix is considered to be everything after the last dot in the property name.

For example, imagine a configuration service instance containing two properties only:

net.java.sip.communicator.PROP1=value1 net.java.sip.communicator.service.protocol.PROP1=value2

A call to this method with suffix equal to "PROP1" will return both properties, whereas the call with suffix equal to "communicator.PROP1" or "PROP2" will return an empty List. Thus, if the suffix argument contains a dot, nothing will be found.

Parameters:

suffix - the suffix for the property names to be returned

Returns:

a List of Strings containing the property names which contain the specified suffix

getString

String getString(String propertyName)

Returns the String value of the specified property and null in case no property value was mapped against the specified propertyName, or in case the returned property string had zero length or contained whitespaces only.

Parameters:

propertyName - the name of the property that is being queried.

Returns:

the result of calling the property's toString method and null in case there was no value mapped against the specified propertyName, or the returned string had zero length or contained whitespaces only.

getString

String getString(String propertyName,
                 String defaultValue)

Returns the String value of the specified property and null in case no property value was mapped against the specified propertyName, or in case the returned property string had zero length or contained whitespaces only.

Parameters:

propertyName - the name of the property that is being queried.

defaultValue - the value to be returned if the specified property name is not associated with a value in this ConfigurationService

Returns:

the result of calling the property's toString method and defaultValue in case there was no value mapped against the specified propertyName, or the returned string had zero length or contained whitespaces only.

getBoolean

boolean getBoolean(String propertyName,
                   boolean defaultValue)

Gets the value of a specific property as a boolean. If the specified property name is associated with a value in this ConfigurationService, the string representation of the value is parsed into a boolean according to the rules of Boolean.parseBoolean(String) . Otherwise, defaultValue is returned.

Parameters:

propertyName - the name of the property to get the value of as a boolean

defaultValue - the value to be returned if the specified property name is not associated with a value in this ConfigurationService

Returns:

the value of the property with the specified name in this ConfigurationService as a boolean; defaultValue if the property with the specified name is not associated with a value in this ConfigurationService

getInt

int getInt(String propertyName,
           int defaultValue)

Gets the value of a specific property as a signed decimal integer. If the specified property name is associated with a value in this ConfigurationService, the string representation of the value is parsed into a signed decimal integer according to the rules of Integer.parseInt(String) . If parsing the value as a signed decimal integer fails or there is no value associated with the specified property name, defaultValue is returned.

Parameters:

propertyName - the name of the property to get the value of as a signed decimal integer

defaultValue - the value to be returned if parsing the value of the specified property name as a signed decimal integer fails or there is no value associated with the specified property name in this ConfigurationService

Returns:

the value of the property with the specified name in this ConfigurationService as a signed decimal integer; defaultValue if parsing the value of the specified property name fails or no value is associated in this ConfigurationService with the specified property name

getLong

long getLong(String propertyName,
             long defaultValue)

Gets the value of a specific property as a signed decimal long integer. If the specified property name is associated with a value in this ConfigurationService, the string representation of the value is parsed into a signed decimal long integer according to the rules of Long.parseLong(String) . If parsing the value as a signed decimal long integer fails or there is no value associated with the specified property name, defaultValue is returned.

Parameters:

propertyName - the name of the property to get the value of as a signed decimal long integer

defaultValue - the value to be returned if parsing the value of the specified property name as a signed decimal long integer fails or there is no value associated with the specified property name in this ConfigurationService

Returns:

the value of the property with the specified name in this ConfigurationService as a signed decimal long integer; defaultValue if parsing the value of the specified property name fails or no value is associated in this ConfigurationService with the specified property name

addPropertyChangeListener

void addPropertyChangeListener(PropertyChangeListener listener)

Adds a PropertyChangeListener to the listener list. The listener is registered for all properties in the current configuration.

Parameters:

listener - the PropertyChangeListener to be added

removePropertyChangeListener

void removePropertyChangeListener(PropertyChangeListener listener)

Removes a PropertyChangeListener from the listener list.

Parameters:

listener - the PropertyChangeListener to be removed

addPropertyChangeListener

void addPropertyChangeListener(String propertyName,
                               PropertyChangeListener listener)

Adds a PropertyChangeListener to the listener list for a specific property. In case a property with the specified name does not exist the listener is still added and would only be taken into account from the moment such a property is set by someone.

Parameters:

propertyName - one of the property names listed above

listener - the PropertyChangeListener to be added

removePropertyChangeListener

void removePropertyChangeListener(String propertyName,
                                  PropertyChangeListener listener)

Removes a PropertyChangeListener from the listener list for a specific property. This method should be used to remove PropertyChangeListeners that were registered for a specific property. The method has no effect when called for a listener that was not registered for that specifiec property.

Parameters:

propertyName - a valid property name

listener - the PropertyChangeListener to be removed

addVetoableChangeListener

void addVetoableChangeListener(ConfigVetoableChangeListener listener)

Adds a VetoableChangeListener to the listener list. The listener is registered for all properties in the configuration.

Parameters:

listener - the VetoableChangeListener to be added

removeVetoableChangeListener

void removeVetoableChangeListener(ConfigVetoableChangeListener listener)

Removes a VetoableChangeListener from the listener list.

Parameters:

listener - the VetoableChangeListener to be removed

addVetoableChangeListener

void addVetoableChangeListener(String propertyName,
                               ConfigVetoableChangeListener listener)

Adds a VetoableChangeListener to the listener list for a specific property.

Parameters:

propertyName - one of the property names listed above

listener - the VetoableChangeListener to be added

removeVetoableChangeListener

void removeVetoableChangeListener(String propertyName,
                                  ConfigVetoableChangeListener listener)

Removes a VetoableChangeListener from the listener list for a specific property.

Parameters:

propertyName - a valid property name

listener - the VetoableChangeListener to be removed

storeConfiguration

void storeConfiguration()
                        throws IOException

Store the current set of properties back to the configuration file. The name of the configuration file is queried from the system property net.java.sip.communicator.PROPERTIES_FILE_NAME, and is set to sip-communicator.xml in case the property does not contain a valid file name. The location might be one of three possibile, checked in the following order:
1. The current directory.
2. The sip-communicator directory in the user.home ($HOME/.sip-communicator) 3. A location in the classpath (such as the sip-communicator jar file).

In the last case the file is copied to the sip-communicator configuration directory right after being extracted from the classpath location.

Throws:

IOException - in case storing the configuration failed.

reloadConfiguration

void reloadConfiguration()
                         throws IOException,
                                XMLException

Deletes the current configuration and reloads it from the configuration file. The name of the configuration file is queried from the system property net.java.sip.communicator.PROPERTIES_FILE_NAME, and is set to sip-communicator.xml in case the property does not contain a valid file name. The location might be one of three possibile, checked in the following order:
1. The current directory.
2. The sip-communicator directory in the user.home ($HOME/.sip-communicator) 3. A location in the classpath (such as the sip-communicator jar file).

In the last case the file is copied to the sip-communicator configuration directory right after being extracted from the classpath location.

Throws:

IOException - in case reading the configuration failes

XMLException - in case parsing the configuration file has failed

purgeStoredConfiguration

void purgeStoredConfiguration()

Removes all locally stored properties leaving an empty configuration. Implementations that use a file for storing properties may simply delete it when this method is called.

getScHomeDirName

String getScHomeDirName()

Returns the name of the directory where SIP Communicator is to store user specific data such as configuration files, message and call history as well as is bundle repository.

Returns:

the name of the directory where SIP Communicator is to store user specific data such as configuration files, message and call history as well as is bundle repository.

getScHomeDirLocation

String getScHomeDirLocation()

Returns the location of the directory where SIP Communicator is to store user specific data such as configuration files, message and call history as well as is bundle repository.

Returns:

the location of the directory where SIP Communicator is to store user specific data such as configuration files, message and call history as well as is bundle repository.