Configurable summary mode (#5944)

* Fix #5871 - Configurable summary mode

* Add docs

* Spotless

* Add javadoc

hapi-fhir-base/src/main/java/ca/uhn/fhir/context/ParserOptions.java

@@ -20,8 +20,10 @@
 package ca.uhn.fhir.context;
 
 import ca.uhn.fhir.parser.IParser;
+import ca.uhn.fhir.util.CollectionUtil;
+import jakarta.annotation.Nonnull;
+import jakarta.annotation.Nullable;
 
-import java.util.Arrays;
 import java.util.Collection;
 import java.util.Collections;
 import java.util.HashSet;
@@ -42,6 +44,8 @@ public class ParserOptions {
 	private Set<String> myDontStripVersionsFromReferencesAtPaths = Collections.emptySet();
 	private boolean myOverrideResourceIdWithBundleEntryFullUrl = true;
 	private boolean myAutoContainReferenceTargetsWithNoId = true;
+	private Set<String> myEncodeElementsForSummaryMode = null;
+	private Set<String> myDontEncodeElementsForSummaryMode = null;
 
 	/**
 	 * If set to {@literal true} (which is the default), contained resources may be specified by
@@ -143,7 +147,7 @@ public ParserOptions setDontStripVersionsFromReferencesAtPaths(String... thePath
 		if (thePaths == null) {
 			setDontStripVersionsFromReferencesAtPaths((List<String>) null);
 		} else {
-			setDontStripVersionsFromReferencesAtPaths(Arrays.asList(thePaths));
+			setDontStripVersionsFromReferencesAtPaths(CollectionUtil.newSet(thePaths));
 		}
 		return this;
 	}
@@ -205,4 +209,119 @@ public ParserOptions setOverrideResourceIdWithBundleEntryFullUrl(
 		myOverrideResourceIdWithBundleEntryFullUrl = theOverrideResourceIdWithBundleEntryFullUrl;
 		return this;
 	}
+
+	/**
+	 * This option specifies one or more elements that should be included when the parser is encoding
+	 * a resource in {@link IParser#setSummaryMode(boolean) summary mode}, even if the element is not
+	 * a part of the base FHIR specification's list of summary elements. Examples of valid values
+	 * include:
+	 * <ul>
+	 * <li><b>Patient.maritalStatus</b> - Encode the entire maritalStatus CodeableConcept, even though Patient.maritalStatus is not a summary element</li>
+	 * <li><b>Patient.maritalStatus.text</b> - Encode only the text component of the patient's maritalStatus</li>
+	 * <li><b>*.text</b> - Encode the text element on any resource (only the very first position may contain a
+	 * wildcard)</li>
+	 * </ul>
+	 *
+	 * @see IParser#setSummaryMode(boolean)
+	 * @see IParser#setEncodeElements(Set) Can be used to specify these values for an individual parser instance.
+	 * @since 7.4.0
+	 */
+	@SuppressWarnings({"UnusedReturnValue"})
+	@Nonnull
+	public ParserOptions setEncodeElementsForSummaryMode(@Nonnull String... theEncodeElements) {
+		return setEncodeElementsForSummaryMode(CollectionUtil.newSet(theEncodeElements));
+	}
+
+	/**
+	 * This option specifies one or more elements that should be included when the parser is encoding
+	 * a resource in {@link IParser#setSummaryMode(boolean) summary mode}, even if the element is not
+	 * a part of the base FHIR specification's list of summary elements. Examples of valid values
+	 * include:
+	 * <ul>
+	 * <li><b>Patient.maritalStatus</b> - Encode the entire maritalStatus CodeableConcept, even though Patient.maritalStatus is not a summary element</li>
+	 * <li><b>Patient.maritalStatus.text</b> - Encode only the text component of the patient's maritalStatus</li>
+	 * <li><b>*.text</b> - Encode the text element on any resource (only the very first position may contain a
+	 * wildcard)</li>
+	 * </ul>
+	 *
+	 * @see IParser#setSummaryMode(boolean)
+	 * @see IParser#setEncodeElements(Set) Can be used to specify these values for an individual parser instance.
+	 * @since 7.4.0
+	 */
+	@Nonnull
+	public ParserOptions setEncodeElementsForSummaryMode(@Nullable Collection<String> theEncodeElements) {
+		Set<String> encodeElements = null;
+		if (theEncodeElements != null && !theEncodeElements.isEmpty()) {
+			encodeElements = new HashSet<>(theEncodeElements);
+		}
+		myEncodeElementsForSummaryMode = encodeElements;
+		return this;
+	}
+
+	/**
+	 * @return Returns the values provided to {@link #setEncodeElementsForSummaryMode(Collection)}
+	 * or <code>null</code>
+	 *
+	 * @since 7.4.0
+	 */
+	@Nullable
+	public Set<String> getEncodeElementsForSummaryMode() {
+		return myEncodeElementsForSummaryMode;
+	}
+
+	/**
+	 * This option specifies one or more elements that should be excluded when the parser is encoding
+	 * a resource in {@link IParser#setSummaryMode(boolean) summary mode}, even if the element is
+	 * a part of the base FHIR specification's list of summary elements. Examples of valid values
+	 * include:
+	 * <ul>
+	 * <li><b>Patient.name</b> - Do not include the patient's name</li>
+	 * <li><b>Patient.name.family</b> - Do not include the patient's family name</li>
+	 * <li><b>*.name</b> - Do not include the name element on any resource type</li>
+	 * </ul>
+	 *
+	 * @see IParser#setSummaryMode(boolean)
+	 * @see IParser#setDontEncodeElements(Collection) Can be used to specify these values for an individual parser instance.
+	 * @since 7.4.0
+	 */
+	@SuppressWarnings({"UnusedReturnValue"})
+	@Nonnull
+	public ParserOptions setDontEncodeElementsForSummaryMode(@Nonnull String... theEncodeElements) {
+		return setDontEncodeElementsForSummaryMode(CollectionUtil.newSet(theEncodeElements));
+	}
+
+	/**
+	 * This option specifies one or more elements that should be excluded when the parser is encoding
+	 * a resource in {@link IParser#setSummaryMode(boolean) summary mode}, even if the element is
+	 * a part of the base FHIR specification's list of summary elements. Examples of valid values
+	 * include:
+	 * <ul>
+	 * <li><b>Patient.name</b> - Do not include the patient's name</li>
+	 * <li><b>Patient.name.family</b> - Do not include the patient's family name</li>
+	 * <li><b>*.name</b> - Do not include the name element on any resource type</li>
+	 * </ul>
+	 *
+	 * @see IParser#setSummaryMode(boolean)
+	 * @see IParser#setDontEncodeElements(Collection) Can be used to specify these values for an individual parser instance.
+	 * @since 7.4.0
+	 */
+	@Nonnull
+	public ParserOptions setDontEncodeElementsForSummaryMode(@Nullable Collection<String> theDontEncodeElements) {
+		Set<String> dontEncodeElements = null;
+		if (theDontEncodeElements != null && !theDontEncodeElements.isEmpty()) {
+			dontEncodeElements = new HashSet<>(theDontEncodeElements);
+		}
+		myDontEncodeElementsForSummaryMode = dontEncodeElements;
+		return this;
+	}
+
+	/**
+	 * @return Returns the values provided to {@link #setDontEncodeElementsForSummaryMode(Collection)}
+	 * or <code>null</code>
+	 * @since 7.4.0
+	 */
+	@Nullable
+	public Set<String> getDontEncodeElementsForSummaryMode() {
+		return myDontEncodeElementsForSummaryMode;
+	}
 }