1 package ca.uhn.fhir.parser;
2
3 /*
4 * #%L
5 * HAPI FHIR - Core Library
6 * %%
7 * Copyright (C) 2014 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.io.IOException;
24 import java.io.Reader;
25 import java.io.Writer;
26
27 import ca.uhn.fhir.context.ConfigurationException;
28 import ca.uhn.fhir.model.api.Bundle;
29 import ca.uhn.fhir.model.api.IResource;
30 import ca.uhn.fhir.model.api.TagList;
31
32 /**
33 *
34 * <p>
35 * Thread safety: <b>Parsers are not guaranteed to be thread safe</b>. Create a new parser instance for every thread or every message being parsed/encoded.
36 * </p>
37 */
38 public interface IParser {
39
40 String encodeBundleToString(Bundle theBundle) throws DataFormatException;
41
42 void encodeBundleToWriter(Bundle theBundle, Writer theWriter) throws IOException, DataFormatException;
43
44 String encodeResourceToString(IResource theResource) throws DataFormatException;
45
46 void encodeResourceToWriter(IResource theResource, Writer theWriter) throws IOException, DataFormatException;
47
48 /**
49 * Encodes a tag list, as defined in the <a href="http://hl7.org/implement/standards/fhir/http.html#tags">FHIR Specification</a>.
50 *
51 * @param theTagList
52 * The tag list to encode. Must not be null.
53 * @return An encoded tag list
54 */
55 String encodeTagListToString(TagList theTagList);
56
57 /**
58 * Encodes a tag list, as defined in the <a href="http://hl7.org/implement/standards/fhir/http.html#tags">FHIR Specification</a>.
59 *
60 * @param theTagList
61 * The tag list to encode. Must not be null.
62 * @param theWriter
63 * The writer to encode to
64 */
65 void encodeTagListToWriter(TagList theTagList, Writer theWriter) throws IOException;
66
67 <T extends IResource> Bundle parseBundle(Class<T> theResourceType, Reader theReader);
68
69 Bundle parseBundle(Reader theReader);
70
71 Bundle parseBundle(String theMessageString) throws ConfigurationException, DataFormatException;
72
73 /**
74 * Parses a resource
75 *
76 * @param theResourceType
77 * The resource type to use. This can be used to explicitly specify a class which extends a built-in type (e.g. a custom type extending the default Patient class)
78 * @param theReader
79 * The reader to parse input from. Note that the Reader will not be closed by the parser upon completion.
80 * @return A parsed resource
81 * @throws DataFormatException
82 * If the resource can not be parsed because the data is not recognized or invalid for any reason
83 */
84 <T extends IResource> T parseResource(Class<T> theResourceType, Reader theReader) throws DataFormatException;
85
86 /**
87 * Parses a resource
88 *
89 * @param theResourceType
90 * The resource type to use. This can be used to explicitly specify a class which extends a built-in type (e.g. a custom type extending the default Patient class)
91 * @param theString
92 * The string to parse
93 * @return A parsed resource
94 * @throws DataFormatException
95 * If the resource can not be parsed because the data is not recognized or invalid for any reason
96 */
97 <T extends IResource> T parseResource(Class<T> theResourceType, String theString) throws DataFormatException;
98
99 /**
100 * Parses a resource
101 *
102 * @param theReader
103 * The reader to parse input from. Note that the Reader will not be closed by the parser upon completion.
104 * @return A parsed resource
105 * @throws DataFormatException
106 * If the resource can not be parsed because the data is not recognized or invalid for any reason
107 */
108 IResource parseResource(Reader theReader) throws ConfigurationException, DataFormatException;
109
110 /**
111 * Parses a resource
112 *
113 * @param theString
114 * The string to parse
115 * @return A parsed resource
116 * @throws DataFormatException
117 * If the resource can not be parsed because the data is not recognized or invalid for any reason
118 */
119 IResource parseResource(String theMessageString) throws ConfigurationException, DataFormatException;
120
121 /**
122 * Parses a tag list, as defined in the <a href="http://hl7.org/implement/standards/fhir/http.html#tags">FHIR Specification</a>.
123 *
124 * @param theReader
125 * A reader which will supply a tag list
126 * @return A parsed tag list
127 */
128 TagList parseTagList(Reader theReader);
129
130 /**
131 * Parses a tag list, as defined in the <a href="http://hl7.org/implement/standards/fhir/http.html#tags">FHIR Specification</a>.
132 *
133 * @param theString
134 * A string containing a tag list
135 * @return A parsed tag list
136 */
137 TagList parseTagList(String theString);
138
139 /**
140 * Sets the "pretty print" flag, meaning that the parser will encode resources with human-readable spacing and newlines between elements instead of condensing output as much as possible.
141 *
142 * @param thePrettyPrint
143 * The flag
144 * @return Returns an instance of <code>this</code> parser so that method calls can be conveniently chained
145 */
146 IParser setPrettyPrint(boolean thePrettyPrint);
147
148 /**
149 * If set to <code>true</code> (default is <code>false</code>), narratives will not be included in the encoded values.
150 */
151 IParser setSuppressNarratives(boolean theSuppressNarratives);
152
153 }