FELIX-1907 added clarification statements regarding the use of the dictionaries and stability of the Enumeration
git-svn-id: https://svn.apache.org/repos/asf/felix/trunk@988952 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/configadmin/src/main/java/org/apache/felix/cm/PersistenceManager.java b/configadmin/src/main/java/org/apache/felix/cm/PersistenceManager.java
index 8073eb4..7069211 100644
--- a/configadmin/src/main/java/org/apache/felix/cm/PersistenceManager.java
+++ b/configadmin/src/main/java/org/apache/felix/cm/PersistenceManager.java
@@ -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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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.