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.*;
026
027/**
028 * This object supplies default configuration to all {@link IParser parser} instances
029 * created by a given {@link FhirContext}. It is accessed using {@link FhirContext#getParserOptions()}
030 * and {@link FhirContext#setParserOptions(ParserOptions)}.
031 * <p>
032 * It is fine to share a ParserOptions instances across multiple context instances.
033 * </p>
034 */
035public class ParserOptions {
036
037        private boolean myStripVersionsFromReferences = true;
038        private Set<String> myDontStripVersionsFromReferencesAtPaths = Collections.emptySet();
039        private boolean myOverrideResourceIdWithBundleEntryFullUrl = true;
040
041        /**
042         * If supplied value(s), any resource references at the specified paths will have their
043         * resource versions encoded instead of being automatically stripped during the encoding
044         * process. This setting has no effect on the parsing process.
045         * <p>
046         * This method provides a finer-grained level of control than {@link #setStripVersionsFromReferences(boolean)}
047         * and any paths specified by this method will be encoded even if {@link #setStripVersionsFromReferences(boolean)}
048         * has been set to <code>true</code> (which is the default)
049         * </p>
050         *
051         * @param thePaths A collection of paths for which the resource versions will not be removed automatically
052         *                 when serializing, e.g. "Patient.managingOrganization" or "AuditEvent.object.reference". Note that
053         *                 only resource name and field names with dots separating is allowed here (no repetition
054         *                 indicators, FluentPath expressions, etc.)
055         * @return Returns a reference to <code>this</code> parser so that method calls can be chained together
056         * @see #setStripVersionsFromReferences(boolean)
057         */
058        public ParserOptions setDontStripVersionsFromReferencesAtPaths(String... thePaths) {
059                if (thePaths == null) {
060                        setDontStripVersionsFromReferencesAtPaths((List<String>) null);
061                } else {
062                        setDontStripVersionsFromReferencesAtPaths(Arrays.asList(thePaths));
063                }
064                return this;
065        }
066
067        /**
068         * If set to <code>true<code> (which is the default), resource references containing a version
069         * will have the version removed when the resource is encoded. This is generally good behaviour because
070         * in most situations, references from one resource to another should be to the resource by ID, not
071         * by ID and version. In some cases though, it may be desirable to preserve the version in resource
072         * links. In that case, this value should be set to <code>false</code>.
073         *
074         * @return Returns the parser instance's configuration setting for stripping versions from resource references when
075         * encoding. Default is <code>true</code>.
076         */
077        public boolean isStripVersionsFromReferences() {
078                return myStripVersionsFromReferences;
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         * <p>
088         * This method provides the ability to globally disable reference encoding. If finer-grained
089         * control is needed, use {@link #setDontStripVersionsFromReferencesAtPaths(String...)}
090         * </p>
091         *
092         * @param theStripVersionsFromReferences Set this to <code>false<code> to prevent the parser from removing
093         *                                       resource versions from references.
094         * @return Returns a reference to <code>this</code> parser so that method calls can be chained together
095         * @see #setDontStripVersionsFromReferencesAtPaths(String...)
096         */
097        public ParserOptions setStripVersionsFromReferences(boolean theStripVersionsFromReferences) {
098                myStripVersionsFromReferences = theStripVersionsFromReferences;
099                return this;
100        }
101
102        /**
103         * Returns the value supplied to {@link IParser#setDontStripVersionsFromReferencesAtPaths(String...)}
104         *
105         * @see #setDontStripVersionsFromReferencesAtPaths(String...)
106         * @see #setStripVersionsFromReferences(boolean)
107         */
108        public Set<String> getDontStripVersionsFromReferencesAtPaths() {
109                return myDontStripVersionsFromReferencesAtPaths;
110        }
111
112        /**
113         * If supplied value(s), any resource references at the specified paths will have their
114         * resource versions encoded instead of being automatically stripped during the encoding
115         * process. This setting has no effect on the parsing process.
116         * <p>
117         * This method provides a finer-grained level of control than {@link #setStripVersionsFromReferences(boolean)}
118         * and any paths specified by this method will be encoded even if {@link #setStripVersionsFromReferences(boolean)}
119         * has been set to <code>true</code> (which is the default)
120         * </p>
121         *
122         * @param thePaths A collection of paths for which the resource versions will not be removed automatically
123         *                 when serializing, e.g. "Patient.managingOrganization" or "AuditEvent.object.reference". Note that
124         *                 only resource name and field names with dots separating is allowed here (no repetition
125         *                 indicators, FluentPath expressions, etc.)
126         * @return Returns a reference to <code>this</code> parser so that method calls can be chained together
127         * @see #setStripVersionsFromReferences(boolean)
128         */
129        @SuppressWarnings("unchecked")
130        public ParserOptions setDontStripVersionsFromReferencesAtPaths(Collection<String> thePaths) {
131                if (thePaths == null) {
132                        myDontStripVersionsFromReferencesAtPaths = Collections.emptySet();
133                } else if (thePaths instanceof HashSet) {
134                        myDontStripVersionsFromReferencesAtPaths = (Set<String>) ((HashSet<String>) thePaths).clone();
135                } else {
136                        myDontStripVersionsFromReferencesAtPaths = new HashSet<>(thePaths);
137                }
138                return this;
139        }
140
141        /**
142         * If set to <code>true</code> (which is the default), the Bundle.entry.fullUrl will override the Bundle.entry.resource's
143         * resource id if the fullUrl is defined. This behavior happens when parsing the source data into a Bundle object. Set this
144         * to <code>false</code> if this is not the desired behavior (e.g. the client code wishes to perform additional
145         * validation checks between the fullUrl and the resource id).
146         *
147         * @return Returns the parser instance's configuration setting for overriding resource ids with Bundle.entry.fullUrl when
148         * parsing the source data into a Bundle object. Default is <code>true</code>.
149         */
150        public boolean isOverrideResourceIdWithBundleEntryFullUrl() {
151                return myOverrideResourceIdWithBundleEntryFullUrl;
152        }
153
154        /**
155         * If set to <code>true</code> (which is the default), the Bundle.entry.fullUrl will override the Bundle.entry.resource's
156         * resource id if the fullUrl is defined. This behavior happens when parsing the source data into a Bundle object. Set this
157         * to <code>false</code> if this is not the desired behavior (e.g. the client code wishes to perform additional
158         * validation checks between the fullUrl and the resource id).
159         *
160         * @param theOverrideResourceIdWithBundleEntryFullUrl Set this to <code>false</code> to prevent the parser from overriding resource ids with the
161         *                                                    Bundle.entry.fullUrl
162         * @return Returns a reference to <code>this</code> parser so that method calls can be chained together
163         */
164        public ParserOptions setOverrideResourceIdWithBundleEntryFullUrl(boolean theOverrideResourceIdWithBundleEntryFullUrl) {
165                myOverrideResourceIdWithBundleEntryFullUrl = theOverrideResourceIdWithBundleEntryFullUrl;
166                return this;
167        }
168
169}