svn commit: r988952 - /felix/trunk/configadmin/src/main/java/org/apache/felix/cm/PersistenceManager.java

[fm...@apache.org]

Author: fmeschbe
Date: Wed Aug 25 09:54:00 2010
New Revision: 988952

URL: http://svn.apache.org/viewvc?rev=988952&view=rev
Log:
FELIX-1907 added clarification statements regarding the use of the dictionaries and stability of the Enumeration

Modified:
    felix/trunk/configadmin/src/main/java/org/apache/felix/cm/PersistenceManager.java

Modified: felix/trunk/configadmin/src/main/java/org/apache/felix/cm/PersistenceManager.java
URL: http://svn.apache.org/viewvc/felix/trunk/configadmin/src/main/java/org/apache/felix/cm/PersistenceManager.java?rev=988952&r1=988951&r2=988952&view=diff
==============================================================================
--- felix/trunk/configadmin/src/main/java/org/apache/felix/cm/PersistenceManager.java (original)
+++ felix/trunk/configadmin/src/main/java/org/apache/felix/cm/PersistenceManager.java Wed Aug 25 09:54:00 2010
@@ -1,4 +1,4 @@
-/* 
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -53,8 +53,8 @@ public interface PersistenceManager
 
     /**
      * Returns <code>true</code> if a persisted <code>Dictionary</code> exists
-     * for the given <code>pid</code>. 
-     * 
+     * for the given <code>pid</code>.
+     *
      * @param pid The identifier for the dictionary to test.
      */
     boolean exists( String pid );
@@ -62,29 +62,43 @@ public interface PersistenceManager
 
     /**
      * Returns the <code>Dictionary</code> for the given <code>pid</code>.
-     * 
+     * <p>
+     * Implementations are expected to return dictionary instances which may be
+     * modified by the caller without affecting any underlying data or affecting
+     * future calls to this method with the same PID. In other words the
+     * reference equation <code>load(pid) != load(pid)</code> must hold
+     * <code>true</code>.
+     *
      * @param pid The identifier for the dictionary to load.
-     * 
+     *
      * @return The dictionary for the identifier. This must not be
      *      <code>null</code> but may be empty.
-     *      
+     *
      * @throws IOException If an error occurrs loading the dictionary. An
      *      <code>IOException</code> must also be thrown if no dictionary
-     *      exists for the given identifier. 
+     *      exists for the given identifier.
      */
     Dictionary load( String pid ) throws IOException;
 
 
     /**
-     * Returns an enumeration of all <code>Dictionary</code> objects known to 
+     * Returns an enumeration of all <code>Dictionary</code> objects known to
      * this persistence manager.
      * <p>
      * Implementations of this method are allowed to return lazy enumerations.
      * That is, it is allowable for the enumeration to not return a dictionary
      * if loading it results in an error.
-     * 
+     * <p>
+     * Implementations are expected to return dictionary instances which may be
+     * modified by the caller without affecting any underlying data or affecting
+     * future calls to this method.
+     * <p>
+     * The <code>Enumeration</code> returned from this method must be stable
+     * against concurrent calls to either of the {@link #load(String)},
+     * {@link #store(String, Dictionary)}, and {@link #delete(String)} methods.
+     *
      * @return A possibly empty Enumeration of all dictionaries.
-     * 
+     *
      * @throws IOException If an error occurrs getting the dictionaries.
      */
     Enumeration getDictionaries() throws IOException;
@@ -92,10 +106,15 @@ public interface PersistenceManager
 
     /**
      * Stores the <code>Dictionary</code> under the given <code>pid</code>.
-     * 
+     * <p>
+     * The dictionary provided to this method must be considered private to the
+     * caller. Any modification by the caller after this method finishes must
+     * not influence any internal storage of the provided data. Implementations
+     * must not modify the dictionary.
+     *
      * @param pid The identifier of the dictionary.
      * @param properties The <code>Dictionary</code> to store.
-     * 
+     *
      * @throws IOException If an error occurrs storing the dictionary. If this
      *      exception is thrown, it is expected, that
      *      {@link #exists(String) exists(pid} returns <code>false</code>.
@@ -106,9 +125,9 @@ public interface PersistenceManager
     /**
      * Removes the <code>Dictionary</code> for the given <code>pid</code>. If
      * such a dictionary does not exist, this method has no effect.
-     * 
+     *
      * @param pid The identifier of the dictionary to delet.
-     * 
+     *
      * @throws IOException If an error occurrs deleting the dictionary. This
      *      exception must not be thrown if no dictionary with the given
      *      identifier exists.