Support 'unless' expression for cache veto

Allow @Cachable, @CachePut and equivalent XML configuration to provide
a SpEL expression that can be used to veto putting an item into the
cache. Unlike 'condition' the 'unless' parameter is evaluated after
the method has been called and can therefore reference the #result.

For example:

    @Cacheable(value="book",
        condition="#name.length < 32",
        unless="#result.hardback")

This commit also allows #result to be referenced from @CacheEvict
expressions as long as 'beforeInvocation' is false.

Issue: SPR-8871

src/dist/changelog.txt

@@ -11,6 +11,7 @@ Changes in version 3.2.2 (2013-03-07)
 * DefaultMessageListenerContainer logs recovery failures at error level and exposes "isRecovering()" method (SPR-10230)
 * MediaType throws dedicated InvalidMediaTypeException instead of generic IllegalArgumentException (SPR-10226)
 * consistent use of LinkedHashMaps and independent getAttributeNames Enumeration in Servlet/Portlet mocks (SPR-10224)
+* support 'unless' expression for cache veto (SPR-8871)
 
 
 Changes in version 3.2.1 (2013-01-24)

src/reference/docbook/cache.xml

@@ -152,6 +152,13 @@ public Book findBook(ISBN isbn, boolean checkWarehouse, boolean includeUsed)</pr
 
             <programlisting language="java"><![CDATA[@Cacheable(value="book", condition="#name.length < 32")
 public Book findBook(String name)]]></programlisting>
+
+            <para>In addition the <literal>conditional</literal> parameter, the <literal>unless</literal> parameter can be used to veto the adding of a value to the cache. Unlike
+            <literal>conditional</literal>, <literal>unless</literal> <literal>SpEL</literal> expressions are evalulated <emphasis>after</emphasis> the method has been called. Expanding
+            on the previous example - perhaps we only want to cache paperback books:</para>
+
+            <programlisting language="java"><![CDATA[@Cacheable(value="book", condition="#name.length < 32", unless="#result.hardback")
+public Book findBook(String name)]]></programlisting>
         </section>
 
         <section xml:id="cache-spel-context">
@@ -218,6 +225,13 @@ public Book findBook(String name)]]></programlisting>
                             <emphasis><![CDATA[#arg]]></emphasis> stands for the argument index (starting from 0).</entry>
                             <entry><screen>iban</screen> or <screen>a0</screen> (one can also use <screen>p0</screen> or <literal><![CDATA[p<#arg>]]></literal> notation as an alias).</entry>
                         </row>
+                        <row>
+                            <entry>result</entry>
+                            <entry>evaluation context</entry>
+                            <entry>The result of the method call (the value to be cached). Only available in '<literal>unless</literal>' expressions and '<literal>cache evict</literal>'
+                            expression (when <literal>beforeInvocation</literal> is <literal>false</literal>).</entry>
+                            <entry><screen>#result</screen></entry>
+                        </row>
                     </tbody>
                  </tgroup>
             </table>