////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
////

The cache plugin adds Spring bean method call, GSP page fragment and
template caching to Grails applications. You configure one or more caches
in `grails-app/conf/application.yml`, and
annotate methods (either in Spring beans (typically Grails services)) to be cached.
You can also wrap GSP sections in cache tags and render cached templates.

There are three annotations; link:{api}grails/plugin/cache/Cacheable.html[Cacheable],
link:{api}grails/plugin/cache/CachePut.html[CachePut],
and link:{api}grails/plugin/cache/CacheEvict.html[CacheEvict]. You use
`Cacheable` to mark a method as one that should check the cache for a
pre-existing result, or generate a new result and cache it. Use `CachePut` to
mark a method as one that should always be evaluated and store its result in the
cache regardless of existing cache values. And use `@CacheEvict` to flush a cache
(either fully or partially) to force the re-evaluation of previously cached
results.

When using distributed caching (such as ehcache with distributed cache enabled,
or redis with multiple instances of the application running against one redis
instance), all classes that use annotation caching or XML caching should
override the `hashCode` method. The hash code of the object with the method
marked as being cacheable is included in the cache key, and the default
`hashCode` implementation will vary each time the application is run. Overriding
`hashCode` ensures that each instance of the applications will appropriately
share cache keys.

This 'core' cache plugin uses an in-memory implementation where the caches and
cache manager are backed by a thread-safe `java.util.concurrent.ConcurrentMap`.
This is fine for testing and possibly for low-traffic sites, but you should
consider using one of the extension plugins if you need clustering, disk
storage, persistence between restarts, and more configurability of features like
time-to-live, maximum cache size, etc. Currently, the only extension plugin available for Grails is https://github.com/grails-plugins/grails-cache-ehcache[cache-ehcache].
