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