Gestion du Cache

Copy of sumaris-pod/.agents/rules/cache.md (rule written for AI coding agents, when adding or modifying cache configuration, or using @Cacheable/@CacheEvict annotations). Do not edit here: run npm run site:sync-rules to update it.

Le projet utilise Spring Cache avec JCache (Ehcache). Les configurations sont centralisées dans des classes *CacheConfiguration.

Architecture et Configuration

• Centralisation : Les noms de cache et leur configuration doivent être regroupés dans une classe de configuration dédiée par module (ex: CacheConfiguration pour core, ServerCacheConfiguration pour le serveur).
• Interface Names : Déclare toujours les noms de cache dans une interface interne Names sous forme de constantes String.

  public interface Names {
      String MY_CACHE_NAME = "net.sumaris.module.service.methodName";
  }
  

• Customisation : Utilise JCacheManagerCustomizer pour enregistrer les caches auprès du CacheManager.
• Méthodes utilitaires : Utilise les méthodes de la classe net.sumaris.core.dao.technical.cache.Caches pour créer les caches :
  • createHeapCache : Cache simple en mémoire avec TTL.
  • createEternalHeapCache : Cache mémoire sans expiration.
  • createCollectionHeapCache : Pour mettre en cache des collections.
• TTL (Time To Live) : Utilise l'énumération CacheTTL pour les durées standards.

Utilisation dans les Services

• Annotation @Cacheable : À utiliser sur les méthodes de lecture lente ou coûteuse.

  @Cacheable(cacheNames = MyCacheConfiguration.Names.MY_CACHE_NAME)
  public MyVO findSomething(String param) { ... }
  

• Annotation @CacheEvict : À utiliser sur les méthodes de mise à jour/suppression pour invalider le cache.
• Conditionnalité : Si un cache dépend d'une option de configuration (ex: sumaris.fishbase.enabled), assure-toi que la configuration du cache respecte cette condition.
• Key Generator : Par défaut, Spring utilise tous les paramètres de la méthode comme clé. Si nécessaire, utilise CacheConfiguration.SIMPLE_KEY_GENERATOR.

Exemple type de configuration (Module)

@Configuration
@ConditionalOnBean({CacheConfiguration.class})
public class MyModuleCacheConfiguration {
    public interface Names {
        String DATA_BY_ID = "net.sumaris.module.dataById";
    }

    @Bean
    public JCacheManagerCustomizer myCacheManagerCustomizer() {
        return cacheManager -> {
            Caches.createHeapCache(cacheManager, Names.DATA_BY_ID, MyVO.class, CacheTTL.DEFAULT.asDuration(), 100);
        };
    }
}