root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity

+ add docs 

+ rename cache:definitions to cache:caching (to be consistent with annotations)
This commit is contained in:
Costin Leau 2011-11-25 19:40:05 +00:00
parent 549c663fba
commit 3416a26136
4 changed files with 52 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
org.springframework.context/src/main/java/org/springframework/cache/config/CacheAdviceParser.java vendored
View File

@ -117,7 +117,7 @@ class CacheAdviceParser extends AbstractSingleBeanDefinitionParser {
private static final String CACHE_EVICT_ELEMENT = "cache-evict";
private static final String CACHE_PUT_ELEMENT = "cache-put";
private static final String METHOD_ATTRIBUTE = "method";
private static final String DEFS_ELEMENT = "definitions";
private static final String DEFS_ELEMENT = "caching";
@Override
protected Class<?> getBeanClass(Element element) {

2
org.springframework.context/src/main/resources/org/springframework/cache/config/spring-cache-3.1.xsd vendored
View File

@ -124,7 +124,7 @@
<xsd:complexContent>
<xsd:extension base="beans:identifiedType">
<xsd:sequence>
<xsd:element name="definitions" type="definitionsType" minOccurs="0" maxOccurs="unbounded"/>
<xsd:element name="caching" type="definitionsType" minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute name="cache-manager" type="xsd:string" default="cacheManager">
<xsd:annotation>

40
org.springframework.context/src/test/resources/org/springframework/cache/config/cache-advice.xml vendored
View File

@ -8,58 +8,58 @@
http://www.springframework.org/schema/cache http://www.springframework.org/schema/cache/spring-cache.xsd">
<cache:advice id="cacheAdviceInterface" cache-manager="cacheManager">
<cache:definitions cache="default">
<cache:caching cache="default">
<cache:cacheable method="cache"/>
<cache:cacheable method="conditional" condition="#classField == 3"/>
<cache:cacheable method="key" key="#p0"/>
<cache:cacheable method="nam*" key="#root.methodName"/>
<cache:cacheable method="rootVars" key="#root.methodName + #root.method.name + #root.targetClass + #root.target"/>
<cache:cacheable method="nullValue" cache="default"/>
</cache:definitions>
<cache:definitions>
</cache:caching>
<cache:caching>
<cache:cache-evict method="invalidate" cache="default"/>
<cache:cache-evict method="evict" key="#p0" cache="default"/>
</cache:definitions>
<cache:definitions cache="default">
</cache:caching>
<cache:caching cache="default">
<cache:cache-put method="update"/>
<cache:cache-put method="conditionalUpdate" condition="#arg.equals(3)"/>
</cache:definitions>
<cache:definitions method="mult*Cache">
</cache:caching>
<cache:caching method="mult*Cache">
<cache:cacheable cache="primary"/>
<cache:cacheable cache="secondary"/>
</cache:definitions>
<cache:definitions method="multiEvict">
</cache:caching>
<cache:caching method="multiEvict">
<cache:cache-evict cache="primary"/>
<cache:cache-evict method="multiEvict" cache="secondary" key="#p0"/>
</cache:definitions>
<cache:definitions>
</cache:caching>
<cache:caching>
<cache:cacheable method="multiCacheAndEvict" cache="primary" key="#root.methodName"/>
<cache:cache-evict method="multiCacheAndEvict" cache="secondary"/>
<cache:cacheable method="multiConditionalCacheAndEvict" cache="primary" condition="#p0 == 3"/>
<cache:cache-evict method="multiConditionalCacheAndEvict" cache="secondary"/>
<cache:cache-put method="multiUpdate" cache="primary"/>
<cache:cache-put method="multiUpdate" cache="secondary"/>
</cache:definitions>
</cache:caching>
</cache:advice>
<cache:advice id="cacheAdviceClass" cache-manager="cacheManager" key-generator="keyGenerator">
<cache:definitions cache="default">
<cache:caching cache="default">
<cache:cacheable method="key" key="#p0"/>
<cache:cacheable method="nam*" key="#root.methodName + #root.caches[0].name"/>
<cache:cacheable method="rootVars" key="#root.methodName + #root.method.name + #root.targetClass + #root.target"/>
<cache:cacheable method="cache"/>
<cache:cacheable method="conditional"/>
<cache:cacheable method="null*"/>
</cache:definitions>
<cache:definitions>
</cache:caching>
<cache:caching>
<cache:cache-evict method="invalidate" cache="default"/>
<cache:cache-evict method="evict" key="#p0" cache="default"/>
</cache:definitions>
<cache:definitions cache="default">
</cache:caching>
<cache:caching cache="default">
<cache:cache-put method="update"/>
<cache:cache-put method="conditionalUpdate" condition="#arg.equals(3)"/>
</cache:definitions>
<cache:definitions>
</cache:caching>
<cache:caching>
<cache:cacheable method="multiCache" cache="primary"/>
<cache:cacheable method="multiCache" cache="secondary"/>
<cache:cache-evict method="multiEvict" cache="primary"/>
@ -70,7 +70,7 @@
<cache:cache-evict method="multiConditionalCacheAndEvict" cache="secondary"/>
<cache:cache-put method="multiUpdate" cache="primary"/>
<cache:cache-put method="multiUpdate" cache="secondary"/>
</cache:definitions>
</cache:caching>
</cache:advice>
<aop:config>

36
spring-framework-reference/src/cache.xml
View File

@ -219,6 +219,18 @@ public Book findBook(String name)]]></programlisting>
</table>
</section>
</section>
<section id="cache-annotations-put">
<title><literal>@CachePut</literal> annotation</title>
<para>For cases where the cache needs to be updated without interferring with the method execution, one can use the <literal>@CachePut</literal> annotation. That is, the method will always
be executed and its result placed into the cache (according to the <literal>@CachePut</literal> options). It supports the same options as <literal>@Cacheable</literal> and should be used
for cache population rather then method flow optimization.</para>
<para>Note that using <literal>@CachePut</literal> and <literal>@Cacheable</literal> annotations on the same method is generaly discouraged because they have different behaviours. While the latter
causes the method execution to be skipped by using the cache, the former forces the execution in order to execute a cache update. This leads to unexpected behaviour and with the exception of specific
corner-cases (such as annotations having conditions that exclude them from each other), such declarations should be avoided.</para>
</section>
<section id="cache-annotations-evict">
<title><literal>@CacheEvict</literal> annotation</title>
@ -240,6 +252,18 @@ public void loadBooks(InputStream batch)]]></programlisting>
the cache) - this is not the case with <literal>@Cacheable</literal> which adds/update data into the cache and thus requires a result.</para>
</section>
<section id="cache-annotations-caching">
<title><literal>@Caching</literal> annotation</title>
<para>There are cases when multiple annotations of the same type, such as <literal>@CacheEvict</literal> or <literal>@CachePut</literal> need to be specified, for example because the condition or the key
expression is different between different caches. Unfortunately Java does not support such declarations however there is a workaround - using a <emphasis>enclosing</emphasis> annotation, in this case,
<literal>@Caching</literal>. <literal>@Caching</literal> allows multiple nested <literal>@Cacheable</literal>, <literal>@CachePut</literal> and <literal>@CacheEvict</literal> to be used on the same method:</para>
<programlisting language="java"><![CDATA[@Caching(evict = { @CacheEvict("primary"), @CacheEvict(value = "secondary", key = "#p0") })
public Book importBooks(String deposit, Date date)]]></programlisting>
</section>
<section id="cache-annotation-enable">
<title>Enable caching annotations</title>
@ -352,10 +376,10 @@ public void loadBooks(InputStream batch)]]></programlisting>
<sidebar>
<title>Method visibility and
<interfacename>@Cacheable/@CacheEvcit</interfacename></title>
<interfacename>@Cacheable/@CachePut/@CacheEvict</interfacename></title>
<para>When using proxies, you should apply the
<interfacename>@Cacheable/@CacheEvict</interfacename> annotations only to
<interfacename>@Cache*</interfacename> annotations only to
methods with <emphasis>public</emphasis> visibility. If you do
annotate protected, private or package-visible methods with these annotations,
no error is raised, but the annotated method does not exhibit the configured
@ -366,9 +390,9 @@ public void loadBooks(InputStream batch)]]></programlisting>
<para><tip>
<para>Spring recommends that you only annotate concrete classes (and
methods of concrete classes) with the
<interfacename>@Cacheable/@CacheEvict</interfacename> annotation, as opposed
<interfacename>@Cache*</interfacename> annotation, as opposed
to annotating interfaces. You certainly can place the
<interfacename>@Cacheable/@CacheEvict</interfacename> annotation on an
<interfacename>@Cache*</interfacename> annotation on an
interface (or an interface method), but this works only as you would
expect it to if you are using interface-based proxies. The fact that
Java annotations are <emphasis>not inherited from interfaces</emphasis>
@ -434,10 +458,10 @@ public Book findBook(ISBN isbn, boolean checkWarehouse, boolean includeUsed)]]><
<!-- cache definitions -->
<cache:advice id="cacheAdvice" cache-manager="cacheManager">
<cache:definitions cache="books">
<cache:caching cache="books">
<cache:cacheable method="findBook" key="#isbn"/>
<cache:cache-evict method="loadBooks" all-entries="true"/>
</cache:definitions>
</cache:caching>
</cache:advice>
<!-- apply the cacheable behaviour to all BookService interfaces -->