openjpa-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mik...@apache.org
Subject svn commit: r798189 - in /openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/writebehind: WriteBehindCache.java WriteBehindCacheKey.java WriteBehindCacheManager.java WriteBehindCallback.java
Date Mon, 27 Jul 2009 15:24:48 GMT
Author: mikedd
Date: Mon Jul 27 15:24:45 2009
New Revision: 798189

URL: http://svn.apache.org/viewvc?rev=798189&view=rev
Log:
OPENJPA-1150:
Adding javadoc for WriteBehind interfaces.
	modified:   openjpa-kernel/src/main/java/org/apache/openjpa/writebehind/WriteBehindCache.java
	modified:   openjpa-kernel/src/main/java/org/apache/openjpa/writebehind/WriteBehindCacheKey.java
	modified:   openjpa-kernel/src/main/java/org/apache/openjpa/writebehind/WriteBehindCacheManager.java
	modified:   openjpa-kernel/src/main/java/org/apache/openjpa/writebehind/WriteBehindCallback.java

Modified:
    openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/writebehind/WriteBehindCache.java
    openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/writebehind/WriteBehindCacheKey.java
    openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/writebehind/WriteBehindCacheManager.java
    openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/writebehind/WriteBehindCallback.java

Modified: openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/writebehind/WriteBehindCache.java
URL: http://svn.apache.org/viewvc/openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/writebehind/WriteBehindCache.java?rev=798189&r1=798188&r2=798189&view=diff
==============================================================================
--- openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/writebehind/WriteBehindCache.java
(original)
+++ openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/writebehind/WriteBehindCache.java
Mon Jul 27 15:24:45 2009
@@ -23,13 +23,32 @@
 
 import org.apache.openjpa.kernel.StateManagerImpl;
 
+/**
+ * The WriteBehindCache stores updates to entities before flushing to the
+ * database. A {@link WriteBehindCallback} instance will be used to write the
+ * changes to the database.
+ * 
+ */
 public interface WriteBehindCache {
+    /**
+     * Obtain the number of entities in the cache.
+     * 
+     * @return number of entities in the cache.
+     */
     public int getSize();
+
+    /**
+     * Answer whether the provided object is included in the WriteBehindCache
+     * 
+     * @param o
+     *            Object which may be in the cache
+     * @return True if the object is in the cache, otherwise false.
+     */
     public boolean contains(Object o);
-    
+
     /**
-     * Returns a string name that can be used by end-user-visible
-     * code to identify this cache.
+     * Returns a string name that can be used by end-user-visible code to
+     * identify this cache.
      */
     public String getName();
 
@@ -38,17 +57,52 @@
      */
     public void setName(String name);
 
+    /**
+     * Add the provided {@link StateManagerImpl}s to the cache. Mimics the
+     * StoreManager.flush() method. If the StateManagers cannot be added to the
+     * cache or if any exceptions occur they will be returned to the caller in a
+     * collection.
+     * 
+     * @param sms
+     *            StateManagerImpls to add.
+     * @return A collection of exceptions if any occurred when adding the
+     *         StateManager to the cache. If no exceptions occur the collection
+     *         will be empty.
+     */
     public List<Exception> add(Collection<StateManagerImpl> sms);
-    
+
+    /**
+     * Obtain the StateManagers currently in the cache.
+     * 
+     * @return collection of state managers.
+     */
     public Collection<StateManagerImpl> getStateManagers();
-    
+
     /**
      * Initialize any resources associated with the given
      * {@link WriteBehindCacheManager}.
+     * 
      */
     public void initialize(WriteBehindCacheManager manager);
-    
+
+    /**
+     * Obtain a cache key for the provided {@link StateManagerImpl}.
+     * 
+     * @param sm
+     *            A StateManager
+     * @return A key that may be used to cache the StateManager.
+     */
     public WriteBehindCacheKey getKey(StateManagerImpl sm);
+
+    /**
+     * Determine whether the cache is empty.
+     * 
+     * @return true if there are no entities in the cache, otherwise false.
+     */
     public boolean isEmpty();
-    public void clear(); 
+
+    /**
+     * Remove all entities from the cache.
+     */
+    public void clear();
 }

Modified: openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/writebehind/WriteBehindCacheKey.java
URL: http://svn.apache.org/viewvc/openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/writebehind/WriteBehindCacheKey.java?rev=798189&r1=798188&r2=798189&view=diff
==============================================================================
--- openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/writebehind/WriteBehindCacheKey.java
(original)
+++ openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/writebehind/WriteBehindCacheKey.java
Mon Jul 27 15:24:45 2009
@@ -18,8 +18,23 @@
  */
 package org.apache.openjpa.writebehind;
 
+/**
+ * Key used for entities in the WriteBehind Cache.
+ */
 public interface WriteBehindCacheKey {
+    /**
+     * Answers an integer hash for this key.
+     * 
+     * @return integer hashcode
+     */
     public int hashCode();
 
+    /**
+     * Return true if the supplied object is equal to this instance.
+     * 
+     * @param obj
+     *            object to compare
+     * @return True if they are equal, otherwise false.
+     */
     public boolean equals(Object obj);
 }

Modified: openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/writebehind/WriteBehindCacheManager.java
URL: http://svn.apache.org/viewvc/openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/writebehind/WriteBehindCacheManager.java?rev=798189&r1=798188&r2=798189&view=diff
==============================================================================
--- openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/writebehind/WriteBehindCacheManager.java
(original)
+++ openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/writebehind/WriteBehindCacheManager.java
Mon Jul 27 15:24:45 2009
@@ -21,11 +21,38 @@
 import org.apache.openjpa.conf.OpenJPAConfiguration;
 import org.apache.openjpa.lib.conf.ObjectValue;
 
+/**
+ * Manages the system's WriteBehind cache(s). You can retrieve the data cache
+ * manager from the {@link OpenJPAConfiguration}.
+ * 
+ */
 public interface WriteBehindCacheManager {
+    /**
+     * Get the default WriteBehind cache.
+     * 
+     * @return If WriteBehind mode is enabled the default WriteBehind cache will
+     *         be returned. If WriteBehind is not enabled return null.
+     */
     public WriteBehindCache getSystemWriteBehindCache();
 
+    /**
+     * Obtain a named WriteBehindCache.
+     * 
+     * @param name
+     *            Name of the WriteBehindCache to obtain
+     * @return If WriteBehind mode is enabled a WriteBehindCache for 'name' will
+     *         be returned (creating a new instance if needed). Otherwise return
+     *         null.
+     */
     public WriteBehindCache getWriteBehindCache(String name);
 
-    public void initialize(OpenJPAConfiguration conf,
-        ObjectValue writeBehindCache);
+    /**
+     * Initialize the WriteBehindCacheManager
+     * 
+     * @param conf
+     *            OpenJPAConfiguration in use
+     * @param writeBehindCache
+     *            The pluginvalue for WritBehindCache.
+     */
+    public void initialize(OpenJPAConfiguration conf, ObjectValue writeBehindCache);
 }

Modified: openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/writebehind/WriteBehindCallback.java
URL: http://svn.apache.org/viewvc/openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/writebehind/WriteBehindCallback.java?rev=798189&r1=798188&r2=798189&view=diff
==============================================================================
--- openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/writebehind/WriteBehindCallback.java
(original)
+++ openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/writebehind/WriteBehindCallback.java
Mon Jul 27 15:24:45 2009
@@ -22,12 +22,36 @@
 
 import org.apache.openjpa.kernel.Broker;
 
+/**
+ * The WriteBehindCallback is responsible for flushing changes to the database
+ * when OpenJPA is used in a Write-Behind mode.
+ * 
+ */
 public interface WriteBehindCallback extends Runnable {
 
-    public void initialize(Broker broker,
-        WriteBehindCache cache);
+    /**
+     * Initialize the WriteBehindCallback. The callback will pull changes from
+     * the provided WriteBehindCache flush them using the provided broker. The
+     * WriteBehindCallback is responsible for closing the Broker.
+     * 
+     * @param broker
+     *            A new broker instance that the writebehind callback will use
+     *            to flush changes to the database.
+     * @param cache
+     *            A {@link WriteBehindCache} which contains the inflight
+     *            changes.
+     */
+    public void initialize(Broker broker, WriteBehindCache cache);
 
+    /**
+     * Manually flush changes to the database.
+     * 
+     * @return A Collection of Exceptions which occurred during the flush.
+     */
     public Collection<Exception> flush();
 
+    /**
+     * Close the WriteBehindCallback releasing resources to the JVM
+     */
     public void close();
 }



Mime
View raw message