View Javadoc
1   package ca.uhn.fhir.context;
2   
3   /*
4    * #%L
5    * HAPI FHIR - Core Library
6    * %%
7    * Copyright (C) 2014 - 2019 University Health Network
8    * %%
9    * Licensed under the Apache License, Version 2.0 (the "License");
10   * you may not use this file except in compliance with the License.
11   * You may obtain a copy of the License at
12   * 
13   *      http://www.apache.org/licenses/LICENSE-2.0
14   * 
15   * Unless required by applicable law or agreed to in writing, software
16   * distributed under the License is distributed on an "AS IS" BASIS,
17   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18   * See the License for the specific language governing permissions and
19   * limitations under the License.
20   * #L%
21   */
22  
23  import ca.uhn.fhir.parser.IParser;
24  
25  import java.util.*;
26  
27  /**
28   * This object supplies default configuration to all {@link IParser parser} instances
29   * created by a given {@link FhirContext}. It is accessed using {@link FhirContext#getParserOptions()}
30   * and {@link FhirContext#setParserOptions(ParserOptions)}.
31   * <p>
32   * It is fine to share a ParserOptions instances across multiple context instances.
33   * </p>
34   */
35  public class ParserOptions {
36  
37  	private boolean myStripVersionsFromReferences = true;
38  	private Set<String> myDontStripVersionsFromReferencesAtPaths = Collections.emptySet();
39  	private boolean myOverrideResourceIdWithBundleEntryFullUrl = true;
40  
41  	/**
42  	 * If supplied value(s), any resource references at the specified paths will have their
43  	 * resource versions encoded instead of being automatically stripped during the encoding
44  	 * process. This setting has no effect on the parsing process.
45  	 * <p>
46  	 * This method provides a finer-grained level of control than {@link #setStripVersionsFromReferences(boolean)}
47  	 * and any paths specified by this method will be encoded even if {@link #setStripVersionsFromReferences(boolean)}
48  	 * has been set to <code>true</code> (which is the default)
49  	 * </p>
50  	 *
51  	 * @param thePaths A collection of paths for which the resource versions will not be removed automatically
52  	 *                 when serializing, e.g. "Patient.managingOrganization" or "AuditEvent.object.reference". Note that
53  	 *                 only resource name and field names with dots separating is allowed here (no repetition
54  	 *                 indicators, FluentPath expressions, etc.)
55  	 * @return Returns a reference to <code>this</code> parser so that method calls can be chained together
56  	 * @see #setStripVersionsFromReferences(boolean)
57  	 */
58  	public ParserOptions setDontStripVersionsFromReferencesAtPaths(String... thePaths) {
59  		if (thePaths == null) {
60  			setDontStripVersionsFromReferencesAtPaths((List<String>) null);
61  		} else {
62  			setDontStripVersionsFromReferencesAtPaths(Arrays.asList(thePaths));
63  		}
64  		return this;
65  	}
66  
67  	/**
68  	 * If set to <code>true<code> (which is the default), resource references containing a version
69  	 * will have the version removed when the resource is encoded. This is generally good behaviour because
70  	 * in most situations, references from one resource to another should be to the resource by ID, not
71  	 * by ID and version. In some cases though, it may be desirable to preserve the version in resource
72  	 * links. In that case, this value should be set to <code>false</code>.
73  	 *
74  	 * @return Returns the parser instance's configuration setting for stripping versions from resource references when
75  	 * encoding. Default is <code>true</code>.
76  	 */
77  	public boolean isStripVersionsFromReferences() {
78  		return myStripVersionsFromReferences;
79  	}
80  
81  	/**
82  	 * If set to <code>true<code> (which is the default), resource references containing a version
83  	 * will have the version removed when the resource is encoded. This is generally good behaviour because
84  	 * in most situations, references from one resource to another should be to the resource by ID, not
85  	 * by ID and version. In some cases though, it may be desirable to preserve the version in resource
86  	 * links. In that case, this value should be set to <code>false</code>.
87  	 * <p>
88  	 * This method provides the ability to globally disable reference encoding. If finer-grained
89  	 * control is needed, use {@link #setDontStripVersionsFromReferencesAtPaths(String...)}
90  	 * </p>
91  	 *
92  	 * @param theStripVersionsFromReferences Set this to <code>false<code> to prevent the parser from removing
93  	 *                                       resource versions from references.
94  	 * @return Returns a reference to <code>this</code> parser so that method calls can be chained together
95  	 * @see #setDontStripVersionsFromReferencesAtPaths(String...)
96  	 */
97  	public ParserOptions setStripVersionsFromReferences(boolean theStripVersionsFromReferences) {
98  		myStripVersionsFromReferences = theStripVersionsFromReferences;
99  		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 }