From 83ab27597cc0e7a7e05b5db079e6cd90633e04ac Mon Sep 17 00:00:00 2001 From: viacheslav_kolesnyk Date: Thu, 15 Oct 2026 18:19:42 +0200 Subject: [PATCH 1/6] feat(packages): add subjects major headings facet to packages search Add filter[subject] query parameter to GET /eholdings/packages and return a facets.subjects list (major headings only, ordered by count descending) in the packages collection response. The facet is requested from HoldingsIQ only when a query or filter is present. Non-numeric filter[subject] values are rejected with 400. Bump eholdings interface to 5.1. Refs: MODKBEKBJ-850 --- NEWS.md | 3 +- descriptors/ModuleDescriptor-template.json | 2 +- ramls/packages.raml | 8 ++ ramls/types/facets.json | 8 ++ ramls/types/packages/packageCollection.json | 5 ++ ramls/types/packages/subjectFacet.json | 30 +++++++ .../converter/facets/FacetsConverter.java | 40 +++++++++- .../facets/SubjectFacetConverter.java | 19 +++++ .../packages/PackageCollectionConverter.java | 10 ++- .../PackageCollectionResultConverter.java | 11 ++- .../rest/impl/EholdingsPackagesImpl.java | 13 +-- .../model/filter/PackageFilterValidator.java | 17 +++- .../model/filter/PackageRecordFilter.java | 24 ++++++ .../converter/facets/FacetsConverterTest.java | 60 ++++++++++++++ .../PackageCollectionResultConverterTest.java | 33 ++++++++ .../rest/impl/EholdingsPackagesImplTest.java | 26 ++++-- .../EholdingsPackagesIntegrationTest.java | 41 ++++++++++ .../model/filter/PackageRecordFilterTest.java | 79 +++++++++++++++++++ ...packages-with-subject-facets-response.json | 54 +++++++++++++ 19 files changed, 463 insertions(+), 20 deletions(-) create mode 100644 ramls/types/packages/subjectFacet.json create mode 100644 src/main/java/org/folio/rest/converter/facets/SubjectFacetConverter.java create mode 100644 src/test/java/org/folio/rest/converter/facets/FacetsConverterTest.java create mode 100644 src/test/java/org/folio/rest/model/filter/PackageRecordFilterTest.java create mode 100644 src/test/resources/responses/rmapi/packages/get-packages-with-subject-facets-response.json diff --git a/NEWS.md b/NEWS.md index 07d6b90f1..69ba22615 100644 --- a/NEWS.md +++ b/NEWS.md @@ -3,7 +3,7 @@ * Drop `visibilityData` field from packages request/response ([MODKBEKBJ-835](https://folio-org.atlassian.net/browse/MODKBEKBJ-835)) ### New APIs versions -* Provides `eholdings v5.0` +* Provides `eholdings v5.1` * Requires `API_NAME vX.Y` ### Features @@ -15,6 +15,7 @@ * Sanitize HTML content for the package description field ([MODKBEKBJ-860](https://folio-org.atlassian.net/browse/MODKBEKBJ-860)) * 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)) +* 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/descriptors/ModuleDescriptor-template.json b/descriptors/ModuleDescriptor-template.json index 982828463..708528a2a 100644 --- a/descriptors/ModuleDescriptor-template.json +++ b/descriptors/ModuleDescriptor-template.json @@ -4,7 +4,7 @@ "provides": [ { "id": "eholdings", - "version": "5.0", + "version": "5.1", "handlers": [ { "methods": ["GET"], diff --git a/ramls/packages.raml b/ramls/packages.raml index 205935605..d25c529e8 100644 --- a/ramls/packages.raml +++ b/ramls/packages.raml @@ -48,6 +48,14 @@ types: - true example: "true" required: false + filter[subject]: + displayName: Subject + type: string[] + description: | + Filter to narrow down results based on subject ids (major headings). + Only numeric subject ids are supported (for example 26224); the parameter is repeatable (OR semantics). + Packages that have any of the specified subjects are returned. + required: false responses: 200: description: OK diff --git a/ramls/types/facets.json b/ramls/types/facets.json index ebec04796..efb7b2d0a 100644 --- a/ramls/types/facets.json +++ b/ramls/types/facets.json @@ -13,6 +13,14 @@ "type": "object", "$ref": "packages/packageFacet.json" } + }, + "subjects": { + "type": "array", + "description": "Subject (major heading) facets", + "items": { + "type": "object", + "$ref": "packages/subjectFacet.json" + } } } } diff --git a/ramls/types/packages/packageCollection.json b/ramls/types/packages/packageCollection.json index 3e5a331c1..0e7e34e88 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": "../facets.json" + }, "meta": { "type": "object", "description": "metadata containing total results in packages collection", diff --git a/ramls/types/packages/subjectFacet.json b/ramls/types/packages/subjectFacet.json new file mode 100644 index 000000000..b6e91c33d --- /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/FacetsConverter.java b/src/main/java/org/folio/rest/converter/facets/FacetsConverter.java index a207774ed..ba7f880b0 100644 --- a/src/main/java/org/folio/rest/converter/facets/FacetsConverter.java +++ b/src/main/java/org/folio/rest/converter/facets/FacetsConverter.java @@ -1,27 +1,59 @@ package org.folio.rest.converter.facets; -import static org.folio.common.ListUtils.mapItems; +import static org.folio.common.ListUtils.mapItemsNullable; +import java.util.Comparator; +import java.util.List; import org.folio.holdingsiq.model.Facets; import org.folio.holdingsiq.model.PackageFacet; +import org.folio.holdingsiq.model.SubjectFacet; import org.folio.rest.jaxrs.model.FacetsDto; import org.folio.rest.jaxrs.model.PackageFacetDto; +import org.folio.rest.jaxrs.model.SubjectFacetDto; +import org.jspecify.annotations.Nullable; import org.springframework.core.convert.converter.Converter; import org.springframework.stereotype.Component; @Component public final class FacetsConverter implements Converter { + // Keep in sync with the default subjectfacetcount sent to HoldingsIQ by folio-holdingsiq-client + static final int MAX_SUBJECT_FACETS = 1000; + private final Converter packageFacetConverter; + private final Converter subjectFacetConverter; - public FacetsConverter(Converter packageFacetConverter) { + public FacetsConverter(Converter packageFacetConverter, + Converter subjectFacetConverter) { this.packageFacetConverter = packageFacetConverter; + this.subjectFacetConverter = subjectFacetConverter; } @Override public FacetsDto convert(Facets facets) { - var packages = mapItems(facets.getPackages(), packageFacetConverter::convert); + var packages = mapItemsNullable(facets.getPackages(), packageFacetConverter::convert); return new FacetsDto() - .withPackages(packages); + .withPackages(packages) + .withSubjects(convertSubjects(facets.getSubjects())); + } + + /** + * Keeps only major headings (subjects without a parent), orders them by descending count and caps the result. + * Counts are passed through as returned by HoldingsIQ. + */ + private @Nullable List convertSubjects(@Nullable List subjects) { + if (subjects == null) { + return null; + } + return subjects.stream() + .filter(subject -> subject.parentId() == null) + .sorted(Comparator.comparingInt(FacetsConverter::countOf).reversed()) + .limit(MAX_SUBJECT_FACETS) + .map(subjectFacetConverter::convert) + .toList(); + } + + private static int countOf(SubjectFacet subject) { + return subject.totalCount() == null ? 0 : subject.totalCount(); } } 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 000000000..b2a445279 --- /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 e926582e2..4c8f59f83 100644 --- a/src/main/java/org/folio/rest/converter/packages/PackageCollectionConverter.java +++ b/src/main/java/org/folio/rest/converter/packages/PackageCollectionConverter.java @@ -1,10 +1,13 @@ 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.FacetsDto; import org.folio.rest.jaxrs.model.MetaTotalResults; import org.folio.rest.jaxrs.model.PackageCollection; import org.folio.rest.jaxrs.model.PackageCollectionItem; @@ -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 9b6c89133..e11712c11 100644 --- a/src/main/java/org/folio/rest/converter/packages/PackageCollectionResultConverter.java +++ b/src/main/java/org/folio/rest/converter/packages/PackageCollectionResultConverter.java @@ -1,15 +1,18 @@ 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; import org.folio.repository.packages.DbPackage; import org.folio.rest.jaxrs.model.AccessType; +import org.folio.rest.jaxrs.model.FacetsDto; import org.folio.rest.jaxrs.model.HasOneRelationship; import org.folio.rest.jaxrs.model.MetaDataIncluded; import org.folio.rest.jaxrs.model.MetaTotalResults; @@ -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 6777a2675..75bfa8d71 100644 --- a/src/main/java/org/folio/rest/impl/EholdingsPackagesImpl.java +++ b/src/main/java/org/folio/rest/impl/EholdingsPackagesImpl.java @@ -73,11 +73,12 @@ 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, - Handler> asyncResultHandler, Context vertxContext) { + public void getEholdingsPackages(String filterCustom, List filterSubject, 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) .queryField(queryField) @@ -90,6 +91,8 @@ public void getEholdingsPackages(String filterCustom, String q, String queryFiel .filterFreeAccess(filterFreeAccess) .filterTags(filterTags) .filterAccessType(filterAccessType) + .filterSubject(filterSubject) + .includeSubjectFacet(true) .sort(sort) .page(page) .count(count) 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 d173b981d..7fa4cfb55 100644 --- a/src/main/java/org/folio/rest/model/filter/PackageFilterValidator.java +++ b/src/main/java/org/folio/rest/model/filter/PackageFilterValidator.java @@ -7,6 +7,7 @@ import static org.folio.rest.util.RestConstants.FILTER_VISIBILITY_MAPPING; import static org.folio.rest.util.RestConstants.SUPPORTED_PACKAGE_FILTER_TYPE_VALUES; +import java.util.ArrayList; import java.util.List; import java.util.Optional; import org.folio.holdingsiq.model.PackageSearchField; @@ -28,6 +29,8 @@ public final class PackageFilterValidator implements FilterValidator> VALIDATORS = List.of( of(PackageRecordFilter::getSort, PackageFilterValidator::isSortValid, INVALID_SORT_PARAMETER_MESSAGE), @@ -54,16 +57,26 @@ public void validate(@NonNull PackageRecordFilter filter) { || isNotEmpty(filter.getFilterAccessType())) { return; } - var failMessages = VALIDATORS.stream() + var failMessages = new ArrayList<>(VALIDATORS.stream() .map(logic -> validate(filter, logic)) .filter(Optional::isPresent) .map(Optional::get) - .toList(); + .toList()); + if (!isFilterSubjectValid(filter.getFilterSubject())) { + failMessages.add(INVALID_FILTER_SUBJECT_PARAMETER_MESSAGE); + } if (!failMessages.isEmpty()) { throw new QueryParamsValidationException(failMessages); } } + private static boolean isFilterSubjectValid(List filterSubject) { + if (filterSubject == null) { + return true; + } + return filterSubject.stream().allMatch(subject -> subject != null && subject.matches("\\d{1,9}")); + } + 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 111d56e72..c5dd42af7 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,9 @@ package org.folio.rest.model.filter; import static java.util.Arrays.asList; +import static org.apache.commons.collections4.CollectionUtils.isEmpty; +import static org.apache.commons.collections4.CollectionUtils.isNotEmpty; +import static org.apache.commons.lang3.StringUtils.isNotBlank; import java.util.List; import java.util.Optional; @@ -23,6 +26,7 @@ public class PackageRecordFilter implements Filter { private static final FilterValidator VALIDATOR = new PackageFilterValidator(); + private static final String ALL_FILTER_VALUE = "all"; String query; String queryField; @@ -40,6 +44,8 @@ public class PackageRecordFilter implements Filter { int count; List filterTags; List filterAccessType; + List filterSubject; + boolean includeSubjectFacet; public static PackageRecordFilterBuilder builder() { return new PackageRecordFilterBuilder() { @@ -104,6 +110,24 @@ public PackageFilter toClientFilter(SearchProperties searchProperties) { .filterType(getPackageFilterType().orElse(null)) .filterPackageFreeAccess(getPackageFilterFreeAccess().orElse(null)) .filterVisibility(getPackageFilterVisibility().orElse(null)) + .includeSubjectFacet(includeSubjectFacet && isSearchOrFilterApplied()) + .filterSubjectIds(parseSubjectIds()) .build(); } + + private List parseSubjectIds() { + return isEmpty(filterSubject) ? null : filterSubject.stream().map(Integer::valueOf).toList(); + } + + private boolean isSearchOrFilterApplied() { + return isNotBlank(query) + || isNotEmpty(filterSubject) + || isFilterApplied(filterType) + || isFilterApplied(filterSelected) + || isNotBlank(filterFreeAccess); + } + + private static boolean isFilterApplied(String filterValue) { + return isNotBlank(filterValue) && !ALL_FILTER_VALUE.equalsIgnoreCase(filterValue); + } } diff --git a/src/test/java/org/folio/rest/converter/facets/FacetsConverterTest.java b/src/test/java/org/folio/rest/converter/facets/FacetsConverterTest.java new file mode 100644 index 000000000..bbdfbf5f1 --- /dev/null +++ b/src/test/java/org/folio/rest/converter/facets/FacetsConverterTest.java @@ -0,0 +1,60 @@ +package org.folio.rest.converter.facets; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNull; + +import java.util.ArrayList; +import java.util.List; +import org.folio.holdingsiq.model.Facets; +import org.folio.holdingsiq.model.SubjectFacet; +import org.junit.jupiter.api.Test; + +class FacetsConverterTest { + + private final FacetsConverter converter = new FacetsConverter(new PackageFacetConverter(), + new SubjectFacetConverter()); + + @Test + void shouldReturnOnlyMajorHeadingsWithOriginalCounts() { + 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(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 shouldOrderByDescendingCountAndLimitTo1000Values() { + var subjects = new ArrayList(); + for (int i = 1; i <= 1100; i++) { + subjects.add(new SubjectFacet(i, null, "BISAC", "Subject " + i, i)); + } + + var result = converter.convert(Facets.builder().subjects(subjects).build()); + + var converted = result.getSubjects(); + assertEquals(1000, converted.size()); + assertEquals(1100, converted.getFirst().getCount()); + assertEquals(101, converted.getLast().getCount()); + assertEquals(converted, converted.stream() + .sorted((a, b) -> b.getCount().compareTo(a.getCount())) + .toList()); + } + + @Test + void shouldReturnNullSubjectsAndPackagesWhenNotPresent() { + var result = converter.convert(Facets.builder().build()); + + assertNull(result.getSubjects()); + assertNull(result.getPackages()); + } +} 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 cef6db1bf..e681d170e 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,34 @@ 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()); + } + + @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 4ee5f59be..f45ad3833 100644 --- a/src/test/java/org/folio/rest/impl/EholdingsPackagesImplTest.java +++ b/src/test/java/org/folio/rest/impl/EholdingsPackagesImplTest.java @@ -131,7 +131,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 +144,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 +153,21 @@ void shouldRetrieveAllPackagesWhenFilterCustomIsNotSet() { verify(packageService).retrievePackages(null, filter, context); } + @Test + void shouldPassFilterSubjectToPackageRecordFilter() { + var filter = PackageRecordFilter.builder().query("foo").filterSubject(List.of("1", "2")).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(true, filterCaptor.getValue().isIncludeSubjectFacet()); + } + @Test void shouldCreateCustomPackage() { var entity = new PackagePostRequest() @@ -317,9 +333,9 @@ 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(), + impl.getEholdingsPackages(filter.getFilterCustom(), filter.getFilterSubject(), 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); } diff --git a/src/test/java/org/folio/rest/impl/EholdingsPackagesIntegrationTest.java b/src/test/java/org/folio/rest/impl/EholdingsPackagesIntegrationTest.java index e7331a4ce..ada2bc5d3 100644 --- a/src/test/java/org/folio/rest/impl/EholdingsPackagesIntegrationTest.java +++ b/src/test/java/org/folio/rest/impl/EholdingsPackagesIntegrationTest.java @@ -110,6 +110,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 +217,45 @@ 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("subjectfilter", WireMock.equalTo("1,2"))); + } + + @Test + void shouldNotRequestSubjectFacetsWhenNoSearchOrFilterIsApplied() { + 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.absent()) + .withQueryParam("subjectfilter", WireMock.absent())); + } + + @Test + void shouldReturn400OnNonNumericFilterSubject() { + var response = getWithStatus(packagesPath() + "?filter[subject]=abc", SC_BAD_REQUEST).asString(); + + assertTrue(response.contains("Invalid Query Parameter for filter[subject]")); + } + @Test void shouldReturnPackagesOnSearchByTagsOnly() { saveTag(vertx, FULL_PACKAGE_ID, PACKAGE, STUB_TAG_VALUE); 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 000000000..e5fc21b3c --- /dev/null +++ b/src/test/java/org/folio/rest/model/filter/PackageRecordFilterTest.java @@ -0,0 +1,79 @@ +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.ArrayList; +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"); + + static List facetRequestCases() { + return List.of( + new Object[] {"no query or filters", builder(), false}, + new Object[] {"filterType=all", builder().filterType("all"), false}, + new Object[] {"query", builder().query("foo"), true}, + new Object[] {"filterType=ebook", builder().filterType("ebook"), true}, + new Object[] {"filterSelected=true", builder().filterSelected("true"), true}, + new Object[] {"filterFreeAccess=public", builder().filterFreeAccess("public"), true}, + new Object[] {"filterSubject", builder().filterSubject(List.of("1")), true}, + new Object[] {"includeSubjectFacet=false with query", + builder().query("foo").includeSubjectFacet(false), false} + ); + } + + @ParameterizedTest(name = "{0}") + @MethodSource("facetRequestCases") + void shouldResolveIncludeSubjectFacet(String name, PackageRecordFilterBuilder builder, boolean expected) { + var clientFilter = builder.build().toClientFilter(SEARCH_PROPERTIES); + + assertEquals(expected, clientFilter.includeSubjectFacet()); + } + + @Test + void shouldConvertFilterSubjectToIntegerIds() { + var filter = builder().filterSubject(List.of("1", "22")).build(); + + assertEquals(List.of(1, 22), filter.toClientFilter(SEARCH_PROPERTIES).filterSubjectIds()); + } + + @Test + void shouldReturnNullSubjectIdsWhenFilterSubjectIsNullOrEmpty() { + assertNull(builder().build().toClientFilter(SEARCH_PROPERTIES).filterSubjectIds()); + assertNull(builder().filterSubject(new ArrayList<>()).build().toClientFilter(SEARCH_PROPERTIES) + .filterSubjectIds()); + } + + @Test + void shouldFailValidationWhenFilterSubjectIsNotNumeric() { + var builder = builder().filterSubject(Arrays.asList("1", "abc")); + + var exception = assertThrows(QueryParamsValidationException.class, builder::build); + + assertTrue(exception.getMessageDetail() + .contains(PackageFilterValidator.INVALID_FILTER_SUBJECT_PARAMETER_MESSAGE)); + } + + @Test + void shouldPassValidationWhenFilterSubjectIsNumeric() { + var filter = builder().filterSubject(List.of("26224")).build(); + + assertFalse(filter.getFilterSubject().isEmpty()); + } + + 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 000000000..09d62f90f --- /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 + } + ] + } +} From 2abd27cf53a546f4df8fe5f4594a17e069442cbf Mon Sep 17 00:00:00 2001 From: viacheslav_kolesnyk Date: Mon, 19 Oct 2026 12:38:00 +0200 Subject: [PATCH 2/6] Refactor package subject filter/facets --- NEWS.md | 2 +- descriptors/ModuleDescriptor-template.json | 2 +- ramls/packages.raml | 12 ++- ramls/types/facets.json | 8 -- ramls/types/packages/packageCollection.json | 2 +- ramls/types/packages/packageFacets.json | 18 ++++ .../converter/facets/FacetsConverter.java | 40 +-------- .../facets/PackageFacetsConverter.java | 40 +++++++++ .../packages/PackageCollectionConverter.java | 6 +- .../PackageCollectionResultConverter.java | 6 +- .../rest/impl/EholdingsPackagesImpl.java | 13 +-- .../rest/model/filter/FilterValidator.java | 2 +- .../model/filter/FilterValidatorLogic.java | 12 +-- .../model/filter/PackageFilterValidator.java | 23 +++-- .../model/filter/PackageRecordFilter.java | 24 +++--- .../converter/facets/FacetsConverterTest.java | 60 ------------- .../facets/PackageFacetsConverterTest.java | 81 ++++++++++++++++++ .../PackageCollectionResultConverterTest.java | 1 + .../rest/impl/EholdingsPackagesImplTest.java | 33 +++++-- .../EholdingsPackagesIntegrationTest.java | 25 +++++- .../model/filter/PackageRecordFilterTest.java | 85 ++++++++++++++----- 21 files changed, 310 insertions(+), 185 deletions(-) create mode 100644 ramls/types/packages/packageFacets.json create mode 100644 src/main/java/org/folio/rest/converter/facets/PackageFacetsConverter.java delete mode 100644 src/test/java/org/folio/rest/converter/facets/FacetsConverterTest.java create mode 100644 src/test/java/org/folio/rest/converter/facets/PackageFacetsConverterTest.java diff --git a/NEWS.md b/NEWS.md index 69ba22615..2a289c7f1 100644 --- a/NEWS.md +++ b/NEWS.md @@ -3,7 +3,7 @@ * Drop `visibilityData` field from packages request/response ([MODKBEKBJ-835](https://folio-org.atlassian.net/browse/MODKBEKBJ-835)) ### New APIs versions -* Provides `eholdings v5.1` +* Provides `eholdings v5.0` * Requires `API_NAME vX.Y` ### Features diff --git a/descriptors/ModuleDescriptor-template.json b/descriptors/ModuleDescriptor-template.json index 708528a2a..982828463 100644 --- a/descriptors/ModuleDescriptor-template.json +++ b/descriptors/ModuleDescriptor-template.json @@ -4,7 +4,7 @@ "provides": [ { "id": "eholdings", - "version": "5.1", + "version": "5.0", "handlers": [ { "methods": ["GET"], diff --git a/ramls/packages.raml b/ramls/packages.raml index d25c529e8..0aafab1a2 100644 --- a/ramls/packages.raml +++ b/ramls/packages.raml @@ -53,8 +53,16 @@ types: type: string[] description: | Filter to narrow down results based on subject ids (major headings). - Only numeric subject ids are supported (for example 26224); the parameter is repeatable (OR semantics). - Packages that have any of the specified subjects are returned. + Each value must be an integer subject id (for example 26224). + The parameter is repeatable (OR semantics): packages that have any 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: diff --git a/ramls/types/facets.json b/ramls/types/facets.json index efb7b2d0a..ebec04796 100644 --- a/ramls/types/facets.json +++ b/ramls/types/facets.json @@ -13,14 +13,6 @@ "type": "object", "$ref": "packages/packageFacet.json" } - }, - "subjects": { - "type": "array", - "description": "Subject (major heading) facets", - "items": { - "type": "object", - "$ref": "packages/subjectFacet.json" - } } } } diff --git a/ramls/types/packages/packageCollection.json b/ramls/types/packages/packageCollection.json index 0e7e34e88..a8affa958 100644 --- a/ramls/types/packages/packageCollection.json +++ b/ramls/types/packages/packageCollection.json @@ -17,7 +17,7 @@ "facets": { "type": "object", "description": "Facets for a package collection", - "$ref": "../facets.json" + "$ref": "packageFacets.json" }, "meta": { "type": "object", diff --git a/ramls/types/packages/packageFacets.json b/ramls/types/packages/packageFacets.json new file mode 100644 index 000000000..70a42fc83 --- /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/src/main/java/org/folio/rest/converter/facets/FacetsConverter.java b/src/main/java/org/folio/rest/converter/facets/FacetsConverter.java index ba7f880b0..a207774ed 100644 --- a/src/main/java/org/folio/rest/converter/facets/FacetsConverter.java +++ b/src/main/java/org/folio/rest/converter/facets/FacetsConverter.java @@ -1,59 +1,27 @@ package org.folio.rest.converter.facets; -import static org.folio.common.ListUtils.mapItemsNullable; +import static org.folio.common.ListUtils.mapItems; -import java.util.Comparator; -import java.util.List; import org.folio.holdingsiq.model.Facets; import org.folio.holdingsiq.model.PackageFacet; -import org.folio.holdingsiq.model.SubjectFacet; import org.folio.rest.jaxrs.model.FacetsDto; import org.folio.rest.jaxrs.model.PackageFacetDto; -import org.folio.rest.jaxrs.model.SubjectFacetDto; -import org.jspecify.annotations.Nullable; import org.springframework.core.convert.converter.Converter; import org.springframework.stereotype.Component; @Component public final class FacetsConverter implements Converter { - // Keep in sync with the default subjectfacetcount sent to HoldingsIQ by folio-holdingsiq-client - static final int MAX_SUBJECT_FACETS = 1000; - private final Converter packageFacetConverter; - private final Converter subjectFacetConverter; - public FacetsConverter(Converter packageFacetConverter, - Converter subjectFacetConverter) { + public FacetsConverter(Converter packageFacetConverter) { this.packageFacetConverter = packageFacetConverter; - this.subjectFacetConverter = subjectFacetConverter; } @Override public FacetsDto convert(Facets facets) { - var packages = mapItemsNullable(facets.getPackages(), packageFacetConverter::convert); + var packages = mapItems(facets.getPackages(), packageFacetConverter::convert); return new FacetsDto() - .withPackages(packages) - .withSubjects(convertSubjects(facets.getSubjects())); - } - - /** - * Keeps only major headings (subjects without a parent), orders them by descending count and caps the result. - * Counts are passed through as returned by HoldingsIQ. - */ - private @Nullable List convertSubjects(@Nullable List subjects) { - if (subjects == null) { - return null; - } - return subjects.stream() - .filter(subject -> subject.parentId() == null) - .sorted(Comparator.comparingInt(FacetsConverter::countOf).reversed()) - .limit(MAX_SUBJECT_FACETS) - .map(subjectFacetConverter::convert) - .toList(); - } - - private static int countOf(SubjectFacet subject) { - return subject.totalCount() == null ? 0 : subject.totalCount(); + .withPackages(packages); } } 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 000000000..e4059aa5b --- /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/packages/PackageCollectionConverter.java b/src/main/java/org/folio/rest/converter/packages/PackageCollectionConverter.java index 4c8f59f83..e8f02347d 100644 --- a/src/main/java/org/folio/rest/converter/packages/PackageCollectionConverter.java +++ b/src/main/java/org/folio/rest/converter/packages/PackageCollectionConverter.java @@ -7,10 +7,10 @@ import org.folio.holdingsiq.model.Facets; import org.folio.holdingsiq.model.PackageData; import org.folio.holdingsiq.model.Packages; -import org.folio.rest.jaxrs.model.FacetsDto; 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; @@ -19,10 +19,10 @@ public class PackageCollectionConverter implements Converter { private final Converter packageCollectionItemConverter; - private final Converter facetsConverter; + private final Converter facetsConverter; public PackageCollectionConverter(Converter packageCollectionItemConverter, - Converter facetsConverter) { + Converter facetsConverter) { this.packageCollectionItemConverter = packageCollectionItemConverter; this.facetsConverter = facetsConverter; } 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 e11712c11..b7281aac0 100644 --- a/src/main/java/org/folio/rest/converter/packages/PackageCollectionResultConverter.java +++ b/src/main/java/org/folio/rest/converter/packages/PackageCollectionResultConverter.java @@ -12,12 +12,12 @@ import org.folio.repository.accesstypes.DbAccessType; import org.folio.repository.packages.DbPackage; import org.folio.rest.jaxrs.model.AccessType; -import org.folio.rest.jaxrs.model.FacetsDto; import org.folio.rest.jaxrs.model.HasOneRelationship; import org.folio.rest.jaxrs.model.MetaDataIncluded; 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; @@ -30,12 +30,12 @@ public class PackageCollectionResultConverter implements Converter packageCollectionItemConverter; private final Converter accessTypeConverter; - private final Converter facetsConverter; + private final Converter facetsConverter; public PackageCollectionResultConverter( Converter packageCollectionItemConverter, Converter accessTypeConverter, - Converter facetsConverter) { + Converter facetsConverter) { this.packageCollectionItemConverter = packageCollectionItemConverter; this.accessTypeConverter = accessTypeConverter; this.facetsConverter = facetsConverter; diff --git a/src/main/java/org/folio/rest/impl/EholdingsPackagesImpl.java b/src/main/java/org/folio/rest/impl/EholdingsPackagesImpl.java index 75bfa8d71..615a6c408 100644 --- a/src/main/java/org/folio/rest/impl/EholdingsPackagesImpl.java +++ b/src/main/java/org/folio/rest/impl/EholdingsPackagesImpl.java @@ -73,12 +73,12 @@ public EholdingsPackagesImpl() { @Override @Validate @HandleValidationErrors - public void getEholdingsPackages(String filterCustom, List filterSubject, 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) { + 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) .queryField(queryField) @@ -92,6 +92,7 @@ public void getEholdingsPackages(String filterCustom, List filterSubject .filterTags(filterTags) .filterAccessType(filterAccessType) .filterSubject(filterSubject) + .subjectFacetCount(subjectFacetCount > 0 ? subjectFacetCount : null) .includeSubjectFacet(true) .sort(sort) .page(page) 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 45dd20de4..89251eb4b 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 40b1d7f14..ad394458a 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 7fa4cfb55..2e82a7aae 100644 --- a/src/main/java/org/folio/rest/model/filter/PackageFilterValidator.java +++ b/src/main/java/org/folio/rest/model/filter/PackageFilterValidator.java @@ -1,15 +1,14 @@ 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; import static org.folio.rest.util.RestConstants.FILTER_VISIBILITY_MAPPING; import static org.folio.rest.util.RestConstants.SUPPORTED_PACKAGE_FILTER_TYPE_VALUES; -import java.util.ArrayList; 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; @@ -32,7 +31,9 @@ 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), @@ -48,23 +49,21 @@ public final class PackageFilterValidator implements FilterValidator(VALIDATORS.stream() + var failMessages = VALIDATORS.stream() .map(logic -> validate(filter, logic)) .filter(Optional::isPresent) .map(Optional::get) - .toList()); - if (!isFilterSubjectValid(filter.getFilterSubject())) { - failMessages.add(INVALID_FILTER_SUBJECT_PARAMETER_MESSAGE); - } + .toList(); if (!failMessages.isEmpty()) { throw new QueryParamsValidationException(failMessages); } @@ -74,7 +73,7 @@ private static boolean isFilterSubjectValid(List filterSubject) { if (filterSubject == null) { return true; } - return filterSubject.stream().allMatch(subject -> subject != null && subject.matches("\\d{1,9}")); + return filterSubject.stream().allMatch(id -> id != null && SUBJECT_ID_PATTERN.matcher(id).matches()); } private static boolean isFilterFreeAccessValid(String filterFreeAccess) { 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 c5dd42af7..7b254825a 100644 --- a/src/main/java/org/folio/rest/model/filter/PackageRecordFilter.java +++ b/src/main/java/org/folio/rest/model/filter/PackageRecordFilter.java @@ -4,6 +4,7 @@ import static org.apache.commons.collections4.CollectionUtils.isEmpty; import static org.apache.commons.collections4.CollectionUtils.isNotEmpty; import static org.apache.commons.lang3.StringUtils.isNotBlank; +import static org.folio.common.ListUtils.mapItemsNullable; import java.util.List; import java.util.Optional; @@ -26,7 +27,6 @@ public class PackageRecordFilter implements Filter { private static final FilterValidator VALIDATOR = new PackageFilterValidator(); - private static final String ALL_FILTER_VALUE = "all"; String query; String queryField; @@ -45,6 +45,7 @@ public class PackageRecordFilter implements Filter { List filterTags; List filterAccessType; List filterSubject; + Integer subjectFacetCount; boolean includeSubjectFacet; public static PackageRecordFilterBuilder builder() { @@ -89,7 +90,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() { @@ -111,23 +112,18 @@ public PackageFilter toClientFilter(SearchProperties searchProperties) { .filterPackageFreeAccess(getPackageFilterFreeAccess().orElse(null)) .filterVisibility(getPackageFilterVisibility().orElse(null)) .includeSubjectFacet(includeSubjectFacet && isSearchOrFilterApplied()) - .filterSubjectIds(parseSubjectIds()) + .subjectFacetCount(subjectFacetCount) + .filterSubjectIds(mapItemsNullable(filterSubject, Integer::valueOf)) .build(); } - private List parseSubjectIds() { - return isEmpty(filterSubject) ? null : filterSubject.stream().map(Integer::valueOf).toList(); - } - private boolean isSearchOrFilterApplied() { return isNotBlank(query) || isNotEmpty(filterSubject) - || isFilterApplied(filterType) - || isFilterApplied(filterSelected) - || isNotBlank(filterFreeAccess); - } - - private static boolean isFilterApplied(String filterValue) { - return isNotBlank(filterValue) && !ALL_FILTER_VALUE.equalsIgnoreCase(filterValue); + || getPackageFilterType().filter(type -> type != PackageFilterType.ALL).isPresent() + || isNotBlank(filterSelected) + || isNotBlank(filterFreeAccess) + || isNotBlank(filterVisibility) + || isNotBlank(filterCustom); } } diff --git a/src/test/java/org/folio/rest/converter/facets/FacetsConverterTest.java b/src/test/java/org/folio/rest/converter/facets/FacetsConverterTest.java deleted file mode 100644 index bbdfbf5f1..000000000 --- a/src/test/java/org/folio/rest/converter/facets/FacetsConverterTest.java +++ /dev/null @@ -1,60 +0,0 @@ -package org.folio.rest.converter.facets; - -import static org.junit.jupiter.api.Assertions.assertEquals; -import static org.junit.jupiter.api.Assertions.assertNull; - -import java.util.ArrayList; -import java.util.List; -import org.folio.holdingsiq.model.Facets; -import org.folio.holdingsiq.model.SubjectFacet; -import org.junit.jupiter.api.Test; - -class FacetsConverterTest { - - private final FacetsConverter converter = new FacetsConverter(new PackageFacetConverter(), - new SubjectFacetConverter()); - - @Test - void shouldReturnOnlyMajorHeadingsWithOriginalCounts() { - 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(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 shouldOrderByDescendingCountAndLimitTo1000Values() { - var subjects = new ArrayList(); - for (int i = 1; i <= 1100; i++) { - subjects.add(new SubjectFacet(i, null, "BISAC", "Subject " + i, i)); - } - - var result = converter.convert(Facets.builder().subjects(subjects).build()); - - var converted = result.getSubjects(); - assertEquals(1000, converted.size()); - assertEquals(1100, converted.getFirst().getCount()); - assertEquals(101, converted.getLast().getCount()); - assertEquals(converted, converted.stream() - .sorted((a, b) -> b.getCount().compareTo(a.getCount())) - .toList()); - } - - @Test - void shouldReturnNullSubjectsAndPackagesWhenNotPresent() { - var result = converter.convert(Facets.builder().build()); - - assertNull(result.getSubjects()); - assertNull(result.getPackages()); - } -} 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 000000000..51ff66828 --- /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 e681d170e..0df8e848e 100644 --- a/src/test/java/org/folio/rest/converter/packages/PackageCollectionResultConverterTest.java +++ b/src/test/java/org/folio/rest/converter/packages/PackageCollectionResultConverterTest.java @@ -99,6 +99,7 @@ void shouldMapSubjectFacetsWhenFacetsArePresent() { assertNotNull(packageCollection.getFacets()); assertEquals(1, packageCollection.getFacets().getSubjects().size()); assertEquals("Science", packageCollection.getFacets().getSubjects().getFirst().getName()); + assertEquals(10, packageCollection.getFacets().getSubjects().getFirst().getCount()); } @Test diff --git a/src/test/java/org/folio/rest/impl/EholdingsPackagesImplTest.java b/src/test/java/org/folio/rest/impl/EholdingsPackagesImplTest.java index f45ad3833..2ccb33e77 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; @@ -155,8 +157,8 @@ void shouldRetrieveAllPackagesWhenFilterCustomIsNotSet() { @Test void shouldPassFilterSubjectToPackageRecordFilter() { - var filter = PackageRecordFilter.builder().query("foo").filterSubject(List.of("1", "2")).includeSubjectFacet(true) - .sort("relevance").page(1).count(25).build(); + 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); @@ -165,7 +167,21 @@ void shouldPassFilterSubjectToPackageRecordFilter() { var filterCaptor = ArgumentCaptor.forClass(PackageRecordFilter.class); verify(packageService).retrievePackages(eq(null), filterCaptor.capture(), eq(context)); assertEquals(List.of("1", "2"), filterCaptor.getValue().getFilterSubject()); - assertEquals(true, filterCaptor.getValue().isIncludeSubjectFacet()); + 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 @@ -333,11 +349,12 @@ private Function> captureRequestActio } private void invokeGetEholdingsPackages(PackageRecordFilter filter) { - impl.getEholdingsPackages(filter.getFilterCustom(), filter.getFilterSubject(), 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 ada2bc5d3..406246133 100644 --- a/src/test/java/org/folio/rest/impl/EholdingsPackagesIntegrationTest.java +++ b/src/test/java/org/folio/rest/impl/EholdingsPackagesIntegrationTest.java @@ -234,9 +234,30 @@ void shouldReturnSubjectFacetsAndSendSubjectFilterToRmApi() { 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 shouldNotRequestSubjectFacetsWhenNoSearchOrFilterIsApplied() { mockGet(matching(packagesRmApi() + ".*"), readFile(GET_PACKAGES_BY_PROVIDER_RESPONSE)); @@ -251,9 +272,7 @@ void shouldNotRequestSubjectFacetsWhenNoSearchOrFilterIsApplied() { @Test void shouldReturn400OnNonNumericFilterSubject() { - var response = getWithStatus(packagesPath() + "?filter[subject]=abc", SC_BAD_REQUEST).asString(); - - assertTrue(response.contains("Invalid Query Parameter for filter[subject]")); + getWithStatus(packagesPath() + "?filter[subject]=abc", SC_BAD_REQUEST); } @Test diff --git a/src/test/java/org/folio/rest/model/filter/PackageRecordFilterTest.java b/src/test/java/org/folio/rest/model/filter/PackageRecordFilterTest.java index e5fc21b3c..175a0f474 100644 --- a/src/test/java/org/folio/rest/model/filter/PackageRecordFilterTest.java +++ b/src/test/java/org/folio/rest/model/filter/PackageRecordFilterTest.java @@ -6,7 +6,6 @@ import static org.junit.jupiter.api.Assertions.assertThrows; import static org.junit.jupiter.api.Assertions.assertTrue; -import java.util.ArrayList; import java.util.Arrays; import java.util.List; import org.folio.properties.common.SearchProperties; @@ -23,14 +22,16 @@ class PackageRecordFilterTest { static List facetRequestCases() { return List.of( new Object[] {"no query or filters", builder(), false}, - new Object[] {"filterType=all", builder().filterType("all"), false}, + new Object[] {"blank query", builder().query(" "), false}, + new Object[] {"default filterType (all)", builder().filterType("all"), false}, new Object[] {"query", builder().query("foo"), true}, - new Object[] {"filterType=ebook", builder().filterType("ebook"), true}, - new Object[] {"filterSelected=true", builder().filterSelected("true"), true}, - new Object[] {"filterFreeAccess=public", builder().filterFreeAccess("public"), true}, + new Object[] {"filterType", builder().filterType("ebook"), true}, + new Object[] {"filterSelected", builder().filterSelected("true"), true}, + new Object[] {"filterFreeAccess", builder().filterFreeAccess("public"), true}, new Object[] {"filterSubject", builder().filterSubject(List.of("1")), true}, - new Object[] {"includeSubjectFacet=false with query", - builder().query("foo").includeSubjectFacet(false), false} + new Object[] {"filterVisibility", builder().filterVisibility("visibleInPF"), true}, + new Object[] {"filterCustom", builder().filterCustom("true"), true}, + new Object[] {"includeSubjectFacet=false with query", builder().query("foo").includeSubjectFacet(false), false} ); } @@ -44,21 +45,62 @@ void shouldResolveIncludeSubjectFacet(String name, PackageRecordFilterBuilder bu @Test void shouldConvertFilterSubjectToIntegerIds() { - var filter = builder().filterSubject(List.of("1", "22")).build(); + var clientFilter = builder().filterSubject(List.of("1", "22")).build().toClientFilter(SEARCH_PROPERTIES); - assertEquals(List.of(1, 22), filter.toClientFilter(SEARCH_PROPERTIES).filterSubjectIds()); + assertEquals(List.of(1, 22), clientFilter.filterSubjectIds()); } @Test - void shouldReturnNullSubjectIdsWhenFilterSubjectIsNullOrEmpty() { - assertNull(builder().build().toClientFilter(SEARCH_PROPERTIES).filterSubjectIds()); - assertNull(builder().filterSubject(new ArrayList<>()).build().toClientFilter(SEARCH_PROPERTIES) - .filterSubjectIds()); + 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 shouldFailValidationWhenFilterSubjectIsNotNumeric() { - var builder = builder().filterSubject(Arrays.asList("1", "abc")); + 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); @@ -66,11 +108,14 @@ void shouldFailValidationWhenFilterSubjectIsNotNumeric() { .contains(PackageFilterValidator.INVALID_FILTER_SUBJECT_PARAMETER_MESSAGE)); } - @Test - void shouldPassValidationWhenFilterSubjectIsNumeric() { - var filter = builder().filterSubject(List.of("26224")).build(); - - assertFalse(filter.getFilterSubject().isEmpty()); + 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() { From 3c108fd0ea7bcf9ce266987673cb4638b0f2b9c4 Mon Sep 17 00:00:00 2001 From: viacheslav_kolesnyk Date: Mon, 19 Oct 2026 14:15:02 +0200 Subject: [PATCH 3/6] Remove subject filter inclusion logic based on other filters applied --- .../model/filter/PackageRecordFilter.java | 14 +------ .../EholdingsPackagesIntegrationTest.java | 42 ++++++++++--------- .../model/filter/PackageRecordFilterTest.java | 28 ++++--------- 3 files changed, 32 insertions(+), 52 deletions(-) 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 7b254825a..73774a18f 100644 --- a/src/main/java/org/folio/rest/model/filter/PackageRecordFilter.java +++ b/src/main/java/org/folio/rest/model/filter/PackageRecordFilter.java @@ -2,8 +2,6 @@ import static java.util.Arrays.asList; import static org.apache.commons.collections4.CollectionUtils.isEmpty; -import static org.apache.commons.collections4.CollectionUtils.isNotEmpty; -import static org.apache.commons.lang3.StringUtils.isNotBlank; import static org.folio.common.ListUtils.mapItemsNullable; import java.util.List; @@ -111,19 +109,9 @@ public PackageFilter toClientFilter(SearchProperties searchProperties) { .filterType(getPackageFilterType().orElse(null)) .filterPackageFreeAccess(getPackageFilterFreeAccess().orElse(null)) .filterVisibility(getPackageFilterVisibility().orElse(null)) - .includeSubjectFacet(includeSubjectFacet && isSearchOrFilterApplied()) + .includeSubjectFacet(includeSubjectFacet) .subjectFacetCount(subjectFacetCount) .filterSubjectIds(mapItemsNullable(filterSubject, Integer::valueOf)) .build(); } - - private boolean isSearchOrFilterApplied() { - return isNotBlank(query) - || isNotEmpty(filterSubject) - || getPackageFilterType().filter(type -> type != PackageFilterType.ALL).isPresent() - || isNotBlank(filterSelected) - || isNotBlank(filterFreeAccess) - || isNotBlank(filterVisibility) - || isNotBlank(filterCustom); - } } diff --git a/src/test/java/org/folio/rest/impl/EholdingsPackagesIntegrationTest.java b/src/test/java/org/folio/rest/impl/EholdingsPackagesIntegrationTest.java index 406246133..be5c40c0a 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 { @@ -259,22 +263,18 @@ void shouldSendSubjectFilterToRmApiWhenCombinedWithTagsFilter() { } @Test - void shouldNotRequestSubjectFacetsWhenNoSearchOrFilterIsApplied() { + 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.absent()) + .withQueryParam("facetstoinclude", WireMock.equalTo("subject")) + .withQueryParam("subjectfacetcount", WireMock.equalTo("1000")) .withQueryParam("subjectfilter", WireMock.absent())); } - @Test - void shouldReturn400OnNonNumericFilterSubject() { - getWithStatus(packagesPath() + "?filter[subject]=abc", SC_BAD_REQUEST); - } - @Test void shouldReturnPackagesOnSearchByTagsOnly() { saveTag(vertx, FULL_PACKAGE_ID, PACKAGE, STUB_TAG_VALUE); @@ -357,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(); - - 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(); + @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")); + assertTrue(response.contains(expectedMessage)); } @Test @@ -1203,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 index 175a0f474..4666a4a65 100644 --- a/src/test/java/org/folio/rest/model/filter/PackageRecordFilterTest.java +++ b/src/test/java/org/folio/rest/model/filter/PackageRecordFilterTest.java @@ -19,28 +19,18 @@ class PackageRecordFilterTest { private static final SearchProperties SEARCH_PROPERTIES = new SearchProperties("contains", "contains", "mark"); - static List facetRequestCases() { - return List.of( - new Object[] {"no query or filters", builder(), false}, - new Object[] {"blank query", builder().query(" "), false}, - new Object[] {"default filterType (all)", builder().filterType("all"), false}, - new Object[] {"query", builder().query("foo"), true}, - new Object[] {"filterType", builder().filterType("ebook"), true}, - new Object[] {"filterSelected", builder().filterSelected("true"), true}, - new Object[] {"filterFreeAccess", builder().filterFreeAccess("public"), true}, - new Object[] {"filterSubject", builder().filterSubject(List.of("1")), true}, - new Object[] {"filterVisibility", builder().filterVisibility("visibleInPF"), true}, - new Object[] {"filterCustom", builder().filterCustom("true"), true}, - new Object[] {"includeSubjectFacet=false with query", builder().query("foo").includeSubjectFacet(false), false} - ); + @Test + void shouldIncludeSubjectFacetWhenRequestedRegardlessOfFilters() { + var clientFilter = builder().build().toClientFilter(SEARCH_PROPERTIES); + + assertTrue(clientFilter.includeSubjectFacet()); } - @ParameterizedTest(name = "{0}") - @MethodSource("facetRequestCases") - void shouldResolveIncludeSubjectFacet(String name, PackageRecordFilterBuilder builder, boolean expected) { - var clientFilter = builder.build().toClientFilter(SEARCH_PROPERTIES); + @Test + void shouldNotIncludeSubjectFacetWhenNotRequested() { + var clientFilter = builder().query("foo").includeSubjectFacet(false).build().toClientFilter(SEARCH_PROPERTIES); - assertEquals(expected, clientFilter.includeSubjectFacet()); + assertFalse(clientFilter.includeSubjectFacet()); } @Test From 2cf9ff973f04beab5042ce60fdb5f69d02f30444 Mon Sep 17 00:00:00 2001 From: viacheslav_kolesnyk Date: Tue, 20 Oct 2026 11:36:48 +0200 Subject: [PATCH 4/6] Update API doc, add AGENTS.md --- AGENTS.md | 47 +++++++++++++++++++++++++++++++++++++++++++++ ramls/packages.raml | 2 +- 2 files changed, 48 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..c754c08cb --- /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 **RestMicroserviceBuilder (RMB)** + Vert.x, with Spring for dependency injection. The external HoldingsIQ client lives in the separate `folio-holdingsiq-client` library (version pinned in `pom.xml`; currently a SNAPSHOT, so it may need to be built/installed locally from `../folio-holdingsiq-client`). + +## 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/ramls/packages.raml b/ramls/packages.raml index 0aafab1a2..cc35b438c 100644 --- a/ramls/packages.raml +++ b/ramls/packages.raml @@ -54,7 +54,7 @@ types: 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 (OR semantics): packages that have any of the specified subjects are returned. + The parameter is repeatable (AND semantics): only packages that have all of the specified subjects are returned. required: false subjectFacetCount: displayName: Subject Facet Count From 58067f643482d980a2033f3c17aa7896f63c4efb Mon Sep 17 00:00:00 2001 From: viacheslav_kolesnyk Date: Tue, 20 Oct 2026 11:58:54 +0200 Subject: [PATCH 5/6] Add api example --- .../packages/packages_get_200_response.json | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/ramls/examples/packages/packages_get_200_response.json b/ramls/examples/packages/packages_get_200_response.json index ec37e4853..09c4fa588 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 }, From 98e2fbf1c2bbf0ea806d91b66cd37f97f8f44bf8 Mon Sep 17 00:00:00 2001 From: viacheslav_kolesnyk Date: Tue, 20 Oct 2026 13:11:25 +0200 Subject: [PATCH 6/6] Update AGENTS.md --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index c754c08cb..eb8ffb6de 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ This file provides guidance to AI coding agents when working with code in this r ## 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 **RestMicroserviceBuilder (RMB)** + Vert.x, with Spring for dependency injection. The external HoldingsIQ client lives in the separate `folio-holdingsiq-client` library (version pinned in `pom.xml`; currently a SNAPSHOT, so it may need to be built/installed locally from `../folio-holdingsiq-client`). +`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