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