folio-spring-support

Copyright (C) 2020-2023 The Open Library Foundation

This software is distributed under the terms of the Apache License, Version 2.0. See the file "LICENSE" for more information.

Table of Contents

• Table of Contents
• Introduction
• Code structure
• Execution Context
• Properties
• CQL support
• Logging
  • Default logging format
  • Logging for incoming and outgoing requests
    • Log examples:
• Custom /_/tenant Logic
  • TenantService Event Methods
  • TenantService Methods and Fields
  • Event Order
    • Upon Creation
    • Upon Deletion
  • Sample
• Internationalization
• Additional information
  • Issue tracker

Introduction

This is a library that contains the basic functionality and main dependencies required for development of FOLIO modules using Spring framework (also known as "Spring Way").

Please find a step-by-step guide on how to create a new FOLIO Spring based module at https://github.com/folio-org/mod-spring-template

An example of the module based on folio-spring-support could be found at https://github.com/folio-org/folio-sample-modules/tree/master/mod-spring-petstore

Code structure

The library comprises several submodules that are built as separate artifacts (jar files) and can be integrated into a project as distinct dependencies. This facilitates more precise dependency management depending on the requirements of each project.

The library includes the following submodules:

• folio-spring-base - provides fundamental functionality for developing FOLIO modules using the Spring framework.
• folio-spring-cql - facilitates CQL querying (refer to the CQL support section below)
• folio-spring-system-user - provides functionality for system-user creation and utilization

Execution Context

FolioExecutionContext is used to store essential request headers (in thread local). Folio Spring Base populates this data using FolioExecutionScopeFilter. It is used by EnrichUrlAndHeadersClient, to provide right tenant id and other headers for outgoing REST requests. It is also used in DataSourceSchemaAdvisorBeanPostProcessor for selection of the appropriate schema for sql queries.

FolioExecutionContext is immutable. In order to start new execution context the construct

  try (var x = new FolioExecutionContextSetter(currentFolioExecutionContext)) {
    chain.doFilter(request, response);
  }

should be used (pick any of the available constructors).

Using try-with-resources is best practice. Not using try-with-resources is error-prone, may result in a wrong tenant and should be avoided. If not using try-with-resources ensure to call folioExecutionContextSetter.close() when the execution is finished. Example:

  // Not using try-with-resources is discouraged!
  var x = new FolioExecutionContextSetter(currentFolioExecutionContext);
  // do some stuff
  x.close();

CAUTION: FolioExecutionContext should not be used in asynchronous code executions (as it is stored in thread local), unless the appropriate data is manually set by using FolioExecutionContextSetter.

Example of asynchronous execution:

private final FolioModuleMetadata folioModuleMetadata;

@Async
void ayncMethod(Map<String, Collection<String>> headers) {
  try (var x = new FolioExecutionContextSetter(folioModuleMetadata, httpHeaders)) {
    _your_code_here_
  }
}

FOLIO scope implementation supports nested FolioExecutionContexts it means that the following code works correctly for

// Autowired
private final FolioModuleMetadata folioModuleMetadata;

// Autowired
protected final FolioExecutionContext context;

void someMethod(Map<String, Collection<String>> headers) {
  Map<String, Collection<String>> headers1 = getHeaderForTenant("Tenant1");
  try (var x = new FolioExecutionContextSetter(folioModuleMetadata, headers1)) {
    String tenant1 = context.getTenantId();
    businessMethod(tenant1);

    Map<String, Collection<String>> headers2 = getHeaderForTenant("Tenant2");
    try (var x = new FolioExecutionContextSetter(folioModuleMetadata, headers2)) {
      String tenant2 = context.getTenantId();
      businessMethod(tenant2);
    }
    
    String tenant1_1 = context.getTenantId();
    assert tenant1.equals(tenant1_1);
  }
}

...

void businessMethod(String tenantId) {
  _do_some_useful_stuff_
  String tenantId = context.getTenantId();

  assert tenant.equals(tenantId);
}

Properties

Property	Description	Default	Example
header.validation.x-okapi-tenant.exclude.base-paths	Specifies base paths to exclude form x-okapi-tenant header validation. See TenantOkapiHeaderValidationFilter.java	/admin	/admin,/swagger-ui
folio.jpa.repository.base-packages	Specifies base packages to scan for repositories	org.folio.*	org.folio.qm.dao
folio.logging.request.enabled	Turn on logging for incoming requests	true	true or false
folio.logging.request.level	Specifies logging level for incoming requests	basic	none, basic, headers, full
folio.logging.feign.enabled	Turn on logging for outgoing requests in feign clients	true	true or false
folio.logging.feign.level	Specifies logging level for outgoing requests	basic	none, basic, headers, full

CQL support

To have ability to search entities in databases by CQL-queries:

• create repository interface for needed entity
• extend it from JpaCqlRepository<T, ID>, where T is entity class and ID is entity's id class.
• the implementation of the repository will be created by Spring

public interface PersonRepository extends JpaCqlRepository<Person, Integer> {

}

Two methods are available for CQL-queries:

public interface JpaCqlRepository<T, ID> extends JpaRepository<T, ID> {

  Page<T> findByCql(String cql, OffsetRequest offset);

  long count(String cql);
}

Logging

Default logging format

Library uses log4j2 for logging. There are two default log4j2 configurations:

• log4j2.properties console/line based logger and it is the default
• log4j2-json.properties JSON structured logging

To choose the JSON structured logging by using setting: -Dlog4j.configurationFile=log4j2-json.properties A module that wants to generate log4J2 logs in a different format can create a log4j2.properties file in the /resources directory.

Logging for incoming and outgoing requests

By default, logging for incoming and outgoing request enabled. Module could disable it by setting:

• folio.logging.request.enabled = false
• folio.logging.feign.enabled = false

Also, it is possible to specify logging level: none - no logs basic - log request method and URI, response status and spent time headers - log all that basic and request headers full - log all that headers and request and response bodies

Note: In case you have async requests in your module (DeferredResult, CompletableFuture, etc.) then you should disable default logging for requests.

Log examples:

• basic:

18:41:18 [<requestId>] [<tenantId>] [<userId>] [<moduleId>] INFO  LoggingRequestFilter ---> PUT /records-editor/records/c9db5d7a-e1d4-11e8-9f32-f2801f1b9fd1 null
18:41:19 [<requestId>] [<tenantId>] [<userId>] [<moduleId>] INFO  LoggingRequestFilter <--- 202 in 753ms

• headers:

18:44:23 [<requestId>] [<tenantId>] [<userId>] [<moduleId>] INFO  LoggingRequestFilter ---> PUT /records-editor/records/c9db5d7a-e1d4-11e8-9f32-f2801f1b9fd1 null
18:44:23 [<requestId>] [<tenantId>] [<userId>] [<moduleId>] INFO  LoggingRequestFilter x-okapi-url: http://localhost:50017
18:44:23 [<requestId>] [<tenantId>] [<userId>] [<moduleId>] INFO  LoggingRequestFilter x-okapi-tenant: <tenantId>
18:44:23 [<requestId>] [<tenantId>] [<userId>] [<moduleId>] INFO  LoggingRequestFilter x-okapi-request-id: <requestId>
18:44:23 [<requestId>] [<tenantId>] [<userId>] [<moduleId>] INFO  LoggingRequestFilter x-okapi-user-id: <userId>
18:44:23 [<requestId>] [<tenantId>] [<userId>] [<moduleId>] INFO  LoggingRequestFilter content-type: application/json; charset=UTF-8
18:44:23 [<requestId>] [<tenantId>] [<userId>] [<moduleId>] INFO  LoggingRequestFilter ---> END HTTP
18:44:24 [<requestId>] [<tenantId>] [<userId>] [<moduleId>] INFO  LoggingRequestFilter <--- 202 in 786ms

• full:

18:46:17 [<requestId>] [<tenantId>] [<userId>] [<moduleId>] INFO  LoggingRequestFilter ---> PUT /records-editor/records/c9db5d7a-e1d4-11e8-9f32-f2801f1b9fd1 null
18:46:17 [<requestId>] [<tenantId>] [<userId>] [<moduleId>] INFO  LoggingRequestFilter x-okapi-url: http://localhost:53146
18:46:17 [<requestId>] [<tenantId>] [<userId>] [<moduleId>] INFO  LoggingRequestFilter x-okapi-tenant: <tenantId>
18:46:17 [<requestId>] [<tenantId>] [<userId>] [<moduleId>] INFO  LoggingRequestFilter x-okapi-request-id: <requestId>
18:46:17 [<requestId>] [<tenantId>] [<userId>] [<moduleId>] INFO  LoggingRequestFilter x-okapi-user-id: <userId>
18:46:17 [<requestId>] [<tenantId>] [<userId>] [<moduleId>] INFO  LoggingRequestFilter content-type: application/json; charset=UTF-8
18:46:17 [<requestId>] [<tenantId>] [<userId>] [<moduleId>] INFO  LoggingRequestFilter Body: {"parsedRecordId":"c9db5d7a-e1d4-11e8-9f32-f2801f1b9fd1","parsedRecordDtoId":"c56b70ce-4ef6-47ef-8bc3-c470bafa0b8c","suppressDiscovery":false}
18:46:17 [<requestId>] [<tenantId>] [<userId>] [<moduleId>] INFO  LoggingRequestFilter ---> END HTTP
18:46:18 [<requestId>] [<tenantId>] [<userId>] [<moduleId>] INFO  LoggingRequestFilter <--- 202 in 714ms
18:46:18 [<requestId>] [<tenantId>] [<userId>] [<moduleId>] INFO  LoggingRequestFilter Body:
18:46:18 [<requestId>] [<tenantId>] [<userId>] [<moduleId>] INFO  LoggingRequestFilter <--- END HTTP

Custom /_/tenant Logic

There are many cases where you may want to add custom logic to the /_/tenant endpoint, such as for loading sample data or performing more complex database migration.

In order to do this, you can extend the TenantService within your module and override any of the methods listed below.

TenantService Event Methods

The following methods can be overridden by your module in order to add custom logic around events relating to tenant creation, updates, and deletion. All of these return void.

Many of these accept a TenantAttributes parameter which can provide information about the previous module (module_from), the module being upgraded to (module_to), as well as any other parameters provided.

⚠️ Please note that methods with "update" in the name will be run on updates as well as when new tenants are created. Be especially careful with methods run before Liquibase -- the database schema could potentially be in an unexpected state, particularly when a new tenant is created.

Visibility	Signature	Purpose
public	loadReferenceData()	Load any reference data (requested with loadReference=true parameter)
public	loadSampleData()	Load any sample data (requested with loadSample=true parameter)
protected	beforeTenantUpdate(TenantAttributes)	Run custom logic before a tenant is created or updated
protected	beforeLiquibaseUpdate(TenantAttributes)	Run custom logic immediately before Liquibase updates are started (after beforeTenantUpdate)
protected	afterLiquibaseUpdate(TenantAttributes)	Run custom logic immediately before Liquibase updates are finished (before afterTenantUpdate)
protected	afterTenantUpdate(TenantAttributes)	Run custom logic after all update jobs are completed
protected	beforeTenantDeletion(TenantAttributes)	Run custom logic before a tenant is deleted/purged
protected	afterTenantDeletion(TenantAttributes)	Run custom logic after a tenant is deleted/purged (the schema will no longer exist)

TenantService Methods and Fields

There are two methods that may be of use in your custom logic:

• boolean tenantExists() which will check if the database schema for this tenant exists (this says nothing about if it is up to date)
• String getSchemaName() will construct and return the name of the schema corresponding to the module and tenant

These fields will also be provided:

• JdbcTemplate jdbcTemplate, for running Postgres queries directly
• FolioExecutionContext context, for getting information about the module
• FolioSpringLiquibase folioSpringLiquibase, for interacting with Liquibase directly (this extends SpringLiquibase and may be null if Liquibase is not enabled!)

Event Order

The events will be called in the following order:

Upon Creation

1. beforeTenantUpdate
2. If Liquibase is enabled:
   1. beforeLiquibaseUpdate
   2. Internal logic to apply Liquibase changes
   3. afterLiquibaseUpdate
3. afterTenantUpdate
4. loadReferenceData, if applicable
5. loadSampleData, if applicable

Upon Deletion

1. beforeTenantDeletion
2. Internal logic to drop the schema
3. afterTenantDeletion

Sample

Overriding these methods to add your own custom logic is quite straightforward. Here is an example of how to override these in your very own @Service:

package org.folio.yourmodule.service;

import org.folio.spring.service.TenantService;
import org.folio.tenant.domain.dto.TenantAttributes;
import org.folio.yourmodule.SuperCoolDataRepository;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Primary;
import org.springframework.stereotype.Service;

@Service
@Primary // required to ensure CustomTenantService will be loaded instead of TenantService
public class CustomTenantService extends TenantService {

  protected final SuperCoolDataRepository repository;

  /**
   * Load reference data
   */
  @Override
  protected void loadReferenceData() {
    repository.loadReferenceData();
  }

  /**
   * Add our custom initial data
   */
  @Override
  protected void beforeTenantUpdate(TenantAttributes attributes) {
    // some custom logic for potentially migrating data
  }
}

Internationalization

Translations may be performed in backend modules using the folio-spring-i18n library. For more information, see the folio-spring-i18n README.

Additional information

Issue tracker

See project FOLSPRINGB at the FOLIO issue tracker.