Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -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).
1 change: 1 addition & 0 deletions NEWS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Expand Down
22 changes: 22 additions & 0 deletions ramls/examples/packages/packages_get_200_response.json
Original file line number Diff line number Diff line change
Expand Up @@ -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
},
Expand Down
16 changes: 16 additions & 0 deletions ramls/packages.raml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 5 additions & 0 deletions ramls/types/packages/packageCollection.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
18 changes: 18 additions & 0 deletions ramls/types/packages/packageFacets.json
Original file line number Diff line number Diff line change
@@ -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"
}
}
}
}
30 changes: 30 additions & 0 deletions ramls/types/packages/subjectFacet.json
Original file line number Diff line number Diff line change
@@ -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
}
}
}
Original file line number Diff line number Diff line change
@@ -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<Facets, PackageFacetsDto> {

private final Converter<SubjectFacet, SubjectFacetDto> subjectFacetConverter;

public PackageFacetsConverter(Converter<SubjectFacet, SubjectFacetDto> 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.<SubjectFacet>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);
}
}
Original file line number Diff line number Diff line change
@@ -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<SubjectFacet, SubjectFacetDto> {

@Override
public SubjectFacetDto convert(SubjectFacet subjectFacet) {
return new SubjectFacetDto()
.withId(subjectFacet.id())
.withName(subjectFacet.subjectName())
.withSchema(subjectFacet.subjectSchema())
.withCount(subjectFacet.totalCount());
}
}
Original file line number Diff line number Diff line change
@@ -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;
Expand All @@ -16,18 +19,23 @@
public class PackageCollectionConverter implements Converter<Packages, PackageCollection> {

private final Converter<PackageData, PackageCollectionItem> packageCollectionItemConverter;
private final Converter<Facets, PackageFacetsDto> facetsConverter;

public PackageCollectionConverter(Converter<PackageData, PackageCollectionItem> packageCollectionItemConverter) {
public PackageCollectionConverter(Converter<PackageData, PackageCollectionItem> packageCollectionItemConverter,
Converter<Facets, PackageFacetsDto> facetsConverter) {
this.packageCollectionItemConverter = packageCollectionItemConverter;
this.facetsConverter = facetsConverter;
}

@Override
public PackageCollection convert(Packages packages) {
List<PackageCollectionItem> 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);
}
Expand Down
Original file line number Diff line number Diff line change
@@ -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;
Expand All @@ -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;
Expand All @@ -27,12 +30,15 @@ public class PackageCollectionResultConverter implements Converter<PackageCollec

private final Converter<PackageData, PackageCollectionItem> packageCollectionItemConverter;
private final Converter<DbAccessType, AccessType> accessTypeConverter;
private final Converter<Facets, PackageFacetsDto> facetsConverter;

public PackageCollectionResultConverter(
Converter<PackageData, PackageCollectionItem> packageCollectionItemConverter,
Converter<DbAccessType, AccessType> accessTypeConverter) {
Converter<DbAccessType, AccessType> accessTypeConverter,
Converter<Facets, PackageFacetsDto> facetsConverter) {
this.packageCollectionItemConverter = packageCollectionItemConverter;
this.accessTypeConverter = accessTypeConverter;
this.facetsConverter = facetsConverter;
}

@Override
Expand All @@ -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);
}
Expand Down
12 changes: 8 additions & 4 deletions src/main/java/org/folio/rest/impl/EholdingsPackagesImpl.java
Original file line number Diff line number Diff line change
Expand Up @@ -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<String> filterTags, List<String> filterAccessType,
String sort, int page, int count, Map<String, String> okapiHeaders,
public void getEholdingsPackages(String filterCustom, List<String> filterSubject, int subjectFacetCount, String q,
String queryField, String queryType, boolean highlight, String filterSelected,
String filterType, String filterVisibility, String filterFreeAccess,
List<String> filterTags, List<String> filterAccessType, String sort, int page,
int count, Map<String, String> okapiHeaders,
Handler<AsyncResult<Response>> asyncResultHandler, Context vertxContext) {
var filter = PackageRecordFilter.builder()
.query(q)
Expand All @@ -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)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ default Optional<String> validate(@NonNull F filter,
}
}

default Optional<String> validate(@NonNull F filter, @NonNull FilterValidatorLogic<F> logic) {
default <P> Optional<String> validate(@NonNull F filter, @NonNull FilterValidatorLogic<F, P> logic) {
var param = logic.extractor().apply(filter);
if (logic.validator().test(param)) {
return Optional.empty();
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,15 @@
import java.util.function.Predicate;
import org.jspecify.annotations.NonNull;

public record FilterValidatorLogic<F extends Filter>(
Function<F, String> extractor,
Predicate<String> validator,
public record FilterValidatorLogic<F extends Filter, P>(
Function<F, P> extractor,
Predicate<P> validator,
String errorMessage
) {

public static <F extends Filter> FilterValidatorLogic<F> of(@NonNull Function<F, String> extractor,
@NonNull Predicate<String> validator,
@NonNull String errorMessage) {
public static <F extends Filter, P> FilterValidatorLogic<F, P> of(@NonNull Function<F, P> extractor,
@NonNull Predicate<P> validator,
@NonNull String errorMessage) {
return new FilterValidatorLogic<>(extractor, validator, errorMessage);
}
}
Loading
Loading