[jboss-cvs] JBossAS SVN: r93211 - projects/jboss-cl/branches/Branch_2_0/classloader/src/test/java/org/jboss/test/classloader/jbcl114.

[jboss-cvs-commits at lists.jboss.org]

Author: david.lloyd at jboss.com
Date: 2009-09-04 11:12:18 -0400 (Fri, 04 Sep 2009)
New Revision: 93211

Modified:
   projects/jboss-cl/branches/Branch_2_0/classloader/src/test/java/org/jboss/test/classloader/jbcl114/BlockingClassLoaderDomain.java
Log:
Add appropriate javadoc

Modified: projects/jboss-cl/branches/Branch_2_0/classloader/src/test/java/org/jboss/test/classloader/jbcl114/BlockingClassLoaderDomain.java
===================================================================
--- projects/jboss-cl/branches/Branch_2_0/classloader/src/test/java/org/jboss/test/classloader/jbcl114/BlockingClassLoaderDomain.java	2009-09-04 15:05:16 UTC (rev 93210)
+++ projects/jboss-cl/branches/Branch_2_0/classloader/src/test/java/org/jboss/test/classloader/jbcl114/BlockingClassLoaderDomain.java	2009-09-04 15:12:18 UTC (rev 93211)
@@ -27,12 +27,26 @@
 import org.jboss.classloader.spi.base.BaseClassLoader;
 
 /**
+ * This classloader domain really does nothing useful.  Its purpose is to avoid lock contention, but ironically, it
+ * uses a condition variable instead which has the same effect: serial access.  So it gets rid of the apparent lock
+ * contention but suffers from the exact same contention problem.  In addition, it does a bunch of other silly stuff as
+ * well.  On the upside, Carlo is implicitly volunteering to maintain this mess for the next 7 years!  Thanks Carlo!
+ *
  * @author <a href="mailto:cdewolf at redhat.com">Carlo de Wolf</a>
  * @version $Revision: $
  */
 public class BlockingClassLoaderDomain extends ClassLoaderDomain
 {
+
+   /**
+    * This field is protected by {@code this}.  However, that doesn't stop us from accessing it without any sort
+    * of protection down below!  Bet that's gonna blow up in somebody's face sometime.
+    */
    private boolean block = true;
+   /**
+    * We use this lock, which we lock one time and never unlock, to ensure that only one thread ever accesses this
+    * object.  Why don't we keep a Thread reference directly?  Your guess is as good as mine.
+    */
    private ReentrantLock lock = new ReentrantLock();
    
    protected BlockingClassLoaderDomain(String name)
@@ -43,16 +57,33 @@
    @Override
    protected Class<?> loadClass(BaseClassLoader classLoader, String name, boolean allExports) throws ClassNotFoundException
    {
+      /*
+       * Block waiting for this to be unblocked.  See, it doesn't count as lock contention because we use a condition
+       * variable.  Clever, eh?  Sadly, it still means that access is serial.
+       */
       try
       {
          waitForIt();
       }
       catch(InterruptedException e)
       {
+         /*
+          * Handle interruption incorrectly.  First, we rethrow another exception without resetting the interrupt status
+          * which ensures that the cancel semantics of the current thread will get screwed up.  Then we nest the
+          * interrupted exception just to make 100% sure that someone can get shot in the foot later.
+          */
          throw new ClassNotFoundException("interrupted", e);
       }
+      /*
+       * Use the above "technique" to ensure that the first thread which calls this method is the only one allowed to
+       * call henceforth.  What happens when you hit the maximum number of repeated lock invocations?  Who knows, but I
+       * bet it's going to be AWESOME.
+       */
       // there can be only 1
       boolean locked = lock.tryLock();
+      /*
+       * It's a good thing we do this check *after* waiting around.
+       */
       if(!locked)
          throw new IllegalStateException("only one thread is allowed to use this class loader domain");
       return super.loadClass(classLoader, name, allExports);
@@ -60,6 +91,9 @@
    
    public void unblock()
    {
+      /*
+       * Be sure to notify all waiters, even though only one will be able to make progress.
+       */
       synchronized (this)
       {
          block = false;
@@ -69,6 +103,10 @@
    
    private void waitForIt() throws InterruptedException
    {
+      /*
+       * Double-checked locking.  Guess we didn't get the memo about that from 5 years ago.  But it's OK as the rest
+       * of this class is kinda f--ked anyway.
+       */
       if(!block) return;
       synchronized (this)
       {