diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..eb8ffb6d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,47 @@ +# AGENTS.md + +This file provides guidance to AI coding agents when working with code in this repository. + +## Overview + +`mod-kb-ebsco-java` is a FOLIO backend module (Java 21, Maven) that brokers between FOLIO and the EBSCO HoldingsIQ (RM API) knowledge base: providers, packages, titles, resources, holdings, custom labels, access types, tags, assigned users, KB credentials, and Usage Consolidation (cost-per-use). It is built on **RAML Module Builder (RMB)** (`domain-models-runtime`) + Vert.x, with Spring for dependency injection. The external HoldingsIQ client lives in the separate `folio-holdingsiq-client` library, whose version is set by `folio-holdingsiq-client.version` in `pom.xml`. That version may be a release or a SNAPSHOT. If a SNAPSHOT isn't resolvable from the FOLIO Maven repository, build and install the library locally from its own repository; its default local location is `../folio-holdingsiq-client` (relative to this project), but the local repository may be located elsewhere or not exist at all. + +## Commands + +```shell +mvn clean install # full build: RAML codegen, AspectJ weaving, checkstyle, tests, fat jar +mvn clean install -DskipTests # build without tests +mvn test -Dtest=SomeTest # single test class +mvn test -Dtest=SomeTest#method # single test method +mvn checkstyle:check # style check (also runs automatically in process-classes; violations fail the build) +docker build -t mod-kb-ebsco-java . # container; fat jar is target/mod-kb-ebsco-java-fat.jar +``` + +Surefire only picks up `Test*.java`, `*Test.java`, `*Tests.java`, `*TestCase.java`. + +## Build pipeline gotchas + +- **API interfaces are generated from RAML.** `ramls/` (a git submodule, see `.gitmodules`; `exec-maven-plugin` runs `git submodule update --init --recursive` at `initialize`) plus JSON schemas under `ramls/types/**` are fed to `domain-models-maven-plugin`, which generates JAX-RS interfaces and POJOs into `target/generated-sources/raml-jaxrs`. Changing an endpoint or model means editing the RAML/schema, then rebuilding — don't hand-edit generated code. +- **AspectJ weaving** (`aspectj-maven-plugin`) applies to `**/impl/*.java` and `*.aj` (e.g. `rest/aspect/ValidationErrorHandlerAspect.aj`, `@HandleValidationErrors`). Builds must go through Maven for aspects to be woven; IDE-only compilation may miss them. +- Lombok and Vert.x `CodeGenProcessor` run as annotation processors; Lombok is `provided`. +- `descriptors/*-template.json` are filtered into `target/ModuleDescriptor.json` / `DeploymentDescriptor.json` and validated by `folio-module-descriptor-validator`. New endpoints/permissions must be added to the ModuleDescriptor template as well as the RAML. +- Checkstyle uses the FOLIO config (`folio-java-checkstyle`) over both main and test sources, with `failOnViolation` on warnings. + +## Architecture + +Request flow: **generated RAML interface → `rest/impl/Eholdings*Impl` → services → repositories / HoldingsIQ client**, with converters mapping between layers. + +- `rest/impl/` — RMB resource implementations, one per RAML resource (`EholdingsPackagesImpl`, `EholdingsTitlesImpl`, `LoadHoldingsImpl`, `TenantApiImpl`, `InitApiImpl`, …). Thin: validate, resolve KB credentials, delegate, convert result, map errors via `rest/util/ErrorHandler` / `ExceptionMappers`. +- `rest/validator/` — request-body/param validators; `rest/model/filter` and `rest/model/query` hold search filter/query models (e.g. package subject filters/facets). +- `rest/converter/` — organized per domain; convert HoldingsIQ models and DB models to the generated API models and back. Facet converters are under `converter/facets`. +- `rmapi/` — services that wrap the HoldingsIQ client for providers/packages/titles/resources (`*ServiceImpl`), plus `result/` aggregate types that combine RM API data with local data (tags, access types, cost-per-use) and `cache/` keys for the Vert.x/Spring-backed caches. +- `service/` — business logic per domain (access types, assigned users, custom labels, KB credentials, holdings load/status, Usage Consolidation under `service/uc`, `loader/` for filtering and related-entity loading). Holdings loading is split into `LoadServiceFacade` variants (default vs. transaction-based) with scheduled status/audit handling. +- `repository/` — PostgreSQL access via RMB `PostgresClient`; each domain has a `*Repository(Impl)`, `Db*` model, and `*TableConstants`. Schema is managed by Liquibase (`folio-liquibase-util`) and applied from `TenantApiImpl` / holdings-load flows. +- `client/uc/` — HTTP clients for the external Usage Consolidation (Apigee/Auth) APIs; configured in `spring/config/UcConfig.java`. +- `spring/config/ApplicationConfig.java` — Spring wiring for the whole module; `folio-di-support` is used so RMB resource impls can `@Autowired` beans. + +Multi-tenancy and credentials: calls are tenant-scoped via Okapi headers. Most RM API calls first look up the tenant's KB credentials (`KbCredentials*`, `UserKbCredentialsService`) to build a HoldingsIQ client configuration. + +## Tests + +Tests live in `src/test/java/org/folio/{common,repository,rest,rmapi,service,spring,util}`. Fixtures are under `src/test/resources/{requests,responses,mappings}` (WireMock stubs in `mappings/` for the RM API / UC / user lookup). Stack: JUnit 5, Mockito, AssertJ, RestAssured, WireMock, vertx-junit5, easy-random, and `postgres-testing` (embedded/containerized Postgres for repository and API tests). diff --git a/NEWS.md b/NEWS.md index 9db40f6a..4cb91cc1 100644 --- a/NEWS.md +++ b/NEWS.md @@ -16,6 +16,7 @@ * Validate blank package url and remove invalid format checks ([MODKBEKBJ-863](https://folio-org.atlassian.net/browse/MODKBEKBJ-863)) * Add managed and custom subjects to package detail record ([MODKBEKBJ-853](https://folio-org.atlassian.net/browse/MODKBEKBJ-853)) * Support visibleSomewhere and hiddenSomewhere for package visibility filter ([MODKBEKBJ-865](https://folio-org.atlassian.net/browse/MODKBEKBJ-865)) +* Add subjects (major headings) facet and `filter[subject]` to packages search ([MODKBEKBJ-850](https://folio-org.atlassian.net/browse/MODKBEKBJ-850)) ### Bug fixes * Fix offset handling when retrieving holdings from HoldingsIQ. ([MODKBEKBJ-825](https://folio-org.atlassian.net/browse/MODKBEKBJ-825)) diff --git a/ramls/examples/packages/packages_get_200_response.json b/ramls/examples/packages/packages_get_200_response.json index ec37e485..09c4fa58 100644 --- a/ramls/examples/packages/packages_get_200_response.json +++ b/ramls/examples/packages/packages_get_200_response.json @@ -444,6 +444,28 @@ } } ], + "facets": { + "subjects": [ + { + "id": 26224, + "name": "Science", + "schema": "BISAC", + "count": 8 + }, + { + "id": 28289, + "name": "History", + "schema": "BISAC", + "count": 5 + }, + { + "id": 31507, + "name": "Medical", + "schema": "BISAC", + "count": 3 + } + ] + }, "meta": { "totalResults": 11 }, diff --git a/ramls/packages.raml b/ramls/packages.raml index 20593560..cc35b438 100644 --- a/ramls/packages.raml +++ b/ramls/packages.raml @@ -48,6 +48,22 @@ types: - true example: "true" required: false + filter[subject]: + displayName: Subject + type: string[] + description: | + Filter to narrow down results based on subject ids (major headings). + Each value must be an integer subject id (for example 26224). + The parameter is repeatable (AND semantics): only packages that have all of the specified subjects are returned. + required: false + subjectFacetCount: + displayName: Subject Facet Count + type: integer + description: | + Maximum number of subject facet values to return in the response. + If not specified (or lower than 1), the default value of the HoldingsIQ client is used. + example: 1000 + required: false responses: 200: description: OK diff --git a/ramls/types/packages/packageCollection.json b/ramls/types/packages/packageCollection.json index 3e5a331c..a8affa95 100644 --- a/ramls/types/packages/packageCollection.json +++ b/ramls/types/packages/packageCollection.json @@ -14,6 +14,11 @@ "$ref": "packageCollectionItem.json" } }, + "facets": { + "type": "object", + "description": "Facets for a package collection", + "$ref": "packageFacets.json" + }, "meta": { "type": "object", "description": "metadata containing total results in packages collection", diff --git a/ramls/types/packages/packageFacets.json b/ramls/types/packages/packageFacets.json new file mode 100644 index 00000000..70a42fc8 --- /dev/null +++ b/ramls/types/packages/packageFacets.json @@ -0,0 +1,18 @@ +{ + "$schema": "http://json-schema.org/draft-04/schema#", + "title": "Package facets schema", + "description": "Facets for a package collection", + "javaType": "org.folio.rest.jaxrs.model.PackageFacetsDto", + "type": "object", + "additionalProperties": false, + "properties": { + "subjects": { + "type": "array", + "description": "Subject (major heading) facets", + "items": { + "type": "object", + "$ref": "subjectFacet.json" + } + } + } +} diff --git a/ramls/types/packages/subjectFacet.json b/ramls/types/packages/subjectFacet.json new file mode 100644 index 00000000..b6e91c33 --- /dev/null +++ b/ramls/types/packages/subjectFacet.json @@ -0,0 +1,30 @@ +{ + "$schema": "http://json-schema.org/draft-04/schema#", + "title": "Subject facet schema", + "description": "Subject (major heading) facet schema for a package collection", + "javaType": "org.folio.rest.jaxrs.model.SubjectFacetDto", + "type": "object", + "additionalProperties": false, + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of subject", + "example": 26224 + }, + "name": { + "type": "string", + "description": "Name of subject", + "example": "Science" + }, + "schema": { + "type": "string", + "description": "Subject schema the subject belongs to", + "example": "BISAC" + }, + "count": { + "type": "integer", + "description": "Total count of search results associated with the subject", + "example": 12 + } + } +} diff --git a/src/main/java/org/folio/rest/converter/facets/PackageFacetsConverter.java b/src/main/java/org/folio/rest/converter/facets/PackageFacetsConverter.java new file mode 100644 index 00000000..e4059aa5 --- /dev/null +++ b/src/main/java/org/folio/rest/converter/facets/PackageFacetsConverter.java @@ -0,0 +1,40 @@ +package org.folio.rest.converter.facets; + +import static java.util.Objects.nonNull; + +import java.util.Comparator; +import java.util.List; +import java.util.Objects; +import org.folio.holdingsiq.model.Facets; +import org.folio.holdingsiq.model.SubjectFacet; +import org.folio.rest.jaxrs.model.PackageFacetsDto; +import org.folio.rest.jaxrs.model.SubjectFacetDto; +import org.springframework.core.convert.converter.Converter; +import org.springframework.stereotype.Component; + +@Component +public final class PackageFacetsConverter implements Converter { + + private final Converter subjectFacetConverter; + + public PackageFacetsConverter(Converter subjectFacetConverter) { + this.subjectFacetConverter = subjectFacetConverter; + } + + /** + * Keeps only major headings (subjects without a parent) that have a positive count and orders them by + * descending count. Counts are passed through as returned by HoldingsIQ. + */ + @Override + public PackageFacetsDto convert(Facets facets) { + var subjects = nonNull(facets.getSubjects()) ? facets.getSubjects() : List.of(); + var subjectDtos = subjects.stream() + .filter(Objects::nonNull) + .filter(subject -> subject.parentId() == null) + .filter(subject -> subject.totalCount() != null && subject.totalCount() > 0) + .sorted(Comparator.comparing(SubjectFacet::totalCount, Comparator.reverseOrder())) + .map(subjectFacetConverter::convert) + .toList(); + return new PackageFacetsDto().withSubjects(subjectDtos); + } +} diff --git a/src/main/java/org/folio/rest/converter/facets/SubjectFacetConverter.java b/src/main/java/org/folio/rest/converter/facets/SubjectFacetConverter.java new file mode 100644 index 00000000..b2a44527 --- /dev/null +++ b/src/main/java/org/folio/rest/converter/facets/SubjectFacetConverter.java @@ -0,0 +1,19 @@ +package org.folio.rest.converter.facets; + +import org.folio.holdingsiq.model.SubjectFacet; +import org.folio.rest.jaxrs.model.SubjectFacetDto; +import org.springframework.core.convert.converter.Converter; +import org.springframework.stereotype.Component; + +@Component +public final class SubjectFacetConverter implements Converter { + + @Override + public SubjectFacetDto convert(SubjectFacet subjectFacet) { + return new SubjectFacetDto() + .withId(subjectFacet.id()) + .withName(subjectFacet.subjectName()) + .withSchema(subjectFacet.subjectSchema()) + .withCount(subjectFacet.totalCount()); + } +} diff --git a/src/main/java/org/folio/rest/converter/packages/PackageCollectionConverter.java b/src/main/java/org/folio/rest/converter/packages/PackageCollectionConverter.java index e926582e..e8f02347 100644 --- a/src/main/java/org/folio/rest/converter/packages/PackageCollectionConverter.java +++ b/src/main/java/org/folio/rest/converter/packages/PackageCollectionConverter.java @@ -1,13 +1,16 @@ package org.folio.rest.converter.packages; +import static java.util.Objects.isNull; import static org.folio.common.ListUtils.mapItems; import java.util.List; +import org.folio.holdingsiq.model.Facets; import org.folio.holdingsiq.model.PackageData; import org.folio.holdingsiq.model.Packages; import org.folio.rest.jaxrs.model.MetaTotalResults; import org.folio.rest.jaxrs.model.PackageCollection; import org.folio.rest.jaxrs.model.PackageCollectionItem; +import org.folio.rest.jaxrs.model.PackageFacetsDto; import org.folio.rest.util.RestConstants; import org.springframework.core.convert.converter.Converter; import org.springframework.stereotype.Component; @@ -16,18 +19,23 @@ public class PackageCollectionConverter implements Converter { private final Converter packageCollectionItemConverter; + private final Converter facetsConverter; - public PackageCollectionConverter(Converter packageCollectionItemConverter) { + public PackageCollectionConverter(Converter packageCollectionItemConverter, + Converter facetsConverter) { this.packageCollectionItemConverter = packageCollectionItemConverter; + this.facetsConverter = facetsConverter; } @Override public PackageCollection convert(Packages packages) { List packageList = mapItems(packages.getPackagesList(), packageCollectionItemConverter::convert); + var facetsDto = isNull(packages.getFacets()) ? null : facetsConverter.convert(packages.getFacets()); return new PackageCollection() .withJsonapi(RestConstants.JSONAPI) + .withFacets(facetsDto) .withMeta(new MetaTotalResults().withTotalResults(packages.getTotalResults())) .withData(packageList); } diff --git a/src/main/java/org/folio/rest/converter/packages/PackageCollectionResultConverter.java b/src/main/java/org/folio/rest/converter/packages/PackageCollectionResultConverter.java index 9b6c8913..b7281aac 100644 --- a/src/main/java/org/folio/rest/converter/packages/PackageCollectionResultConverter.java +++ b/src/main/java/org/folio/rest/converter/packages/PackageCollectionResultConverter.java @@ -1,10 +1,12 @@ package org.folio.rest.converter.packages; +import static java.util.Objects.isNull; import static org.folio.common.ListUtils.mapItems; import java.util.Collections; import java.util.List; import java.util.Map; +import org.folio.holdingsiq.model.Facets; import org.folio.holdingsiq.model.PackageData; import org.folio.holdingsiq.model.PackageId; import org.folio.repository.accesstypes.DbAccessType; @@ -15,6 +17,7 @@ import org.folio.rest.jaxrs.model.MetaTotalResults; import org.folio.rest.jaxrs.model.PackageCollection; import org.folio.rest.jaxrs.model.PackageCollectionItem; +import org.folio.rest.jaxrs.model.PackageFacetsDto; import org.folio.rest.jaxrs.model.RelationshipData; import org.folio.rest.jaxrs.model.Tags; import org.folio.rest.util.RestConstants; @@ -27,12 +30,15 @@ public class PackageCollectionResultConverter implements Converter packageCollectionItemConverter; private final Converter accessTypeConverter; + private final Converter facetsConverter; public PackageCollectionResultConverter( Converter packageCollectionItemConverter, - Converter accessTypeConverter) { + Converter accessTypeConverter, + Converter facetsConverter) { this.packageCollectionItemConverter = packageCollectionItemConverter; this.accessTypeConverter = accessTypeConverter; + this.facetsConverter = facetsConverter; } @Override @@ -50,8 +56,11 @@ public PackageCollection convert(PackageCollectionResult packagesResult) { return item; }); + var facetsDto = isNull(packages.getFacets()) ? null : facetsConverter.convert(packages.getFacets()); + return new PackageCollection() .withJsonapi(RestConstants.JSONAPI) + .withFacets(facetsDto) .withMeta(new MetaTotalResults().withTotalResults(packages.getTotalResults())) .withData(packageList); } diff --git a/src/main/java/org/folio/rest/impl/EholdingsPackagesImpl.java b/src/main/java/org/folio/rest/impl/EholdingsPackagesImpl.java index 6777a267..615a6c40 100644 --- a/src/main/java/org/folio/rest/impl/EholdingsPackagesImpl.java +++ b/src/main/java/org/folio/rest/impl/EholdingsPackagesImpl.java @@ -73,10 +73,11 @@ public EholdingsPackagesImpl() { @Override @Validate @HandleValidationErrors - public void getEholdingsPackages(String filterCustom, String q, String queryField, String queryType, - boolean highlight, String filterSelected, String filterType, String filterVisibility, - String filterFreeAccess, List filterTags, List filterAccessType, - String sort, int page, int count, Map okapiHeaders, + public void getEholdingsPackages(String filterCustom, List filterSubject, int subjectFacetCount, String q, + String queryField, String queryType, boolean highlight, String filterSelected, + String filterType, String filterVisibility, String filterFreeAccess, + List filterTags, List filterAccessType, String sort, int page, + int count, Map okapiHeaders, Handler> asyncResultHandler, Context vertxContext) { var filter = PackageRecordFilter.builder() .query(q) @@ -90,6 +91,9 @@ public void getEholdingsPackages(String filterCustom, String q, String queryFiel .filterFreeAccess(filterFreeAccess) .filterTags(filterTags) .filterAccessType(filterAccessType) + .filterSubject(filterSubject) + .subjectFacetCount(subjectFacetCount > 0 ? subjectFacetCount : null) + .includeSubjectFacet(true) .sort(sort) .page(page) .count(count) diff --git a/src/main/java/org/folio/rest/model/filter/FilterValidator.java b/src/main/java/org/folio/rest/model/filter/FilterValidator.java index 45dd20de..89251eb4 100644 --- a/src/main/java/org/folio/rest/model/filter/FilterValidator.java +++ b/src/main/java/org/folio/rest/model/filter/FilterValidator.java @@ -21,7 +21,7 @@ default Optional validate(@NonNull F filter, } } - default Optional validate(@NonNull F filter, @NonNull FilterValidatorLogic logic) { + default

Optional validate(@NonNull F filter, @NonNull FilterValidatorLogic logic) { var param = logic.extractor().apply(filter); if (logic.validator().test(param)) { return Optional.empty(); diff --git a/src/main/java/org/folio/rest/model/filter/FilterValidatorLogic.java b/src/main/java/org/folio/rest/model/filter/FilterValidatorLogic.java index 40b1d7f1..ad394458 100644 --- a/src/main/java/org/folio/rest/model/filter/FilterValidatorLogic.java +++ b/src/main/java/org/folio/rest/model/filter/FilterValidatorLogic.java @@ -4,15 +4,15 @@ import java.util.function.Predicate; import org.jspecify.annotations.NonNull; -public record FilterValidatorLogic( - Function extractor, - Predicate validator, +public record FilterValidatorLogic( + Function extractor, + Predicate

validator, String errorMessage ) { - public static FilterValidatorLogic of(@NonNull Function extractor, - @NonNull Predicate validator, - @NonNull String errorMessage) { + public static FilterValidatorLogic of(@NonNull Function extractor, + @NonNull Predicate

validator, + @NonNull String errorMessage) { return new FilterValidatorLogic<>(extractor, validator, errorMessage); } } diff --git a/src/main/java/org/folio/rest/model/filter/PackageFilterValidator.java b/src/main/java/org/folio/rest/model/filter/PackageFilterValidator.java index d173b981..2e82a7aa 100644 --- a/src/main/java/org/folio/rest/model/filter/PackageFilterValidator.java +++ b/src/main/java/org/folio/rest/model/filter/PackageFilterValidator.java @@ -1,6 +1,5 @@ package org.folio.rest.model.filter; -import static org.apache.commons.collections4.CollectionUtils.isNotEmpty; import static org.folio.rest.model.filter.FilterValidatorLogic.of; import static org.folio.rest.util.RestConstants.FILTER_FREE_ACCESS_MAPPING; import static org.folio.rest.util.RestConstants.FILTER_SELECTED_MAPPING; @@ -9,6 +8,7 @@ import java.util.List; import java.util.Optional; +import java.util.regex.Pattern; import org.folio.holdingsiq.model.PackageSearchField; import org.folio.holdingsiq.model.SearchType; import org.folio.holdingsiq.model.Sort; @@ -28,8 +28,12 @@ public final class PackageFilterValidator implements FilterValidator> VALIDATORS = List.of( + private static final Pattern SUBJECT_ID_PATTERN = Pattern.compile("\\d{1,9}"); + + private static final List> VALIDATORS = List.of( of(PackageRecordFilter::getSort, PackageFilterValidator::isSortValid, INVALID_SORT_PARAMETER_MESSAGE), of(PackageRecordFilter::getQueryType, PackageFilterValidator::isQueryTypeValid, INVALID_QUERY_TYPE_PARAMETER_MESSAGE), @@ -45,13 +49,14 @@ public final class PackageFilterValidator implements FilterValidator filterSubject) { + if (filterSubject == null) { + return true; + } + return filterSubject.stream().allMatch(id -> id != null && SUBJECT_ID_PATTERN.matcher(id).matches()); + } + private static boolean isFilterFreeAccessValid(String filterFreeAccess) { if (filterFreeAccess == null) { return true; diff --git a/src/main/java/org/folio/rest/model/filter/PackageRecordFilter.java b/src/main/java/org/folio/rest/model/filter/PackageRecordFilter.java index 111d56e7..73774a18 100644 --- a/src/main/java/org/folio/rest/model/filter/PackageRecordFilter.java +++ b/src/main/java/org/folio/rest/model/filter/PackageRecordFilter.java @@ -1,6 +1,8 @@ package org.folio.rest.model.filter; import static java.util.Arrays.asList; +import static org.apache.commons.collections4.CollectionUtils.isEmpty; +import static org.folio.common.ListUtils.mapItemsNullable; import java.util.List; import java.util.Optional; @@ -40,6 +42,9 @@ public class PackageRecordFilter implements Filter { int count; List filterTags; List filterAccessType; + List filterSubject; + Integer subjectFacetCount; + boolean includeSubjectFacet; public static PackageRecordFilterBuilder builder() { return new PackageRecordFilterBuilder() { @@ -83,7 +88,7 @@ public RecordType getRecordType() { @Override public List searchCriteriaValues() { - return asList(query, filterCustom, filterSelected); + return asList(query, filterCustom, filterSelected, isEmpty(filterSubject) ? null : String.join(",", filterSubject)); } public Integer parseProviderId() { @@ -104,6 +109,9 @@ public PackageFilter toClientFilter(SearchProperties searchProperties) { .filterType(getPackageFilterType().orElse(null)) .filterPackageFreeAccess(getPackageFilterFreeAccess().orElse(null)) .filterVisibility(getPackageFilterVisibility().orElse(null)) + .includeSubjectFacet(includeSubjectFacet) + .subjectFacetCount(subjectFacetCount) + .filterSubjectIds(mapItemsNullable(filterSubject, Integer::valueOf)) .build(); } } diff --git a/src/test/java/org/folio/rest/converter/facets/PackageFacetsConverterTest.java b/src/test/java/org/folio/rest/converter/facets/PackageFacetsConverterTest.java new file mode 100644 index 00000000..51ff6682 --- /dev/null +++ b/src/test/java/org/folio/rest/converter/facets/PackageFacetsConverterTest.java @@ -0,0 +1,81 @@ +package org.folio.rest.converter.facets; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.Arrays; +import java.util.List; +import org.folio.holdingsiq.model.Facets; +import org.folio.holdingsiq.model.SubjectFacet; +import org.folio.rest.jaxrs.model.SubjectFacetDto; +import org.junit.jupiter.api.Test; + +class PackageFacetsConverterTest { + + private final PackageFacetsConverter converter = new PackageFacetsConverter(new SubjectFacetConverter()); + + @Test + void shouldMapSubjectWithOriginalCount() { + var facets = Facets.builder() + .subjects(List.of(new SubjectFacet(1, null, "BISAC", "Science", 10))) + .build(); + + var result = converter.convert(facets); + + assertEquals(1, result.getSubjects().size()); + var subject = result.getSubjects().getFirst(); + assertEquals(1, subject.getId()); + assertEquals("Science", subject.getName()); + assertEquals("BISAC", subject.getSchema()); + assertEquals(10, subject.getCount()); + } + + @Test + void shouldReturnOnlyMajorHeadings() { + var facets = Facets.builder() + .subjects(List.of( + new SubjectFacet(1, null, "BISAC", "Science", 10), + new SubjectFacet(2, 1, "BISAC", "Genetics", 4))) + .build(); + + var result = converter.convert(facets); + + assertEquals(List.of(1), result.getSubjects().stream().map(SubjectFacetDto::getId).toList()); + } + + @Test + void shouldSkipNullSubjectsAndSubjectsWithoutPositiveCount() { + var facets = Facets.builder() + .subjects(Arrays.asList( + null, + new SubjectFacet(1, null, "BISAC", "Science", 10), + new SubjectFacet(2, null, "BISAC", "Zero count", 0), + new SubjectFacet(3, null, "BISAC", "Null count", null))) + .build(); + + var result = converter.convert(facets); + + assertEquals(List.of(1), result.getSubjects().stream().map(SubjectFacetDto::getId).toList()); + } + + @Test + void shouldOrderSubjectsByDescendingCount() { + var facets = Facets.builder() + .subjects(List.of( + new SubjectFacet(1, null, "BISAC", "Science", 10), + new SubjectFacet(2, null, "BISAC", "History", 20), + new SubjectFacet(3, null, "BISAC", "Art", 15))) + .build(); + + var result = converter.convert(facets); + + assertEquals(List.of(20, 15, 10), result.getSubjects().stream().map(SubjectFacetDto::getCount).toList()); + } + + @Test + void shouldReturnEmptySubjectsWhenNotPresent() { + var result = converter.convert(Facets.builder().build()); + + assertTrue(result.getSubjects().isEmpty()); + } +} diff --git a/src/test/java/org/folio/rest/converter/packages/PackageCollectionResultConverterTest.java b/src/test/java/org/folio/rest/converter/packages/PackageCollectionResultConverterTest.java index cef6db1b..0df8e848 100644 --- a/src/test/java/org/folio/rest/converter/packages/PackageCollectionResultConverterTest.java +++ b/src/test/java/org/folio/rest/converter/packages/PackageCollectionResultConverterTest.java @@ -7,9 +7,12 @@ import static org.junit.jupiter.api.Assertions.assertTrue; import java.util.Collections; +import java.util.List; import java.util.Map; import java.util.UUID; +import org.folio.holdingsiq.model.Facets; import org.folio.holdingsiq.model.Packages; +import org.folio.holdingsiq.model.SubjectFacet; import org.folio.repository.accesstypes.DbAccessType; import org.folio.rest.jaxrs.model.AccessType; import org.folio.rest.jaxrs.model.PackageCollection; @@ -78,4 +81,35 @@ void shouldNotIncludeAccessTypeWhenAccessTypesMapIsEmpty() { assertTrue(item.getIncluded().isEmpty()); assertNull(item.getRelationships().getAccessType()); } + + @Test + void shouldMapSubjectFacetsWhenFacetsArePresent() { + var packages = readJsonFile(PACKAGES_FIXTURE, Packages.class).toBuilder() + .facets(Facets.builder() + .subjects(List.of( + new SubjectFacet(1, null, "BISAC", "Science", 10), + new SubjectFacet(2, 1, "BISAC", "Genetics", 4))) + .build()) + .build(); + var result = new PackageCollectionResult(packages, Collections.emptyList()); + + var packageCollection = conversionService.convert(result, PackageCollection.class); + + assertNotNull(packageCollection); + assertNotNull(packageCollection.getFacets()); + assertEquals(1, packageCollection.getFacets().getSubjects().size()); + assertEquals("Science", packageCollection.getFacets().getSubjects().getFirst().getName()); + assertEquals(10, packageCollection.getFacets().getSubjects().getFirst().getCount()); + } + + @Test + void shouldNotSetFacetsWhenFacetsAreAbsent() { + var packages = readJsonFile(PACKAGES_FIXTURE, Packages.class); + var result = new PackageCollectionResult(packages, Collections.emptyList()); + + var packageCollection = conversionService.convert(result, PackageCollection.class); + + assertNotNull(packageCollection); + assertNull(packageCollection.getFacets()); + } } diff --git a/src/test/java/org/folio/rest/impl/EholdingsPackagesImplTest.java b/src/test/java/org/folio/rest/impl/EholdingsPackagesImplTest.java index 4ee5f59b..2ccb33e7 100644 --- a/src/test/java/org/folio/rest/impl/EholdingsPackagesImplTest.java +++ b/src/test/java/org/folio/rest/impl/EholdingsPackagesImplTest.java @@ -3,6 +3,8 @@ import static io.netty.handler.codec.http.HttpHeaderValues.APPLICATION_JSON; import static java.util.concurrent.CompletableFuture.completedFuture; import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertTrue; import static org.mockito.ArgumentMatchers.any; import static org.mockito.ArgumentMatchers.anyMap; import static org.mockito.ArgumentMatchers.eq; @@ -131,7 +133,8 @@ void shouldFetchPackagesByAccessTypeFilterWhenAccessTypeFilterIsGiven() { @Test void shouldResolveCustomProviderIdWhenFilterCustomIsTrue() { - var filter = PackageRecordFilter.builder().filterCustom("true").sort("relevance").page(1).count(25).build(); + var filter = PackageRecordFilter.builder().filterCustom("true").includeSubjectFacet(true).sort("relevance") + .page(1).count(25).build(); when(packageService.getCustomProviderIdAndRetrievePackages(filter, context)).thenReturn(completedFuture(null)); invokeGetEholdingsPackages(filter); @@ -143,7 +146,7 @@ void shouldResolveCustomProviderIdWhenFilterCustomIsTrue() { @Test void shouldRetrieveAllPackagesWhenFilterCustomIsNotSet() { - var filter = PackageRecordFilter.builder().sort("relevance").page(1).count(25).build(); + var filter = PackageRecordFilter.builder().includeSubjectFacet(true).sort("relevance").page(1).count(25).build(); when(packageService.retrievePackages(null, filter, context)).thenReturn(completedFuture(null)); invokeGetEholdingsPackages(filter); @@ -152,6 +155,35 @@ void shouldRetrieveAllPackagesWhenFilterCustomIsNotSet() { verify(packageService).retrievePackages(null, filter, context); } + @Test + void shouldPassFilterSubjectToPackageRecordFilter() { + var filter = PackageRecordFilter.builder().query("foo").filterSubject(List.of("1", "2")).subjectFacetCount(50) + .includeSubjectFacet(true).sort("relevance").page(1).count(25).build(); + when(packageService.retrievePackages(any(), any(), any())).thenReturn(completedFuture(null)); + + invokeGetEholdingsPackages(filter); + + captureRequestAction().apply(context); + var filterCaptor = ArgumentCaptor.forClass(PackageRecordFilter.class); + verify(packageService).retrievePackages(eq(null), filterCaptor.capture(), eq(context)); + assertEquals(List.of("1", "2"), filterCaptor.getValue().getFilterSubject()); + assertEquals(50, filterCaptor.getValue().getSubjectFacetCount()); + assertTrue(filterCaptor.getValue().isIncludeSubjectFacet()); + } + + @Test + void shouldPassNullSubjectFacetCountWhenNotProvided() { + var filter = PackageRecordFilter.builder().includeSubjectFacet(true).sort("relevance").page(1).count(25).build(); + when(packageService.retrievePackages(any(), any(), any())).thenReturn(completedFuture(null)); + + invokeGetEholdingsPackages(filter); + + captureRequestAction().apply(context); + var filterCaptor = ArgumentCaptor.forClass(PackageRecordFilter.class); + verify(packageService).retrievePackages(eq(null), filterCaptor.capture(), eq(context)); + assertNull(filterCaptor.getValue().getSubjectFacetCount()); + } + @Test void shouldCreateCustomPackage() { var entity = new PackagePostRequest() @@ -317,11 +349,12 @@ private Function> captureRequestActio } private void invokeGetEholdingsPackages(PackageRecordFilter filter) { - impl.getEholdingsPackages(filter.getFilterCustom(), filter.getQuery(), filter.getQueryField(), - filter.getQueryType(), filter.isHighlight(), filter.getFilterSelected(), filter.getFilterType(), - filter.getFilterVisibility(), filter.getFilterFreeAccess(), filter.getFilterTags(), - filter.getFilterAccessType(), filter.getSort(), filter.getPage(), filter.getCount(), OKAPI_HEADERS, - asyncResultHandler, null); + var subjectFacetCount = filter.getSubjectFacetCount() == null ? 0 : filter.getSubjectFacetCount(); + impl.getEholdingsPackages(filter.getFilterCustom(), filter.getFilterSubject(), subjectFacetCount, + filter.getQuery(), filter.getQueryField(), filter.getQueryType(), filter.isHighlight(), + filter.getFilterSelected(), filter.getFilterType(), filter.getFilterVisibility(), filter.getFilterFreeAccess(), + filter.getFilterTags(), filter.getFilterAccessType(), filter.getSort(), filter.getPage(), filter.getCount(), + OKAPI_HEADERS, asyncResultHandler, null); } private void invokeGetResources(ResourceFilter filter) { diff --git a/src/test/java/org/folio/rest/impl/EholdingsPackagesIntegrationTest.java b/src/test/java/org/folio/rest/impl/EholdingsPackagesIntegrationTest.java index e7331a4c..be5c40c0 100644 --- a/src/test/java/org/folio/rest/impl/EholdingsPackagesIntegrationTest.java +++ b/src/test/java/org/folio/rest/impl/EholdingsPackagesIntegrationTest.java @@ -66,6 +66,7 @@ import java.util.LinkedHashMap; import java.util.List; import java.util.Objects; +import java.util.stream.Stream; import org.folio.holdingsiq.model.CoverageDates; import org.folio.holdingsiq.model.PackageData; import org.folio.holdingsiq.model.PackagePut; @@ -88,6 +89,9 @@ import org.junit.jupiter.api.AfterEach; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.Arguments; +import org.junit.jupiter.params.provider.MethodSource; class EholdingsPackagesIntegrationTest extends IntegrationTestBase { @@ -110,6 +114,8 @@ class EholdingsPackagesIntegrationTest extends IntegrationTestBase { "responses/rmapi/packages/get-packages-response.json"; private static final String GET_PACKAGES_BY_PROVIDER_RESPONSE = "responses/rmapi/packages/get-packages-by-provider-id.json"; + private static final String GET_PACKAGES_WITH_SUBJECT_FACETS_RESPONSE = + "responses/rmapi/packages/get-packages-with-subject-facets-response.json"; private static final String GET_PACKAGE_PROVIDER_RESPONSE = "responses/rmapi/packages/get-package-provider-by-id.json"; private static final String POST_PACKAGE_CREATED_RESPONSE = @@ -215,6 +221,60 @@ void shouldReturnPackagesOnGet() { assertEquals(expected, actual); } + @Test + void shouldReturnSubjectFacetsAndSendSubjectFilterToRmApi() { + mockGet(matching(packagesRmApi() + ".*"), readFile(GET_PACKAGES_WITH_SUBJECT_FACETS_RESPONSE)); + + var actual = getWithOk(packagesPath() + "?q=foo&filter[subject]=1&filter[subject]=2") + .as(PackageCollection.class); + + var subjects = actual.getFacets().getSubjects(); + assertEquals(2, subjects.size()); + assertEquals(3, subjects.get(0).getId()); + assertEquals("History", subjects.get(0).getName()); + assertEquals(20, subjects.get(0).getCount()); + assertEquals(1, subjects.get(1).getId()); + assertEquals("Science", subjects.get(1).getName()); + assertEquals(10, subjects.get(1).getCount()); + wm.verify(1, getRequestedFor(urlPathEqualTo(packagesRmApi())) + .withQueryParam("facetstoinclude", WireMock.equalTo("subject")) + .withQueryParam("subjectfacetcount", WireMock.equalTo("1000")) + .withQueryParam("subjectfilter", WireMock.equalTo("1,2"))); + } + + @Test + void shouldSendSubjectFacetCountToRmApi() { + mockGet(matching(packagesRmApi() + ".*"), readFile(GET_PACKAGES_WITH_SUBJECT_FACETS_RESPONSE)); + + getWithOk(packagesPath() + "?q=foo&subjectFacetCount=50"); + + wm.verify(1, getRequestedFor(urlPathEqualTo(packagesRmApi())) + .withQueryParam("subjectfacetcount", WireMock.equalTo("50"))); + } + + @Test + void shouldSendSubjectFilterToRmApiWhenCombinedWithTagsFilter() { + mockGet(matching(packagesRmApi() + ".*"), readFile(GET_PACKAGES_WITH_SUBJECT_FACETS_RESPONSE)); + + getWithOk(packagesPath() + "?filter[tags]=" + STUB_TAG_VALUE + "&filter[subject]=1"); + + wm.verify(1, getRequestedFor(urlPathEqualTo(packagesRmApi())) + .withQueryParam("subjectfilter", WireMock.equalTo("1"))); + } + + @Test + void shouldRequestSubjectFacetsWithoutSearchOrFilterAndReturnNullFacetsWhenAbsent() { + mockGet(matching(packagesRmApi() + ".*"), readFile(GET_PACKAGES_BY_PROVIDER_RESPONSE)); + + var actual = getWithOk(packagesPath()).as(PackageCollection.class); + + assertNull(actual.getFacets()); + wm.verify(1, getRequestedFor(urlPathEqualTo(packagesRmApi())) + .withQueryParam("facetstoinclude", WireMock.equalTo("subject")) + .withQueryParam("subjectfacetcount", WireMock.equalTo("1000")) + .withQueryParam("subjectfilter", WireMock.absent())); + } + @Test void shouldReturnPackagesOnSearchByTagsOnly() { saveTag(vertx, FULL_PACKAGE_ID, PACKAGE, STUB_TAG_VALUE); @@ -297,20 +357,12 @@ void shouldReturnEmptyResponseWhenPackagesReturnedWithErrorOnSearchByAccessType( assertEquals(2, (int) packageCollection.getMeta().getTotalResults()); } - @Test - void shouldReturn400OnInvalidFilterCustomParameter() { - var resourcePath = packagesPath() + "?filter[custom]=test"; - var response = getWithStatus(resourcePath, SC_BAD_REQUEST).asString(); + @ParameterizedTest(name = "{0}") + @MethodSource("invalidFilterParameters") + void shouldReturn400OnInvalidFilterParameter(String name, String queryParam, String expectedMessage) { + var response = getWithStatus(packagesPath() + "?" + queryParam, SC_BAD_REQUEST).asString(); - assertTrue(response.contains("Invalid Query Parameter for filter[custom]: only 'true' is supported")); - } - - @Test - void shouldReturn400OnNotSupportedFilterCustomParameter() { - var resourcePath = packagesPath() + "?filter[custom]=false"; - var response = getWithStatus(resourcePath, SC_BAD_REQUEST).asString(); - - assertTrue(response.contains("Invalid Query Parameter for filter[custom]: only 'true' is supported")); + assertTrue(response.contains(expectedMessage)); } @Test @@ -1143,6 +1195,16 @@ private String getPackageResponse(String packageName, int packageId, int provide .build()); } + static Stream invalidFilterParameters() { + var customMessage = "Invalid Query Parameter for filter[custom]: only 'true' is supported"; + var subjectMessage = "Invalid Query Parameter for filter[subject]: only numeric subject ids are supported"; + return Stream.of( + Arguments.of("invalid filter[custom]", "filter[custom]=test", customMessage), + Arguments.of("not supported filter[custom]", "filter[custom]=false", customMessage), + Arguments.of("non-numeric filter[subject]", "filter[subject]=test", subjectMessage) + ); + } + private void setUpPackages(Vertx vertx, String credentialsId) { setUpPackage(vertx, credentialsId, STUB_PACKAGE_ID, STUB_VENDOR_ID, STUB_PACKAGE_NAME); setUpPackage(vertx, credentialsId, STUB_PACKAGE_ID_2, STUB_VENDOR_ID_2, STUB_PACKAGE_NAME_2); diff --git a/src/test/java/org/folio/rest/model/filter/PackageRecordFilterTest.java b/src/test/java/org/folio/rest/model/filter/PackageRecordFilterTest.java new file mode 100644 index 00000000..4666a4a6 --- /dev/null +++ b/src/test/java/org/folio/rest/model/filter/PackageRecordFilterTest.java @@ -0,0 +1,114 @@ +package org.folio.rest.model.filter; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.Arrays; +import java.util.List; +import org.folio.properties.common.SearchProperties; +import org.folio.rest.exception.QueryParamsValidationException; +import org.folio.rest.model.filter.PackageRecordFilter.PackageRecordFilterBuilder; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.MethodSource; + +class PackageRecordFilterTest { + + private static final SearchProperties SEARCH_PROPERTIES = new SearchProperties("contains", "contains", "mark"); + + @Test + void shouldIncludeSubjectFacetWhenRequestedRegardlessOfFilters() { + var clientFilter = builder().build().toClientFilter(SEARCH_PROPERTIES); + + assertTrue(clientFilter.includeSubjectFacet()); + } + + @Test + void shouldNotIncludeSubjectFacetWhenNotRequested() { + var clientFilter = builder().query("foo").includeSubjectFacet(false).build().toClientFilter(SEARCH_PROPERTIES); + + assertFalse(clientFilter.includeSubjectFacet()); + } + + @Test + void shouldConvertFilterSubjectToIntegerIds() { + var clientFilter = builder().filterSubject(List.of("1", "22")).build().toClientFilter(SEARCH_PROPERTIES); + + assertEquals(List.of(1, 22), clientFilter.filterSubjectIds()); + } + + @Test + void shouldPassNullSubjectIdsToClientFilterWhenNotProvided() { + var clientFilter = builder().build().toClientFilter(SEARCH_PROPERTIES); + + assertNull(clientFilter.filterSubjectIds()); + } + + @Test + void shouldPassSubjectFacetCountToClientFilter() { + var clientFilter = builder().subjectFacetCount(50).build().toClientFilter(SEARCH_PROPERTIES); + + assertEquals(50, clientFilter.subjectFacetCount()); + } + + @Test + void shouldPassNullSubjectFacetCountToClientFilterWhenNotProvided() { + var clientFilter = builder().build().toClientFilter(SEARCH_PROPERTIES); + + assertNull(clientFilter.subjectFacetCount()); + } + + @Test + void shouldBeTagsFilterWhenOnlyTagsAreProvided() { + assertTrue(builder().filterTags(List.of("tag")).build().isTagsFilter()); + } + + @Test + void shouldNotBeTagsFilterWhenFilterSubjectIsProvidedWithTags() { + var filter = builder().filterTags(List.of("tag")).filterSubject(List.of("1")).build(); + + assertFalse(filter.isTagsFilter()); + } + + @Test + void shouldNotBeAccessTypeFilterWhenFilterSubjectIsProvidedWithAccessType() { + var filter = builder().filterAccessType(List.of("type")).filterSubject(List.of("1")).build(); + + assertFalse(filter.isAccessTypeFilter()); + } + + @Test + void shouldValidateFilterSubjectWhenProvidedWithTags() { + var builder = builder().filterTags(List.of("tag")).filterSubject(List.of("abc")); + + assertThrows(QueryParamsValidationException.class, builder::build); + } + + @ParameterizedTest(name = "{0}") + @MethodSource("invalidFilterSubjectCases") + void shouldFailValidationWhenFilterSubjectIsNotNumeric(String name, List filterSubject) { + var builder = builder().filterSubject(filterSubject); + + var exception = assertThrows(QueryParamsValidationException.class, builder::build); + + assertTrue(exception.getMessageDetail() + .contains(PackageFilterValidator.INVALID_FILTER_SUBJECT_PARAMETER_MESSAGE)); + } + + static List invalidFilterSubjectCases() { + return List.of( + new Object[] {"non-numeric", List.of("1", "abc")}, + new Object[] {"empty", List.of("")}, + new Object[] {"negative", List.of("-1")}, + new Object[] {"too large for integer", List.of("12345678901")}, + new Object[] {"null element", Arrays.asList("1", null)} + ); + } + + private static PackageRecordFilterBuilder builder() { + return PackageRecordFilter.builder().sort("relevance").page(1).count(25).includeSubjectFacet(true); + } +} diff --git a/src/test/resources/responses/rmapi/packages/get-packages-with-subject-facets-response.json b/src/test/resources/responses/rmapi/packages/get-packages-with-subject-facets-response.json new file mode 100644 index 00000000..09d62f90 --- /dev/null +++ b/src/test/resources/responses/rmapi/packages/get-packages-with-subject-facets-response.json @@ -0,0 +1,54 @@ +{ + "totalResults": 1, + "packagesList": [ + { + "listId": 3964, + "packageName": "TEST_PACKAGE_NAME", + "isCustom": true, + "vendorId": 19, + "vendorName": "TEST_VENDOR_NAME", + "titleCount": 5, + "isSelected": true, + "visibility": [ + { + "category": "PF", + "hidden": false, + "reason": "Hidden by customer" + } + ], + "selectedCount": 5, + "isTokenNeeded": false, + "contentType": "OnlineReference", + "customCoverage": { + "beginCoverage": "", + "endCoverage": "" + }, + "packageType": "Custom" + } + ], + "facets": { + "subjects": [ + { + "id": 2, + "parentId": 1, + "schema": "BISAC", + "name": "Genetics", + "count": 4 + }, + { + "id": 3, + "parentId": null, + "schema": "BISAC", + "name": "History", + "count": 20 + }, + { + "id": 1, + "parentId": null, + "schema": "BISAC", + "name": "Science", + "count": 10 + } + ] + } +}