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

1 files changed, 66 insertions, 6 deletions

diff --git a/docs/adk15ProgGuideDB/miscellaneous.xml b/docs/adk15ProgGuideDB/miscellaneous.xml
index 545a66418..063c8b816 100644
--- 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>