ozeigermann 2005/01/09 16:31:48
Modified: transaction/xdocs/locks concepts.xml index.xml
transaction/xdocs navigation.xml
Added: transaction/xdocs/locks preference.xml
Log:
Finished docs for 1.1
Revision Changes Path
1.2 +42 -13 jakarta-commons/transaction/xdocs/locks/concepts.xml
Index: concepts.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/transaction/xdocs/locks/concepts.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- concepts.xml 9 Jan 2005 23:10:06 -0000 1.1
+++ concepts.xml 10 Jan 2005 00:31:48 -0000 1.2
@@ -3,26 +3,55 @@
<document>
<properties>
- <title>Locking concepts</title>
+ <title>Transaction concepts</title>
<author email="[email protected]">Commons Documentation
Team</author>
</properties>
<body>
-<section name="Locking Concepts">
+<section name="Transaction Concepts">
-<subsection name="Rudimentary Transaction support for GenericLockManager
implementing LockManager2">
- - Transaction wide lock management
- - Global transaction timeouts
- - Deadlock detection
-</subsection>
-
-<subsection name="Extended Locking capacities of GenricLock implementing
MultiLevelLock2">
- - preference locks
- - waiter recording and management
- - improved debugging with toString
-</subsection>
+<p><em>Note: </em>Before reading further be sure to read the <a
+href="tutorial.html">introductory tutorial.</a></p>
+<p>Beginning with version 1.1 the Commons Transaction package features
+extended transaction support mechanisms. They are grouped around the
+new <a
+href="../apidocs/org/apache/commons/transaction/locking/LockManager2.html">lock
+manager</a> and its <a
+href="../apidocs/org/apache/commons/transaction/locking/GenericLockManager.html">implementation</a>
+that should be used as the only interface to access locks
+associated to some sort of transaction. To do so it offers you locking
+methods like <a
+href="../apidocs/org/apache/commons/transaction/locking/LockManager2.html#lock(java.lang.Object,%20java.lang.Object,%20int,%20int,%20boolean,%20long)">lock</a>
+and <a
+href="../apidocs/org/apache/commons/transaction/locking/LockManager2.html#tryLock(java.lang.Object,%20java.lang.Object,%20int,%20boolean)">tryLock</a>.</p>
+
+<p>It is important for this manager to be central and have
+knowledge of all locking operations to perform tasks like <a
href="deadlock.html">deadlock
+detection</a>, incorporate <a
+href="../apidocs/org/apache/commons/transaction/locking/LockManager2.html#startGlobalTimeout(java.lang.Object,%20long)">global
+transaction timeouts</a> and add convenience methods to <a
+href="../apidocs/org/apache/commons/transaction/locking/LockManager2.html#releaseAll(java.lang.Object)">release
+all locks</a> of a transaction.</p>
+
+<p>Additional to the <a href="preference.html">preference feature</a>
+in the new <a
href="../apidocs/org/apache/commons/transaction/locking/MultiLevelLock2.html">lock</a>,
its <a
+href="../apidocs/org/apache/commons/transaction/locking/GenericLock.html">implementation</a>
+has some internal means to record all requests that wait for
+(partially) acquiring a lock in the sequence they occur. This is
+used by the deadlock detection in the lock manager. Another possible
+use is in custom implementations of fair scheduling lock
+mechanisms. Even though the specific protected methods
+<a
+href="../apidocs/org/apache/commons/transaction/locking/GenericLock.html#registerWaiter(org.apache.commons.transaction.locking.GenericLock.LockOwner)">registerWaiter</a>
+and
+<a
+href="../apidocs/org/apache/commons/transaction/locking/GenericLock.html#unregisterWaiter(org.apache.commons.transaction.locking.GenericLock.LockOwner)">unregisterWaiter</a>
+and field
+<a
+href="../apidocs/org/apache/commons/transaction/locking/GenericLock.html#waitingOwners">waitingOwners</a>
are not made available
+through interfaces subclasses can still use them and even make their means
public.</p>
</section>
</body>
1.2 +10 -2 jakarta-commons/transaction/xdocs/locks/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/transaction/xdocs/locks/index.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- index.xml 18 Nov 2004 23:27:19 -0000 1.1
+++ index.xml 10 Jan 2005 00:31:48 -0000 1.2
@@ -44,9 +44,17 @@
component make heavy
use of them.
</p>
+<subsection name="Where go to from here?">
<p>To learn more about multi level locks and how you can use them continue
- with the <a href="tutorial.html">tutorial</a>. It explains how
- Jakarta Slide's WebDAV layer uses them to deadlock free avoid
conflicts.</p>
+ with the <a href="tutorial.html">introductory tutorial</a>. It explains how
+ Jakarta Slide's WebDAV layer uses them to deadlock free avoid
+ conflicts. New features introduced in 1.1 are <a
+ href="concepts.html">extended transaction support</a> and <a
+ href="preference.html">general preferences for locks</a>. You can also find
information about <a
+ href="deadlock.html">deadlocks and how they are handled in the
+ Commons Transaction package</a>. </p>
+</subsection>
+
</section>
</body>
1.1 jakarta-commons/transaction/xdocs/locks/preference.xml
Index: preference.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Preference Locks</title>
<author email="[email protected]">Commons Documentation
Team</author>
</properties>
<body>
<section name="Preference Locks">
<p><em>Note: </em>Before reading further be sure to read the <a
href="tutorial.html">introductory tutorial.</a></p>
<p>With the new <a
href="../apidocs/org/apache/commons/transaction/locking/MultiLevelLock2.html">lock</a>
and its <a
href="../apidocs/org/apache/commons/transaction/locking/GenericLock.html">implementation</a>
introduced in version 1.1 there now is the possibility to prefer
certain lock request. If a lock is not directly available
a preferred lock request will be fulfilled before any other request
that is not preferred.</p>
<p>Putting preferences on certain lock levels is what the <a
href="../apidocs/org/apache/commons/transaction/locking/ReadWriteLockManager.html">read/write
lock manager</a> and the <a
href="../apidocs/org/apache/commons/transaction/locking/ReadWriteUpgradeLockManager.html">read/write/upgrade
lock manager</a> with their respective implementations for <a
href="../apidocs/org/apache/commons/transaction/locking/ReadWriteLock.html">read/write</a>
and <a
href="../apidocs/org/apache/commons/transaction/locking/ReadWriteUpgradeLock.html">upgrade</a>
locks do.</p>
<p>For full flexibility there is an option to specify preference for any
locking request both in the <a
href="../apidocs/org/apache/commons/transaction/locking/LockManager2.html#lock(java.lang.Object,%20java.lang.Object,%20int,%20int,%20boolean,%20long)">lock
manager</a> as well as in the <a
href="../apidocs/org/apache/commons/transaction/locking/MultiLevelLock2.html#acquire(java.lang.Object,%20int,%20boolean,%20int,%20boolean,%20long)">lock</a>.</p>
</section>
</body>
</document>
1.2 +4 -1 jakarta-commons/transaction/xdocs/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/transaction/xdocs/navigation.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- navigation.xml 18 Nov 2004 23:27:19 -0000 1.1
+++ navigation.xml 10 Jan 2005 00:31:48 -0000 1.2
@@ -9,7 +9,10 @@
<item name="Map Wrapper comparision"
href="/maps/wrappers-comparision.html"/>
</item>
<item name="Locking" href="/locks/index.html">
- <item name="Lock tutorial" href="/locks/tutorial.html"/>
+ <item name="Introduction" href="/locks/tutorial.html"/>
+ <item name="Preference Locks" href="/locks/preference.html"/>
+ <item name="Transaction Concepts" href="/locks/concepts.html"/>
+ <item name="Deadlocks" href="/locks/deadlock.html"/>
</item>
<item name="Transactional file access" href="/file/index.html"/>
<!-- <item name="Configuration"
href="/configuration.html" /> -->
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
