bug 4669 - javadoc for Freeze

3 files changed, 143 insertions, 3 deletions

diff --git a/java/src/Freeze/FatalErrorCallback.java b/java/src/Freeze/FatalErrorCallback.java
index 08c6ab6bba5..e610eb5ef7f 100644
--- a/java/src/Freeze/FatalErrorCallback.java
+++ b/java/src/Freeze/FatalErrorCallback.java
@@ -9,7 +9,17 @@
 
 package Freeze;
 
+/**
+ * Handles fatal errors encountered by the background save evictor.
+ */
 public interface FatalErrorCallback
 {
+    /**
+     * Called when the background save evictor encounters a fatal error.
+     *
+     * @param evictor The evictor that detected the error.
+     * @param communicator The communicator associated with the evictor.
+     * @param ex The exception that caused the error.
+     */
     void handleError(Evictor evictor, Ice.Communicator communicator, RuntimeException ex);
 }
diff --git a/java/src/Freeze/NavigableMap.java b/java/src/Freeze/NavigableMap.java
index 646dcc326fd..eab0ecca2a0 100644
--- a/java/src/Freeze/NavigableMap.java
+++ b/java/src/Freeze/NavigableMap.java
@@ -194,7 +194,7 @@ public interface NavigableMap<K, V> extends java.util.SortedMap<K, V>
     /**
      * Returns a view of the portion of this map whose keys range from <code>fromKey</code> to <code>toKey</code>.
      * If <code>fromKey</code> and <code>toKey</code> are equal, the returned map is empty unless
-     * <code>fromExclusive</code> and <code>toExclusive</code> are both <code>true</code>.
+     * <code>fromInclusive</code> and <code>toInclusive</code> are both <code>true</code>.
      *<p>
      * Insertions cannot be made via the returned map and must be made on the main map.
      * <p>
@@ -207,10 +207,10 @@ public interface NavigableMap<K, V> extends java.util.SortedMap<K, V>
      *
      * @param fromKey Low endpoint of the keys in the returned map.
      * @param fromInclusive <code>true</code> if the low endpoint is to be included in the returned view;
-     * <code>false, otherwise</code>.
+     * <code>false</code>, otherwise.
      * @param toKey High endpoint of the keys in the returned map.
      * @param toInclusive <code>true</code> if the high endpoint is to be included in the returned view;
-     * <code>false, otherwise</code>.
+     * <code>false</code>, otherwise.
      * @return A view of the portion of this map whose keys range from <code>fromKey</code> to <code>toKey</code>.
      **/
     NavigableMap<K, V> subMap(K fromKey, boolean fromInclusive, K toKey, boolean toInclusive);
diff --git a/java/src/Freeze/Util.java b/java/src/Freeze/Util.java
index e2af67a1ecf..62a21d4534e 100644
--- a/java/src/Freeze/Util.java
+++ b/java/src/Freeze/Util.java
@@ -11,6 +11,27 @@ package Freeze;
 
 public class Util
 {
+    /**
+     * Returns a new background save evictor. The Berkeley DB database with the
+     * name given in <code>filename</code> is opened if it already exists.
+     * If the database does not exist yet and <code>createDb</code>
+     * is true, the database is created automatically; otherwise,
+     * <code>DatabaseException</code> is raised.
+     *
+     * @param adapter The object adapter to associate with this evictor.
+     * @param envName The name of the Berkeley DB database environment. The
+     *   environment must already exist.
+     * @param filename The name of the Berkeley DB database file.
+     * @param initializer An object that is used to initialize a servant after its
+     *   state is restored from the database, or <code>null</code> if no initializer
+     *   is necessary.
+     * @param indices An array of Freeze indices, or <code>null</code if no indices
+     *   are defined.
+     * @param createDb True if the Berkeley DB database should be created if it does
+     *   not exist, false otherwise.
+     * @return A new background save evictor.
+     * @throws Freeze.DatabaseException If an error occurs during database operations.
+     */
     public static BackgroundSaveEvictor
     createBackgroundSaveEvictor(Ice.ObjectAdapter adapter, String envName, String filename,
                                 ServantInitializer initializer, Index[] indices, boolean createDb)
@@ -18,6 +39,28 @@ public class Util
         return new BackgroundSaveEvictorI(adapter, envName, filename, initializer, indices, createDb);
     }
 
+    /**
+     * Returns a new background save evictor. The Berkeley DB database with the
+     * name given in <code>filename</code> is opened if it already exists.
+     * If the database does not exist yet and <code>createDb</code>
+     * is true, the database is created automatically; otherwise,
+     * <code>DatabaseException</code> is raised.
+     *
+     * @param adapter The object adapter to associate with this evictor.
+     * @param envName The name of the Berkeley DB database environment. The
+     *   environment must already exist.
+     * @param dbEnv The database environment in which to open the database.
+     * @param filename The name of the Berkeley DB database file.
+     * @param initializer An object that is used to initialize a servant after its
+     *   state is restored from the database, or <code>null</code> if no initializer
+     *   is necessary.
+     * @param indices An array of Freeze indices, or <code>null</code if no indices
+     *   are defined.
+     * @param createDb True if the Berkeley DB database should be created if it does
+     *   not exist, false otherwise.
+     * @return A new background save evictor.
+     * @throws Freeze.DatabaseException If an error occurs during database operations.
+     */
     public static BackgroundSaveEvictor
     createBackgroundSaveEvictor(Ice.ObjectAdapter adapter, String envName, com.sleepycat.db.Environment dbEnv,
                                 String filename, ServantInitializer initializer, Index[] indices, boolean createDb)
@@ -25,6 +68,29 @@ public class Util
         return new BackgroundSaveEvictorI(adapter, envName, dbEnv, filename, initializer, indices, createDb);
     }
 
+    /**
+     * Returns a new transactional evictor. The Berkeley DB database with the
+     * name given in <code>filename</code> is opened if it already exists.
+     * If the database does not exist yet and <code>createDb</code>
+     * is true, the database is created automatically; otherwise,
+     * <code>DatabaseException</code> is raised.
+     *
+     * @param adapter The object adapter to associate with this evictor.
+     * @param envName The name of the Berkeley DB database environment. The
+     *   environment must already exist.
+     * @param filename The name of the Berkeley DB database file.
+     * @param facetTypes A map of facet name to Slice type id, or <code>null</code if
+     *   no map is necessary.
+     * @param initializer An object that is used to initialize a servant after its
+     *   state is restored from the database, or <code>null</code> if no initializer
+     *   is necessary.
+     * @param indices An array of Freeze indices, or <code>null</code if no indices
+     *   are defined.
+     * @param createDb True if the Berkeley DB database should be created if it does
+     *   not exist, false otherwise.
+     * @return A new transactional evictor.
+     * @throws Freeze.DatabaseException If an error occurs during database operations.
+     */
     public static TransactionalEvictor
     createTransactionalEvictor(Ice.ObjectAdapter adapter, String envName, String filename,
                                java.util.Map<String, String> facetTypes, ServantInitializer initializer,
@@ -33,6 +99,30 @@ public class Util
         return new TransactionalEvictorI(adapter, envName, filename, facetTypes, initializer, indices, createDb);
     }
 
+    /**
+     * Returns a new transactional evictor. The Berkeley DB database with the
+     * name given in <code>filename</code> is opened if it already exists.
+     * If the database does not exist yet and <code>createDb</code>
+     * is true, the database is created automatically; otherwise,
+     * <code>DatabaseException</code> is raised.
+     *
+     * @param adapter The object adapter to associate with this evictor.
+     * @param envName The name of the Berkeley DB database environment. The
+     *   environment must already exist.
+     * @param dbEnv The database environment in which to open the database.
+     * @param filename The name of the Berkeley DB database file.
+     * @param facetTypes A map of facet name to Slice type id, or <code>null</code if
+     *   no map is necessary.
+     * @param initializer An object that is used to initialize a servant after its
+     *   state is restored from the database, or <code>null</code> if no initializer
+     *   is necessary.
+     * @param indices An array of Freeze indices, or <code>null</code if no indices
+     *   are defined.
+     * @param createDb True if the Berkeley DB database should be created if it does
+     *   not exist, false otherwise.
+     * @return A new transactional evictor.
+     * @throws Freeze.DatabaseException If an error occurs during database operations.
+     */
     public static TransactionalEvictor
     createTransactionalEvictor(Ice.ObjectAdapter adapter, String envName, com.sleepycat.db.Environment dbEnv,
                                String filename, java.util.Map<String, String> facetTypes,
@@ -41,30 +131,65 @@ public class Util
         return new TransactionalEvictorI(adapter, envName, dbEnv, filename, facetTypes, initializer, indices, createDb);
     }
 
+    /**
+     * Creates a new Freeze connection using the given communicator and database
+     * environment.
+     *
+     * @param communicator The communicator associated with this connection.
+     * @param envName The name of the Berkeley DB database environment.
+     * @return A new Freeze connection.
+     * @throws Freeze.DatabaseException If an error occurs during database operations.
+     */
     public static Connection
     createConnection(Ice.Communicator communicator, String envName)
     {
         return new ConnectionI(communicator, envName, null);
     }
 
+    /**
+     * Creates a new Freeze connection using the given communicator and database
+     * environment.
+     *
+     * @param communicator The communicator associated with this connection.
+     * @param envName The name of the Berkeley DB database environment.
+     * @param dbEnv The database environment associated with this connection.
+     * @return A new Freeze connection.
+     * @throws Freeze.DatabaseException If an error occurs during database operations.
+     */
     public static Connection
     createConnection(Ice.Communicator communicator, String envName, com.sleepycat.db.Environment dbEnv)
     {
         return new ConnectionI(communicator, envName, dbEnv);
     }
 
+    /**
+     * Returns the database file name of the Freeze catalog.
+     *
+     * @return The database file name.
+     */
     public static String
     catalogName()
     {
         return _catalogName;
     }
 
+    /**
+     * Returns the database file name of the Freeze catalog index list.
+     *
+     * @return The database file name.
+     */
     public static String
     catalogIndexListName()
     {
         return _catalogIndexListName;
     }
 
+    /**
+     * Returns the Berkeley DB transaction object associated with a Freeze transaction.
+     *
+     * @param tx The Freeze transaction.
+     * @return The Berkeley DB transaction.
+     */
     public static com.sleepycat.db.Transaction
     getTxn(Transaction tx)
     {
@@ -78,6 +203,11 @@ public class Util
         }
     }
 
+    /**
+     * Registers a handler for fatal errors encountered by the background save evictor.
+     *
+     * @param cb The error callback.
+     */
     public static synchronized FatalErrorCallback
     registerFatalErrorCallback(FatalErrorCallback cb)
     {