com.itextpdf.signatures.validation.lotl

Class LotlService

java.lang.Object

com.itextpdf.signatures.validation.lotl.LotlService

All Implemented Interfaces:

AutoCloseable

Direct Known Subclasses:

EuropeanLotlService, SingleFileLotlService

public class LotlService
extends Object
implements AutoCloseable

This class provides API for managing the List of Trusted Lists (LOTL) and related resources. It includes API for fetching, validating, and caching LOTL data, as well as managing the European Resource Fetcher and Country-Specific LOTL Fetcher. It also allows for setting custom resource retrievers and cache timeouts.

Field Summary

Fields

Modifier and Type	Field and Description
protected LotlFetchingProperties	lotlFetchingProperties

Constructor Summary

Constructors

Constructor and Description
LotlService(LotlFetchingProperties lotlFetchingProperties) Creates a new instance of LotlService.

Method Summary

Modifier and Type	Method and Description
protected void	cancelTimer() Cancels timer, if it was already set up.
void	close()
static LotlService	getGlobalService() Gets global static instance of LotlService.
List<IServiceContext>	getNationalTrustedCertificates() Retrieves national trusted certificates.
ValidationReport	getValidationResult() Get the validation results for the List of Trusted Lists (LOTL).
void	initializeCache() Initializes the cache with the latest LOTL data and related resources.
void	initializeCache(InputStream stream) Initializes the cache with the latest LOTL data and related resources.
static void	initializeGlobalCache(LotlFetchingProperties lotlFetchingProperties) Initializes the global service with the provided LotlFetchingProperties.
void	loadFromCache(InputStream stream) Loads the cache from the provided input stream.
protected void	loadFromNetwork() Loads the cache from the network by fetching the latest LOTL data and related resources.
void	serializeCache(OutputStream outputStream) Serializes the current state of the cache to the provided output stream.
protected void	setupTimer() Sets up a timer to periodically refresh the LOTL cache.
protected void	tryAndRefreshCache() This method is intended to refresh the cache, it will try to download the latest LOTL data and update the cache accordingly.
LotlService	withCountrySpecificLotlFetcher(CountrySpecificLotlFetcher countrySpecificLotlFetcher) Sets the country-specific LOTL fetcher for the LOTL service.
LotlService	withCustomResourceRetriever(com.itextpdf.io.resolver.resource.IResourceRetriever resourceRetriever) Sets a custom resource retriever for fetching resources.
LotlService	withEuropeanLotlFetcher(EuropeanLotlFetcher fetcher) Sets the European List of Trusted Lists (LOTL) byte fetcher for the LOTL service.
LotlService	withEuropeanResourceFetcher(EuropeanResourceFetcher europeanResourceFetcher) Sets the European Resource Fetcher for the LotlService.
LotlService	withLotlServiceCache(LotlServiceCache cache) Sets the cache for the LotlService.
LotlService	withLotlValidator(Supplier<LotlValidator> lotlValidatorFactory) Sets up factory which is responsible for LotlValidator creation.
LotlService	withPivotFetcher(PivotFetcher pivotFetcher) Sets the pivot fetcher for the LOTL service.
LotlService	withXmlSignatureValidator(Function<TrustedCertificatesStore,XmlSignatureValidator> xmlSignatureValidatorFactory) Sets up factory which is responsible for XmlSignatureValidator creation.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

lotlFetchingProperties

protected final LotlFetchingProperties lotlFetchingProperties

Constructor Detail

LotlService

public LotlService(LotlFetchingProperties lotlFetchingProperties)

Creates a new instance of LotlService.

Parameters:

lotlFetchingProperties - LotlFetchingProperties to configure the way in which LOTL will be fetched

Method Detail

initializeGlobalCache

public static void initializeGlobalCache(LotlFetchingProperties lotlFetchingProperties)

Initializes the global service with the provided LotlFetchingProperties. This method must be called before using the LotlService to ensure that the cache is set up.

If you are using a custom implementation of LotlService you can use the instance method.

Parameters:

lotlFetchingProperties - the LotlFetchingProperties to use for initializing the cache

getGlobalService

public static LotlService getGlobalService()

Gets global static instance of LotlService.

Returns:

global static instance of LotlService

withLotlServiceCache

public LotlService withLotlServiceCache(LotlServiceCache cache)

Sets the cache for the LotlService.

This method allows you to provide a custom implementation of LotlServiceCache to be used for caching LOTL data, pivot files, and country-specific LOTLs.

Parameters:

cache - the custom cache to be used for caching LOTL data

Returns:

the current instance of LotlService for method chaining

withCustomResourceRetriever

public final LotlService withCustomResourceRetriever(com.itextpdf.io.resolver.resource.IResourceRetriever resourceRetriever)

Sets a custom resource retriever for fetching resources.

This method allows you to provide a custom implementation of IResourceRetriever to be used for fetching resources such as the LOTL XML, pivot files, and country-specific LOTLs.

Multiple LOTL endpoints require a userAgent header to be sent. This should be taken into account when providing a custom IResourceRetriever.

Parameters:

resourceRetriever - the custom resource retriever to be used for fetching resources

Returns:

the current instance of LotlService for method chaining

initializeCache

public void initializeCache()

Initializes the cache with the latest LOTL data and related resources.

loadFromCache

public void loadFromCache(InputStream stream)

Loads the cache from the provided input stream.

The input stream should contain serialized cache data, which can be created using the serializeCache(OutputStream) method.

Parameters:

stream - the input stream to read the cached data from

getValidationResult

public ValidationReport getValidationResult()

Get the validation results for the List of Trusted Lists (LOTL).

Returns:

a ValidationReport containing the results of the LOTL validation

getNationalTrustedCertificates

public List<IServiceContext> getNationalTrustedCertificates()

Retrieves national trusted certificates.

Returns:

the list of the national trusted certificates

initializeCache

public void initializeCache(InputStream stream)

Initializes the cache with the latest LOTL data and related resources.

Important: By default when providing a stream, we will still set up a timer to refresh the cache periodically. If you don't want this behavior, please set LotlFetchingProperties.setRefreshIntervalCalculator(LongUnaryOperator) to int.Max.

Parameters:

stream - InputStream to read the cached data from. If null, the data will be fetched from the network. The data can be serialized using serializeCache(OutputStream) method.

withPivotFetcher

public LotlService withPivotFetcher(PivotFetcher pivotFetcher)

Sets the pivot fetcher for the LOTL service.

Parameters:

pivotFetcher - the pivot fetcher to be used for fetching and validating pivot files

Returns:

the current instance of LotlService for method chaining

withCountrySpecificLotlFetcher

public LotlService withCountrySpecificLotlFetcher(CountrySpecificLotlFetcher countrySpecificLotlFetcher)

Sets the country-specific LOTL fetcher for the LOTL service.

Parameters:

countrySpecificLotlFetcher - the country-specific LOTL fetcher to be used for fetching and validating country-specific LOTLs

Returns:

the current instance of LotlService for method chaining

withEuropeanLotlFetcher

public LotlService withEuropeanLotlFetcher(EuropeanLotlFetcher fetcher)

Sets the European List of Trusted Lists (LOTL) byte fetcher for the LOTL service.

Parameters:

fetcher - the fetcher to be used for fetching the LOTL XML data

Returns:

the current instance of LotlService for method chaining

withXmlSignatureValidator

public LotlService withXmlSignatureValidator(Function<TrustedCertificatesStore,XmlSignatureValidator> xmlSignatureValidatorFactory)

Sets up factory which is responsible for XmlSignatureValidator creation.

Parameters:

xmlSignatureValidatorFactory - factory responsible for XmlSignatureValidator creation

Returns:

the current instance of LotlService for method chaining

withLotlValidator

public LotlService withLotlValidator(Supplier<LotlValidator> lotlValidatorFactory)

Sets up factory which is responsible for LotlValidator creation.

Parameters:

lotlValidatorFactory - factory responsible for LotlValidator creation

Returns:

this same instance of LotlService

withEuropeanResourceFetcher

public LotlService withEuropeanResourceFetcher(EuropeanResourceFetcher europeanResourceFetcher)

Sets the European Resource Fetcher for the LotlService.

Parameters:

europeanResourceFetcher - the European Resource Fetcher to be used for fetching EU journal certificates

Returns:

the current instance of LotlService for method chaining

close

public void close()

Specified by:

close in interface AutoCloseable

serializeCache

public void serializeCache(OutputStream outputStream)
                    throws IOException

Serializes the current state of the cache to the provided output stream.

Parameters:

outputStream - the output stream to which the cache will be serialized

Throws:

IOException - if an I/O error occurs during serialization

loadFromNetwork

protected void loadFromNetwork()

Loads the cache from the network by fetching the latest LOTL data and related resources.

This method fetches the main LOTL file, EU journal certificates, pivot files, and country-specific LOTLs, validates them, and stores them in the cache.

Note: This method is called during cache initialization and should not be called directly in normal operation.

tryAndRefreshCache

protected void tryAndRefreshCache()

This method is intended to refresh the cache, it will try to download the latest LOTL data and update the cache accordingly.

setupTimer

protected void setupTimer()

Sets up a timer to periodically refresh the LOTL cache.

The timer will use the refresh interval calculated based on the stale-ness of the cache. If the cache is null, it will create a new instance of InMemoryLotlServiceCache.

cancelTimer

protected void cancelTimer()

Cancels timer, if it was already set up.