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