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