001/*
002 * #%L
003 * HAPI FHIR - Core Library
004 * %%
005 * Copyright (C) 2014 - 2024 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.util;
021
022import ca.uhn.fhir.context.BaseRuntimeChildDefinition;
023import ca.uhn.fhir.context.BaseRuntimeElementCompositeDefinition;
024import ca.uhn.fhir.context.BaseRuntimeElementDefinition;
025import ca.uhn.fhir.context.BaseRuntimeElementDefinition.ChildTypeEnum;
026import ca.uhn.fhir.context.ConfigurationException;
027import ca.uhn.fhir.context.FhirContext;
028import ca.uhn.fhir.context.FhirVersionEnum;
029import ca.uhn.fhir.context.RuntimeChildChoiceDefinition;
030import ca.uhn.fhir.context.RuntimeChildDirectResource;
031import ca.uhn.fhir.context.RuntimeExtensionDtDefinition;
032import ca.uhn.fhir.context.RuntimeResourceDefinition;
033import ca.uhn.fhir.context.RuntimeSearchParam;
034import ca.uhn.fhir.i18n.Msg;
035import ca.uhn.fhir.model.api.ExtensionDt;
036import ca.uhn.fhir.model.api.IIdentifiableElement;
037import ca.uhn.fhir.model.api.IResource;
038import ca.uhn.fhir.model.api.ISupportsUndeclaredExtensions;
039import ca.uhn.fhir.model.base.composite.BaseContainedDt;
040import ca.uhn.fhir.model.base.composite.BaseResourceReferenceDt;
041import ca.uhn.fhir.model.primitive.IdDt;
042import ca.uhn.fhir.model.primitive.StringDt;
043import ca.uhn.fhir.parser.DataFormatException;
044import com.google.common.collect.Lists;
045import jakarta.annotation.Nonnull;
046import jakarta.annotation.Nullable;
047import org.apache.commons.lang3.StringUtils;
048import org.apache.commons.lang3.Validate;
049import org.hl7.fhir.instance.model.api.IBase;
050import org.hl7.fhir.instance.model.api.IBaseElement;
051import org.hl7.fhir.instance.model.api.IBaseExtension;
052import org.hl7.fhir.instance.model.api.IBaseHasExtensions;
053import org.hl7.fhir.instance.model.api.IBaseHasModifierExtensions;
054import org.hl7.fhir.instance.model.api.IBaseReference;
055import org.hl7.fhir.instance.model.api.IBaseResource;
056import org.hl7.fhir.instance.model.api.IDomainResource;
057import org.hl7.fhir.instance.model.api.IIdType;
058import org.hl7.fhir.instance.model.api.IPrimitiveType;
059
060import java.util.ArrayList;
061import java.util.Arrays;
062import java.util.Collection;
063import java.util.Collections;
064import java.util.HashMap;
065import java.util.HashSet;
066import java.util.IdentityHashMap;
067import java.util.Iterator;
068import java.util.List;
069import java.util.Map;
070import java.util.Objects;
071import java.util.Optional;
072import java.util.Set;
073import java.util.regex.Matcher;
074import java.util.regex.Pattern;
075import java.util.stream.Collectors;
076
077import static org.apache.commons.lang3.StringUtils.defaultString;
078import static org.apache.commons.lang3.StringUtils.isBlank;
079import static org.apache.commons.lang3.StringUtils.isNotBlank;
080import static org.apache.commons.lang3.StringUtils.substring;
081
082public class FhirTerser {
083
084        private static final Pattern COMPARTMENT_MATCHER_PATH =
085                        Pattern.compile("([a-zA-Z.]+)\\.where\\(resolve\\(\\) is ([a-zA-Z]+)\\)");
086        private static final String USER_DATA_KEY_CONTAIN_RESOURCES_COMPLETED =
087                        FhirTerser.class.getName() + "_CONTAIN_RESOURCES_COMPLETED";
088        private final FhirContext myContext;
089
090        public FhirTerser(FhirContext theContext) {
091                super();
092                myContext = theContext;
093        }
094
095        private List<String> addNameToList(List<String> theCurrentList, BaseRuntimeChildDefinition theChildDefinition) {
096                if (theChildDefinition == null) return null;
097                if (theCurrentList == null || theCurrentList.isEmpty())
098                        return new ArrayList<>(Collections.singletonList(theChildDefinition.getElementName()));
099                List<String> newList = new ArrayList<>(theCurrentList);
100                newList.add(theChildDefinition.getElementName());
101                return newList;
102        }
103
104        private ExtensionDt createEmptyExtensionDt(IBaseExtension theBaseExtension, String theUrl) {
105                return createEmptyExtensionDt(theBaseExtension, false, theUrl);
106        }
107
108        @SuppressWarnings("unchecked")
109        private ExtensionDt createEmptyExtensionDt(IBaseExtension theBaseExtension, boolean theIsModifier, String theUrl) {
110                ExtensionDt retVal = new ExtensionDt(theIsModifier, theUrl);
111                theBaseExtension.getExtension().add(retVal);
112                return retVal;
113        }
114
115        private ExtensionDt createEmptyExtensionDt(
116                        ISupportsUndeclaredExtensions theSupportsUndeclaredExtensions, String theUrl) {
117                return createEmptyExtensionDt(theSupportsUndeclaredExtensions, false, theUrl);
118        }
119
120        private ExtensionDt createEmptyExtensionDt(
121                        ISupportsUndeclaredExtensions theSupportsUndeclaredExtensions, boolean theIsModifier, String theUrl) {
122                return theSupportsUndeclaredExtensions.addUndeclaredExtension(theIsModifier, theUrl);
123        }
124
125        private IBaseExtension createEmptyExtension(IBaseHasExtensions theBaseHasExtensions, String theUrl) {
126                return (IBaseExtension) theBaseHasExtensions.addExtension().setUrl(theUrl);
127        }
128
129        private IBaseExtension createEmptyModifierExtension(
130                        IBaseHasModifierExtensions theBaseHasModifierExtensions, String theUrl) {
131                return (IBaseExtension)
132                                theBaseHasModifierExtensions.addModifierExtension().setUrl(theUrl);
133        }
134
135        private ExtensionDt createEmptyModifierExtensionDt(
136                        ISupportsUndeclaredExtensions theSupportsUndeclaredExtensions, String theUrl) {
137                return createEmptyExtensionDt(theSupportsUndeclaredExtensions, true, theUrl);
138        }
139
140        /**
141         * Clones all values from a source object into the equivalent fields in a target object
142         *
143         * @param theSource              The source object (must not be null)
144         * @param theTarget              The target object to copy values into (must not be null)
145         * @param theIgnoreMissingFields The ignore fields in the target which do not exist (if false, an exception will be thrown if the target is unable to accept a value from the source)
146         * @return Returns the target (which will be the same object that was passed into theTarget) for easy chaining
147         */
148        public IBase cloneInto(IBase theSource, IBase theTarget, boolean theIgnoreMissingFields) {
149                Validate.notNull(theSource, "theSource must not be null");
150                Validate.notNull(theTarget, "theTarget must not be null");
151
152                // DSTU3+
153                if (theSource instanceof IBaseElement) {
154                        IBaseElement source = (IBaseElement) theSource;
155                        IBaseElement target = (IBaseElement) theTarget;
156                        target.setId(source.getId());
157                }
158
159                // DSTU2 only
160                if (theSource instanceof IIdentifiableElement) {
161                        IIdentifiableElement source = (IIdentifiableElement) theSource;
162                        IIdentifiableElement target = (IIdentifiableElement) theTarget;
163                        target.setElementSpecificId(source.getElementSpecificId());
164                }
165
166                // DSTU2 only
167                if (theSource instanceof IResource) {
168                        IResource source = (IResource) theSource;
169                        IResource target = (IResource) theTarget;
170                        target.setId(source.getId());
171                        target.getResourceMetadata().putAll(source.getResourceMetadata());
172                }
173
174                if (theSource instanceof IPrimitiveType<?>) {
175                        if (theTarget instanceof IPrimitiveType<?>) {
176                                String valueAsString = ((IPrimitiveType<?>) theSource).getValueAsString();
177                                if (isNotBlank(valueAsString)) {
178                                        ((IPrimitiveType<?>) theTarget).setValueAsString(valueAsString);
179                                }
180                                if (theSource instanceof IBaseHasExtensions && theTarget instanceof IBaseHasExtensions) {
181                                        List<? extends IBaseExtension<?, ?>> extensions = ((IBaseHasExtensions) theSource).getExtension();
182                                        for (IBaseExtension<?, ?> nextSource : extensions) {
183                                                IBaseExtension<?, ?> nextTarget = ((IBaseHasExtensions) theTarget).addExtension();
184                                                cloneInto(nextSource, nextTarget, theIgnoreMissingFields);
185                                        }
186                                }
187                                return theSource;
188                        }
189                        if (theIgnoreMissingFields) {
190                                return theSource;
191                        }
192                        throw new DataFormatException(Msg.code(1788) + "Can not copy value from primitive of type "
193                                        + theSource.getClass().getName() + " into type "
194                                        + theTarget.getClass().getName());
195                }
196
197                BaseRuntimeElementCompositeDefinition<?> sourceDef =
198                                (BaseRuntimeElementCompositeDefinition<?>) myContext.getElementDefinition(theSource.getClass());
199                BaseRuntimeElementCompositeDefinition<?> targetDef =
200                                (BaseRuntimeElementCompositeDefinition<?>) myContext.getElementDefinition(theTarget.getClass());
201
202                List<BaseRuntimeChildDefinition> children = sourceDef.getChildren();
203                if (sourceDef instanceof RuntimeExtensionDtDefinition) {
204                        children = ((RuntimeExtensionDtDefinition) sourceDef).getChildrenIncludingUrl();
205                }
206
207                for (BaseRuntimeChildDefinition nextChild : children)
208                        for (IBase nextValue : nextChild.getAccessor().getValues(theSource)) {
209                                Class<? extends IBase> valueType = nextValue.getClass();
210                                String elementName = nextChild.getChildNameByDatatype(valueType);
211                                BaseRuntimeChildDefinition targetChild = targetDef.getChildByName(elementName);
212                                if (targetChild == null) {
213                                        if (theIgnoreMissingFields) {
214                                                continue;
215                                        }
216                                        throw new DataFormatException(Msg.code(1789) + "Type "
217                                                        + theTarget.getClass().getName() + " does not have a child with name " + elementName);
218                                }
219
220                                BaseRuntimeElementDefinition<?> element = myContext.getElementDefinition(valueType);
221                                Object instanceConstructorArg = targetChild.getInstanceConstructorArguments();
222                                IBase target;
223                                if (element == null && BaseContainedDt.class.isAssignableFrom(valueType)) {
224                                        /*
225                                         * This is a hack for DSTU2 - The way we did contained resources in
226                                         * the DSTU2 model was weird, since the element isn't actually a FHIR type.
227                                         * This is fixed in DSTU3+ so this hack only applies there.
228                                         */
229                                        BaseContainedDt containedTarget = (BaseContainedDt) ReflectionUtil.newInstance(valueType);
230                                        BaseContainedDt containedSource = (BaseContainedDt) nextValue;
231                                        for (IResource next : containedSource.getContainedResources()) {
232                                                List containedResources = containedTarget.getContainedResources();
233                                                containedResources.add(next);
234                                        }
235                                        targetChild.getMutator().addValue(theTarget, containedTarget);
236                                        continue;
237                                } else if (instanceConstructorArg != null) {
238                                        target = element.newInstance(instanceConstructorArg);
239                                } else {
240                                        target = element.newInstance();
241                                }
242
243                                targetChild.getMutator().addValue(theTarget, target);
244                                cloneInto(nextValue, target, theIgnoreMissingFields);
245                        }
246
247                return theTarget;
248        }
249
250        /**
251         * Returns a list containing all child elements (including the resource itself) which are <b>non-empty</b> and are either of the exact type specified, or are a subclass of that type.
252         * <p>
253         * For example, specifying a type of {@link StringDt} would return all non-empty string instances within the message. Specifying a type of {@link IResource} would return the resource itself, as
254         * well as any contained resources.
255         * </p>
256         * <p>
257         * Note on scope: This method will descend into any contained resources ({@link IResource#getContained()}) as well, but will not descend into linked resources (e.g.
258         * {@link BaseResourceReferenceDt#getResource()}) or embedded resources (e.g. Bundle.entry.resource)
259         * </p>
260         *
261         * @param theResource The resource instance to search. Must not be null.
262         * @param theType     The type to search for. Must not be null.
263         * @return Returns a list of all matching elements
264         */
265        public <T extends IBase> List<T> getAllPopulatedChildElementsOfType(
266                        IBaseResource theResource, final Class<T> theType) {
267                final ArrayList<T> retVal = new ArrayList<>();
268                BaseRuntimeElementCompositeDefinition<?> def = myContext.getResourceDefinition(theResource);
269                visit(newMap(), theResource, theResource, null, null, def, new IModelVisitor() {
270                        @SuppressWarnings("unchecked")
271                        @Override
272                        public void acceptElement(
273                                        IBaseResource theOuterResource,
274                                        IBase theElement,
275                                        List<String> thePathToElement,
276                                        BaseRuntimeChildDefinition theChildDefinition,
277                                        BaseRuntimeElementDefinition<?> theDefinition) {
278                                if (theElement == null || theElement.isEmpty()) {
279                                        return;
280                                }
281
282                                if (theType.isAssignableFrom(theElement.getClass())) {
283                                        retVal.add((T) theElement);
284                                }
285                        }
286                });
287                return retVal;
288        }
289
290        /**
291         * Extracts all outbound references from a resource
292         *
293         * @param theResource the resource to be analyzed
294         * @return a list of references to other resources
295         */
296        public List<ResourceReferenceInfo> getAllResourceReferences(final IBaseResource theResource) {
297                return getAllResourceReferencesExcluding(theResource, Lists.newArrayList());
298        }
299
300        /**
301         * Extracts all outbound references from a resource, excluding any that are located on black-listed parts of the
302         * resource
303         *
304         * @param theResource       the resource to be analyzed
305         * @param thePathsToExclude a list of dot-delimited paths not to include in the result
306         * @return a list of references to other resources
307         */
308        public List<ResourceReferenceInfo> getAllResourceReferencesExcluding(
309                        final IBaseResource theResource, List<String> thePathsToExclude) {
310                final ArrayList<ResourceReferenceInfo> retVal = new ArrayList<>();
311                BaseRuntimeElementCompositeDefinition<?> def = myContext.getResourceDefinition(theResource);
312                List<List<String>> tokenizedPathsToExclude = thePathsToExclude.stream()
313                                .map(path -> StringUtils.split(path, "."))
314                                .map(Lists::newArrayList)
315                                .collect(Collectors.toList());
316
317                visit(newMap(), theResource, theResource, null, null, def, new IModelVisitor() {
318                        @Override
319                        public void acceptElement(
320                                        IBaseResource theOuterResource,
321                                        IBase theElement,
322                                        List<String> thePathToElement,
323                                        BaseRuntimeChildDefinition theChildDefinition,
324                                        BaseRuntimeElementDefinition<?> theDefinition) {
325                                if (theElement == null || theElement.isEmpty()) {
326                                        return;
327                                }
328
329                                if (thePathToElement != null && pathShouldBeExcluded(tokenizedPathsToExclude, thePathToElement)) {
330                                        return;
331                                }
332                                if (IBaseReference.class.isAssignableFrom(theElement.getClass())) {
333                                        retVal.add(new ResourceReferenceInfo(
334                                                        myContext, theOuterResource, thePathToElement, (IBaseReference) theElement));
335                                }
336                        }
337                });
338                return retVal;
339        }
340
341        private boolean pathShouldBeExcluded(List<List<String>> theTokenizedPathsToExclude, List<String> thePathToElement) {
342                return theTokenizedPathsToExclude.stream().anyMatch(p -> {
343                        // Check whether the path to the element starts with the path to be excluded
344                        if (p.size() > thePathToElement.size()) {
345                                return false;
346                        }
347
348                        List<String> prefix = thePathToElement.subList(0, p.size());
349
350                        return Objects.equals(p, prefix);
351                });
352        }
353
354        private BaseRuntimeChildDefinition getDefinition(
355                        BaseRuntimeElementCompositeDefinition<?> theCurrentDef, List<String> theSubList) {
356                BaseRuntimeChildDefinition nextDef = theCurrentDef.getChildByNameOrThrowDataFormatException(theSubList.get(0));
357
358                if (theSubList.size() == 1) {
359                        return nextDef;
360                }
361                BaseRuntimeElementCompositeDefinition<?> cmp =
362                                (BaseRuntimeElementCompositeDefinition<?>) nextDef.getChildByName(theSubList.get(0));
363                return getDefinition(cmp, theSubList.subList(1, theSubList.size()));
364        }
365
366        public BaseRuntimeChildDefinition getDefinition(Class<? extends IBaseResource> theResourceType, String thePath) {
367                RuntimeResourceDefinition def = myContext.getResourceDefinition(theResourceType);
368
369                List<String> parts = Arrays.asList(thePath.split("\\."));
370                List<String> subList = parts.subList(1, parts.size());
371                if (subList.size() < 1) {
372                        throw new ConfigurationException(Msg.code(1790) + "Invalid path: " + thePath);
373                }
374                return getDefinition(def, subList);
375        }
376
377        public Object getSingleValueOrNull(IBase theTarget, String thePath) {
378                Class<IBase> wantedType = IBase.class;
379
380                return getSingleValueOrNull(theTarget, thePath, wantedType);
381        }
382
383        public <T extends IBase> T getSingleValueOrNull(IBase theTarget, String thePath, Class<T> theWantedType) {
384                Validate.notNull(theTarget, "theTarget must not be null");
385                Validate.notBlank(thePath, "thePath must not be empty");
386
387                BaseRuntimeElementDefinition<?> def = myContext.getElementDefinition(theTarget.getClass());
388                if (!(def instanceof BaseRuntimeElementCompositeDefinition)) {
389                        throw new IllegalArgumentException(Msg.code(1791) + "Target is not a composite type: "
390                                        + theTarget.getClass().getName());
391                }
392
393                BaseRuntimeElementCompositeDefinition<?> currentDef = (BaseRuntimeElementCompositeDefinition<?>) def;
394
395                List<String> parts = parsePath(currentDef, thePath);
396
397                List<T> retVal = getValues(currentDef, theTarget, parts, theWantedType);
398                if (retVal.isEmpty()) {
399                        return null;
400                }
401                return retVal.get(0);
402        }
403
404        public Optional<String> getSinglePrimitiveValue(IBase theTarget, String thePath) {
405                return getSingleValue(theTarget, thePath, IPrimitiveType.class).map(t -> t.getValueAsString());
406        }
407
408        public String getSinglePrimitiveValueOrNull(IBase theTarget, String thePath) {
409                return getSingleValue(theTarget, thePath, IPrimitiveType.class)
410                                .map(t -> t.getValueAsString())
411                                .orElse(null);
412        }
413
414        public <T extends IBase> Optional<T> getSingleValue(IBase theTarget, String thePath, Class<T> theWantedType) {
415                return Optional.ofNullable(getSingleValueOrNull(theTarget, thePath, theWantedType));
416        }
417
418        private <T extends IBase> List<T> getValues(
419                        BaseRuntimeElementCompositeDefinition<?> theCurrentDef,
420                        IBase theCurrentObj,
421                        List<String> theSubList,
422                        Class<T> theWantedClass) {
423                return getValues(theCurrentDef, theCurrentObj, theSubList, theWantedClass, false, false);
424        }
425
426        @SuppressWarnings("unchecked")
427        private <T extends IBase> List<T> getValues(
428                        BaseRuntimeElementCompositeDefinition<?> theCurrentDef,
429                        IBase theCurrentObj,
430                        List<String> theSubList,
431                        Class<T> theWantedClass,
432                        boolean theCreate,
433                        boolean theAddExtension) {
434                if (theSubList.isEmpty()) {
435                        return Collections.emptyList();
436                }
437
438                String name = theSubList.get(0);
439                List<T> retVal = new ArrayList<>();
440
441                if (name.startsWith("extension('")) {
442                        String extensionUrl = name.substring("extension('".length());
443                        int endIndex = extensionUrl.indexOf('\'');
444                        if (endIndex != -1) {
445                                extensionUrl = extensionUrl.substring(0, endIndex);
446                        }
447
448                        if (myContext.getVersion().getVersion().isOlderThan(FhirVersionEnum.DSTU3)) {
449                                // DTSU2
450                                final String extensionDtUrlForLambda = extensionUrl;
451                                List<ExtensionDt> extensionDts = Collections.emptyList();
452                                if (theCurrentObj instanceof ISupportsUndeclaredExtensions) {
453                                        extensionDts = ((ISupportsUndeclaredExtensions) theCurrentObj)
454                                                        .getUndeclaredExtensions().stream()
455                                                                        .filter(t -> t.getUrl().equals(extensionDtUrlForLambda))
456                                                                        .collect(Collectors.toList());
457
458                                        if (theAddExtension
459                                                        && (!(theCurrentObj instanceof IBaseExtension)
460                                                                        || (extensionDts.isEmpty() && theSubList.size() == 1))) {
461                                                extensionDts.add(
462                                                                createEmptyExtensionDt((ISupportsUndeclaredExtensions) theCurrentObj, extensionUrl));
463                                        }
464
465                                        if (extensionDts.isEmpty() && theCreate) {
466                                                extensionDts.add(
467                                                                createEmptyExtensionDt((ISupportsUndeclaredExtensions) theCurrentObj, extensionUrl));
468                                        }
469
470                                } else if (theCurrentObj instanceof IBaseExtension) {
471                                        extensionDts = ((IBaseExtension) theCurrentObj).getExtension();
472
473                                        if (theAddExtension && (extensionDts.isEmpty() && theSubList.size() == 1)) {
474                                                extensionDts.add(createEmptyExtensionDt((IBaseExtension) theCurrentObj, extensionUrl));
475                                        }
476
477                                        if (extensionDts.isEmpty() && theCreate) {
478                                                extensionDts.add(createEmptyExtensionDt((IBaseExtension) theCurrentObj, extensionUrl));
479                                        }
480                                }
481
482                                for (ExtensionDt next : extensionDts) {
483                                        if (theWantedClass.isAssignableFrom(next.getClass())) {
484                                                retVal.add((T) next);
485                                        }
486                                }
487                        } else {
488                                // DSTU3+
489                                final String extensionUrlForLambda = extensionUrl;
490                                List<IBaseExtension> extensions = Collections.emptyList();
491                                if (theCurrentObj instanceof IBaseHasExtensions) {
492                                        extensions = ((IBaseHasExtensions) theCurrentObj)
493                                                        .getExtension().stream()
494                                                                        .filter(t -> t.getUrl().equals(extensionUrlForLambda))
495                                                                        .collect(Collectors.toList());
496
497                                        if (theAddExtension
498                                                        && (!(theCurrentObj instanceof IBaseExtension)
499                                                                        || (extensions.isEmpty() && theSubList.size() == 1))) {
500                                                extensions.add(createEmptyExtension((IBaseHasExtensions) theCurrentObj, extensionUrl));
501                                        }
502
503                                        if (extensions.isEmpty() && theCreate) {
504                                                extensions.add(createEmptyExtension((IBaseHasExtensions) theCurrentObj, extensionUrl));
505                                        }
506                                }
507
508                                for (IBaseExtension next : extensions) {
509                                        if (theWantedClass.isAssignableFrom(next.getClass())) {
510                                                retVal.add((T) next);
511                                        }
512                                }
513                        }
514
515                        if (theSubList.size() > 1) {
516                                List<T> values = retVal;
517                                retVal = new ArrayList<>();
518                                for (T nextElement : values) {
519                                        BaseRuntimeElementCompositeDefinition<?> nextChildDef = (BaseRuntimeElementCompositeDefinition<?>)
520                                                        myContext.getElementDefinition(nextElement.getClass());
521                                        List<T> foundValues = getValues(
522                                                        nextChildDef,
523                                                        nextElement,
524                                                        theSubList.subList(1, theSubList.size()),
525                                                        theWantedClass,
526                                                        theCreate,
527                                                        theAddExtension);
528                                        retVal.addAll(foundValues);
529                                }
530                        }
531
532                        return retVal;
533                }
534
535                if (name.startsWith("modifierExtension('")) {
536                        String extensionUrl = name.substring("modifierExtension('".length());
537                        int endIndex = extensionUrl.indexOf('\'');
538                        if (endIndex != -1) {
539                                extensionUrl = extensionUrl.substring(0, endIndex);
540                        }
541
542                        if (myContext.getVersion().getVersion().isOlderThan(FhirVersionEnum.DSTU3)) {
543                                // DSTU2
544                                final String extensionDtUrlForLambda = extensionUrl;
545                                List<ExtensionDt> extensionDts = Collections.emptyList();
546                                if (theCurrentObj instanceof ISupportsUndeclaredExtensions) {
547                                        extensionDts = ((ISupportsUndeclaredExtensions) theCurrentObj)
548                                                        .getUndeclaredModifierExtensions().stream()
549                                                                        .filter(t -> t.getUrl().equals(extensionDtUrlForLambda))
550                                                                        .collect(Collectors.toList());
551
552                                        if (theAddExtension
553                                                        && (!(theCurrentObj instanceof IBaseExtension)
554                                                                        || (extensionDts.isEmpty() && theSubList.size() == 1))) {
555                                                extensionDts.add(createEmptyModifierExtensionDt(
556                                                                (ISupportsUndeclaredExtensions) theCurrentObj, extensionUrl));
557                                        }
558
559                                        if (extensionDts.isEmpty() && theCreate) {
560                                                extensionDts.add(createEmptyModifierExtensionDt(
561                                                                (ISupportsUndeclaredExtensions) theCurrentObj, extensionUrl));
562                                        }
563
564                                } else if (theCurrentObj instanceof IBaseExtension) {
565                                        extensionDts = ((IBaseExtension) theCurrentObj).getExtension();
566
567                                        if (theAddExtension && (extensionDts.isEmpty() && theSubList.size() == 1)) {
568                                                extensionDts.add(createEmptyExtensionDt((IBaseExtension) theCurrentObj, extensionUrl));
569                                        }
570
571                                        if (extensionDts.isEmpty() && theCreate) {
572                                                extensionDts.add(createEmptyExtensionDt((IBaseExtension) theCurrentObj, extensionUrl));
573                                        }
574                                }
575
576                                for (ExtensionDt next : extensionDts) {
577                                        if (theWantedClass.isAssignableFrom(next.getClass())) {
578                                                retVal.add((T) next);
579                                        }
580                                }
581                        } else {
582                                // DSTU3+
583                                final String extensionUrlForLambda = extensionUrl;
584                                List<IBaseExtension> extensions = Collections.emptyList();
585
586                                if (theCurrentObj instanceof IBaseHasModifierExtensions) {
587                                        extensions = ((IBaseHasModifierExtensions) theCurrentObj)
588                                                        .getModifierExtension().stream()
589                                                                        .filter(t -> t.getUrl().equals(extensionUrlForLambda))
590                                                                        .collect(Collectors.toList());
591
592                                        if (theAddExtension
593                                                        && (!(theCurrentObj instanceof IBaseExtension)
594                                                                        || (extensions.isEmpty() && theSubList.size() == 1))) {
595                                                extensions.add(
596                                                                createEmptyModifierExtension((IBaseHasModifierExtensions) theCurrentObj, extensionUrl));
597                                        }
598
599                                        if (extensions.isEmpty() && theCreate) {
600                                                extensions.add(
601                                                                createEmptyModifierExtension((IBaseHasModifierExtensions) theCurrentObj, extensionUrl));
602                                        }
603                                }
604
605                                for (IBaseExtension next : extensions) {
606                                        if (theWantedClass.isAssignableFrom(next.getClass())) {
607                                                retVal.add((T) next);
608                                        }
609                                }
610                        }
611
612                        if (theSubList.size() > 1) {
613                                List<T> values = retVal;
614                                retVal = new ArrayList<>();
615                                for (T nextElement : values) {
616                                        BaseRuntimeElementCompositeDefinition<?> nextChildDef = (BaseRuntimeElementCompositeDefinition<?>)
617                                                        myContext.getElementDefinition(nextElement.getClass());
618                                        List<T> foundValues = getValues(
619                                                        nextChildDef,
620                                                        nextElement,
621                                                        theSubList.subList(1, theSubList.size()),
622                                                        theWantedClass,
623                                                        theCreate,
624                                                        theAddExtension);
625                                        retVal.addAll(foundValues);
626                                }
627                        }
628
629                        return retVal;
630                }
631
632                BaseRuntimeChildDefinition nextDef = theCurrentDef.getChildByNameOrThrowDataFormatException(name);
633                List<? extends IBase> values = nextDef.getAccessor().getValues(theCurrentObj);
634
635                if (values.isEmpty() && theCreate) {
636                        BaseRuntimeElementDefinition<?> childByName = nextDef.getChildByName(name);
637                        Object arg = nextDef.getInstanceConstructorArguments();
638                        IBase value;
639                        if (arg != null) {
640                                value = childByName.newInstance(arg);
641                        } else {
642                                value = childByName.newInstance();
643                        }
644                        nextDef.getMutator().addValue(theCurrentObj, value);
645                        List<IBase> list = new ArrayList<>();
646                        list.add(value);
647                        values = list;
648                }
649
650                if (theSubList.size() == 1) {
651                        if (nextDef instanceof RuntimeChildChoiceDefinition) {
652                                for (IBase next : values) {
653                                        if (next != null) {
654                                                if (name.endsWith("[x]")) {
655                                                        if (theWantedClass == null || theWantedClass.isAssignableFrom(next.getClass())) {
656                                                                retVal.add((T) next);
657                                                        }
658                                                } else {
659                                                        String childName = nextDef.getChildNameByDatatype(next.getClass());
660                                                        if (theSubList.get(0).equals(childName)) {
661                                                                if (theWantedClass == null || theWantedClass.isAssignableFrom(next.getClass())) {
662                                                                        retVal.add((T) next);
663                                                                }
664                                                        }
665                                                }
666                                        }
667                                }
668                        } else {
669                                for (IBase next : values) {
670                                        if (next != null) {
671                                                if (theWantedClass == null || theWantedClass.isAssignableFrom(next.getClass())) {
672                                                        retVal.add((T) next);
673                                                }
674                                        }
675                                }
676                        }
677                } else {
678                        for (IBase nextElement : values) {
679                                BaseRuntimeElementCompositeDefinition<?> nextChildDef = (BaseRuntimeElementCompositeDefinition<?>)
680                                                myContext.getElementDefinition(nextElement.getClass());
681                                List<T> foundValues = getValues(
682                                                nextChildDef,
683                                                nextElement,
684                                                theSubList.subList(1, theSubList.size()),
685                                                theWantedClass,
686                                                theCreate,
687                                                theAddExtension);
688                                retVal.addAll(foundValues);
689                        }
690                }
691                return retVal;
692        }
693
694        /**
695         * Returns values stored in an element identified by its path. The list of values is of
696         * type {@link Object}.
697         *
698         * @param theElement The element to be accessed. Must not be null.
699         * @param thePath    The path for the element to be accessed.@param theElement The resource instance to be accessed. Must not be null.
700         * @return A list of values of type {@link Object}.
701         */
702        public List<IBase> getValues(IBase theElement, String thePath) {
703                Class<IBase> wantedClass = IBase.class;
704
705                return getValues(theElement, thePath, wantedClass);
706        }
707
708        /**
709         * Returns values stored in an element identified by its path. The list of values is of
710         * type {@link Object}.
711         *
712         * @param theElement The element to be accessed. Must not be null.
713         * @param thePath    The path for the element to be accessed.
714         * @param theCreate  When set to <code>true</code>, the terser will create a null-valued element where none exists.
715         * @return A list of values of type {@link Object}.
716         */
717        public List<IBase> getValues(IBase theElement, String thePath, boolean theCreate) {
718                Class<IBase> wantedClass = IBase.class;
719
720                return getValues(theElement, thePath, wantedClass, theCreate);
721        }
722
723        /**
724         * Returns values stored in an element identified by its path. The list of values is of
725         * type {@link Object}.
726         *
727         * @param theElement      The element to be accessed. Must not be null.
728         * @param thePath         The path for the element to be accessed.
729         * @param theCreate       When set to <code>true</code>, the terser will create a null-valued element where none exists.
730         * @param theAddExtension When set to <code>true</code>, the terser will add a null-valued extension where one or more such extensions already exist.
731         * @return A list of values of type {@link Object}.
732         */
733        public List<IBase> getValues(IBase theElement, String thePath, boolean theCreate, boolean theAddExtension) {
734                Class<IBase> wantedClass = IBase.class;
735
736                return getValues(theElement, thePath, wantedClass, theCreate, theAddExtension);
737        }
738
739        /**
740         * Returns values stored in an element identified by its path. The list of values is of
741         * type <code>theWantedClass</code>.
742         *
743         * @param theElement     The element to be accessed. Must not be null.
744         * @param thePath        The path for the element to be accessed.
745         * @param theWantedClass The desired class to be returned in a list.
746         * @param <T>            Type declared by <code>theWantedClass</code>
747         * @return A list of values of type <code>theWantedClass</code>.
748         */
749        public <T extends IBase> List<T> getValues(IBase theElement, String thePath, Class<T> theWantedClass) {
750                BaseRuntimeElementCompositeDefinition<?> def =
751                                (BaseRuntimeElementCompositeDefinition<?>) myContext.getElementDefinition(theElement.getClass());
752                List<String> parts = parsePath(def, thePath);
753                return getValues(def, theElement, parts, theWantedClass);
754        }
755
756        /**
757         * Returns values stored in an element identified by its path. The list of values is of
758         * type <code>theWantedClass</code>.
759         *
760         * @param theElement     The element to be accessed. Must not be null.
761         * @param thePath        The path for the element to be accessed.
762         * @param theWantedClass The desired class to be returned in a list.
763         * @param theCreate      When set to <code>true</code>, the terser will create a null-valued element where none exists.
764         * @param <T>            Type declared by <code>theWantedClass</code>
765         * @return A list of values of type <code>theWantedClass</code>.
766         */
767        public <T extends IBase> List<T> getValues(
768                        IBase theElement, String thePath, Class<T> theWantedClass, boolean theCreate) {
769                BaseRuntimeElementCompositeDefinition<?> def =
770                                (BaseRuntimeElementCompositeDefinition<?>) myContext.getElementDefinition(theElement.getClass());
771                List<String> parts = parsePath(def, thePath);
772                return getValues(def, theElement, parts, theWantedClass, theCreate, false);
773        }
774
775        /**
776         * Returns values stored in an element identified by its path. The list of values is of
777         * type <code>theWantedClass</code>.
778         *
779         * @param theElement      The element to be accessed. Must not be null.
780         * @param thePath         The path for the element to be accessed.
781         * @param theWantedClass  The desired class to be returned in a list.
782         * @param theCreate       When set to <code>true</code>, the terser will create a null-valued element where none exists.
783         * @param theAddExtension When set to <code>true</code>, the terser will add a null-valued extension where one or more such extensions already exist.
784         * @param <T>             Type declared by <code>theWantedClass</code>
785         * @return A list of values of type <code>theWantedClass</code>.
786         */
787        public <T extends IBase> List<T> getValues(
788                        IBase theElement, String thePath, Class<T> theWantedClass, boolean theCreate, boolean theAddExtension) {
789                BaseRuntimeElementCompositeDefinition<?> def =
790                                (BaseRuntimeElementCompositeDefinition<?>) myContext.getElementDefinition(theElement.getClass());
791                List<String> parts = parsePath(def, thePath);
792                return getValues(def, theElement, parts, theWantedClass, theCreate, theAddExtension);
793        }
794
795        private List<String> parsePath(BaseRuntimeElementCompositeDefinition<?> theElementDef, String thePath) {
796                List<String> parts = new ArrayList<>();
797
798                int currentStart = 0;
799                boolean inSingleQuote = false;
800                for (int i = 0; i < thePath.length(); i++) {
801                        switch (thePath.charAt(i)) {
802                                case '\'':
803                                        inSingleQuote = !inSingleQuote;
804                                        break;
805                                case '.':
806                                        if (!inSingleQuote) {
807                                                parts.add(thePath.substring(currentStart, i));
808                                                currentStart = i + 1;
809                                        }
810                                        break;
811                        }
812                }
813
814                parts.add(thePath.substring(currentStart));
815
816                String firstPart = parts.get(0);
817                if (Character.isUpperCase(firstPart.charAt(0)) && theElementDef instanceof RuntimeResourceDefinition) {
818                        if (firstPart.equals(theElementDef.getName())) {
819                                parts = parts.subList(1, parts.size());
820                        } else {
821                                parts = Collections.emptyList();
822                                return parts;
823                        }
824                } else if (firstPart.equals(theElementDef.getName())) {
825                        parts = parts.subList(1, parts.size());
826                }
827
828                if (parts.size() < 1) {
829                        throw new ConfigurationException(Msg.code(1792) + "Invalid path: " + thePath);
830                }
831                return parts;
832        }
833
834        /**
835         * Returns <code>true</code> if <code>theSource</code> is in the compartment named <code>theCompartmentName</code>
836         * belonging to resource <code>theTarget</code>
837         *
838         * @param theCompartmentName The name of the compartment
839         * @param theSource          The potential member of the compartment
840         * @param theTarget          The owner of the compartment. Note that both the resource type and ID must be filled in on this IIdType or the method will throw an {@link IllegalArgumentException}
841         * @return <code>true</code> if <code>theSource</code> is in the compartment
842         * @throws IllegalArgumentException If theTarget does not contain both a resource type and ID
843         */
844        public boolean isSourceInCompartmentForTarget(
845                        String theCompartmentName, IBaseResource theSource, IIdType theTarget) {
846                return isSourceInCompartmentForTarget(theCompartmentName, theSource, theTarget, null);
847        }
848
849        /**
850         * Returns <code>true</code> if <code>theSource</code> is in the compartment named <code>theCompartmentName</code>
851         * belonging to resource <code>theTarget</code>
852         *
853         * @param theCompartmentName                 The name of the compartment
854         * @param theSource                          The potential member of the compartment
855         * @param theTarget                          The owner of the compartment. Note that both the resource type and ID must be filled in on this IIdType or the method will throw an {@link IllegalArgumentException}
856         * @param theAdditionalCompartmentParamNames If provided, search param names provided here will be considered as included in the given compartment for this comparison.
857         * @return <code>true</code> if <code>theSource</code> is in the compartment or one of the additional parameters matched.
858         * @throws IllegalArgumentException If theTarget does not contain both a resource type and ID
859         */
860        public boolean isSourceInCompartmentForTarget(
861                        String theCompartmentName,
862                        IBaseResource theSource,
863                        IIdType theTarget,
864                        Set<String> theAdditionalCompartmentParamNames) {
865                Validate.notBlank(theCompartmentName, "theCompartmentName must not be null or blank");
866                Validate.notNull(theSource, "theSource must not be null");
867                Validate.notNull(theTarget, "theTarget must not be null");
868                Validate.notBlank(
869                                defaultString(theTarget.getResourceType()),
870                                "theTarget must have a populated resource type (theTarget.getResourceType() does not return a value)");
871                Validate.notBlank(
872                                defaultString(theTarget.getIdPart()),
873                                "theTarget must have a populated ID (theTarget.getIdPart() does not return a value)");
874
875                String wantRef = theTarget.toUnqualifiedVersionless().getValue();
876
877                RuntimeResourceDefinition sourceDef = myContext.getResourceDefinition(theSource);
878                if (theSource.getIdElement().hasIdPart()) {
879                        if (wantRef.equals(
880                                        sourceDef.getName() + '/' + theSource.getIdElement().getIdPart())) {
881                                return true;
882                        }
883                }
884
885                class CompartmentOwnerVisitor implements ICompartmentOwnerVisitor {
886
887                        private final String myWantRef;
888
889                        public boolean isFound() {
890                                return myFound;
891                        }
892
893                        private boolean myFound;
894
895                        public CompartmentOwnerVisitor(String theWantRef) {
896                                myWantRef = theWantRef;
897                        }
898
899                        @Override
900                        public boolean consume(IIdType theCompartmentOwner) {
901                                if (myWantRef.equals(
902                                                theCompartmentOwner.toUnqualifiedVersionless().getValue())) {
903                                        myFound = true;
904                                }
905                                return !myFound;
906                        }
907                }
908
909                CompartmentOwnerVisitor consumer = new CompartmentOwnerVisitor(wantRef);
910                visitCompartmentOwnersForResource(theCompartmentName, theSource, theAdditionalCompartmentParamNames, consumer);
911                return consumer.isFound();
912        }
913
914        /**
915         * Returns the owners of the compartment in <code>theSource</code> is in the compartment named <code>theCompartmentName</code>.
916         *
917         * @param theCompartmentName                 The name of the compartment
918         * @param theSource                          The potential member of the compartment
919         * @param theAdditionalCompartmentParamNames If provided, search param names provided here will be considered as included in the given compartment for this comparison.
920         */
921        @Nonnull
922        public List<IIdType> getCompartmentOwnersForResource(
923                        String theCompartmentName, IBaseResource theSource, Set<String> theAdditionalCompartmentParamNames) {
924                Validate.notBlank(theCompartmentName, "theCompartmentName must not be null or blank");
925                Validate.notNull(theSource, "theSource must not be null");
926
927                class CompartmentOwnerVisitor implements ICompartmentOwnerVisitor {
928
929                        private final Set<String> myOwnersAdded = new HashSet<>();
930                        private final List<IIdType> myOwners = new ArrayList<>(2);
931
932                        public List<IIdType> getOwners() {
933                                return myOwners;
934                        }
935
936                        @Override
937                        public boolean consume(IIdType theCompartmentOwner) {
938                                if (myOwnersAdded.add(theCompartmentOwner.getValue())) {
939                                        myOwners.add(theCompartmentOwner);
940                                }
941                                return true;
942                        }
943                }
944
945                CompartmentOwnerVisitor consumer = new CompartmentOwnerVisitor();
946                visitCompartmentOwnersForResource(theCompartmentName, theSource, theAdditionalCompartmentParamNames, consumer);
947                return consumer.getOwners();
948        }
949
950        private void visitCompartmentOwnersForResource(
951                        String theCompartmentName,
952                        IBaseResource theSource,
953                        Set<String> theAdditionalCompartmentParamNames,
954                        ICompartmentOwnerVisitor theConsumer) {
955                Validate.notBlank(theCompartmentName, "theCompartmentName must not be null or blank");
956                Validate.notNull(theSource, "theSource must not be null");
957
958                RuntimeResourceDefinition sourceDef = myContext.getResourceDefinition(theSource);
959                List<RuntimeSearchParam> params = sourceDef.getSearchParamsForCompartmentName(theCompartmentName);
960
961                // If passed an additional set of searchparameter names, add them for comparison purposes.
962                if (theAdditionalCompartmentParamNames != null) {
963                        List<RuntimeSearchParam> additionalParams = theAdditionalCompartmentParamNames.stream()
964                                        .map(sourceDef::getSearchParam)
965                                        .filter(Objects::nonNull)
966                                        .collect(Collectors.toList());
967                        if (params == null || params.isEmpty()) {
968                                params = additionalParams;
969                        } else {
970                                List<RuntimeSearchParam> existingParams = params;
971                                params = new ArrayList<>(existingParams.size() + additionalParams.size());
972                                params.addAll(existingParams);
973                                params.addAll(additionalParams);
974                        }
975                }
976
977                for (RuntimeSearchParam nextParam : params) {
978                        for (String nextPath : nextParam.getPathsSplit()) {
979
980                                /*
981                                 * DSTU3 and before just defined compartments as being (e.g.) named
982                                 * Patient with a path like CarePlan.subject
983                                 *
984                                 * R4 uses a fancier format like CarePlan.subject.where(resolve() is Patient)
985                                 *
986                                 * The following Regex is a hack to make that efficient at runtime.
987                                 */
988                                String wantType = null;
989                                Pattern pattern = COMPARTMENT_MATCHER_PATH;
990                                Matcher matcher = pattern.matcher(nextPath);
991                                if (matcher.matches()) {
992                                        nextPath = matcher.group(1);
993                                        wantType = matcher.group(2);
994                                }
995
996                                List<IBaseReference> values = getValues(theSource, nextPath, IBaseReference.class);
997                                for (IBaseReference nextValue : values) {
998                                        IIdType nextTargetId = nextValue.getReferenceElement().toUnqualifiedVersionless();
999
1000                                        /*
1001                                         * If the reference isn't an explicit resource ID, but instead is just
1002                                         * a resource object, we'll calculate its ID and treat the target
1003                                         * as that.
1004                                         */
1005                                        if (isBlank(nextTargetId.getValue()) && nextValue.getResource() != null) {
1006                                                IBaseResource nextTarget = nextValue.getResource();
1007                                                nextTargetId = nextTarget.getIdElement().toUnqualifiedVersionless();
1008                                                if (!nextTargetId.hasResourceType()) {
1009                                                        String resourceType = myContext.getResourceType(nextTarget);
1010                                                        nextTargetId.setParts(null, resourceType, nextTargetId.getIdPart(), null);
1011                                                }
1012                                        }
1013
1014                                        if (isNotBlank(wantType)) {
1015                                                String nextTargetIdResourceType = nextTargetId.getResourceType();
1016                                                if (nextTargetIdResourceType == null || !nextTargetIdResourceType.equals(wantType)) {
1017                                                        continue;
1018                                                }
1019                                        }
1020
1021                                        if (isNotBlank(nextTargetId.getValue())) {
1022                                                boolean shouldContinue = theConsumer.consume(nextTargetId);
1023                                                if (!shouldContinue) {
1024                                                        return;
1025                                                }
1026                                        }
1027                                }
1028                        }
1029                }
1030        }
1031
1032        private void visit(
1033                        IBase theElement,
1034                        BaseRuntimeChildDefinition theChildDefinition,
1035                        BaseRuntimeElementDefinition<?> theDefinition,
1036                        IModelVisitor2 theCallback,
1037                        List<IBase> theContainingElementPath,
1038                        List<BaseRuntimeChildDefinition> theChildDefinitionPath,
1039                        List<BaseRuntimeElementDefinition<?>> theElementDefinitionPath) {
1040                if (theChildDefinition != null) {
1041                        theChildDefinitionPath.add(theChildDefinition);
1042                }
1043                theContainingElementPath.add(theElement);
1044                theElementDefinitionPath.add(theDefinition);
1045
1046                boolean recurse = theCallback.acceptElement(
1047                                theElement,
1048                                Collections.unmodifiableList(theContainingElementPath),
1049                                Collections.unmodifiableList(theChildDefinitionPath),
1050                                Collections.unmodifiableList(theElementDefinitionPath));
1051                if (recurse) {
1052
1053                        /*
1054                         * Visit undeclared extensions
1055                         */
1056                        if (theElement instanceof ISupportsUndeclaredExtensions) {
1057                                ISupportsUndeclaredExtensions containingElement = (ISupportsUndeclaredExtensions) theElement;
1058                                for (ExtensionDt nextExt : containingElement.getUndeclaredExtensions()) {
1059                                        theContainingElementPath.add(nextExt);
1060                                        theCallback.acceptUndeclaredExtension(
1061                                                        nextExt, theContainingElementPath, theChildDefinitionPath, theElementDefinitionPath);
1062                                        theContainingElementPath.remove(theContainingElementPath.size() - 1);
1063                                }
1064                        }
1065
1066                        /*
1067                         * Now visit the children of the given element
1068                         */
1069                        switch (theDefinition.getChildType()) {
1070                                case ID_DATATYPE:
1071                                case PRIMITIVE_XHTML_HL7ORG:
1072                                case PRIMITIVE_XHTML:
1073                                case PRIMITIVE_DATATYPE:
1074                                        // These are primitive types, so we don't need to visit their children
1075                                        break;
1076                                case RESOURCE:
1077                                case RESOURCE_BLOCK:
1078                                case COMPOSITE_DATATYPE: {
1079                                        BaseRuntimeElementCompositeDefinition<?> childDef =
1080                                                        (BaseRuntimeElementCompositeDefinition<?>) theDefinition;
1081                                        for (BaseRuntimeChildDefinition nextChild : childDef.getChildrenAndExtension()) {
1082                                                List<? extends IBase> values = nextChild.getAccessor().getValues(theElement);
1083                                                if (values != null) {
1084                                                        for (IBase nextValue : values) {
1085                                                                if (nextValue == null) {
1086                                                                        continue;
1087                                                                }
1088                                                                if (nextValue.isEmpty()) {
1089                                                                        continue;
1090                                                                }
1091                                                                BaseRuntimeElementDefinition<?> childElementDef;
1092                                                                Class<? extends IBase> valueType = nextValue.getClass();
1093                                                                childElementDef = nextChild.getChildElementDefinitionByDatatype(valueType);
1094                                                                while (childElementDef == null && IBase.class.isAssignableFrom(valueType)) {
1095                                                                        childElementDef = nextChild.getChildElementDefinitionByDatatype(valueType);
1096                                                                        valueType = (Class<? extends IBase>) valueType.getSuperclass();
1097                                                                }
1098
1099                                                                Class<? extends IBase> typeClass = nextValue.getClass();
1100                                                                while (childElementDef == null && IBase.class.isAssignableFrom(typeClass)) {
1101                                                                        //noinspection unchecked
1102                                                                        typeClass = (Class<? extends IBase>) typeClass.getSuperclass();
1103                                                                        childElementDef = nextChild.getChildElementDefinitionByDatatype(typeClass);
1104                                                                }
1105
1106                                                                Validate.notNull(
1107                                                                                childElementDef,
1108                                                                                "Found value of type[%s] which is not valid for field[%s] in %s",
1109                                                                                nextValue.getClass(),
1110                                                                                nextChild.getElementName(),
1111                                                                                childDef.getName());
1112
1113                                                                visit(
1114                                                                                nextValue,
1115                                                                                nextChild,
1116                                                                                childElementDef,
1117                                                                                theCallback,
1118                                                                                theContainingElementPath,
1119                                                                                theChildDefinitionPath,
1120                                                                                theElementDefinitionPath);
1121                                                        }
1122                                                }
1123                                        }
1124                                        break;
1125                                }
1126                                case CONTAINED_RESOURCES: {
1127                                        BaseContainedDt value = (BaseContainedDt) theElement;
1128                                        for (IResource next : value.getContainedResources()) {
1129                                                BaseRuntimeElementCompositeDefinition<?> def = myContext.getResourceDefinition(next);
1130                                                visit(
1131                                                                next,
1132                                                                null,
1133                                                                def,
1134                                                                theCallback,
1135                                                                theContainingElementPath,
1136                                                                theChildDefinitionPath,
1137                                                                theElementDefinitionPath);
1138                                        }
1139                                        break;
1140                                }
1141                                case EXTENSION_DECLARED:
1142                                case UNDECL_EXT: {
1143                                        throw new IllegalStateException(
1144                                                        Msg.code(1793) + "state should not happen: " + theDefinition.getChildType());
1145                                }
1146                                case CONTAINED_RESOURCE_LIST: {
1147                                        if (theElement != null) {
1148                                                BaseRuntimeElementDefinition<?> def = myContext.getElementDefinition(theElement.getClass());
1149                                                visit(
1150                                                                theElement,
1151                                                                null,
1152                                                                def,
1153                                                                theCallback,
1154                                                                theContainingElementPath,
1155                                                                theChildDefinitionPath,
1156                                                                theElementDefinitionPath);
1157                                        }
1158                                        break;
1159                                }
1160                        }
1161                }
1162
1163                if (theChildDefinition != null) {
1164                        theChildDefinitionPath.remove(theChildDefinitionPath.size() - 1);
1165                }
1166                theContainingElementPath.remove(theContainingElementPath.size() - 1);
1167                theElementDefinitionPath.remove(theElementDefinitionPath.size() - 1);
1168        }
1169
1170        /**
1171         * Visit all elements in a given resource
1172         *
1173         * <p>
1174         * Note on scope: This method will descend into any contained resources ({@link IResource#getContained()}) as well, but will not descend into linked resources (e.g.
1175         * {@link BaseResourceReferenceDt#getResource()}) or embedded resources (e.g. Bundle.entry.resource)
1176         * </p>
1177         *
1178         * @param theResource The resource to visit
1179         * @param theVisitor  The visitor
1180         */
1181        public void visit(IBaseResource theResource, IModelVisitor theVisitor) {
1182                BaseRuntimeElementCompositeDefinition<?> def = myContext.getResourceDefinition(theResource);
1183                visit(newMap(), theResource, theResource, null, null, def, theVisitor);
1184        }
1185
1186        public Map<Object, Object> newMap() {
1187                return new IdentityHashMap<>();
1188        }
1189
1190        /**
1191         * Visit all elements in a given resource or element
1192         * <p>
1193         * <b>THIS ALTERNATE METHOD IS STILL EXPERIMENTAL! USE WITH CAUTION</b>
1194         * </p>
1195         * <p>
1196         * Note on scope: This method will descend into any contained resources ({@link IResource#getContained()}) as well, but will not descend into linked resources (e.g.
1197         * {@link BaseResourceReferenceDt#getResource()}) or embedded resources (e.g. Bundle.entry.resource)
1198         * </p>
1199         *
1200         * @param theElement The element to visit
1201         * @param theVisitor The visitor
1202         */
1203        public void visit(IBase theElement, IModelVisitor2 theVisitor) {
1204                BaseRuntimeElementDefinition<?> def = myContext.getElementDefinition(theElement.getClass());
1205                if (def instanceof BaseRuntimeElementCompositeDefinition) {
1206                        BaseRuntimeElementCompositeDefinition<?> defComposite = (BaseRuntimeElementCompositeDefinition<?>) def;
1207                        visit(theElement, null, def, theVisitor, new ArrayList<>(), new ArrayList<>(), new ArrayList<>());
1208                } else if (theElement instanceof IBaseExtension) {
1209                        theVisitor.acceptUndeclaredExtension(
1210                                        (IBaseExtension<?, ?>) theElement,
1211                                        Collections.emptyList(),
1212                                        Collections.emptyList(),
1213                                        Collections.emptyList());
1214                } else {
1215                        theVisitor.acceptElement(
1216                                        theElement, Collections.emptyList(), Collections.emptyList(), Collections.emptyList());
1217                }
1218        }
1219
1220        private void visit(
1221                        Map<Object, Object> theStack,
1222                        IBaseResource theResource,
1223                        IBase theElement,
1224                        List<String> thePathToElement,
1225                        BaseRuntimeChildDefinition theChildDefinition,
1226                        BaseRuntimeElementDefinition<?> theDefinition,
1227                        IModelVisitor theCallback) {
1228                List<String> pathToElement = addNameToList(thePathToElement, theChildDefinition);
1229
1230                if (theStack.put(theElement, theElement) != null) {
1231                        return;
1232                }
1233
1234                theCallback.acceptElement(theResource, theElement, pathToElement, theChildDefinition, theDefinition);
1235
1236                BaseRuntimeElementDefinition<?> def = theDefinition;
1237                if (def.getChildType() == ChildTypeEnum.CONTAINED_RESOURCE_LIST) {
1238                        Class<? extends IBase> clazz = theElement.getClass();
1239                        def = myContext.getElementDefinition(clazz);
1240                        Validate.notNull(def, "Unable to find element definition for class: %s", clazz);
1241                }
1242
1243                if (theElement instanceof IBaseReference) {
1244                        IBaseResource target = ((IBaseReference) theElement).getResource();
1245                        if (target != null) {
1246                                if (target.getIdElement().hasIdPart() == false
1247                                                || target.getIdElement().isLocal()) {
1248                                        RuntimeResourceDefinition targetDef = myContext.getResourceDefinition(target);
1249                                        visit(theStack, target, target, pathToElement, null, targetDef, theCallback);
1250                                }
1251                        }
1252                }
1253
1254                switch (def.getChildType()) {
1255                        case ID_DATATYPE:
1256                        case PRIMITIVE_XHTML_HL7ORG:
1257                        case PRIMITIVE_XHTML:
1258                        case PRIMITIVE_DATATYPE:
1259                                // These are primitive types
1260                                break;
1261                        case RESOURCE:
1262                        case RESOURCE_BLOCK:
1263                        case COMPOSITE_DATATYPE: {
1264                                BaseRuntimeElementCompositeDefinition<?> childDef = (BaseRuntimeElementCompositeDefinition<?>) def;
1265                                List<BaseRuntimeChildDefinition> childrenAndExtensionDefs = childDef.getChildrenAndExtension();
1266                                for (BaseRuntimeChildDefinition nextChild : childrenAndExtensionDefs) {
1267
1268                                        List<?> values = nextChild.getAccessor().getValues(theElement);
1269
1270                                        if (values != null) {
1271                                                for (Object nextValueObject : values) {
1272                                                        IBase nextValue;
1273                                                        try {
1274                                                                nextValue = (IBase) nextValueObject;
1275                                                        } catch (ClassCastException e) {
1276                                                                String s = "Found instance of " + nextValueObject.getClass()
1277                                                                                + " - Did you set a field value to the incorrect type? Expected "
1278                                                                                + IBase.class.getName();
1279                                                                throw new ClassCastException(Msg.code(1794) + s);
1280                                                        }
1281                                                        if (nextValue == null) {
1282                                                                continue;
1283                                                        }
1284                                                        if (nextValue.isEmpty()) {
1285                                                                continue;
1286                                                        }
1287                                                        BaseRuntimeElementDefinition<?> childElementDef;
1288                                                        Class<? extends IBase> clazz = nextValue.getClass();
1289                                                        childElementDef = nextChild.getChildElementDefinitionByDatatype(clazz);
1290
1291                                                        if (childElementDef == null) {
1292                                                                childElementDef = myContext.getElementDefinition(clazz);
1293                                                                Validate.notNull(
1294                                                                                childElementDef, "Unable to find element definition for class: %s", clazz);
1295                                                        }
1296
1297                                                        if (nextChild instanceof RuntimeChildDirectResource) {
1298                                                                // Don't descend into embedded resources
1299                                                                theCallback.acceptElement(theResource, nextValue, null, nextChild, childElementDef);
1300                                                        } else {
1301                                                                visit(
1302                                                                                theStack,
1303                                                                                theResource,
1304                                                                                nextValue,
1305                                                                                pathToElement,
1306                                                                                nextChild,
1307                                                                                childElementDef,
1308                                                                                theCallback);
1309                                                        }
1310                                                }
1311                                        }
1312                                }
1313                                break;
1314                        }
1315                        case CONTAINED_RESOURCES: {
1316                                BaseContainedDt value = (BaseContainedDt) theElement;
1317                                for (IResource next : value.getContainedResources()) {
1318                                        def = myContext.getResourceDefinition(next);
1319                                        visit(theStack, next, next, pathToElement, null, def, theCallback);
1320                                }
1321                                break;
1322                        }
1323                        case CONTAINED_RESOURCE_LIST:
1324                        case EXTENSION_DECLARED:
1325                        case UNDECL_EXT: {
1326                                throw new IllegalStateException(Msg.code(1795) + "state should not happen: " + def.getChildType());
1327                        }
1328                }
1329
1330                theStack.remove(theElement);
1331        }
1332
1333        /**
1334         * Returns all embedded resources that are found embedded within <code>theResource</code>.
1335         * An embedded resource is a resource that can be found as a direct child within a resource,
1336         * as opposed to being referenced by the resource.
1337         * <p>
1338         * Examples include resources found within <code>Bundle.entry.resource</code>
1339         * and <code>Parameters.parameter.resource</code>, as well as contained resources
1340         * found within <code>Resource.contained</code>
1341         * </p>
1342         *
1343         * @param theRecurse Should embedded resources be recursively scanned for further embedded
1344         *                   resources
1345         * @return A collection containing the embedded resources. Order is arbitrary.
1346         */
1347        public Collection<IBaseResource> getAllEmbeddedResources(IBaseResource theResource, boolean theRecurse) {
1348                Validate.notNull(theResource, "theResource must not be null");
1349                ArrayList<IBaseResource> retVal = new ArrayList<>();
1350
1351                visit(theResource, new IModelVisitor2() {
1352                        @Override
1353                        public boolean acceptElement(
1354                                        IBase theElement,
1355                                        List<IBase> theContainingElementPath,
1356                                        List<BaseRuntimeChildDefinition> theChildDefinitionPath,
1357                                        List<BaseRuntimeElementDefinition<?>> theElementDefinitionPath) {
1358                                if (theElement == theResource) {
1359                                        return true;
1360                                }
1361                                if (theElement instanceof IBaseResource) {
1362                                        retVal.add((IBaseResource) theElement);
1363                                        return theRecurse;
1364                                }
1365                                return true;
1366                        }
1367
1368                        @Override
1369                        public boolean acceptUndeclaredExtension(
1370                                        IBaseExtension<?, ?> theNextExt,
1371                                        List<IBase> theContainingElementPath,
1372                                        List<BaseRuntimeChildDefinition> theChildDefinitionPath,
1373                                        List<BaseRuntimeElementDefinition<?>> theElementDefinitionPath) {
1374                                return true;
1375                        }
1376                });
1377
1378                return retVal;
1379        }
1380
1381        /**
1382         * Clear all content on a resource
1383         */
1384        public void clear(IBaseResource theInput) {
1385                visit(theInput, new IModelVisitor2() {
1386                        @Override
1387                        public boolean acceptElement(
1388                                        IBase theElement,
1389                                        List<IBase> theContainingElementPath,
1390                                        List<BaseRuntimeChildDefinition> theChildDefinitionPath,
1391                                        List<BaseRuntimeElementDefinition<?>> theElementDefinitionPath) {
1392                                if (theElement instanceof IPrimitiveType) {
1393                                        ((IPrimitiveType) theElement).setValueAsString(null);
1394                                }
1395                                return true;
1396                        }
1397
1398                        @Override
1399                        public boolean acceptUndeclaredExtension(
1400                                        IBaseExtension<?, ?> theNextExt,
1401                                        List<IBase> theContainingElementPath,
1402                                        List<BaseRuntimeChildDefinition> theChildDefinitionPath,
1403                                        List<BaseRuntimeElementDefinition<?>> theElementDefinitionPath) {
1404                                theNextExt.setUrl(null);
1405                                theNextExt.setValue(null);
1406                                return true;
1407                        }
1408                });
1409        }
1410
1411        private void containResourcesForEncoding(
1412                        ContainedResources theContained, IBaseResource theResource, boolean theModifyResource) {
1413                List<IBaseReference> allReferences = getAllPopulatedChildElementsOfType(theResource, IBaseReference.class);
1414                for (IBaseReference next : allReferences) {
1415                        IBaseResource resource = next.getResource();
1416                        if (resource == null && next.getReferenceElement().isLocal()) {
1417                                if (theContained.hasExistingIdToContainedResource()) {
1418                                        IBaseResource potentialTarget = theContained
1419                                                        .getExistingIdToContainedResource()
1420                                                        .remove(next.getReferenceElement().getValue());
1421                                        if (potentialTarget != null) {
1422                                                theContained.addContained(next.getReferenceElement(), potentialTarget);
1423                                                containResourcesForEncoding(theContained, potentialTarget, theModifyResource);
1424                                        }
1425                                }
1426                        }
1427                }
1428
1429                for (IBaseReference next : allReferences) {
1430                        IBaseResource resource = next.getResource();
1431                        if (resource != null) {
1432                                if (resource.getIdElement().isEmpty() || resource.getIdElement().isLocal()) {
1433                                        if (theContained.getResourceId(resource) != null) {
1434                                                // Prevent infinite recursion if there are circular loops in the contained resources
1435                                                continue;
1436                                        }
1437                                        IIdType id = theContained.addContained(resource);
1438                                        if (theModifyResource) {
1439                                                getContainedResourceList(theResource).add(resource);
1440                                                next.setReference(id.getValue());
1441                                        }
1442                                        if (resource.getIdElement().isLocal() && theContained.hasExistingIdToContainedResource()) {
1443                                                theContained
1444                                                                .getExistingIdToContainedResource()
1445                                                                .remove(resource.getIdElement().getValue());
1446                                        }
1447                                }
1448                        }
1449                }
1450        }
1451
1452        /**
1453         * Iterate through the whole resource and identify any contained resources. Optionally this method
1454         * can also assign IDs and modify references where the resource link has been specified but not the
1455         * reference text.
1456         *
1457         * @since 5.4.0
1458         */
1459        public ContainedResources containResources(IBaseResource theResource, OptionsEnum... theOptions) {
1460                boolean storeAndReuse = false;
1461                boolean modifyResource = false;
1462                for (OptionsEnum next : theOptions) {
1463                        switch (next) {
1464                                case MODIFY_RESOURCE:
1465                                        modifyResource = true;
1466                                        break;
1467                                case STORE_AND_REUSE_RESULTS:
1468                                        storeAndReuse = true;
1469                                        break;
1470                        }
1471                }
1472
1473                if (storeAndReuse) {
1474                        Object cachedValue = theResource.getUserData(USER_DATA_KEY_CONTAIN_RESOURCES_COMPLETED);
1475                        if (cachedValue != null) {
1476                                return (ContainedResources) cachedValue;
1477                        }
1478                }
1479
1480                ContainedResources contained = new ContainedResources();
1481
1482                List<? extends IBaseResource> containedResources = getContainedResourceList(theResource);
1483                for (IBaseResource next : containedResources) {
1484                        String nextId = next.getIdElement().getValue();
1485                        if (StringUtils.isNotBlank(nextId)) {
1486                                if (!nextId.startsWith("#")) {
1487                                        nextId = '#' + nextId;
1488                                }
1489                                next.getIdElement().setValue(nextId);
1490                        }
1491                        contained.addContained(next);
1492                }
1493
1494                if (myContext.getParserOptions().isAutoContainReferenceTargetsWithNoId()) {
1495                        containResourcesForEncoding(contained, theResource, modifyResource);
1496                }
1497
1498                if (storeAndReuse) {
1499                        theResource.setUserData(USER_DATA_KEY_CONTAIN_RESOURCES_COMPLETED, contained);
1500                }
1501
1502                return contained;
1503        }
1504
1505        @SuppressWarnings("unchecked")
1506        private <T extends IBaseResource> List<T> getContainedResourceList(T theResource) {
1507                List<T> containedResources = Collections.emptyList();
1508                if (theResource instanceof IResource) {
1509                        containedResources =
1510                                        (List<T>) ((IResource) theResource).getContained().getContainedResources();
1511                } else if (theResource instanceof IDomainResource) {
1512                        containedResources = (List<T>) ((IDomainResource) theResource).getContained();
1513                }
1514                return containedResources;
1515        }
1516
1517        /**
1518         * Adds and returns a new element at the given path within the given structure. The paths used here
1519         * are <b>not FHIRPath expressions</b> but instead just simple dot-separated path expressions.
1520         * <p>
1521         * Only the last entry in the path is always created, existing repetitions of elements before
1522         * the final dot are returned if they exists (although they are created if they do not). For example,
1523         * given the path <code>Patient.name.given</code>, a new repetition of <code>given</code> is always
1524         * added to the first (index 0) repetition of the name. If an index-0 repetition of <code>name</code>
1525         * already exists, it is added to. If one does not exist, it if created and then added to.
1526         * </p>
1527         * <p>
1528         * If the last element in the path refers to a non-repeatable element that is already present and
1529         * is not empty, a {@link DataFormatException} error will be thrown.
1530         * </p>
1531         *
1532         * @param theTarget The element to add to. This will often be a {@link IBaseResource resource}
1533         *                  instance, but does not need to be.
1534         * @param thePath   The path.
1535         * @return The newly added element
1536         * @throws DataFormatException If the path is invalid or does not end with either a repeatable element, or
1537         *                             an element that is non-repeatable but not already populated.
1538         */
1539        @SuppressWarnings("unchecked")
1540        @Nonnull
1541        public <T extends IBase> T addElement(@Nonnull IBase theTarget, @Nonnull String thePath) {
1542                return (T) doAddElement(theTarget, thePath, 1).get(0);
1543        }
1544
1545        @SuppressWarnings("unchecked")
1546        private <T extends IBase> List<T> doAddElement(IBase theTarget, String thePath, int theElementsToAdd) {
1547                if (theElementsToAdd == 0) {
1548                        return Collections.emptyList();
1549                }
1550
1551                IBase target = theTarget;
1552                BaseRuntimeElementCompositeDefinition<?> def =
1553                                (BaseRuntimeElementCompositeDefinition<?>) myContext.getElementDefinition(target.getClass());
1554                List<String> parts = parsePath(def, thePath);
1555
1556                for (int i = 0, partsSize = parts.size(); ; i++) {
1557                        String nextPart = parts.get(i);
1558                        boolean lastPart = i == partsSize - 1;
1559
1560                        BaseRuntimeChildDefinition nextChild = def.getChildByName(nextPart);
1561                        if (nextChild == null) {
1562                                throw new DataFormatException(Msg.code(1796) + "Invalid path " + thePath + ": Element of type "
1563                                                + def.getName() + " has no child named " + nextPart + ". Valid names: "
1564                                                + def.getChildrenAndExtension().stream()
1565                                                                .map(t -> t.getElementName())
1566                                                                .sorted()
1567                                                                .collect(Collectors.joining(", ")));
1568                        }
1569
1570                        List<IBase> childValues = nextChild.getAccessor().getValues(target);
1571                        IBase childValue;
1572                        if (childValues.size() > 0 && !lastPart) {
1573                                childValue = childValues.get(0);
1574                        } else {
1575
1576                                if (lastPart) {
1577                                        if (!childValues.isEmpty()) {
1578                                                if (theElementsToAdd == -1) {
1579                                                        return (List<T>) Collections.singletonList(childValues.get(0));
1580                                                } else if (nextChild.getMax() == 1
1581                                                                && !childValues.get(0).isEmpty()) {
1582                                                        throw new DataFormatException(
1583                                                                        Msg.code(1797) + "Element at path " + thePath + " is not repeatable and not empty");
1584                                                } else if (nextChild.getMax() == 1 && childValues.get(0).isEmpty()) {
1585                                                        return (List<T>) Collections.singletonList(childValues.get(0));
1586                                                }
1587                                        }
1588                                }
1589
1590                                BaseRuntimeElementDefinition<?> elementDef = nextChild.getChildByName(nextPart);
1591                                childValue = elementDef.newInstance(nextChild.getInstanceConstructorArguments());
1592                                nextChild.getMutator().addValue(target, childValue);
1593
1594                                if (lastPart) {
1595                                        if (theElementsToAdd == 1 || theElementsToAdd == -1) {
1596                                                return (List<T>) Collections.singletonList(childValue);
1597                                        } else {
1598                                                if (nextChild.getMax() == 1) {
1599                                                        throw new DataFormatException(Msg.code(1798) + "Can not add multiple values at path "
1600                                                                        + thePath + ": Element does not repeat");
1601                                                }
1602
1603                                                List<T> values = (List<T>) Lists.newArrayList(childValue);
1604                                                for (int j = 1; j < theElementsToAdd; j++) {
1605                                                        childValue = elementDef.newInstance(nextChild.getInstanceConstructorArguments());
1606                                                        nextChild.getMutator().addValue(target, childValue);
1607                                                        values.add((T) childValue);
1608                                                }
1609
1610                                                return values;
1611                                        }
1612                                }
1613                        }
1614
1615                        target = childValue;
1616
1617                        if (!lastPart) {
1618                                BaseRuntimeElementDefinition<?> nextDef = myContext.getElementDefinition(target.getClass());
1619                                if (!(nextDef instanceof BaseRuntimeElementCompositeDefinition)) {
1620                                        throw new DataFormatException(Msg.code(1799) + "Invalid path " + thePath + ": Element of type "
1621                                                        + def.getName() + " has no child named " + nextPart + " (this is a primitive type)");
1622                                }
1623                                def = (BaseRuntimeElementCompositeDefinition<?>) nextDef;
1624                        }
1625                }
1626        }
1627
1628        /**
1629         * Adds and returns a new element at the given path within the given structure. The paths used here
1630         * are <b>not FHIRPath expressions</b> but instead just simple dot-separated path expressions.
1631         * <p>
1632         * This method follows all of the same semantics as {@link #addElement(IBase, String)} but it
1633         * requires the path to point to an element with a primitive datatype and set the value of
1634         * the datatype to the given value.
1635         * </p>
1636         *
1637         * @param theTarget The element to add to. This will often be a {@link IBaseResource resource}
1638         *                  instance, but does not need to be.
1639         * @param thePath   The path.
1640         * @param theValue  The value to set, or <code>null</code>.
1641         * @return The newly added element
1642         * @throws DataFormatException If the path is invalid or does not end with either a repeatable element, or
1643         *                             an element that is non-repeatable but not already populated.
1644         */
1645        @SuppressWarnings("unchecked")
1646        @Nonnull
1647        public <T extends IBase> T addElement(
1648                        @Nonnull IBase theTarget, @Nonnull String thePath, @Nullable String theValue) {
1649                T value = (T) doAddElement(theTarget, thePath, 1).get(0);
1650                if (!(value instanceof IPrimitiveType)) {
1651                        throw new DataFormatException(
1652                                        Msg.code(1800) + "Element at path " + thePath + " is not a primitive datatype. Found: "
1653                                                        + myContext.getElementDefinition(value.getClass()).getName());
1654                }
1655
1656                ((IPrimitiveType<?>) value).setValueAsString(theValue);
1657
1658                return value;
1659        }
1660
1661        /**
1662         * Adds and returns a new element at the given path within the given structure. The paths used here
1663         * are <b>not FHIRPath expressions</b> but instead just simple dot-separated path expressions.
1664         * <p>
1665         * This method follows all of the same semantics as {@link #addElement(IBase, String)} but it
1666         * requires the path to point to an element with a primitive datatype and set the value of
1667         * the datatype to the given value.
1668         * </p>
1669         *
1670         * @param theTarget The element to add to. This will often be a {@link IBaseResource resource}
1671         *                  instance, but does not need to be.
1672         * @param thePath   The path.
1673         * @param theValue  The value to set, or <code>null</code>.
1674         * @return The newly added element
1675         * @throws DataFormatException If the path is invalid or does not end with either a repeatable element, or
1676         *                             an element that is non-repeatable but not already populated.
1677         */
1678        @SuppressWarnings("unchecked")
1679        @Nonnull
1680        public <T extends IBase> T setElement(
1681                        @Nonnull IBase theTarget, @Nonnull String thePath, @Nullable String theValue) {
1682                T value = (T) doAddElement(theTarget, thePath, -1).get(0);
1683                if (!(value instanceof IPrimitiveType)) {
1684                        throw new DataFormatException(
1685                                        Msg.code(1801) + "Element at path " + thePath + " is not a primitive datatype. Found: "
1686                                                        + myContext.getElementDefinition(value.getClass()).getName());
1687                }
1688
1689                ((IPrimitiveType<?>) value).setValueAsString(theValue);
1690
1691                return value;
1692        }
1693
1694        /**
1695         * This method has the same semantics as {@link #addElement(IBase, String, String)} but adds
1696         * a collection of primitives instead of a single one.
1697         *
1698         * @param theTarget The element to add to. This will often be a {@link IBaseResource resource}
1699         *                  instance, but does not need to be.
1700         * @param thePath   The path.
1701         * @param theValues The values to set, or <code>null</code>.
1702         */
1703        public void addElements(IBase theTarget, String thePath, Collection<String> theValues) {
1704                List<IBase> targets = doAddElement(theTarget, thePath, theValues.size());
1705                Iterator<String> valuesIter = theValues.iterator();
1706                for (IBase target : targets) {
1707
1708                        if (!(target instanceof IPrimitiveType)) {
1709                                throw new DataFormatException(Msg.code(1802) + "Element at path " + thePath
1710                                                + " is not a primitive datatype. Found: "
1711                                                + myContext.getElementDefinition(target.getClass()).getName());
1712                        }
1713
1714                        ((IPrimitiveType<?>) target).setValueAsString(valuesIter.next());
1715                }
1716        }
1717
1718        /**
1719         * Clones a resource object, copying all data elements from theSource into a new copy of the same type.
1720         * <p>
1721         * Note that:
1722         * <ul>
1723         *    <li>Only FHIR data elements are copied (i.e. user data maps are not copied)</li>
1724         *    <li>If a class extending a HAPI FHIR type (e.g. an instance of a class extending the Patient class) is supplied, an instance of the base type will be returned.</li>
1725         * </ul>
1726         *
1727         * @param theSource The source resource
1728         * @return A copy of the source resource
1729         * @since 5.6.0
1730         */
1731        @SuppressWarnings("unchecked")
1732        public <T extends IBaseResource> T clone(T theSource) {
1733                Validate.notNull(theSource, "theSource must not be null");
1734                T target = (T) myContext.getResourceDefinition(theSource).newInstance();
1735                cloneInto(theSource, target, false);
1736                return target;
1737        }
1738
1739        public enum OptionsEnum {
1740
1741                /**
1742                 * Should we modify the resource in the case that contained resource IDs are assigned
1743                 * during a {@link #containResources(IBaseResource, OptionsEnum...)} pass.
1744                 */
1745                MODIFY_RESOURCE,
1746
1747                /**
1748                 * Store the results of the operation in the resource metadata and reuse them if
1749                 * subsequent calls are made.
1750                 */
1751                STORE_AND_REUSE_RESULTS
1752        }
1753
1754        @FunctionalInterface
1755        private interface ICompartmentOwnerVisitor {
1756
1757                /**
1758                 * @return Returns true if we should keep looking for more
1759                 */
1760                boolean consume(IIdType theCompartmentOwner);
1761        }
1762
1763        public static class ContainedResources {
1764                private long myNextContainedId = 1;
1765
1766                private List<IBaseResource> myResourceList;
1767                private IdentityHashMap<IBaseResource, IIdType> myResourceToIdMap;
1768                private Map<String, IBaseResource> myExistingIdToContainedResourceMap;
1769
1770                public Map<String, IBaseResource> getExistingIdToContainedResource() {
1771                        if (myExistingIdToContainedResourceMap == null) {
1772                                myExistingIdToContainedResourceMap = new HashMap<>();
1773                        }
1774                        return myExistingIdToContainedResourceMap;
1775                }
1776
1777                public IIdType addContained(IBaseResource theResource) {
1778                        IIdType existing = getResourceToIdMap().get(theResource);
1779                        if (existing != null) {
1780                                return existing;
1781                        }
1782
1783                        IIdType newId = theResource.getIdElement();
1784                        if (isBlank(newId.getValue())) {
1785                                newId.setValue("#" + myNextContainedId++);
1786                        } else {
1787                                // Avoid auto-assigned contained IDs colliding with pre-existing ones
1788                                String idPart = newId.getValue();
1789                                if (substring(idPart, 0, 1).equals("#")) {
1790                                        idPart = idPart.substring(1);
1791                                        if (StringUtils.isNumeric(idPart)) {
1792                                                myNextContainedId = Long.parseLong(idPart) + 1;
1793                                        }
1794                                }
1795                        }
1796
1797                        getResourceToIdMap().put(theResource, newId);
1798                        getOrCreateResourceList().add(theResource);
1799                        return newId;
1800                }
1801
1802                public void addContained(IIdType theId, IBaseResource theResource) {
1803                        if (!getResourceToIdMap().containsKey(theResource)) {
1804                                getResourceToIdMap().put(theResource, theId);
1805                                getOrCreateResourceList().add(theResource);
1806                        }
1807                }
1808
1809                public List<IBaseResource> getContainedResources() {
1810                        if (getResourceToIdMap() == null) {
1811                                return Collections.emptyList();
1812                        }
1813                        return getOrCreateResourceList();
1814                }
1815
1816                public IIdType getResourceId(IBaseResource theNext) {
1817                        if (getResourceToIdMap() == null) {
1818                                return null;
1819                        }
1820                        return getResourceToIdMap().get(theNext);
1821                }
1822
1823                private List<IBaseResource> getOrCreateResourceList() {
1824                        if (myResourceList == null) {
1825                                myResourceList = new ArrayList<>();
1826                        }
1827                        return myResourceList;
1828                }
1829
1830                private IdentityHashMap<IBaseResource, IIdType> getResourceToIdMap() {
1831                        if (myResourceToIdMap == null) {
1832                                myResourceToIdMap = new IdentityHashMap<>();
1833                        }
1834                        return myResourceToIdMap;
1835                }
1836
1837                public boolean isEmpty() {
1838                        if (myResourceToIdMap == null) {
1839                                return true;
1840                        }
1841                        return myResourceToIdMap.isEmpty();
1842                }
1843
1844                public boolean hasExistingIdToContainedResource() {
1845                        return myExistingIdToContainedResourceMap != null;
1846                }
1847
1848                public void assignIdsToContainedResources() {
1849
1850                        if (!getContainedResources().isEmpty()) {
1851
1852                                /*
1853                                 * The idea with the code block below:
1854                                 *
1855                                 * We want to preserve any IDs that were user-assigned, so that if it's really
1856                                 * important to someone that their contained resource have the ID of #FOO
1857                                 * or #1 we will keep that.
1858                                 *
1859                                 * For any contained resources where no ID was assigned by the user, we
1860                                 * want to manually create an ID but make sure we don't reuse an existing ID.
1861                                 */
1862
1863                                Set<String> ids = new HashSet<>();
1864
1865                                // Gather any user assigned IDs
1866                                for (IBaseResource nextResource : getContainedResources()) {
1867                                        if (getResourceToIdMap().get(nextResource) != null) {
1868                                                ids.add(getResourceToIdMap().get(nextResource).getValue());
1869                                        }
1870                                }
1871
1872                                // Automatically assign IDs to the rest
1873                                for (IBaseResource nextResource : getContainedResources()) {
1874
1875                                        while (getResourceToIdMap().get(nextResource) == null) {
1876                                                String nextCandidate = "#" + myNextContainedId;
1877                                                myNextContainedId++;
1878                                                if (!ids.add(nextCandidate)) {
1879                                                        continue;
1880                                                }
1881
1882                                                getResourceToIdMap().put(nextResource, new IdDt(nextCandidate));
1883                                        }
1884                                }
1885                        }
1886                }
1887        }
1888}