Return-Path: X-Original-To: apmail-felix-commits-archive@www.apache.org Delivered-To: apmail-felix-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 9DC4B10A51 for ; Mon, 1 Jul 2013 12:57:49 +0000 (UTC) Received: (qmail 16186 invoked by uid 500); 1 Jul 2013 12:57:49 -0000 Delivered-To: apmail-felix-commits-archive@felix.apache.org Received: (qmail 16117 invoked by uid 500); 1 Jul 2013 12:57:49 -0000 Mailing-List: contact commits-help@felix.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@felix.apache.org Delivered-To: mailing list commits@felix.apache.org Received: (qmail 15840 invoked by uid 99); 1 Jul 2013 12:57:48 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 01 Jul 2013 12:57:48 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 01 Jul 2013 12:57:41 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id 2981A2388C63; Mon, 1 Jul 2013 12:56:27 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1498419 [27/35] - in /felix/site/trunk/content/apidocs: ./ configadmin/ configadmin/1.0.0/ configadmin/1.0.0/org/ configadmin/1.0.0/org/apache/ configadmin/1.0.0/org/apache/felix/ configadmin/1.0.0/org/apache/felix/cm/ configadmin/1.0.0/or... Date: Mon, 01 Jul 2013 12:56:13 -0000 To: commits@felix.apache.org From: fmeschbe@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20130701125627.2981A2388C63@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Added: felix/site/trunk/content/apidocs/configadmin/1.2.8/org/apache/felix/cm/file/ConfigurationHandler.html URL: http://svn.apache.org/viewvc/felix/site/trunk/content/apidocs/configadmin/1.2.8/org/apache/felix/cm/file/ConfigurationHandler.html?rev=1498419&view=auto ============================================================================== --- felix/site/trunk/content/apidocs/configadmin/1.2.8/org/apache/felix/cm/file/ConfigurationHandler.html (added) +++ felix/site/trunk/content/apidocs/configadmin/1.2.8/org/apache/felix/cm/file/ConfigurationHandler.html Mon Jul 1 12:56:06 2013 @@ -0,0 +1,726 @@ + + + + + + +ConfigurationHandler (Apache Felix Configuration Admin Service 1.2.8 API) + + + + + + + +
+ + + + + +
+
+ + + +
+ +
+
+
    +
  • Summary: 
    • +
  • Nested | 
    • +
  • Field | 
    • +
  • Constr | 
    • +
  • Method
    • +
+ +
+ + +
+ + +
+
org.apache.felix.cm.file
+

Class ConfigurationHandler

+
+
+ +
+
    +
  • +
    +
    +
    public class ConfigurationHandler
+extends Object
    +
    The ConfigurationHandler class implements configuration reading + form a java.io.InputStream and writing to a + java.io.OutputStream on behalf of the + FilePersistenceManager class. + + 
    + cfg = prop "=" value .
+  prop = symbolic-name . // 1.4.2 of OSGi Core Specification
+  symbolic-name = token { "." token } .
+  token = { [ 0..9 ] | [ a..z ] | [ A..Z ] | '_' | '-' } .
+  value = [ type ] ( "[" values "]" | "(" values ")" | simple ) .
+  values = simple { "," simple } .
+  simple = """ stringsimple """ .
+  type = // 1-char type code .
+  stringsimple = // quoted string representation of the value .
+
    +
    • +
+
+
+ +
+
+
    +
  • + + + +
      +
    • + + +

      Method Detail

      + + + +
        +
      • +

        write

        +
        public static void write(OutputStream out,
+         Dictionary properties)
+                  throws IOException
        +
        Writes the configuration data from the Dictionary to the + given OutputStream. +

        + This method writes at the current location in the stream and does not + close the outputstream.

        +
        Parameters:
        out - The OutputStream to write the configurtion data + to.
        properties - The Dictionary to write.
        +
        Throws:
        +
        IOException - If an error occurrs writing to the output stream.
        +
        • +
      + + + +
        +
      • +

        read

        +
        public static Dictionary read(InputStream ins)
+                       throws IOException
        +
        Reads configuration data from the given InputStream and + returns a new Dictionary object containing the data. +

        + This method reads from the current location in the stream upto the end of + the stream but does not close the stream at the end.

        +
        Parameters:
        ins - The InputStream from which to read the + configuration data.
        +
        Returns:
        A Dictionary object containing the configuration + data. This object may be empty if the stream contains no + configuration data.
        +
        Throws:
        +
        IOException - If an error occurrs reading from the stream. This exception + is also thrown if a syntax error is encountered.
        +
        • +
      +
      • +
    +
    • +
+
+
+ + +
+ + + + + +
+
+ + + +
+ +
+
+
    +
  • Summary: 
    • +
  • Nested | 
    • +
  • Field | 
    • +
  • Constr | 
    • +
  • Method
    • +
+ +
+ + +
+ +

Copyright © 2006–2013 The Apache Software Foundation. All rights reserved.

+ + Added: felix/site/trunk/content/apidocs/configadmin/1.2.8/org/apache/felix/cm/file/FilePersistenceManager.html URL: http://svn.apache.org/viewvc/felix/site/trunk/content/apidocs/configadmin/1.2.8/org/apache/felix/cm/file/FilePersistenceManager.html?rev=1498419&view=auto ============================================================================== --- felix/site/trunk/content/apidocs/configadmin/1.2.8/org/apache/felix/cm/file/FilePersistenceManager.html (added) +++ felix/site/trunk/content/apidocs/configadmin/1.2.8/org/apache/felix/cm/file/FilePersistenceManager.html Mon Jul 1 12:56:06 2013 @@ -0,0 +1,576 @@ + + + + + + +FilePersistenceManager (Apache Felix Configuration Admin Service 1.2.8 API) + + + + + + + +
+ + + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
org.apache.felix.cm.file
+

Class FilePersistenceManager

+
+
+ +
+
    +
  • +
    +
    All Implemented Interfaces:
    +
    PersistenceManager
    +
    +
    +
    +
    public class FilePersistenceManager
+extends 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 + org.apache.felix.cm.impl.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: +

      +
    • The store(String, Dictionary) method writes a temporary file + with file extension .tmp. When done, the file is renamed to + actual configuration file name as implied by the PID. This last step of + renaming the file is synchronized on the FilePersistenceManager instance.
      • +
    • The #load(File) method is completeley synchronized on the + FilePersistenceManager instance such that the store(java.lang.String, java.util.Dictionary) method might + inadvertantly try to replace the file while it is being read.
      • +
    • Finally the Iterator returned by getDictionaries() + is implemented such that any temporary configuration file is just ignored.
      • +
    +
    • +
+
+
+
    +
  • + +
      +
    • + + +

      Field Summary

      + + + + + + + + + + +
      Fields 
      Modifier and TypeField and Description
      static StringDEFAULT_CONFIG_DIR +
      The default configuration data directory if no location is configured + (value is "config").
      +
      +
      • +
    + +
      +
    • + + +

      Constructor Summary

      + + + + + + + + + + + +
      Constructors 
      Constructor and Description
      FilePersistenceManager(org.osgi.framework.BundleContext bundleContext, + String location) +
      Creates an instance of this persistence manager using the given location + as the directory to store and retrieve the configuration files.
      +
      FilePersistenceManager(String location) +
      Creates an instance of this persistence manager using the given location + as the directory to store and retrieve the configuration files.
      +
      +
      • +
    + + +
    • +
+
+
+
    +
  • + +
      +
    • + + +

      Field Detail

      + + + +
        +
      • +

        DEFAULT_CONFIG_DIR

        +
        public static final 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(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: +

          +
        • If location is null, the config + directory in the current working directory as specified in the + user.dir system property is assumed.
          • +
        • Otherwise the named directory is used.
          • +
        • If the directory name resolved in the first or second step is not an + absolute path, it is resolved to an absolute path calling the + File.getAbsoluteFile() method.
          • +
        • If a non-directory file exists as the location found in the previous + step or the named directory (including any parent directories) cannot be + created, an IllegalArgumentException is thrown.
          • +
        +

        + 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:
        +
        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,
+                      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: +

          +
        • If location is null, the config + directory in the persistent storage area of the bundle identified by + bundleContext is used.
          • +
        • If the framework does not support persistent storage area for bundles + in the filesystem or if bundleContext is null, + the config directory in the current working directory as + specified in the user.dir system property is assumed.
          • +
        • Otherwise the named directory is used.
          • +
        • If the directory name resolved in the first, second or third step is + not an absolute path and a bundleContext is provided which + provides access to persistent storage area, the directory name is + resolved as being inside the persistent storage area. Otherwise the + directory name is resolved to an absolute path calling the + File.getAbsoluteFile() method.
          • +
        • If a non-directory file exists as the location found in the previous + step or the named directory (including any parent directories) cannot be + created, an IllegalArgumentException is thrown.
          • +
        +
        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:
        +
        IllegalArgumentException - If the location exists but is not a + directory or does not exist and cannot be created.
        +
        IllegalStateException - If the bundleContext is not + valid.
        +
        • +
      +
      • +
    + +
      +
    • + + +

      Method Detail

      + + + +
        +
      • +

        getLocation

        +
        public File getLocation()
        +
        Returns the directory in which the configuration files are written as + a File object.
        +
        Returns:
        The configuration file location.
        +
        • +
      + + + +
        +
      • +

        getDictionaries

        +
        public 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(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(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 Dictionary load(String pid)
+                throws 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:
        +
        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(String pid,
+         Dictionary props)
+           throws 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:
        +
        IOException - If an error occurrs writing the configuration data.
        +
        • +
      +
      • +
    +
    • +
+
+
+ + +
+ + + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ +

Copyright © 2006–2013 The Apache Software Foundation. All rights reserved.

+ + Added: felix/site/trunk/content/apidocs/configadmin/1.2.8/org/apache/felix/cm/file/class-use/ConfigurationHandler.html URL: http://svn.apache.org/viewvc/felix/site/trunk/content/apidocs/configadmin/1.2.8/org/apache/felix/cm/file/class-use/ConfigurationHandler.html?rev=1498419&view=auto ============================================================================== --- felix/site/trunk/content/apidocs/configadmin/1.2.8/org/apache/felix/cm/file/class-use/ConfigurationHandler.html (added) +++ felix/site/trunk/content/apidocs/configadmin/1.2.8/org/apache/felix/cm/file/class-use/ConfigurationHandler.html Mon Jul 1 12:56:06 2013 @@ -0,0 +1,117 @@ + + + + + + +Uses of Class org.apache.felix.cm.file.ConfigurationHandler (Apache Felix Configuration Admin Service 1.2.8 API) + + + + + + + +
+ + + + + +
+
+
    +
  • Prev
    • +
  • Next
    • +
+ + +
+ +
+ + +
+ +
+

Uses of Class
org.apache.felix.cm.file.ConfigurationHandler

+
+
No usage of org.apache.felix.cm.file.ConfigurationHandler
+ +
+ + + + + +
+
+
    +
  • Prev
    • +
  • Next
    • +
+ + +
+ +
+ + +
+ +

Copyright © 2006–2013 The Apache Software Foundation. All rights reserved.

+ + Added: felix/site/trunk/content/apidocs/configadmin/1.2.8/org/apache/felix/cm/file/class-use/FilePersistenceManager.html URL: http://svn.apache.org/viewvc/felix/site/trunk/content/apidocs/configadmin/1.2.8/org/apache/felix/cm/file/class-use/FilePersistenceManager.html?rev=1498419&view=auto ============================================================================== --- felix/site/trunk/content/apidocs/configadmin/1.2.8/org/apache/felix/cm/file/class-use/FilePersistenceManager.html (added) +++ felix/site/trunk/content/apidocs/configadmin/1.2.8/org/apache/felix/cm/file/class-use/FilePersistenceManager.html Mon Jul 1 12:56:06 2013 @@ -0,0 +1,117 @@ + + + + + + +Uses of Class org.apache.felix.cm.file.FilePersistenceManager (Apache Felix Configuration Admin Service 1.2.8 API) + + + + + + + +
+ + + + + +
+
+
    +
  • Prev
    • +
  • Next
    • +
+ + +
+ +
+ + +
+ +
+

Uses of Class
org.apache.felix.cm.file.FilePersistenceManager

+
+
No usage of org.apache.felix.cm.file.FilePersistenceManager
+ +
+ + + + + +
+
+
    +
  • Prev
    • +
  • Next
    • +
+ + +
+ +
+ + +
+ +

Copyright © 2006–2013 The Apache Software Foundation. All rights reserved.

+ + Added: felix/site/trunk/content/apidocs/configadmin/1.2.8/org/apache/felix/cm/file/package-frame.html URL: http://svn.apache.org/viewvc/felix/site/trunk/content/apidocs/configadmin/1.2.8/org/apache/felix/cm/file/package-frame.html?rev=1498419&view=auto ============================================================================== --- felix/site/trunk/content/apidocs/configadmin/1.2.8/org/apache/felix/cm/file/package-frame.html (added) +++ felix/site/trunk/content/apidocs/configadmin/1.2.8/org/apache/felix/cm/file/package-frame.html Mon Jul 1 12:56:06 2013 @@ -0,0 +1,21 @@ + + + + + + +org.apache.felix.cm.file (Apache Felix Configuration Admin Service 1.2.8 API) + + + + +

org.apache.felix.cm.file

+
+

Classes

+ +
+ + Added: felix/site/trunk/content/apidocs/configadmin/1.2.8/org/apache/felix/cm/file/package-summary.html URL: http://svn.apache.org/viewvc/felix/site/trunk/content/apidocs/configadmin/1.2.8/org/apache/felix/cm/file/package-summary.html?rev=1498419&view=auto ============================================================================== --- felix/site/trunk/content/apidocs/configadmin/1.2.8/org/apache/felix/cm/file/package-summary.html (added) +++ felix/site/trunk/content/apidocs/configadmin/1.2.8/org/apache/felix/cm/file/package-summary.html Mon Jul 1 12:56:06 2013 @@ -0,0 +1,147 @@ + + + + + + +org.apache.felix.cm.file (Apache Felix Configuration Admin Service 1.2.8 API) + + + + + + + +
+ + + + + +
+
+ + + +
+ +
+ + +
+ +
+

Package org.apache.felix.cm.file

+
+
+
    +
  • + + + + + + + + + + + + + + + + +
    Class Summary 
    ClassDescription
    ConfigurationHandler +
    The ConfigurationHandler class implements configuration reading + form a java.io.InputStream and writing to a + java.io.OutputStream on behalf of the + FilePersistenceManager class.
    +
    FilePersistenceManager +
    The FilePersistenceManager class stores configuration data in + properties-like files inside a given directory.
    +
    +
    • +
+
+ +
+ + + + + +
+
+ + + +
+ +
+ + +
+ +

Copyright © 2006–2013 The Apache Software Foundation. All rights reserved.

+ +