crystalspace.jbind.interfaces.iutil.cfgmgr
Interface iConfigManager

All Superinterfaces:

iBase, iConfigFile, iPointer

All Known Implementing Classes:

csConfigManager

public interface iConfigManager

extends iConfigFile

The configuration manager is used to make a number of iConfigFile object appear like a single object. To do this, each iConfigFile object (also called a 'domain') is assigned a priority value. Options from config files with higher priority override or shadow options from configuration objects with lower priority. The lower priority options are still present, so if you access the lower priority iConfigFile directly you will still find their real values. If two iConfigFile objects use the same priority value, then one will shadow the other (but it is not possible to predict which will be the victor). One iConfigFile object is the so-called 'dynamic' domain. When you alter a setting in the configuration manager, the change is applied to the dynamic iConfigFile object. As a side-effect, the changed key is also removed from all objects with higher priority. The dynamic domain has always priority 0 (medium). Differences in behaviour compared to a normal confguration object are: * Deleting a key will not always remove the key from the configuration completely. It will only remove the key from the dyamic iConfigFile object and all higher-priority objects; and will thus reveal a value in a lower priority domain, if present. This also applies to the Clear() method. * The Load() and Save() methods will load or save the configuration of the dynamic domain. The other domains are not affected by Load(); and Save() will not write any keys from other domains. (In the unlikely event that you need to load or save one of the other domains, simply access the iConfigFile object for that domain directly and invoke its Load() and Save() methods rather than the methods of iConfigManager.) * Iterators: If you change an option after an iterator has passed the option, it may appear again, this time with the new value. If you change the option while the iterator looks at it, you may even read it twice after this change, once with the old and once with the new value. In general it is a bad idea to change something while an iterator exists.

Author:

Java wrapper - Quentin Anciaux, c++ version - http://crystal.sourceforge.net/docs/online/devapi/structiConfigManager.php

Field Summary

static int	ConfigPriorityApplication
static int	ConfigPriorityCmdLine
static int	ConfigPriorityPlugin
static int	ConfigPriorityUserApp
static int	ConfigPriorityUserGlobal
static int	PriorityHigh
static int	PriorityLow
static int	PriorityMax
static int	PriorityMedium
static int	PriorityMin
static int	PriorityVeryHigh
static int	PriorityVeryLow

Method Summary

void	addDomain(iConfigFile config, int priority) Add a configuration domain.
iConfigFile	addDomain(java.lang.String path, iVFS vfs, int priority) Add a configuration domain by loading it from a file.
void	flushRemoved() Flush all removed configuration files (only required in optimize mode);.
int	getDomainPriority(iConfigFile config) Return the priority of a configuration domain.
int	getDomainPriority(java.lang.String path) Return the priority of a configuration domain.
iConfigFile	getDynamicDomain() Return a pointer to the dynamic configuration domain.
int	getDynamicDomainPriority() Return the priority of the dynamic configuration domain.
iConfigFile	lookupDomain(java.lang.String path) Find the iConfigFile object for a registered domain.
void	removeDomain(iConfigFile config) Remove a configuration domain.
void	removeDomain(java.lang.String path) Remove a configuration domain.
void	setDomainPriority(iConfigFile config, int priority) Set the priority of a registered configuration domain.
void	setDomainPriority(java.lang.String path, int priority) Set the priority of a configuration domain.
boolean	setDynamicDomain(iConfigFile config) Change the dynamic domain.
void	setDynamicDomainPriority(int priority) Set the priority of the dynamic configuration domain.

Methods inherited from interface crystalspace.jbind.interfaces.iutil.cfgfile.iConfigFile

clear, deleteKey, enumerate, enumerate, getBool, getBool, getComment, getEOFComment, getFileName, getFloat, getFloat, getInt, getInt, getStr, getStr, getVFS, keyExists, load, load, load, load, save, save, save, setBool, setComment, setEOFComment, setFileName, setFloat, setInt, setStr, subsectionExists

Methods inherited from interface crystalspace.jbind.interfaces.iutil.scf.iBase

decRef, getName, getRefCount, getVersion, incRef, queryInterface, queryInterfaceSafe

Methods inherited from interface crystalspace.jbind.interfaces.iPointer

changePointer, getPointer, isMemoryOwner, setMemoryOwner

Field Detail

PriorityMin

public static final int PriorityMin

See Also:

Constant Field Values

PriorityVeryLow

public static final int PriorityVeryLow

See Also:

Constant Field Values

PriorityLow

public static final int PriorityLow

See Also:

Constant Field Values

PriorityMedium

public static final int PriorityMedium

See Also:

Constant Field Values

PriorityHigh

public static final int PriorityHigh

See Also:

Constant Field Values

PriorityVeryHigh

public static final int PriorityVeryHigh

See Also:

Constant Field Values

PriorityMax

public static final int PriorityMax

See Also:

Constant Field Values

ConfigPriorityPlugin

public static final int ConfigPriorityPlugin

See Also:

Constant Field Values

ConfigPriorityApplication

public static final int ConfigPriorityApplication

See Also:

Constant Field Values

ConfigPriorityUserGlobal

public static final int ConfigPriorityUserGlobal

See Also:

Constant Field Values

ConfigPriorityUserApp

public static final int ConfigPriorityUserApp

See Also:

Constant Field Values

ConfigPriorityCmdLine

public static final int ConfigPriorityCmdLine

See Also:

Constant Field Values

Method Detail

addDomain

public iConfigFile addDomain(java.lang.String path,
                             iVFS vfs,
                             int priority)

Add a configuration domain by loading it from a file. The new iConfigFile object which represents the loaded file is also returned. If you want to hold onto the iConfigFile even after it is removed from this object or after the configuration manager is destroyed, be sure to invoke IncRef(); or assign it to a csRef <>. The incoming iVFS may be null, in which case the path is assumed to point at a file in the pyhysical filesystem, rather than at a file in the public filesystem. Implemented in csConfigManager.

Parameters:

path -

vfs -

priority -

Returns:

addDomain

public void addDomain(iConfigFile config,
                      int priority)

Add a configuration domain. The configuration manager invokes IncRef(); upon the incoming iConfigFile. Implemented in csConfigManager.

Parameters:

config -

priority -

flushRemoved

public void flushRemoved()

Flush all removed configuration files (only required in optimize mode);. Implemented in csConfigManager.

getDomainPriority

public int getDomainPriority(iConfigFile config)

Return the priority of a configuration domain. If the domain is not registered, PriorityMedium is returned. Implemented in csConfigManager.

Parameters:

config -

Returns:

getDomainPriority

public int getDomainPriority(java.lang.String path)

Return the priority of a configuration domain. If the domain is not registered, PriorityMedium is returned. Implemented in csConfigManager.

Parameters:

path -

Returns:

getDynamicDomain

public iConfigFile getDynamicDomain()

Return a pointer to the dynamic configuration domain. The returned pointer will remain valid as long as the domain is registered with the configuration manager. Implemented in csConfigManager.

Returns:

getDynamicDomainPriority

public int getDynamicDomainPriority()

Return the priority of the dynamic configuration domain. Implemented in csConfigManager.

Returns:

lookupDomain

public iConfigFile lookupDomain(java.lang.String path)

Find the iConfigFile object for a registered domain. Returns null if the domain is not registered. Implemented in csConfigManager.

Parameters:

path -

Returns:

removeDomain

public void removeDomain(java.lang.String path)

Remove a configuration domain. Implemented in csConfigManager.

Parameters:

path -

removeDomain

public void removeDomain(iConfigFile config)

Remove a configuration domain. If registered, the configuration manager will relinquish its reference to the domain by invoking DecRef(); on it to balance the IncRef(); it performed when the domain was added. If the domain is not registered, the RemoveDomain(); request is ignored. It is not legal to remove the dynamic domain. Implemented in csConfigManager.

Parameters:

config -

setDomainPriority

public void setDomainPriority(iConfigFile config,
                              int priority)

Set the priority of a registered configuration domain. If the domain is not registered, the request is ignored. Implemented in csConfigManager.

Parameters:

config -

priority -

setDomainPriority

public void setDomainPriority(java.lang.String path,
                              int priority)

Set the priority of a configuration domain. Implemented in csConfigManager.

Parameters:

path -

priority -

setDynamicDomain

public boolean setDynamicDomain(iConfigFile config)

Change the dynamic domain. The domain must already have been registered with AddDomain(); before calling this method. If the domain is not registered, then false is returned. Implemented in csConfigManager.

Parameters:

config -

Returns:

setDynamicDomainPriority

public void setDynamicDomainPriority(int priority)

Set the priority of the dynamic configuration domain. Implemented in csConfigManager.

Parameters:

priority -