{"id":18494906,"url":"https://github.com/qaware/collection-cacheable-for-spring","last_synced_at":"2025-09-06T10:33:16.880Z","repository":{"id":38776772,"uuid":"325536015","full_name":"qaware/collection-cacheable-for-spring","owner":"qaware","description":"Spring cache extension for putting a whole collection of entities as single cache items","archived":false,"fork":false,"pushed_at":"2024-07-01T07:49:59.000Z","size":112,"stargazers_count":60,"open_issues_count":6,"forks_count":9,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-12-25T17:06:48.814Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qaware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-30T11:42:47.000Z","updated_at":"2024-10-12T18:05:29.000Z","dependencies_parsed_at":"2024-11-06T13:27:09.418Z","dependency_job_id":"8dd077b3-9eb3-433a-95a1-c674f62a8837","html_url":"https://github.com/qaware/collection-cacheable-for-spring","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qaware%2Fcollection-cacheable-for-spring","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qaware%2Fcollection-cacheable-for-spring/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qaware%2Fcollection-cacheable-for-spring/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qaware%2Fcollection-cacheable-for-spring/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qaware","download_url":"https://codeload.github.com/qaware/collection-cacheable-for-spring/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232116232,"owners_count":18474824,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T13:22:40.707Z","updated_at":"2025-01-01T19:10:15.223Z","avatar_url":"https://github.com/qaware.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Collection Cacheable for Spring\n\n[![Build Status](https://github.com/qaware/collection-cacheable-for-spring/workflows/build/badge.svg?branch=master)](https://github.com/qaware/collection-cacheable-for-spring/actions?query=workflow%3A%22build%22)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=qaware_collection-cacheable-for-spring\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=qaware_collection-cacheable-for-spring)\n[![Code Coverage](https://sonarcloud.io/api/project_badges/measure?project=qaware_collection-cacheable-for-spring\u0026metric=coverage)](https://sonarcloud.io/dashboard?id=qaware_collection-cacheable-for-spring)\n[![Maven Central](https://img.shields.io/maven-central/v/de.qaware.tools.collection-cacheable-for-spring/collection-cacheable-for-spring-starter)](https://mvnrepository.com/artifact/de.qaware.tools.collection-cacheable-for-spring/collection-cacheable-for-spring-starter)\n\nThis library provides the `@CollectionCacheable` annotation extending Spring's caching mechanism, in\nparticular `@Cacheable`.\n\n`@CollectionCacheable` supports putting a whole collection of entities as single cache items, thus enabling an efficient\nintegration of batch retrieval of entities. See the example usage below for a detailed explanation.\n\n## Getting started\n\nInside your Spring Boot application, add the following (maven) dependency:\n\n```\n\u003cdependency\u003e\n    \u003cgroupId\u003ede.qaware.tools.collection-cacheable-for-spring\u003c/groupId\u003e\n    \u003cartifactId\u003ecollection-cacheable-for-spring-starter\u003c/artifactId\u003e\n    \u003cversion\u003e1.3.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nYou may also use the separate artifact `collection-cacheable-for-spring-api`\nproviding the annotation only with minimal dependencies.\n\n## Example usage\n\nSuppose your entity looks as follows,\n\n```java\nclass MyEntity {\n    long id;\n    String value;\n}\n```\n\nand you have defined a method to retrieve one and many values by their unique `id` as follows:\n\n```java\nclass MyRepository {\n    @Nullable\n    MyEntity findById(long id) {\n        // retrieve one MyEntity from persistence layer (if existing)\n    }\n\n    // map key is MyEntity.id\n    Map\u003cLong, MyEntity\u003e findByIds(Collection\u003cLong\u003e ids) {\n        // do efficient batch retrieve of many MyEntity's and build result map\n    }\n} \n```\n\nNow, to efficiently implement a cache on `MyRepository`, you want the following to happen:\n\n* Whenever a call to `findById` occurs, either a cache hit should be returned, or the method is called putting the\n  result in the cache unless it is `null`.\n\n* Whenever a call to `findByIds` occurs, the method should be called with the non-empty subset of the given `ids`\n  parameter which are **not** in the cache. Otherwise, the cache hits are simply returned.\n\nTo illustrate the above behavior further, consider the following call sequence:\n\n1. `findById(1)` retrieves an entity from the persistence layer and fills the cache for id `1`\n1. `findByIds({1, 2})` finds the cache hit for id `1` and only calls `findByIds({2})` as a delegate. It then fills the\n   cache for id `2`.\n1. `findById(2)` just retrieves the cache hit for id `2`.\n1. `findByIds({1, 2})` will not call anything and just returns a map built from the cache hits for id `1` and `2`.\n\nIn order to implement exactly this behavior, this library is used as follows:\n\n```java\nclass MyRepository {\n    @Nullable\n    @Cacheable(cacheNames = \"myCache\", unless = \"#result == null\")\n    MyEntity findById(long id) {\n        // retrieve one MyEntity from persistence layer (if existing)\n    }\n\n    @CollectionCacheable(cacheNames = \"myCache\")\n    Map\u003cLong, MyEntity\u003e findByIds(Collection\u003cLong\u003e ids) {\n        // do efficient batch retrieve of many MyEntity's and build result map\n    }\n} \n```\n\nSee [this test repository](collection-cacheable-for-spring-starter/src/test/java/de/qaware/tools/collectioncacheableforspring/CollectionCacheableTestRepository.java)\nfor a completely worked out example.\n\n## Advanced usage\n\n### Additional \"findAll\" method\n\nIf your repository also provides a \"findAll\"-like method without any arguments, you can integrate this as well into your\ncache as follows:\n\n```java\nclass MyRepository {\n\n    @CollectionCacheable(cacheNames = \"myCache\")\n        // map key is MyEntity.id\n    Map\u003cLong, MyEntity\u003e findAll() {\n        // do efficient batch retrieve of many MyEntity's and build result map\n    }\n} \n```\n\nThe library assumes that such methods do not have any arguments. Note that the return value must still be a `Map`,\notherwise the library is unable to determine the cache id.\n\n### Also consider `null` as cache hit\n\nUnder some circumstances, it is also desirable to cache also `null` results. This must be explicitly enabled via\nthe `putNull` flag on batch retrieval as follows:\n\n```java\nclass MyRepository {\n    @CollectionCacheable(cacheNames = \"myCache\", putNull = true)\n    Map\u003cLong, MyEntity\u003e findByIds(Collection\u003cLong\u003e ids) {\n        // do efficient batch retrieve of many MyEntity's and build result map\n    }\n} \n```\n\n### Using Set or List as method argument\n\nThe methods annotated with `@CollectionCacheable` use the base interface `Collection` in the above examples, but\nalso `List\u003c\u003e` and `Set\u003c\u003e` interfaces are supported. Note though that this may change the actual passed implementation\nto `LinkedList` or `HashSet`, respectively (see `DefaultCollectionCreator` and `SetCollectionCreator` implementations).\nYou can add support for more collection-like types by providing beans deriving from `CollectionCreator`, or even\noverride the given creators thanks to Spring Boot autoconfiguration.\n\n## Contributing\n\nPlease report [issues or feature requests](https://github.com/qaware/collection-cacheable-for-spring/issues).\n\nAlso see this [Spring issue here](https://github.com/spring-projects/spring-framework/issues/23221). As of now,\nintegration into Spring is not ideal, so this library might break with future Spring releases.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqaware%2Fcollection-cacheable-for-spring","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqaware%2Fcollection-cacheable-for-spring","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqaware%2Fcollection-cacheable-for-spring/lists"}