docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cacheInvalidation.adoc

// 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.

include::../var.adoc[]

[#ext-cache-invalidation]
=== Cache Invalidation Extension

Cache invalidation module is an extension that allows to define cache invalidation policy programmatically.

==== Maven

[source, XML,subs="verbatim,attributes"]
----
<dependency>
    <groupId>org.apache.cayenne</groupId>
    <artifactId>cayenne-cache-invalidation</artifactId>
    <version>{version}</version>
</dependency>
----

==== Gradle

[source, Groovy,subs="verbatim,attributes"]
----
compile 'org.apache.cayenne:cayenne-cache-invalidation:{version}'
----

==== Usage

Module supports autoloading mechanism, so no other actions required to enable it. Just mark your entities with @CacheGroups
annotation and you are ready to use it:

[source, java]
----
@CacheGroups("some-group")
public class MyEntity extends _MyEntity {
    // ...
}
----

After any modification of `MyEntity` objects cache group `"some-group"` will be dropped from cache automatically.

NOTE: You can read more about cache and cache groups in corresponding xref:caching[chapter] of this documentation.

In case you need some complex logic of cache invalidation you can disable default behaviour and provide your own.

To do so you need to implement `o.a.c.cache.invalidation.InvalidationHandler` interface and setup Cache
Invalidation module to use it. Let's use implementation class called `CustomInvalidationHandler` that will simply match
all entities' types with `"custom-group"` cache group regardless of any annotations:

[source, java]
----
public class CustomInvalidationHandler implements InvalidationHandler {
    @Override
    public InvalidationFunction canHandle(Class<? extends Persistent> type) {
        return p -> Collections.singleton(new CacheGroupDescriptor("custom-group"));
    }
}
----

Now we'll set up it's usage by `ServerRuntime`:

[source, java]
----
ServerRuntime.builder()
        .addModule(CacheInvalidationModule.extend()
                // optionally you can disable @CacheGroups annotation processing
                .noCacheGroupsHandler()
                .addHandler(CustomInvalidationHandler.class)
                .module())
----

NOTE: You can combine as many invalidation handlers as you need.