001package org.hl7.fhir.r4.formats;
002
003/*-
004 * #%L
005 * org.hl7.fhir.r4
006 * %%
007 * Copyright (C) 2014 - 2019 Health Level 7
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
023
024
025import java.io.IOException;
026
027/*
028  Copyright (c) 2011+, HL7, Inc.
029  All rights reserved.
030  
031  Redistribution and use in source and binary forms, with or without modification, 
032  are permitted provided that the following conditions are met:
033  
034   * Redistributions of source code must retain the above copyright notice, this 
035     list of conditions and the following disclaimer.
036   * Redistributions in binary form must reproduce the above copyright notice, 
037     this list of conditions and the following disclaimer in the documentation 
038     and/or other materials provided with the distribution.
039   * Neither the name of HL7 nor the names of its contributors may be used to 
040     endorse or promote products derived from this software without specific 
041     prior written permission.
042  
043  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 
044  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
045  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 
046  IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 
047  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 
048  NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
049  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
050  WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
051  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
052  POSSIBILITY OF SUCH DAMAGE.
053  
054*/
055
056
057import java.io.InputStream;
058import java.io.OutputStream;
059import java.io.UnsupportedEncodingException;
060
061import org.hl7.fhir.exceptions.FHIRFormatError;
062import org.hl7.fhir.r4.model.Resource;
063import org.hl7.fhir.r4.model.Type;
064import org.xmlpull.v1.XmlPullParserException;
065
066
067/**
068 * General interface - either an XML or JSON parser: read or write instances
069 *  
070 * Defined to allow a factory to create a parser of the right type
071 */
072public interface IParser {
073
074        /** 
075         * check what kind of parser this is
076         *  
077         * @return what kind of parser this is
078         */
079        public ParserType getType();
080        
081  // -- Parser Configuration ----------------------------------
082  /**
083   * Whether to parse or ignore comments - either reading or writing
084   */
085  public boolean getHandleComments(); 
086  public IParser setHandleComments(boolean value);
087
088  /**
089   * @param allowUnknownContent Whether to throw an exception if unknown content is found (or just skip it) when parsing
090   */
091  public boolean isAllowUnknownContent();
092  public IParser setAllowUnknownContent(boolean value);
093  
094  
095  public enum OutputStyle {
096    /**
097     * Produce normal output - no whitespace, except in HTML where whitespace is untouched
098     */
099    NORMAL,
100    
101    /**
102     * Produce pretty output - human readable whitespace, HTML whitespace untouched
103     */
104    PRETTY,
105    
106    /**
107     * Produce canonical output - no comments, no whitspace, HTML whitespace normlised, JSON attributes sorted alphabetically (slightly slower) 
108     */
109    CANONICAL,
110  }
111
112  /**
113   * Writing: 
114   */
115  public OutputStyle getOutputStyle();
116  public IParser setOutputStyle(OutputStyle value);
117  
118  /**
119   * This method is used by the publication tooling to stop the xhrtml narrative being generated. 
120   * It is not valid to use in production use. The tooling uses it to generate json/xml representations in html that are not cluttered by escaped html representations of the html representation
121   */
122  public IParser setSuppressXhtml(String message);
123
124  // -- Reading methods ----------------------------------------
125  
126  /**
127   * parse content that is known to be a resource  
128 * @throws XmlPullParserException 
129 * @throws FHIRFormatError 
130 * @throws IOException 
131   */
132  public Resource parse(InputStream input) throws IOException, FHIRFormatError;
133
134  /**
135   * parse content that is known to be a resource  
136 * @throws UnsupportedEncodingException 
137 * @throws IOException 
138 * @throws FHIRFormatError 
139   */
140  public Resource parse(String input) throws UnsupportedEncodingException, FHIRFormatError, IOException;
141  
142  /**
143   * parse content that is known to be a resource  
144 * @throws IOException 
145 * @throws FHIRFormatError 
146   */
147  public Resource parse(byte[] bytes) throws FHIRFormatError, IOException;
148
149  /**
150   * This is used to parse a type - a fragment of a resource. 
151   * There's no reason to use this in production - it's used 
152   * in the build tools 
153   * 
154   * Not supported by all implementations
155   * 
156   * @param input
157   * @param knownType. if this is blank, the parser may try to infer the type (xml only)
158   * @return
159 * @throws XmlPullParserException 
160 * @throws FHIRFormatError 
161 * @throws IOException 
162   */
163  public Type parseType(InputStream input, String knownType) throws IOException, FHIRFormatError;
164  public Type parseAnyType(InputStream input, String knownType) throws IOException, FHIRFormatError;
165  
166  /**
167   * This is used to parse a type - a fragment of a resource. 
168   * There's no reason to use this in production - it's used 
169   * in the build tools 
170   * 
171   * Not supported by all implementations
172   * 
173   * @param input
174   * @param knownType. if this is blank, the parser may try to infer the type (xml only)
175   * @return
176 * @throws UnsupportedEncodingException 
177 * @throws IOException 
178 * @throws FHIRFormatError 
179   */
180  public Type parseType(String input, String knownType) throws UnsupportedEncodingException, FHIRFormatError, IOException;
181  /**
182   * This is used to parse a type - a fragment of a resource. 
183   * There's no reason to use this in production - it's used 
184   * in the build tools 
185   * 
186   * Not supported by all implementations
187   * 
188   * @param input
189   * @param knownType. if this is blank, the parser may try to infer the type (xml only)
190   * @return
191 * @throws IOException 
192 * @throws FHIRFormatError 
193         */
194  public Type parseType(byte[] bytes, String knownType) throws FHIRFormatError, IOException;
195  
196  // -- Writing methods ----------------------------------------
197
198        /**
199         * Compose a resource to a stream, possibly using pretty presentation for a human reader (used in the spec, for example, but not normally in production)
200         * @throws IOException 
201         */
202        public void compose(OutputStream stream, Resource resource) throws IOException;
203        
204  /**
205   * Compose a resource to a stream, possibly using pretty presentation for a human reader (used in the spec, for example, but not normally in production)
206 * @throws IOException 
207   */
208        public String composeString(Resource resource) throws IOException;
209
210        /**
211   * Compose a resource to a stream, possibly using pretty presentation for a human reader (used in the spec, for example, but not normally in production)
212         * @throws IOException 
213   */
214        public byte[] composeBytes(Resource resource) throws IOException;
215
216
217        /**
218         * Compose a type to a stream, possibly using pretty presentation for a human reader (used in the spec, for example, but not normally in production)
219         * 
220         * Not supported by all implementations. rootName is ignored in the JSON format
221         * @throws XmlPullParserException 
222         * @throws FHIRFormatError 
223         * @throws IOException 
224         */
225        public void compose(OutputStream stream, Type type, String rootName) throws IOException;
226
227        /**
228   * Compose a type to a stream, possibly using pretty presentation for a human reader (used in the spec, for example, but not normally in production)
229   * 
230   * Not supported by all implementations. rootName is ignored in the JSON format
231         * @throws IOException 
232   */
233  public String composeString(Type type, String rootName) throws IOException;
234
235        /**
236         * Compose a type to a stream, possibly using pretty presentation for a human reader (used in the spec, for example, but not normally in production)
237   * 
238   * Not supported by all implementations. rootName is ignored in the JSON format
239         * @throws IOException 
240         */
241        public byte[] composeBytes(Type type, String rootName) throws IOException;
242
243
244}