org.apache.felix.cm.file
Class FilePersistenceManager

java.lang.Object
  extended by org.apache.felix.cm.file.FilePersistenceManager
All Implemented Interfaces:
PersistenceManager

public class FilePersistenceManager
extends java.lang.Object
implements PersistenceManager

The FilePersistenceManager class stores configuration data in properties-like files inside a given directory. All configuration files are located in the same directory.

The configuration directory is set by either the FilePersistenceManager(String) constructor or the FilePersistenceManager(BundleContext, String) constructor. Refer to the respective JavaDocs for more information.

When this persistence manager is used by the Configuration Admin Service, the location may be configured using the ConfigurationManager.CM_CONFIG_DIR bundle context property. That is the Configuration Admin Service creates an instance of this class calling new FilePersistenceManager(bundleContext, bundleContext.getProperty(CM_CONFIG_DIR)).

If the location is not set, the config directory in the current working directory (as set in the user.dir system property) is used. If the the location is set but, no such directory exists, the directory and any missing parent directories are created. If a file exists at the given location, the constructor fails.

Configuration files are created in the configuration directory by appending the extension .config to the PID of the configuration. The PID is converted into a relative path name by replacing enclosed dots to slashes. Non-symbolic-name characters in the PID are encoded with their Unicode character code in hexadecimal.

Examples of PID to name conversion:
PIDConfiguration File Name
samplesample.config
org.apache.felix.log.LogServiceorg/apache/felix/log/LogService.config
sample.flächesample/fl%00e8che.config

Mulithreading Issues

In a multithreaded environment the store(String, Dictionary) and load(File) methods may be called at the the quasi-same time for the same configuration PID. It may no happen, that the store method starts writing the file and the load method might at the same time read from the file currently being written and thus loading corrupt data (if data is available at all).

To prevent this situation from happening, the methods use synchronization and temporary files as follows:

Author:
fmeschbe

Field Summary
static java.lang.String DEFAULT_CONFIG_DIR
          The default configuration data directory if no location is configured (value is "config").
 
Constructor Summary
FilePersistenceManager(org.osgi.framework.BundleContext bundleContext, java.lang.String location)
          Creates an instance of this persistence manager using the given location as the directory to store and retrieve the configuration files.
FilePersistenceManager(java.lang.String location)
          Creates an instance of this persistence manager using the given location as the directory to store and retrieve the configuration files.
 
Method Summary
 void delete(java.lang.String pid)
          Deletes the file for the given identifier.
 boolean exists(java.lang.String pid)
          Returns true if a (configuration) file exists for the given identifier.
 java.util.Enumeration getDictionaries()
          Loads configuration data from the configuration location and returns it as Dictionary objects.
 java.io.File getLocation()
          Returns the directory in which the configuration files are written as a File object.
 java.util.Dictionary load(java.lang.String pid)
          Reads the (configuration) for the given identifier into a Dictionary object.
 void store(java.lang.String pid, java.util.Dictionary props)
          Stores the contents of the Dictionary in a file denoted by the given identifier.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_CONFIG_DIR

public static final java.lang.String DEFAULT_CONFIG_DIR
The default configuration data directory if no location is configured (value is "config").

See Also:
Constant Field Values
Constructor Detail

FilePersistenceManager

public FilePersistenceManager(java.lang.String location)
Creates an instance of this persistence manager using the given location as the directory to store and retrieve the configuration files.

This constructor resolves the configuration file location as follows:

This constructor is equivalent to calling FilePersistenceManager(BundleContext, String) with a null BundleContext.

Parameters:
location - The configuration file location. If this is null the config directory below the current working directory is used.
Throws:
java.lang.IllegalArgumentException - If the location exists but is not a directory or does not exist and cannot be created.

FilePersistenceManager

public FilePersistenceManager(org.osgi.framework.BundleContext bundleContext,
                              java.lang.String location)
Creates an instance of this persistence manager using the given location as the directory to store and retrieve the configuration files.

This constructor resolves the configuration file location as follows:

Parameters:
bundleContext - The BundleContext to optionally get the data location for the configuration files. This may be null, in which case this constructor acts exactly the same as calling FilePersistenceManager(String).
location - The configuration file location. If this is null the config directory below the current working directory is used.
Throws:
java.lang.IllegalArgumentException - If the location exists but is not a directory or does not exist and cannot be created.
java.lang.IllegalStateException - If the bundleContext is not valid.
Method Detail

getLocation

public java.io.File getLocation()
Returns the directory in which the configuration files are written as a File object.

Returns:
The configuration file location.

getDictionaries

public java.util.Enumeration getDictionaries()
Loads configuration data from the configuration location and returns it as Dictionary objects.

This method is a lazy implementation, which is just one configuration file ahead of the current enumeration location.

Specified by:
getDictionaries in interface PersistenceManager
Returns:
an enumeration of configuration data returned as instances of the Dictionary class.

delete

public void delete(java.lang.String pid)
Deletes the file for the given identifier.

Specified by:
delete in interface PersistenceManager
Parameters:
pid - The identifier of the configuration file to delete.

exists

public boolean exists(java.lang.String pid)
Returns true if a (configuration) file exists for the given identifier.

Specified by:
exists in interface PersistenceManager
Parameters:
pid - The identifier of the configuration file to check.
Returns:
true if the file exists

load

public java.util.Dictionary load(java.lang.String pid)
                          throws java.io.IOException
Reads the (configuration) for the given identifier into a Dictionary object.

Specified by:
load in interface PersistenceManager
Parameters:
pid - The identifier of the configuration file to delete.
Returns:
The configuration read from the file. This Dictionary may be empty if the file contains no configuration information or is not properly formatted.
Throws:
java.io.IOException - If an error occurrs loading the dictionary. An IOException must also be thrown if no dictionary exists for the given identifier.

store

public void store(java.lang.String pid,
                  java.util.Dictionary props)
           throws java.io.IOException
Stores the contents of the Dictionary in a file denoted by the given identifier.

Specified by:
store in interface PersistenceManager
Parameters:
pid - The identifier of the configuration file to which to write the configuration contents.
props - The configuration data to write.
Throws:
java.io.IOException - If an error occurrs writing the configuration data.