[prev in list] [next in list] [prev in thread] [next in thread]
List: jboss-cvs-commits
Subject: [jboss-cvs] jboss-cache/src/main/org/jboss/cache Cache.java
From: Bela Ban <belaban () users ! sourceforge ! net>
Date: 2002-12-31 19:13:43
[Download RAW message or body]
User: belaban
Date: 02/12/31 11:13:43
Modified: src/main/org/jboss/cache Cache.java
Log:
Added javadoc
Revision Changes Path
1.4 +190 -10 jboss-cache/src/main/org/jboss/cache/Cache.java
Index: Cache.java
===================================================================
RCS file: /cvsroot/jboss/jboss-cache/src/main/org/jboss/cache/Cache.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- Cache.java 31 Dec 2002 18:22:34 -0000 1.3
+++ Cache.java 31 Dec 2002 19:13:42 -0000 1.4
@@ -1,4 +1,4 @@
-// $Id: Cache.java,v 1.3 2002/12/31 18:22:34 belaban Exp $
+// $Id: Cache.java,v 1.4 2002/12/31 19:13:42 belaban Exp $
/*
* JBoss, the OpenSource J2EE webOS
@@ -53,14 +53,16 @@
* replicate the entry. Also, when the default replication mode is asynchronous,
* the above method can be called to be synchronously executed.
* <br/>
- *
+ * Note that when an entry is to be replicated, its key and value (unless null)
+ * have to be serializable. If this is not the case, the entry will be marked as
+ * transient (with an error message in the log). This applies to all methods.
*
* @author <a href="mailto:bela@jboss.org">Bela Ban</a>.
- * @version $Revision: 1.3 $
+ * @version $Revision: 1.4 $
*
* <p><b>Revisions:</b>
*
- * <p><b>Dec 27 2002 Bela Ban:</b>
+ * <p>Dec 27 2002 Bela Ban:
* <ul>
* <li> First implementation </li>
* </ul>
@@ -142,43 +144,221 @@
boolean commit) throws LockingException, TimeoutException;
-
+ /**
+ * Adds all values from a map to this map. Existing entries will be
+ * overwritten. Updates will be handled according to the default policy.
+ * @param m The map
+ * @see java.util.Map#putAll(Map)
+ */
void putAll(Map m);
+
+ /**
+ * Adds all values from a map to this map. Existing entries will be
+ * overwritten. Updates will be handled according to the default policy.
+ * @param m The map
+ * @param transient_entries If true the entries will not be replicated,
+ * regardless of the default policy.
+ */
void putAll(Map m, boolean transient_entries);
+
+
+ /**
+ * Replicates the update to all members. Depending on the value of the
+ * parameters the update will be synchronous or asynchronous.
+ * @param m The map
+ * @param synchronous If true the update will be synchronous, ie. the caller
+ * will block until all responses have been received. If
+ * <code>timeout</code> is 0, we will block indefinitely (until all
+ * responses have been received), otherwise the call is guaranteed to return
+ * after at most <code>timeout</code> milliseconds. If false, the call will
+ * be asynchronous.
+ * @param timeout The number of milliseconds to wait for a synchronous call.
+ * 0 means to wait forever. This parameter is not used if
+ * <code>synchronous</code> is false.
+ */
void putAll(Map m, boolean synchronous, long timeout);
+
+
+ /**
+ * Replicates the update to all members, and use locks at each member to \
ensure transactional serializability. + * When a lock in a member cannot be \
acquired, a LockingException will be thrown. Typically the caller will + * then \
abort the transaction (releasing all locks) and retry.<p> + * This call can be \
one of many inside the same transaction, or it may be the only one. In the first \
case, the + * caller is responsible to call commit() or rollback() once the \
transaction is done. In the latter case, the + * transaction can be committed by \
setting <code>commit</code> to true.<br> + * A transaction (Xid) is always \
associated with the current thread. If this call is invoked, and there is no + * \
transaction associated with the current thread, a default transaction will be \
created. Otherwise the current + * transaction will be used.
+ * @param m The map.
+ * @param sync_timeout Max number of milliseconds to wait for all responses. \
Note that this needs to be higher + * than \
<code>lock_acquisition_timeout</code>. 0 means to wait forever for all responses. + \
* @param lock_acquisition_timeout Number of milliseonds to wait until a lock becomes \
available. Needs to be lower + * than \
<code>sync_timeout</code>. 0 means to wait forever. <em>0 will block + * \
forever in case of deadlocks. Once we have deadlock detection in place, + * \
this parameter may be deprecated.</em> + * @param lock_lease_timeout \
Number of milliseonds until a lock is released automatically (if not released + \
* before). Not currently used. + * @param commit \
If true the transaction will be committed after this call if the call was successful. \
+ * @exception LockingException Throw when one or more of the members failed \
acquiring the lock within + * \
<code>lock_acquisition_timeout</code> milliseconds + * @exception \
TimeoutException Thrown when one or more of the members didn't send a response. \
LockingExceptions + * take precedence over \
TimeoutExceptions, e.g. if we have both locking and timeout + * \
exceptions, a LockingException will be thrown. + */
void putAll(Map m, long sync_timeout,
long lock_acquisition_timeout, long lock_lease_timeout,
boolean commit) throws LockingException, TimeoutException;
-
+ /**
+ * Removes an entry from the cache according to the default policy. If the key \
cannot be found, this + * is a null operation.
+ * @param key The key to the entry to be removed.
+ * @return Object The previous value associated with the given key, or null if \
none was associated + */
Object remove(Object key);
- Object remove(Object key, boolean transient_entry);
+
+ /**
+ * Removes the entry with the given key and replicates the update to all \
members. + * Depending on the value of the parameters the update will be \
synchronous or asynchronous. + * @param key The key to the entry to be removed.
+ * @param synchronous If true the update will be synchronous, ie. the caller
+ * will block until all responses have been received. If
+ * <code>timeout</code> is 0, we will block indefinitely (until all
+ * responses have been received), otherwise the call is guaranteed to return
+ * after at most <code>timeout</code> milliseconds. If false, the call will
+ * be asynchronous.
+ * @param timeout The number of milliseconds to wait for a synchronous call.
+ * 0 means to wait forever. This parameter is not used if
+ * <code>synchronous</code> is false.
+ */
Object remove(Object key, boolean synchronous, long timeout);
+
+
+
+ /**
+ * Removes the entry at the given key and replicates the update to all \
members, + * and use locks at each member to ensure transactional \
serializability. + * When a lock in a member cannot be acquired, a \
LockingException will be thrown. Typically the caller will + * then abort the \
transaction (releasing all locks) and retry.<p> + * This call can be one of many \
inside the same transaction, or it may be the only one. In the first case, the + \
* caller is responsible to call commit() or rollback() once the transaction is done. \
In the latter case, the + * transaction can be committed by setting \
<code>commit</code> to true.<br> + * A transaction (Xid) is always associated \
with the current thread. If this call is invoked, and there is no + * \
transaction associated with the current thread, a default transaction will be \
created. Otherwise the current + * transaction will be used.
+ * @param key The key to the entry to be removed.
+ * @param sync_timeout Max number of milliseconds to wait for all responses. \
Note that this needs to be higher + * than \
<code>lock_acquisition_timeout</code>. 0 means to wait forever for all responses. + \
* @param lock_acquisition_timeout Number of milliseonds to wait until a lock becomes \
available. Needs to be lower + * than \
<code>sync_timeout</code>. 0 means to wait forever. <em>0 will block + * \
forever in case of deadlocks. Once we have deadlock detection in place, + * \
this parameter may be deprecated.</em> + * @param lock_lease_timeout \
Number of milliseonds until a lock is released automatically (if not released + \
* before). Not currently used. + * @param commit \
If true the transaction will be committed after this call if the call was successful. \
+ * @return Object The previous value associated with the given key, or null if \
none was associated + * @exception LockingException Throw when one or more of \
the members failed acquiring the lock within + * \
<code>lock_acquisition_timeout</code> milliseconds + * @exception \
TimeoutException Thrown when one or more of the members didn't send a response. \
LockingExceptions + * take precedence over \
TimeoutExceptions, e.g. if we have both locking and timeout + * \
exceptions, a LockingException will be thrown. + */
Object remove(Object key, long sync_timeout,
long lock_acquisition_timeout, long lock_lease_timeout,
boolean commit) throws LockingException, TimeoutException;
-
+
+ /**
+ * Removes all entries from the map. Replication takes place acording to the \
default policy. + */
void clear();
+
+
+ /**
+ * Remove all entries from the map and replicates the update to all members.
+ * Depending on the value of the parameters the update will be synchronous or \
asynchronous. + * @param key The key to the entry to be removed.
+ * @param synchronous If true the update will be synchronous, ie. the caller
+ * will block until all responses have been received. If
+ * <code>timeout</code> is 0, we will block indefinitely (until all
+ * responses have been received), otherwise the call is guaranteed to return
+ * after at most <code>timeout</code> milliseconds. If false, the call will
+ * be asynchronous.
+ * @param timeout The number of milliseconds to wait for a synchronous call.
+ * 0 means to wait forever. This parameter is not used if
+ * <code>synchronous</code> is false.
+ */
void clear(boolean synchronous, long timeout);
+
+
+ /**
+ * Removes all entries from the cache and replicates the update to all \
members. Uses locks at each member + * to ensure transactional serializability.
+ * When a lock in a member cannot be acquired, a LockingException will be \
thrown. Typically the caller will + * then abort the transaction (releasing all \
locks) and retry.<p> + * This call can be one of many inside the same \
transaction, or it may be the only one. In the first case, the + * caller is \
responsible to call commit() or rollback() once the transaction is done. In the \
latter case, the + * transaction can be committed by setting <code>commit</code> \
to true.<br> + * A transaction (Xid) is always associated with the current \
thread. If this call is invoked, and there is no + * transaction associated with \
the current thread, a default transaction will be created. Otherwise the current + \
* transaction will be used. + * @param sync_timeout Max number of milliseconds \
to wait for all responses. Note that this needs to be higher + * \
than <code>lock_acquisition_timeout</code>. 0 means to wait forever for all \
responses. + * @param lock_acquisition_timeout Number of milliseonds to wait \
until a lock becomes available. Needs to be lower + * \
than <code>sync_timeout</code>. 0 means to wait forever. <em>0 will block + * \
forever in case of deadlocks. Once we have deadlock detection in place, + * \
this parameter may be deprecated.</em> + * @param lock_lease_timeout \
Number of milliseonds until a lock is released automatically (if not released + \
* before). Not currently used. + * @param commit \
If true the transaction will be committed after this call if the call was successful. \
+ * @exception LockingException Throw when one or more of the members failed \
acquiring the lock within + * \
<code>lock_acquisition_timeout</code> milliseconds + * @exception \
TimeoutException Thrown when one or more of the members didn't send a response. \
LockingExceptions + * take precedence over \
TimeoutExceptions, e.g. if we have both locking and timeout + * \
exceptions, a LockingException will be thrown. + */
void clear(long sync_timeout,
long lock_acquisition_timeout, long lock_lease_timeout,
boolean commit) throws LockingException, TimeoutException;
-
+ /**
+ * Starts a new transaction and associates it with the current thread. Reuses \
the transaction if the + * current thread already has a transaction.
+ */
void begin() throws Exception;
+
+ /**
+ * Starts a new transaction and associates it with the current thread. Reuses \
the transaction if the + * current thread already has a transaction.
+ * @param transaction_mode Mode in which the transaction should run. Possible \
values are Xid.DIRTY_READS, + * Xid.READ_COMMITTED, \
Xid.REPEATABLE_READ and Xid.SERIALIZABLE + */
void begin(int transaction_mode) throws Exception;
+
+ /**
+ * Commits all modifications done in the current transaction (kept in \
temporary storage) + * to the hashtable. Releases all locks acquired by the \
current transaction. + */
void commit(Xid transaction);
+
+ /**
+ * Discards all changes done within the current transaction. Releases all \
locks acquired + * by the current transaction.
+ */
void rollback(Xid transaction);
+
+
/**
* Changes an entry from transient to non-transient and vice versa. If an
* entry has been transient up to now, and becomes non-transient, it's
* value is replicated to all caches in the cluster. From then on, all
* changes will be replicated. If an entry has been non-transient up to now,
* and becomes transient, all further modifications to that entry will not
- * be replicated.
+ * be replicated.<br/>
+ * If the key or value of the entry is not serializable, this method is a
+ * null operation (an error will be logged).
* @param key The key of the entry
* @param transient_entry Whether or not to make the entry transient. Note
* that setting an entry to the mode it has been in so far is a null
-------------------------------------------------------
This sf.net email is sponsored by:ThinkGeek
Welcome to geek heaven.
http://thinkgeek.com/sf
_______________________________________________
jboss-cvs-commits mailing list
jboss-cvs-commits@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/jboss-cvs-commits
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic