View Javadoc
1   package ca.uhn.fhir.context;
2   
3   /*
4    * #%L
5    * HAPI FHIR - Core Library
6    * %%
7    * Copyright (C) 2014 - 2018 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 java.util.Arrays;
24  import java.util.Collection;
25  import java.util.Collections;
26  import java.util.HashSet;
27  import java.util.List;
28  import java.util.Set;
29  
30  import ca.uhn.fhir.parser.IParser;
31  
32  /**
33   * This object supplies default configuration to all {@link IParser parser} instances
34   * created by a given {@link FhirContext}. It is accessed using {@link FhirContext#getParserOptions()}
35   * and {@link FhirContext#setParserOptions(ParserOptions)}.
36   * <p>
37   * It is fine to share a ParserOptions instances across multiple context instances.
38   * </p>
39   */
40  public class ParserOptions {
41  
42  	private boolean myStripVersionsFromReferences = true;
43  	private Set<String> myDontStripVersionsFromReferencesAtPaths = Collections.emptySet();
44  	private boolean myOverrideResourceIdWithBundleEntryFullUrl = true;
45  	
46  	/**
47  	 * If supplied value(s), any resource references at the specified paths will have their
48  	 * resource versions encoded instead of being automatically stripped during the encoding
49  	 * process. This setting has no effect on the parsing process.
50  	 * <p>
51  	 * This method provides a finer-grained level of control than {@link #setStripVersionsFromReferences(boolean)}
52  	 * and any paths specified by this method will be encoded even if {@link #setStripVersionsFromReferences(boolean)}
53  	 * has been set to <code>true</code> (which is the default)
54  	 * </p>
55  	 *
56  	 * @param thePaths
57  	 *           A collection of paths for which the resource versions will not be removed automatically
58  	 *           when serializing, e.g. "Patient.managingOrganization" or "AuditEvent.object.reference". Note that
59  	 *           only resource name and field names with dots separating is allowed here (no repetition
60  	 *           indicators, FluentPath expressions, etc.)
61  	 * @see #setStripVersionsFromReferences(boolean)
62  	 * @return Returns a reference to <code>this</code> parser so that method calls can be chained together
63  	 */
64  	public ParserOptions setDontStripVersionsFromReferencesAtPaths(String... thePaths) {
65  		if (thePaths == null) {
66  			setDontStripVersionsFromReferencesAtPaths((List<String>) null);
67  		} else {
68  			setDontStripVersionsFromReferencesAtPaths(Arrays.asList(thePaths));
69  		}
70  		return this;
71  	}
72  	
73  	/**
74  	 * If set to <code>true<code> (which is the default), resource references containing a version
75  	 * will have the version removed when the resource is encoded. This is generally good behaviour because
76  	 * in most situations, references from one resource to another should be to the resource by ID, not
77  	 * by ID and version. In some cases though, it may be desirable to preserve the version in resource
78  	 * links. In that case, this value should be set to <code>false</code>.
79  	 * 
80  	 * @return Returns the parser instance's configuration setting for stripping versions from resource references when
81  	 *         encoding. Default is <code>true</code>.
82  	 */
83  	public boolean isStripVersionsFromReferences() {
84  		return myStripVersionsFromReferences ;
85  	}
86  
87  	/**
88  	 * If set to <code>true<code> (which is the default), resource references containing a version
89  	 * will have the version removed when the resource is encoded. This is generally good behaviour because
90  	 * in most situations, references from one resource to another should be to the resource by ID, not
91  	 * by ID and version. In some cases though, it may be desirable to preserve the version in resource
92  	 * links. In that case, this value should be set to <code>false</code>.
93  	 * <p>
94  	 * This method provides the ability to globally disable reference encoding. If finer-grained
95  	 * control is needed, use {@link #setDontStripVersionsFromReferencesAtPaths(String...)}
96  	 * </p>
97  	 * @param theStripVersionsFromReferences
98  	 *           Set this to <code>false<code> to prevent the parser from removing
99  	 *           resource versions from references.
100 	 * @return Returns a reference to <code>this</code> parser so that method calls can be chained together
101 	 * @see #setDontStripVersionsFromReferencesAtPaths(String...)
102 	 */
103 	public ParserOptions setStripVersionsFromReferences(boolean theStripVersionsFromReferences) {
104 		myStripVersionsFromReferences = theStripVersionsFromReferences;
105 		return this;
106 	}
107 
108 	/**
109 	 * If supplied value(s), any resource references at the specified paths will have their
110 	 * resource versions encoded instead of being automatically stripped during the encoding
111 	 * process. This setting has no effect on the parsing process.
112 	 * <p>
113 	 * This method provides a finer-grained level of control than {@link #setStripVersionsFromReferences(boolean)}
114 	 * and any paths specified by this method will be encoded even if {@link #setStripVersionsFromReferences(boolean)}
115 	 * has been set to <code>true</code> (which is the default)
116 	 * </p>
117 	 *
118 	 * @param thePaths
119 	 *           A collection of paths for which the resource versions will not be removed automatically
120 	 *           when serializing, e.g. "Patient.managingOrganization" or "AuditEvent.object.reference". Note that
121 	 *           only resource name and field names with dots separating is allowed here (no repetition
122 	 *           indicators, FluentPath expressions, etc.)
123 	 * @see #setStripVersionsFromReferences(boolean)
124 	 * @return Returns a reference to <code>this</code> parser so that method calls can be chained together
125 	 */
126 	@SuppressWarnings("unchecked")
127 	public ParserOptions setDontStripVersionsFromReferencesAtPaths(Collection<String> thePaths) {
128 		if (thePaths == null) {
129 			myDontStripVersionsFromReferencesAtPaths = Collections.emptySet();
130 		} else if (thePaths instanceof HashSet) {
131 			myDontStripVersionsFromReferencesAtPaths = (Set<String>) ((HashSet<String>)thePaths).clone();
132 		} else {
133 			myDontStripVersionsFromReferencesAtPaths = new HashSet<String>(thePaths);
134 		}
135 		return this;
136 	}
137 
138 	/**
139 	 * Returns the value supplied to {@link IParser#setDontStripVersionsFromReferencesAtPaths(String...)}
140 	 * 
141 	 * @see #setDontStripVersionsFromReferencesAtPaths(String...)
142 	 * @see #setStripVersionsFromReferences(boolean)
143 	 */
144 	public Set<String> getDontStripVersionsFromReferencesAtPaths() {
145 		return myDontStripVersionsFromReferencesAtPaths;
146 	}
147 
148 	/**
149 	 * If set to <code>true</code> (which is the default), the Bundle.entry.fullUrl will override the Bundle.entry.resource's
150 	 * resource id if the fullUrl is defined. This behavior happens when parsing the source data into a Bundle object. Set this
151 	 * to <code>false</code> if this is not the desired behavior (e.g. the client code wishes to perform additional
152 	 * validation checks between the fullUrl and the resource id).
153 	 *
154 	 * @return Returns the parser instance's configuration setting for overriding resource ids with Bundle.entry.fullUrl when
155 	 *         parsing the source data into a Bundle object. Default is <code>true</code>.
156 	 */
157 	public boolean isOverrideResourceIdWithBundleEntryFullUrl() {
158 		return myOverrideResourceIdWithBundleEntryFullUrl;
159 	}
160 
161 	/**
162 	 * If set to <code>true</code> (which is the default), the Bundle.entry.fullUrl will override the Bundle.entry.resource's
163 	 * resource id if the fullUrl is defined. This behavior happens when parsing the source data into a Bundle object. Set this
164 	 * to <code>false</code> if this is not the desired behavior (e.g. the client code wishes to perform additional
165 	 * validation checks between the fullUrl and the resource id).
166 	 *
167 	 * @param theOverrideResourceIdWithBundleEntryFullUrl
168 	 *           Set this to <code>false</code> to prevent the parser from overriding resource ids with the
169 	 *           Bundle.entry.fullUrl
170 	 *
171 	 * @return Returns a reference to <code>this</code> parser so that method calls can be chained together
172 	 */
173 	public ParserOptions setOverrideResourceIdWithBundleEntryFullUrl(boolean theOverrideResourceIdWithBundleEntryFullUrl) {
174 		myOverrideResourceIdWithBundleEntryFullUrl = theOverrideResourceIdWithBundleEntryFullUrl;
175 		return this;
176 	}
177 }