001/*-
002 * #%L
003 * Smile CDR - CDR
004 * %%
005 * Copyright (C) 2016 - 2025 Smile CDR, Inc.
006 * %%
007 * All rights reserved.
008 * #L%
009 */
010package ca.cdr.api.fhir.tokenization;
011
012import ca.uhn.fhir.rest.api.server.RequestDetails;
013
014/**
015 * This interface implements the conversion of non-tokenized strings into
016 * tokens, and vice versa.
017 *
018 * @since 2025.05
019 */
020public interface ITokenizationProvider {
021
022        /**
023         * Performs tokenization for a collection of requests. This method is invoked
024         * when Smile CDR needs to convert one or more strings into their corresponding
025         * tokens. The algorithm used to tokenize is flexible, and could rely on an
026         * external database or a cryptographic algorithm (or both). It must however be
027         * deterministic, meaning that repeated calls to tokenize the same input string must
028         * produce the same result.
029         *
030         * @param theRequestDetails The request associated with the tokenization
031         * @param theRequests       The requests, which include the specific rule as well as the object being tokenized
032         * @return Returns a collection of tokenized results. A result must be provided for every request in the request object.
033         */
034        TokenizationResults tokenize(RequestDetails theRequestDetails, TokenizationRequests theRequests);
035
036        /**
037         * Performs de-tokenization for a collection of requests. This method will be
038         * provided a collection of tokens originally obtained by invoking
039         * {@link #tokenize(RequestDetails, TokenizationRequests)}, and
040         * should supply the same input string. This method will not be called if none
041         * of the configured tokenization rules allow for de-tokenization, in which case
042         * this method may simply throw a {@link UnsupportedOperationException}.
043         *
044         * @param theRequestDetails The request associated with the tokenization
045         * @param theRequests       The requests, which include the specific rule as well as the token being detokenized
046         * @return Returns a collection of detokenized results. A result must be provided for every request in the request object.
047         */
048        DetokenizationResults detokenize(RequestDetails theRequestDetails, DetokenizationRequests theRequests);
049}