# HG changeset patch
# User Jaroslav Tulach <jtulach@netbeans.org>
# Date 1213430693 -7200
# Node ID acf2c31e22d47a15b35640b724ab91745a12cf8b
# Parent  1c999569643b8fdbfb102df8ee8084781bfe6421
Merge: Geertjan's changes to the end of the chapter

diff -r 1c999569643b -r acf2c31e22d4 samples/composition/src-api1.0/api/Arithmetica.java
--- a/samples/composition/src-api1.0/api/Arithmetica.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/composition/src-api1.0/api/Arithmetica.java	Sat Jun 14 10:04:53 2008 +0200
@@ -24,6 +24,10 @@
     
     public int sumRange(int from, int to) {
         int len = to - from;
+        if (len < 0) {
+            len = -len;
+            from = to;
+        }
         int[] array = new int[len + 1];
         for (int i = 0; i <= len; i++) {
             array[i] = from + i;
diff -r 1c999569643b -r acf2c31e22d4 samples/composition/src-api2.0-compat/api/Arithmetica.java
--- a/samples/composition/src-api2.0-compat/api/Arithmetica.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/composition/src-api2.0-compat/api/Arithmetica.java	Sat Jun 14 10:04:53 2008 +0200
@@ -43,6 +43,10 @@
 
     private int sumRange1(int from, int to) {
         int len = to - from;
+        if (len < 0) {
+            len = -len;
+            from = to;
+        }
         int[] array = new int[len + 1];
         for (int i = 0; i <= len; i++) {
             array[i] = from + i;
@@ -51,7 +55,7 @@
     }
     
     private int sumRange2(int from, int to) {
-        return (from + to) * (to - from + 1) / 2;
+        return (from + to) * (Math.abs(to - from) + 1) / 2;
     }
 }
 // END: design.composition.arith2.0.compat
diff -r 1c999569643b -r acf2c31e22d4 samples/composition/src-api2.0-enum/api/Arithmetica.java
--- a/samples/composition/src-api2.0-enum/api/Arithmetica.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/composition/src-api2.0-enum/api/Arithmetica.java	Sat Jun 14 10:04:53 2008 +0200
@@ -49,6 +49,10 @@
 
     private int sumRange1(int from, int to) {
         int len = to - from;
+        if (len < 0) {
+            len = -len;
+            from = to;
+        }
         int[] array = new int[len + 1];
         for (int i = 0; i <= len; i++) {
             array[i] = from + i;
@@ -57,6 +61,6 @@
     }
     
     private int sumRange2(int from, int to) {
-        return (from + to) * (to - from + 1) / 2;
+        return (from + to) * (Math.abs(to - from) + 1) / 2;
     }
 }
diff -r 1c999569643b -r acf2c31e22d4 samples/composition/src-api2.0-property/api/Arithmetica.java
--- a/samples/composition/src-api2.0-property/api/Arithmetica.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/composition/src-api2.0-property/api/Arithmetica.java	Sat Jun 14 10:04:53 2008 +0200
@@ -36,6 +36,10 @@
 
     private int sumRange1(int from, int to) {
         int len = to - from;
+        if (len < 0) {
+            len = -len;
+            from = to;
+        }
         int[] array = new int[len + 1];
         for (int i = 0; i <= len; i++) {
             array[i] = from + i;
@@ -44,7 +48,7 @@
     }
     
     private int sumRange2(int from, int to) {
-        return (from + to) * (to - from + 1) / 2;
+        return (from + to) * (Math.abs(to - from) + 1) / 2;
     }
 }
 // END: design.composition.arith2.0.property
diff -r 1c999569643b -r acf2c31e22d4 samples/composition/src-api2.0-runtime/api/Arithmetica.java
--- a/samples/composition/src-api2.0-runtime/api/Arithmetica.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/composition/src-api2.0-runtime/api/Arithmetica.java	Sat Jun 14 10:04:53 2008 +0200
@@ -35,6 +35,10 @@
 
     private int sumRange1(int from, int to) {
         int len = to - from;
+        if (len < 0) {
+            len = -len;
+            from = to;
+        }
         int[] array = new int[len + 1];
         for (int i = 0; i <= len; i++) {
             array[i] = from + i;
@@ -43,7 +47,7 @@
     }
     
     private int sumRange2(int from, int to) {
-        return (from + to) * (to - from + 1) / 2;
+        return (from + to) * (Math.abs(to - from) + 1) / 2;
     }
 
     private static boolean calledByV2AwareLoader() {
diff -r 1c999569643b -r acf2c31e22d4 samples/composition/src-api2.0/api/Arithmetica.java
--- a/samples/composition/src-api2.0/api/Arithmetica.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/composition/src-api2.0/api/Arithmetica.java	Sat Jun 14 10:04:53 2008 +0200
@@ -24,7 +24,7 @@
     
 // BEGIN: design.composition.arith2.0
     public int sumRange(int from, int to) {
-        return (from + to) * (to - from + 1) / 2;
+        return (from + to) * (Math.abs(to - from) + 1) / 2;
     }
 // END: design.composition.arith2.0
 }
diff -r 1c999569643b -r acf2c31e22d4 samples/composition/src-test/api/ArithmeticaCompatibilityTest.java
--- a/samples/composition/src-test/api/ArithmeticaCompatibilityTest.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/composition/src-test/api/ArithmeticaCompatibilityTest.java	Sat Jun 14 10:04:53 2008 +0200
@@ -66,15 +66,15 @@
             compare(now, old, seed);
         
             assertEquals(
-                "Verify amount of sumRange is the same", 
+                "Verify amount calls to of sumRange is the same", 
                 now.countSumRange, old.countSumRange
             );
             assertEquals(
-                "Verify amount of sumAll is the same", 
+                "Verify amount calls to of sumAll is the same", 
                 now.countSumAll, old.countSumAll
             );
             assertEquals(
-                "Verify amount of sumTwo is the same", 
+                "Verify amount calls to of sumTwo is the same", 
                 now.countSumTwo, old.countSumTwo
             );
         } catch (AssertionFailedError ex) {
@@ -99,15 +99,15 @@
         compare(now, old, 1208120436947L);
 
         assertEquals(
-            "Verify amount of sumRange is the same", 
+            "Verify amount of calls to sumRange is the same", 
             now.countSumRange, old.countSumRange
         );
         assertEquals(
-            "Verify amount of sumAll is the same", 
+            "Verify amount of calls to sumAll is the same", 
             now.countSumAll, old.countSumAll
         );
         assertEquals(
-            "Verify amount of sumTwo is the same", 
+            "Verify amount of calls to sumTwo is the same", 
             now.countSumTwo, old.countSumTwo
         );
     }
@@ -119,15 +119,15 @@
         compare(now, old, 1208120628821L);
 
         assertEquals(
-            "Verify amount of sumRange is the same", 
+            "Verify amount of calls to sumRange is the same", 
             now.countSumRange, old.countSumRange
         );
         assertEquals(
-            "Verify amount of sumAll is the same", 
+            "Verify amount of calls to sumAll is the same", 
             now.countSumAll, old.countSumAll
         );
         assertEquals(
-            "Verify amount of sumTwo is the same", 
+            "Verify amount of calls to sumTwo is the same", 
             now.countSumTwo, old.countSumTwo
         );
     }
diff -r 1c999569643b -r acf2c31e22d4 samples/composition/src-test/api/ArithmeticaTest.java
--- a/samples/composition/src-test/api/ArithmeticaTest.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/composition/src-test/api/ArithmeticaTest.java	Sat Jun 14 10:04:53 2008 +0200
@@ -35,8 +35,10 @@
 
     public void testSumRange() {
         Arithmetica instance = new Arithmetica();
-        assertEquals("+", 6, instance.sumRange(1, 3));
-        assertEquals("10", 55, instance.sumRange(1, 10));
+        assertEquals("1+2+3=6", 6, instance.sumRange(1, 3));
+        assertEquals("sum(1,10)=55", 55, instance.sumRange(1, 10));
+        assertEquals("sum(1,1)=1", 1, instance.sumRange(1, 1));
+        assertEquals("sum(10,1)=55", 55, instance.sumRange(10, 1));
     }
     //END: design.composition.arith.test
 
diff -r 1c999569643b -r acf2c31e22d4 samples/composition/src-test/api/FactorialTest.java
--- a/samples/composition/src-test/api/FactorialTest.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/composition/src-test/api/FactorialTest.java	Sat Jun 14 10:04:53 2008 +0200
@@ -38,22 +38,4 @@
     public void testFactorial5() {
         assertEquals(120, Factorial.factorial(5));
     }
-
-    /** Class showing inventive, non-expected use of 
-     * Arithmetica methods to do multiplication instead of
-     * addition.
-     */
-    //BEGIN: design.composition.arith.factorial
-    public static final class Factorial extends Arithmetica {
-        public static int factorial(int n) {
-            return new Factorial().sumRange(1, n);
-        }
-        @Override
-        public int sumTwo(int one, int second) {
-            return one * second;
-        }
-    }
-    //END: design.composition.arith.factorial
-
-    
 }
diff -r 1c999569643b -r acf2c31e22d4 samples/consistency/src-api1.0/api/Lookups.java
--- a/samples/consistency/src-api1.0/api/Lookups.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/consistency/src-api1.0/api/Lookups.java	Sat Jun 14 10:04:53 2008 +0200
@@ -1,6 +1,9 @@
 package api;
 
+import java.util.ArrayList;
 import java.util.Collection;
+import java.util.HashSet;
+import java.util.List;
 import java.util.Set;
 
 /** Factory to create various types of lookup instances.
@@ -12,7 +15,39 @@
     private Lookups() {
     }
     
-    public static Lookup fixed(Object... instances) {
-        return null;
+    public static Lookup fixed(final Object... instances) {
+        return new Lookup() {
+            @Override
+            public <T> T lookup(Class<T> clazz) {
+                for (Object obj : instances) {
+                    if (clazz.isInstance(obj)) {
+                        return clazz.cast(obj);
+                    }
+                }
+                return null;
+            }
+
+            @Override
+            public <T> Collection<? extends T> lookupAll(Class<T> clazz) {
+                List<T> result = new ArrayList<T>();
+                for (Object obj : instances) {
+                    if (clazz.isInstance(obj)) {
+                        result.add(clazz.cast(obj));
+                    }
+                }
+                return result;
+            }
+
+            @Override
+            public <T> Set<Class<? extends T>> lookupAllClasses(Class<T> clazz) {
+                Set<Class<? extends T>> result = new HashSet<Class<? extends T>>();
+                for (Object obj : instances) {
+                    if (clazz.isInstance(obj)) {
+                        result.add(obj.getClass().asSubclass(clazz));
+                    }
+                }
+                return result;
+            }
+        };
     }
 }
diff -r 1c999569643b -r acf2c31e22d4 samples/consistency/src-api2.0/api/Lookup.java
--- a/samples/consistency/src-api2.0/api/Lookup.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/consistency/src-api2.0/api/Lookup.java	Sat Jun 14 10:04:53 2008 +0200
@@ -1,6 +1,11 @@
 package api;
 
+import java.util.ArrayList;
 import java.util.Collection;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.Iterator;
+import java.util.List;
 import java.util.Set;
 
 /** Simplified version of NetBeans 
@@ -13,26 +18,49 @@
  * @version 2.0
  */
 // BEGIN: design.consistency.2.0
-public final class Lookup {
+public abstract class Lookup {
+    /** only for classes in the same package */
     Lookup() {
     }
     
     // BEGIN: design.consistency.lookup.2.0
     public <T> T lookup(Class<T> clazz) {
-        return null;
+        Iterator<T> it = doLookup(clazz);
+        return it.hasNext() ? it.next() : null;
     }
     // END: design.consistency.lookup.2.0
 
     // BEGIN: design.consistency.lookupAll.2.0
     public <T> Collection<? extends T> lookupAll(Class<T> clazz) {
-        return null;
+        Iterator<T> it = doLookup(clazz);
+        if (!it.hasNext()) {
+            return Collections.emptyList();
+        } else {
+            List<T> result = new ArrayList<T>();
+            while (it.hasNext()) {
+                result.add(it.next());
+            }
+            return result;
+        }
     }
     // END: design.consistency.lookupAll.2.0
 
     // BEGIN: design.consistency.lookupAllClasses.2.0
     public <T> Set<Class<? extends T>> lookupAllClasses(Class<T> clazz) {
-        return null;
+        Iterator<T> it = doLookup(clazz);
+        if (!it.hasNext()) {
+            return Collections.emptySet();
+        } else {
+            Set<Class<? extends T>> result = 
+                new HashSet<Class<? extends T>>();
+            while (it.hasNext()) {
+                result.add(it.next().getClass().asSubclass(clazz));
+            }
+            return result;
+        }
     }
     // END: design.consistency.lookupAllClasses.2.0
+// FINISH: design.consistency.2.0
+    
+    abstract <T> Iterator<T> doLookup(Class<T> clazz);
 }
-// END: design.consistency.2.0
\ No newline at end of file
diff -r 1c999569643b -r acf2c31e22d4 samples/consistency/src-api2.0/api/Lookups.java
--- a/samples/consistency/src-api2.0/api/Lookups.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/consistency/src-api2.0/api/Lookups.java	Sat Jun 14 10:04:53 2008 +0200
@@ -1,6 +1,8 @@
 package api;
 
+import java.util.ArrayList;
 import java.util.Collection;
+import java.util.Iterator;
 import java.util.Set;
 
 /** Factory to create various types of lookup instances.
@@ -12,12 +14,30 @@
     private Lookups() {
     }
     
-    public static Lookup fixed(Object... instances) {
-        return null;
+    public static Lookup fixed(final Object... instances) {
+        return new Lookup() {
+            @Override
+            <T> Iterator<T> doLookup(Class<T> clazz) {
+                ArrayList<T> result = new ArrayList<T>();
+                for (Object obj : instances) {
+                    if (clazz.isInstance(obj)) {
+                        result.add(clazz.cast(obj));
+                    }
+                }
+                return result.iterator();
+            }
+        };
     }
     
-    public static Lookup dynamic(Dynamic provider) {
-        return null;
+    public static Lookup dynamic(final Dynamic provider) {
+        return new Lookup() {
+            @Override
+            <T> Iterator<T> doLookup(Class<T> clazz) {
+                ArrayList<T> result = new ArrayList<T>();
+                provider.computeInstances(clazz, result);
+                return result.iterator();
+            }
+        };
     }
     
     public interface Dynamic {
diff -r 1c999569643b -r acf2c31e22d4 samples/deadlock/src/org/apidesign/deadlock/logs/Parallel.java
--- a/samples/deadlock/src/org/apidesign/deadlock/logs/Parallel.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/deadlock/src/org/apidesign/deadlock/logs/Parallel.java	Sat Jun 14 10:04:53 2008 +0200
@@ -5,7 +5,7 @@
 import java.util.logging.Logger;
 
 // BEGIN: test.parallel
-class Parael implements Runnable {
+class Parallel implements Runnable {
     public void run() {
         Random r = new Random();
         for (int i = 0; i < 10; i++) {
@@ -16,8 +16,8 @@
         }
     }
     public static void main(String[] args) throws InterruptedException {
-        Thread t1 = new Thread(new Parael(), "1st");
-        Thread t2 = new Thread(new Parael(), "2nd");
+        Thread t1 = new Thread(new Parallel(), "1st");
+        Thread t2 = new Thread(new Parallel(), "2nd");
         t1.start(); t2.start();
         t1.join(); t2.join();
     }
diff -r 1c999569643b -r acf2c31e22d4 samples/deadlock/test/org/apidesign/deadlock/logs/ParallelControlFlowTest.java
--- a/samples/deadlock/test/org/apidesign/deadlock/logs/ParallelControlFlowTest.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/deadlock/test/org/apidesign/deadlock/logs/ParallelControlFlowTest.java	Sat Jun 14 10:04:53 2008 +0200
@@ -47,7 +47,7 @@
             "THREAD: 2nd MSG: cnt: 9",
             500
         );
-        Parael.main(null);
+        Parallel.main(null);
         fail("Ok, just print the logged output");
     }
 // END: test.parallel.test.controlflow
@@ -61,7 +61,7 @@
             "THREAD: 1st MSG: cnt: 6",
             5000
         );
-        Parael.main(null);
+        Parallel.main(null);
         fail("Ok, just print the logged output");
     }
     // END: test.parallel.test.fivetwo
diff -r 1c999569643b -r acf2c31e22d4 samples/deadlock/test/org/apidesign/deadlock/logs/ParallelSortedTest.java
--- a/samples/deadlock/test/org/apidesign/deadlock/logs/ParallelSortedTest.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/deadlock/test/org/apidesign/deadlock/logs/ParallelSortedTest.java	Sat Jun 14 10:04:53 2008 +0200
@@ -25,7 +25,7 @@
 
     public void testMain() throws Exception {
         Logger.global.addHandler(new BlockingHandler());
-        Parael.main(null);
+        Parallel.main(null);
         fail("Ok, just print the logged output");
     }
 
diff -r 1c999569643b -r acf2c31e22d4 samples/deadlock/test/org/apidesign/deadlock/logs/ParallelTest.java
--- a/samples/deadlock/test/org/apidesign/deadlock/logs/ParallelTest.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/deadlock/test/org/apidesign/deadlock/logs/ParallelTest.java	Sat Jun 14 10:04:53 2008 +0200
@@ -21,7 +21,7 @@
     }
 
     public void testMain() throws Exception {
-        Parael.main(null);
+        Parallel.main(null);
         fail("Ok, just print logged messages");
     }
 }
diff -r 1c999569643b -r acf2c31e22d4 samples/delegatingwriter/src/org/apidesign/delegatingwriter/AltBufferedWriter.java
--- a/samples/delegatingwriter/src/org/apidesign/delegatingwriter/AltBufferedWriter.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/delegatingwriter/src/org/apidesign/delegatingwriter/AltBufferedWriter.java	Sat Jun 14 10:04:53 2008 +0200
@@ -68,7 +68,7 @@
         // BEGIN: writer.delegateout
         // efficient, yet dangerous delegation skipping methods unknown to 
         // subclasses that used version 1.4
-        if (csq != null && csq.length() < 1024) {
+        if (shouldBufferAsTheSequenceIsNotTooBig(csq)) {
             write(csq.toString());
         } else {
             flush();
@@ -103,7 +103,7 @@
             throw new IOException(ex);
         }
         
-        if (isOverriden || (csq != null && csq.length() < 1024)) {
+        if (isOverriden || shouldBufferAsTheSequenceIsNotTooBig(csq)) {
             write(csq.toString());
         } else {
             flush();
@@ -112,6 +112,28 @@
         return this;
         // END: writer.conditionally
     }
+
+    /** At the end the purpose of BufferedWriter is to buffer writes, this
+     * method is here to decide when it is OK to prefer buffering and when 
+     * it is better to delegate directly into the underlaying stream.
+     * 
+     * @param csq the seqence to evaluate
+     * @return true if buffering from super class should be used
+     */
+    private static boolean shouldBufferAsTheSequenceIsNotTooBig(CharSequence csq) {
+        if (csq == null) {
+            return false;
+        }
+        // as buffers are usually bigger than 1024, it makes sense to 
+        // pay the penalty of converting the sequence to string, but buffering
+        // the write
+        if (csq.length() < 1024) {
+            return true;
+        } else {
+            // otherwise, just directly write down the char sequence
+            return false;
+        }
+    }
     
     public enum Behaviour {
         THROW_EXCEPTION, 
diff -r 1c999569643b -r acf2c31e22d4 samples/delegatingwriter/test/org/apidesign/delegatingwriter/CountingWriter.java
--- a/samples/delegatingwriter/test/org/apidesign/delegatingwriter/CountingWriter.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/delegatingwriter/test/org/apidesign/delegatingwriter/CountingWriter.java	Sat Jun 14 10:04:53 2008 +0200
@@ -6,8 +6,6 @@
 
 // BEGIN: writer.CountingWriter
 /** Writer that counts the number of written in characters.
- *
- * @author Jaroslav Tulach
  */
 public class CountingWriter extends Writer {
     private int counter;
diff -r 1c999569643b -r acf2c31e22d4 samples/delegatingwriter/test/org/apidesign/delegatingwriter/CryptoWriter.java
--- a/samples/delegatingwriter/test/org/apidesign/delegatingwriter/CryptoWriter.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/delegatingwriter/test/org/apidesign/delegatingwriter/CryptoWriter.java	Sat Jun 14 10:04:53 2008 +0200
@@ -34,26 +34,26 @@
     public void write(char[] buf, int off, int len) throws IOException {
         char[] arr = new char[len];
         for (int i = 0; i < len; i++) {
-            arr[i] = convertChar(buf[off + i]);
+            arr[i] = encryptChar(buf[off + i]);
         }
         super.write(arr, 0, len);
     }
 
     @Override
     public void write(int c) throws IOException {
-        super.write(convertChar(c));
+        super.write(encryptChar(c));
     }
 
     @Override
     public void write(String str, int off, int len) throws IOException {
         StringBuffer sb = new StringBuffer();
         for (int i = 0; i < len; i++) {
-            sb.append(convertChar(str.charAt(off + i)));
+            sb.append(encryptChar(str.charAt(off + i)));
         }
         super.write(sb.toString(), 0, len);
     }
 
-    private char convertChar(int c) {
+    private char encryptChar(int c) {
         if (c == 'Z') {
             return 'A';
         }
diff -r 1c999569643b -r acf2c31e22d4 samples/delegatingwriterfinal/src-api2.0/api/SimpleBuffer.java
--- a/samples/delegatingwriterfinal/src-api2.0/api/SimpleBuffer.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/delegatingwriterfinal/src-api2.0/api/SimpleBuffer.java	Sat Jun 14 10:04:53 2008 +0200
@@ -28,7 +28,7 @@
     }
 
     public void write(CharSequence seq) throws IOException {
-        if (seq.length() < 1024) {
+        if (shouldBufferAsTheSequenceIsNotTooBig(seq)) {
             sb.append(seq);
         } else {
             flush();
@@ -36,4 +36,26 @@
         }
     }
 
+    /** At the end the purpose of BufferedWriter is to buffer writes, this
+     * method is here to decide when it is OK to prefer buffering and when 
+     * it is better to delegate directly into the underlaying stream.
+     * 
+     * @param csq the seqence to evaluate
+     * @return true if buffering from super class should be used
+     */
+    private static boolean shouldBufferAsTheSequenceIsNotTooBig(CharSequence csq) {
+        if (csq == null) {
+            return false;
+        }
+        // as buffers are usually bigger than 1024, it makes sense to 
+        // pay the penalty of converting the sequence to string, but buffering
+        // the write
+        if (csq.length() < 1024) {
+            return true;
+        } else {
+            // otherwise, just directly write down the char sequence
+            return false;
+        }
+    }
+    
 }
diff -r 1c999569643b -r acf2c31e22d4 samples/delegatingwriterfinal/src-api2.0/api/Writer.java
--- a/samples/delegatingwriterfinal/src-api2.0/api/Writer.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/delegatingwriterfinal/src-api2.0/api/Writer.java	Sat Jun 14 10:04:53 2008 +0200
@@ -97,8 +97,8 @@
         return new Writer(impl, null);
     }
 
-    public static Writer create(ImplSeq impl) {
-        return new Writer(null, impl);
+    public static Writer create(ImplSeq seq) {
+        return new Writer(null, seq);
     }
     
     public static Writer create(final java.io.Writer w) {
diff -r 1c999569643b -r acf2c31e22d4 samples/delegatingwriterfinal/src-test2.0/api/usage/twodotzero/CountingWriter.java
--- a/samples/delegatingwriterfinal/src-test2.0/api/usage/twodotzero/CountingWriter.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/delegatingwriterfinal/src-test2.0/api/usage/twodotzero/CountingWriter.java	Sat Jun 14 10:04:53 2008 +0200
@@ -6,8 +6,6 @@
 import java.util.concurrent.atomic.AtomicInteger;
 
 /** Writer that counts the number of written in characters.
- *
- * @author Jaroslav Tulach
  */
 public class CountingWriter implements Writer.ImplSeq {
     private final AtomicInteger counter;
diff -r 1c999569643b -r acf2c31e22d4 samples/growingparameters/src-api1.0/api/request/response/Compute.java
--- a/samples/growingparameters/src-api1.0/api/request/response/Compute.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/growingparameters/src-api1.0/api/request/response/Compute.java	Sat Jun 14 10:04:53 2008 +0200
@@ -21,11 +21,11 @@
         }
         
         public void add(String s) {
-            this.result.add(s);
+            result.add(s);
         }
         
         public void addAll(List<String> all) {
-            this.result.addAll(all);
+            result.addAll(all);
         }
     }
 }
diff -r 1c999569643b -r acf2c31e22d4 samples/growingparameters/src-api2.0/api/request/response/Compute.java
--- a/samples/growingparameters/src-api2.0/api/request/response/Compute.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/growingparameters/src-api2.0/api/request/response/Compute.java	Sat Jun 14 10:04:53 2008 +0200
@@ -22,7 +22,7 @@
         }
         
         public void add(String s) {
-            this.result.put(s, s);
+            result.put(s, s);
         }
         
         public void addAll(List<String> all) {
@@ -33,7 +33,7 @@
 
         /** @since 2.0 */
         public void add(String s, String description) {
-            this.result.put(s, description);
+            result.put(s, description);
         }
     }
 }
diff -r 1c999569643b -r acf2c31e22d4 samples/instanceof/src/api/InstanceProvider.java
--- a/samples/instanceof/src/api/InstanceProvider.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/instanceof/src/api/InstanceProvider.java	Sat Jun 14 10:04:53 2008 +0200
@@ -3,7 +3,7 @@
 
 // BEGIN: instanceof.InstanceProvider
 public interface InstanceProvider {
-    public Class<?> instanceClass();
-    public Object instanceCreate();
+    public Class<?> instanceClass() throws Exception;
+    public Object instanceCreate() throws Exception;
 }
 // END: instanceof.InstanceProvider
diff -r 1c999569643b -r acf2c31e22d4 samples/instanceofclass/src-api1.0/api/InstanceProvider.java
--- a/samples/instanceofclass/src-api1.0/api/InstanceProvider.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/instanceofclass/src-api1.0/api/InstanceProvider.java	Sat Jun 14 10:04:53 2008 +0200
@@ -2,18 +2,21 @@
 package api;
 
 // BEGIN: instanceof.class.InstanceProvider1
+
+import java.util.concurrent.Callable;
+
 public final class InstanceProvider {
-    private final Object instance;
+    private final Callable<Object> instance;
 
-    public InstanceProvider(Object instance) {
+    public InstanceProvider(Callable<Object> instance) {
         this.instance = instance;
     }
     
-    public Class<?> instanceClass() {
-        return instance.getClass();
+    public Class<?> instanceClass() throws Exception {
+        return instance.call().getClass();
     }
-    public Object instanceCreate() {
-        return instance;
+    public Object instanceCreate() throws Exception {
+        return instance.call();
     }
 }
 // END: instanceof.class.InstanceProvider1
diff -r 1c999569643b -r acf2c31e22d4 samples/instanceofclass/src-api2.0/api/InstanceProvider.java
--- a/samples/instanceofclass/src-api2.0/api/InstanceProvider.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/instanceofclass/src-api2.0/api/InstanceProvider.java	Sat Jun 14 10:04:53 2008 +0200
@@ -2,24 +2,50 @@
 package api;
 
 // BEGIN: instanceof.class.InstanceProvider2
+
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.Set;
+import java.util.concurrent.Callable;
+
 public final class InstanceProvider {
-    private final Object instance;
+    private final Callable<Object> instance;
+    private final Set<String> types;
 
-    public InstanceProvider(Object instance) {
+    public InstanceProvider(Callable<Object> instance) {
         this.instance = instance;
+        this.types = null;
+    }
+    /** Specifies not only a factory for creating objects, but
+     * also additional information about them.
+     * @param instance the factory to create the object
+     * @param type the class that the create object will be instance of
+     * @since 2.0 
+     */
+    public InstanceProvider(Callable<Object> instance, String... types) {
+        this.instance = instance;
+        this.types = new HashSet<String>();
+        this.types.addAll(Arrays.asList(types));
     }
     
-    public Class<?> instanceClass() {
-        return instance.getClass();
+    public Class<?> instanceClass() throws Exception {
+        return instance.call().getClass();
     }
-    public Object instanceCreate() {
-        return instance;
+    public Object instanceCreate() throws Exception {
+        return instance.call();
     }
     
-    /** @since 2.0 */
-    public boolean isInstanceOf(Class<?> c) {
-        if (Helper.knownHowToDoItBetter()) {
-            return Helper.computeTheResultOfIsInstanceOfInSomeBetterWay(c);
+    /** Allows to find out if the InstanceProvider creates object of given
+     * type. This check can be done without loading the actual object or
+     * its implementation class into memory.
+     * 
+     * @param c class to test 
+     * @return if the instances produced by this provider is instance of c
+     * @since 2.0 
+     */
+    public boolean isInstanceOf(Class<?> c) throws Exception {
+        if (types != null) {
+            return types.contains(c.getName());
         } else {
             // fallback
             return c.isAssignableFrom(instanceClass());
@@ -29,12 +55,3 @@
     
 }
 // END: instanceof.class.InstanceProvider2
-
-class Helper {
-    static boolean computeTheResultOfIsInstanceOfInSomeBetterWay(Class<?> c) {
-        return false;
-    }
-    static boolean knownHowToDoItBetter() {
-        return false;
-    }
-}
\ No newline at end of file
diff -r 1c999569643b -r acf2c31e22d4 samples/misuse/src/org/apidesign/misuse/Connection.java
--- a/samples/misuse/src/org/apidesign/misuse/Connection.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/misuse/src/org/apidesign/misuse/Connection.java	Sat Jun 14 10:04:53 2008 +0200
@@ -2,10 +2,10 @@
 
 // BEGIN: misuse.Connection
 public interface Connection {
-    Savepoint setSavepoint();
+    public Savepoint setSavepoint();
     
     public interface Savepoint {
-        void rollback();
+        public void rollback();
         // and other useful operations
     }
 }
diff -r 1c999569643b -r acf2c31e22d4 samples/misuse/src/org/apidesign/misuse/projectconfig/ProjectConfigurationCorrect.java
--- a/samples/misuse/src/org/apidesign/misuse/projectconfig/ProjectConfigurationCorrect.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/misuse/src/org/apidesign/misuse/projectconfig/ProjectConfigurationCorrect.java	Sat Jun 14 10:04:53 2008 +0200
@@ -4,9 +4,9 @@
     // BEGIN: misuse.prjconfig.correct
     interface ProjectConfigurationProvider
         <Configuration extends ProjectConfiguration> {
-        Configuration[] getConfigurations();
-        Configuration getActive();
-        void setActive(Configuration c);
+        public Configuration[] getConfigurations();
+        public Configuration getActive();
+        public void setActive(Configuration c);
     }
     interface ProjectConfiguration {
         public String getDisplayName();
@@ -24,12 +24,13 @@
     }
     */
 
-    static { 
-        // BEGIN: misuse.prjconfig.correct.access
+    static 
+    // BEGIN: misuse.prjconfig.correct.access
+    { 
         ProjectConfigurationProvider<?> provider = null; // obtain elsewhere;
         resetToZero(provider);
-        // END: misuse.prjconfig.correct.access
     }
+    // END: misuse.prjconfig.correct.access
 
     // BEGIN: misuse.prjconfig.correct.openmethod
     private static <C extends ProjectConfiguration> void resetToZero(
diff -r 1c999569643b -r acf2c31e22d4 samples/misuse/src/org/apidesign/misuse/projectconfig/ProjectConfigurationOriginal.java
--- a/samples/misuse/src/org/apidesign/misuse/projectconfig/ProjectConfigurationOriginal.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/misuse/src/org/apidesign/misuse/projectconfig/ProjectConfigurationOriginal.java	Sat Jun 14 10:04:53 2008 +0200
@@ -3,9 +3,9 @@
 public class ProjectConfigurationOriginal {
     // BEGIN: misuse.prjconfig.orig
     interface ProjectConfigurationProvider {
-        ProjectConfiguration[] getConfigurations();
-        ProjectConfiguration getActive();
-        void setActive(ProjectConfiguration c);
+        public ProjectConfiguration[] getConfigurations();
+        public ProjectConfiguration getActive();
+        public void setActive(ProjectConfiguration c);
     }
     interface ProjectConfiguration {
         public String getDisplayName();
diff -r 1c999569643b -r acf2c31e22d4 samples/reentrant/src/org/apidesign/reentrant/CriticalSectionReentrant.java
--- a/samples/reentrant/src/org/apidesign/reentrant/CriticalSectionReentrant.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/reentrant/src/org/apidesign/reentrant/CriticalSectionReentrant.java	Sat Jun 14 10:04:53 2008 +0200
@@ -5,13 +5,13 @@
 
 public class CriticalSectionReentrant<T extends Comparable<T>> implements CriticalSection<T> {
     private T pilot;
-    private AtomicInteger cnt = new AtomicInteger();
     
     public void assignPilot(T pilot) {
         this.pilot = pilot;
     }
 
     // BEGIN: reentrant.merge.int
+    private AtomicInteger cnt = new AtomicInteger();
     public int sumBigger(Collection<T> args) {
         T pilotCopy = this.pilot;
         int own = doCriticalSection(args, pilotCopy);
diff -r 1c999569643b -r acf2c31e22d4 samples/reentrant/src/org/apidesign/reentrant/CriticalSectionReentrantImmutable.java
--- a/samples/reentrant/src/org/apidesign/reentrant/CriticalSectionReentrantImmutable.java	Sat Jun 14 10:04:51 2008 +0200
+++ b/samples/reentrant/src/org/apidesign/reentrant/CriticalSectionReentrantImmutable.java	Sat Jun 14 10:04:53 2008 +0200
@@ -13,7 +13,10 @@
     // BEGIN: reentrant.merge.immutable
     public int sumBigger(Collection<T> args) {
         for (;;) {
-            ImmutableData<T> previous = this.data;
+            ImmutableData<T> previous;
+            synchronized (this) {
+                previous = this.data;
+            }
             int[] ret = { 0 };
             ImmutableData<T> now = doCriticalSection(args, previous, ret);