added some words on context binding across disjunctions and declare soft behaviour...

diff --git a/docs/adk15ProgGuideDB/miscellaneous.xml b/docs/adk15ProgGuideDB/miscellaneous.xml
index 545a664181e492ced968605dd8466ea0e9ad909c..063c8b816a1448119f2b7797a8b9c80b64b14636 100644 (file)
--- a/docs/adk15ProgGuideDB/miscellaneous.xml
+++ b/docs/adk15ProgGuideDB/miscellaneous.xml
@@ -8,10 +8,24 @@
       <sect2>
           <title>Binding of formals</title>
           <para>
-            Binding of formals (cannot bind same formal more than once in a conjunction, 
-            can bind exactly once in each branch of a disjunction, iff the branches are mutually
-            exclusive based on e.g. join point kind).     
-          </para>  
+           AspectJ 5 is more liberal than AspectJ 1.2.1 in accepting pointcut expressions
+           that bind context variables in more than one location. For example, AspectJ
+           1.2.1 does not allow:
+           </para>
+
+               <programlisting><![CDATA[
+               pointcut foo(Foo foo) : (execution(* *(..)) && this(foo) ) ||
+                                               (set(* *) && target(foo));
+               ]]></programlisting>
+               
+                <para>
+                    whereas this expression is permitted in AspectJ 5. Each context variable must
+                    be bound exactly once in each branch of a disjunction, and the disjunctive branches
+                    must be mutually exclusive. In the above example for instance, no join point
+                    can be both an execution join point and a set join point so the two branches
+                    are mutually exclusive.
+                 </para>
+           
       </sect2>
       
       <sect2>
@@ -27,9 +41,55 @@
   <sect1 id="declare-soft">
       <title>Declare Soft</title>
       <para>
-          Describe change to only soften checked exceptions if we decide to 
-          make it.
+          The semantics of the <literal>declare soft</literal> statement have been 
+          refined in AspectJ 5 to only soften exceptions that are not already runtime 
+          exceptions. If the exception type specified in a declare soft statement is <literal>RuntimeException</literal>
+          or a subtype of <literal>RuntimeException</literal> then a new XLint warning will be issued:</para>
+    
+               <programlisting><![CDATA[
+                 declare soft : SomeRuntimeException : execution(* *(..));
+                 
+                 &gt;&gt; "SomeRuntimeException will not be softened as it is already a RuntimeException" [XLint:runtimeExceptionNotSoftened]
+               ]]></programlisting>
+       
+          <para>
+              This XLint message can be controlled by setting the <literal>runtimeExceptionNotSoftened</literal> XLint parameter.
+          </para>
+       
+          <para>
+             If the exception type specified in a declare soft statement is a super type of <literal>RuntimeException</literal>
+             (such as <literal>Exception</literal> for example) then any <i>checked</i> exception thrown at a matched join point, 
+             where the exception is an instance of the softened exception, will be softened to an 
+             <literal>org.aspectj.lang.SoftException</literal>. 
       </para>
+      
+               <programlisting><![CDATA[
+               public aspect SoftenExample {
+               
+                 declare soft : Exception : execution(* Foo.*(..));
+               
+               }
+               
+               class Foo {
+               
+                 public static void main(String[] args) {
+                   Foo foo = new Foo();
+                   foo.foo();   
+                   foo.bar();
+                 }
+               
+                 void foo() throws Exception {
+                   throw new Exception();        // this will be converted to a SoftException
+                 }
+                 
+                 void bar() throws Exception {
+                   throw new RuntimeException();  // this will remain a RuntimeException
+                 }
+               
+               }
+               ]]></programlisting>
+               
+      
   </sect1>
 </chapter>