001/*-
002 * #%L
003 * HAPI FHIR JPA - Search Parameters
004 * %%
005 * Copyright (C) 2014 - 2025 Smile CDR, Inc.
006 * %%
007 * Licensed under the Apache License, Version 2.0 (the "License");
008 * you may not use this file except in compliance with the License.
009 * You may obtain a copy of the License at
010 *
011 *      http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing, software
014 * distributed under the License is distributed on an "AS IS" BASIS,
015 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016 * See the License for the specific language governing permissions and
017 * limitations under the License.
018 * #L%
019 */
020package ca.uhn.fhir.jpa.searchparam.fulltext;
021
022import javax.annotation.Nullable;
023
024/**
025 * This is a response object containing the FullText index data which should be stored during
026 * indexing, or an instruction to skip FullText indexing for the given resource.
027 *
028 * @see ca.uhn.fhir.interceptor.api.Pointcut#JPA_INDEX_EXTRACT_FULLTEXT for a description of how this should be used.
029 * @since 8.4.0
030 */
031public class FullTextExtractionResponse {
032
033        private final boolean myDoNotIndex;
034        private final boolean myIndexNormally;
035        private final String myPayload;
036
037        /**
038         * Private Constructor - Use the factory methods in order to instantiate this class.
039         */
040        private FullTextExtractionResponse(boolean theDoNotIndex, boolean theIndexNormally, String thePayload) {
041                myDoNotIndex = theDoNotIndex;
042                myIndexNormally = theIndexNormally;
043                myPayload = thePayload;
044        }
045
046        /**
047         * Creates a response signalling that the given resource should not be
048         * indexed.
049         * <p>
050         * <b>Note the difference between invoking {@literal doNotIndex()} and invoking
051         * {@link #indexPayload(String)} with a <code>null</code> payload!</b>
052         * Invoking {@literal doNotIndex()} signals to the fulltext engine that the fulltext
053         * indexer should skip processing this resource, whereas invoking
054         * {@link #indexPayload(String)} with a <code>null</code> payload signals to
055         * the fulltext engine that any existing row should be cleared.
056         * This distinction is important in the case of resource deletions, since invoking
057         * {@literal #doNotIndex()} when deleting a previously fulltext indexed row will
058         * leave the previous fulltext index in place, which can waste index space and
059         * make queries inefficient.
060         * </p>
061         */
062        public static FullTextExtractionResponse doNotIndex() {
063                return new FullTextExtractionResponse(true, false, null);
064        }
065
066        /**
067         * Creates a response signalling that the given resource should be indexed
068         * with the given payload. Calling this method with a <code>null</code> payload value
069         * is subtly different from calling {@link #doNotIndex()}. This method will clear any
070         * existing indexing and write an empty index, where {@link #doNotIndex()} will not
071         * touch any existing index.
072         *
073         * @param thePayload The fulltext payload string. May be <code>null</code> if no payload should be specified for the given resource.
074         */
075        public static FullTextExtractionResponse indexPayload(@Nullable String thePayload) {
076                return new FullTextExtractionResponse(false, false, thePayload);
077        }
078
079        /**
080         * Creates a response signalling that the standard indexing should be used.
081         */
082        public static FullTextExtractionResponse indexNormally() {
083                return new FullTextExtractionResponse(false, true, null);
084        }
085
086        public boolean isDoNotIndex() {
087                return myDoNotIndex;
088        }
089
090        public String getPayload() {
091                return myPayload;
092        }
093
094        public boolean isIndexNormally() {
095                return myIndexNormally;
096        }
097}