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.context;
021
022import ca.uhn.fhir.parser.IParser;
023
024import java.util.Arrays;
025import java.util.Collection;
026import java.util.Collections;
027import java.util.HashSet;
028import java.util.List;
029import java.util.Set;
030
031/**
032 * This object supplies default configuration to all {@link IParser parser} instances
033 * created by a given {@link FhirContext}. It is accessed using {@link FhirContext#getParserOptions()}
034 * and {@link FhirContext#setParserOptions(ParserOptions)}.
035 * <p>
036 * It is fine to share a ParserOptions instances across multiple context instances.
037 * </p>
038 */
039public class ParserOptions {
040
041        private boolean myStripVersionsFromReferences = true;
042        private Set<String> myDontStripVersionsFromReferencesAtPaths = Collections.emptySet();
043        private boolean myOverrideResourceIdWithBundleEntryFullUrl = true;
044        private boolean myAutoContainReferenceTargetsWithNoId = true;
045
046        /**
047         * If set to {@literal true} (which is the default), contained resources may be specified by
048         * populating the target (contained) resource directly in {@link org.hl7.fhir.instance.model.api.IBaseReference#setReference(String)}
049         * and the parser will automatically locate it and insert it into <code>Resource.contained</code> when
050         * serializing. This is convenient, but also imposes a performance cost when serializing large numbers
051         * of resources, so this can be disabled if it is not needed.
052         * <p>
053         * If disabled, only resources that are directly placed in <code>Resource.contained</code> will be
054         * serialized.
055         * </p>
056         *
057         * @since 5.7.0
058         */
059        public boolean isAutoContainReferenceTargetsWithNoId() {
060                return myAutoContainReferenceTargetsWithNoId;
061        }
062
063        /**
064         * If set to {@literal true} (which is the default), contained resources may be specified by
065         * populating the target (contained) resource directly in {@link org.hl7.fhir.instance.model.api.IBaseReference#setReference(String)}
066         * and the parser will automatically locate it and insert it into <code>Resource.contained</code> when
067         * serializing. This is convenient, but also imposes a performance cost when serializing large numbers
068         * of resources, so this can be disabled if it is not needed.
069         * <p>
070         * If disabled, only resources that are directly placed in <code>Resource.contained</code> will be
071         * serialized.
072         * </p>
073         *
074         * @since 5.7.0
075         */
076        public void setAutoContainReferenceTargetsWithNoId(boolean theAllowAutoContainedReferences) {
077                myAutoContainReferenceTargetsWithNoId = theAllowAutoContainedReferences;
078        }
079
080        /**
081         * If set to <code>true<code> (which is the default), resource references containing a version
082         * will have the version removed when the resource is encoded. This is generally good behaviour because
083         * in most situations, references from one resource to another should be to the resource by ID, not
084         * by ID and version. In some cases though, it may be desirable to preserve the version in resource
085         * links. In that case, this value should be set to <code>false</code>.
086         *
087         * @return Returns the parser instance's configuration setting for stripping versions from resource references when
088         * encoding. Default is <code>true</code>.
089         */
090        public boolean isStripVersionsFromReferences() {
091                return myStripVersionsFromReferences;
092        }
093
094        /**
095         * If set to <code>true<code> (which is the default), resource references containing a version
096         * will have the version removed when the resource is encoded. This is generally good behaviour because
097         * in most situations, references from one resource to another should be to the resource by ID, not
098         * by ID and version. In some cases though, it may be desirable to preserve the version in resource
099         * links. In that case, this value should be set to <code>false</code>.
100         * <p>
101         * This method provides the ability to globally disable reference encoding. If finer-grained
102         * control is needed, use {@link #setDontStripVersionsFromReferencesAtPaths(String...)}
103         * </p>
104         *
105         * @param theStripVersionsFromReferences Set this to <code>false<code> to prevent the parser from removing
106         *                                       resource versions from references.
107         * @return Returns a reference to <code>this</code> parser so that method calls can be chained together
108         * @see #setDontStripVersionsFromReferencesAtPaths(String...)
109         */
110        public ParserOptions setStripVersionsFromReferences(boolean theStripVersionsFromReferences) {
111                myStripVersionsFromReferences = theStripVersionsFromReferences;
112                return this;
113        }
114
115        /**
116         * Returns the value supplied to {@link IParser#setDontStripVersionsFromReferencesAtPaths(String...)}
117         *
118         * @see #setDontStripVersionsFromReferencesAtPaths(String...)
119         * @see #setStripVersionsFromReferences(boolean)
120         */
121        public Set<String> getDontStripVersionsFromReferencesAtPaths() {
122                return myDontStripVersionsFromReferencesAtPaths;
123        }
124
125        /**
126         * If supplied value(s), any resource references at the specified paths will have their
127         * resource versions encoded instead of being automatically stripped during the encoding
128         * process. This setting has no effect on the parsing process.
129         * <p>
130         * This method provides a finer-grained level of control than {@link #setStripVersionsFromReferences(boolean)}
131         * and any paths specified by this method will be encoded even if {@link #setStripVersionsFromReferences(boolean)}
132         * has been set to <code>true</code> (which is the default)
133         * </p>
134         *
135         * @param thePaths A collection of paths for which the resource versions will not be removed automatically
136         *                 when serializing, e.g. "Patient.managingOrganization" or "AuditEvent.object.reference". Note that
137         *                 only resource name and field names with dots separating is allowed here (no repetition
138         *                 indicators, FluentPath expressions, etc.)
139         * @return Returns a reference to <code>this</code> parser so that method calls can be chained together
140         * @see #setStripVersionsFromReferences(boolean)
141         */
142        public ParserOptions setDontStripVersionsFromReferencesAtPaths(String... thePaths) {
143                if (thePaths == null) {
144                        setDontStripVersionsFromReferencesAtPaths((List<String>) null);
145                } else {
146                        setDontStripVersionsFromReferencesAtPaths(Arrays.asList(thePaths));
147                }
148                return this;
149        }
150
151        /**
152         * If supplied value(s), any resource references at the specified paths will have their
153         * resource versions encoded instead of being automatically stripped during the encoding
154         * process. This setting has no effect on the parsing process.
155         * <p>
156         * This method provides a finer-grained level of control than {@link #setStripVersionsFromReferences(boolean)}
157         * and any paths specified by this method will be encoded even if {@link #setStripVersionsFromReferences(boolean)}
158         * has been set to <code>true</code> (which is the default)
159         * </p>
160         *
161         * @param thePaths A collection of paths for which the resource versions will not be removed automatically
162         *                 when serializing, e.g. "Patient.managingOrganization" or "AuditEvent.object.reference". Note that
163         *                 only resource name and field names with dots separating is allowed here (no repetition
164         *                 indicators, FluentPath expressions, etc.)
165         * @return Returns a reference to <code>this</code> parser so that method calls can be chained together
166         * @see #setStripVersionsFromReferences(boolean)
167         */
168        @SuppressWarnings("unchecked")
169        public ParserOptions setDontStripVersionsFromReferencesAtPaths(Collection<String> thePaths) {
170                if (thePaths == null) {
171                        myDontStripVersionsFromReferencesAtPaths = Collections.emptySet();
172                } else if (thePaths instanceof HashSet) {
173                        myDontStripVersionsFromReferencesAtPaths = (Set<String>) ((HashSet<String>) thePaths).clone();
174                } else {
175                        myDontStripVersionsFromReferencesAtPaths = new HashSet<>(thePaths);
176                }
177                return this;
178        }
179
180        /**
181         * If set to <code>true</code> (which is the default), the Bundle.entry.fullUrl will override the Bundle.entry.resource's
182         * resource id if the fullUrl is defined. This behavior happens when parsing the source data into a Bundle object. Set this
183         * to <code>false</code> if this is not the desired behavior (e.g. the client code wishes to perform additional
184         * validation checks between the fullUrl and the resource id).
185         *
186         * @return Returns the parser instance's configuration setting for overriding resource ids with Bundle.entry.fullUrl when
187         * parsing the source data into a Bundle object. Default is <code>true</code>.
188         */
189        public boolean isOverrideResourceIdWithBundleEntryFullUrl() {
190                return myOverrideResourceIdWithBundleEntryFullUrl;
191        }
192
193        /**
194         * If set to <code>true</code> (which is the default), the Bundle.entry.fullUrl will override the Bundle.entry.resource's
195         * resource id if the fullUrl is defined. This behavior happens when parsing the source data into a Bundle object. Set this
196         * to <code>false</code> if this is not the desired behavior (e.g. the client code wishes to perform additional
197         * validation checks between the fullUrl and the resource id).
198         *
199         * @param theOverrideResourceIdWithBundleEntryFullUrl Set this to <code>false</code> to prevent the parser from overriding resource ids with the
200         *                                                    Bundle.entry.fullUrl
201         * @return Returns a reference to <code>this</code> parser so that method calls can be chained together
202         */
203        public ParserOptions setOverrideResourceIdWithBundleEntryFullUrl(
204                        boolean theOverrideResourceIdWithBundleEntryFullUrl) {
205                myOverrideResourceIdWithBundleEntryFullUrl = theOverrideResourceIdWithBundleEntryFullUrl;
206                return this;
207        }
208}