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}