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