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();
}
|