001/** 002The contents of this file are subject to the Mozilla Public License Version 1.1 003(the "License"); you may not use this file except in compliance with the License. 004You may obtain a copy of the License at http://www.mozilla.org/MPL/ 005Software distributed under the License is distributed on an "AS IS" basis, 006WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the 007specific language governing rights and limitations under the License. 008 009The Original Code is "Message.java". Description: 010"Represents a complete HL7 message including all structures, segments, and fields" 011 012The Initial Developer of the Original Code is University Health Network. Copyright (C) 0132001. All Rights Reserved. 014 015Contributor(s): ______________________________________. 016 017Alternatively, the contents of this file may be used under the terms of the 018GNU General Public License (the �GPL�), in which case the provisions of the GPL are 019applicable instead of those above. If you wish to allow use of your version of this 020file only under the terms of the GPL and not to allow others to use your version 021of this file under the MPL, indicate your decision by deleting the provisions above 022and replace them with the notice and other provisions required by the GPL License. 023If you do not delete the provisions above, a recipient may use your version of 024this file under either the MPL or the GPL. 025 026 */ 027 028package ca.uhn.hl7v2.model; 029 030import java.io.IOException; 031 032import ca.uhn.hl7v2.AcknowledgmentCode; 033import ca.uhn.hl7v2.HL7Exception; 034import ca.uhn.hl7v2.parser.Parser; 035import ca.uhn.hl7v2.validation.ValidationContext; 036 037/** 038 * <p> 039 * Represents a complete HL7 message including all structures, segments, and fields. 040 * </p> 041 * <p> 042 * Note this it is not recommended to implement this interface directly, as it is subject to change. 043 * Instead, extend abstract implementations for your model classes, such as {@link AbstractMessage} 044 * and {@link AbstractGroup} 045 * </p> 046 * 047 * @author Bryan Tripp (bryan_tripp@sourceforge.net) 048 */ 049public interface Message extends Group { 050 051 /** 052 * Returns the version number of the HL7 version in which this message structure is defined 053 * (e.g. "2.4") 054 * @return version number of the HL7 version 055 */ 056 public abstract String getVersion(); 057 058 /** 059 * @return the set of validation rules that applies to this message 060 * 061 * @deprecated ValidationContext instances private for Message instances will be removed in the 062 * next release. Use getParser().getValidationContext(). 063 */ 064 public abstract ValidationContext getValidationContext(); 065 066 /** 067 * @param theContext the set of validation rules that are to apply to this message 068 * 069 * @deprecated ValidationContext instances private for Message instances will be removed in the 070 * next release. Use 071 * {@link ca.uhn.hl7v2.HapiContext#setValidationContext(ValidationContext)} then. 072 */ 073 public void setValidationContext(ValidationContext theContext); 074 075 /** 076 * Convenience method which retrieves the field separator value from the first field of the 077 * first segment. 078 * 079 * Typically, the first segment is MSH, so this method will retrieve the value of MSH-1. 080 * 081 * @return The field separator 082 * @throws HL7Exception If an error occurs 083 * @since 1.0 084 */ 085 public Character getFieldSeparatorValue() throws HL7Exception; 086 087 /** 088 * Convenience method which retrieves the encoding characters value from the second field of the 089 * first segment. 090 * 091 * Typically, the first segment is MSH, so this method will retrieve the value of MSH-2. 092 * 093 * @return The encoding characters 094 * @throws HL7Exception If an error occurs 095 * @since 1.0 096 */ 097 public String getEncodingCharactersValue() throws HL7Exception; 098 099 /** 100 * Sets the parser to be used when parse/encode methods are called on this Message, as well as 101 * its children. It is recommended that if these methods are going to be called, a parser be 102 * supplied with the validation context wanted. Where possible, the parser should be reused for 103 * best performance, unless thread safety is an issue. 104 * 105 * Note that not all parsers can be used. As of version 1.0, only PipeParser supports 106 * this functionality 107 * 108 * @param parser the parser to be used when parse/encode methods are called on this Message 109 */ 110 public void setParser(Parser parser); 111 112 /** 113 * Returns the parser to be used when parse/encode methods are called on this Message, as well 114 * as its children. The default value is a new PipeParser. 115 * 116 * @return the parser to be used when parse/encode methods are called on this Message 117 */ 118 public Parser getParser(); 119 120 /** 121 * Parses the string into this message using the parser returned by {@link #getParser() } 122 * @param string the message to be parsed 123 * @throws HL7Exception if errors occurred during parsing 124 */ 125 public void parse(String string) throws HL7Exception; 126 127 /** 128 * Encodes this message using the parser returned by {@link #getParser() } 129 * @return the string-encoded message 130 * @throws HL7Exception if error occurred during encoding 131 */ 132 public String encode() throws HL7Exception; 133 134 /** 135 * <p> 136 * Generates and returns an ACK message which would be used to acknowledge this message 137 * successfully, with an MSA-1 code of "AA". The ACK generated will be of the same version as 138 * the value of MSH-12 in this message (as opposed to the version of the message class instance, 139 * if they are different) 140 * </p> 141 * 142 * <p> 143 * Note that this method will fail if it is not possible to generate an ACK for any reason, such 144 * as 145 * <ul> 146 * <li>Message version is invalid</li> 147 * <li>First segment is not an MSH</li> 148 * </p> 149 * 150 * @return the acknowledgment message 151 * @throws HL7Exception If the message can not be constructed 152 * @throws IOException If a failure occurs in generating a control ID for the message 153 */ 154 public Message generateACK() throws HL7Exception, IOException; 155 156 /** 157 * <p> 158 * Generates and returns an ACK message which would be used to acknowledge this message 159 * successfully. The ACK generated will be of the same version as the value of MSH-12 in this 160 * message (as opposed to the version of the message class instance, if they are different) 161 * </p> 162 * 163 * <p> 164 * Note that this method will fail if it is not possible to generate an ACK for any reason, such 165 * as 166 * <ul> 167 * <li>Message version is invalid</li> 168 * <li>First segment is not an MSH</li> 169 * </p> 170 * 171 * @param theAcknowldegementCode The acknowledement code (MSA-1) to supply. If null, defaults to 172 * "AA". To generate a typical NAK, use "AE" 173 * @param theException The exceptions used to populate the ERR segment (if any) 174 * @throws HL7Exception If the message can not be constructed 175 * @throws IOException If a failure occurs in generating a control ID for the message 176 * 177 * @deprecated use {@link #generateACK(AcknowledgmentCode, HL7Exception)} 178 */ 179 public Message generateACK(String theAcknowldegementCode, HL7Exception theException) 180 throws HL7Exception, IOException; 181 182 /** 183 * <p> 184 * Generates and returns an ACK message which would be used to acknowledge this message 185 * successfully. The ACK generated will be of the same version as the value of MSH-12 in this 186 * message (as opposed to the version of the message class instance, if they are different) 187 * </p> 188 * 189 * <p> 190 * Note that this method will fail if it is not possible to generate an ACK for any reason, such 191 * as 192 * <ul> 193 * <li>Message version is invalid</li> 194 * <li>First segment is not an MSH</li> 195 * </p> 196 * 197 * @param theAcknowlegementCode If null, defaults to 198 * AcknowledgmentCode.AA. To generate a typical NAK, use AcknowledgmentCode.AE 199 * @param theException The exceptions used to populate the ERR segment (if any) 200 * @return the acknoeldgement message 201 * @throws HL7Exception If the message can not be constructed 202 * @throws IOException If a failure occurs in generating a control ID for the message 203 */ 204 public Message generateACK(AcknowledgmentCode theAcknowlegementCode, HL7Exception theException) 205 throws HL7Exception, IOException; 206 /** 207 * <p> 208 * Prints a summary of the contents and structure of this message. This is useful for debugging 209 * purposes, if you want to figure out where in the structure of a message a given segment has 210 * been placed. 211 * </p> 212 * <p> 213 * For instance, the following message (containing a few quirks for demonstration purposes): 214 * <code> 215 * <pre>MSH|^~\\&|^QueryServices||||20021011161756.297-0500||ADT^A01|1|D|2.4\r 216 * EVN|R01 217 * EVN|R02 218 * PID|1 219 * IN1|1 220 * IN1|2 221 * PID|2</pre></code> ...produces the following output: <code> 222 * <pre>ADT_A01 (start) 223 * MSH - MSH|^~\&|^QueryServices||||20021011161756.297-0500||ADT^A01|1|D|2.4 224 * EVN - EVN|R01 225 * [ { EVN2 } ] (non-standard) - EVN|R02 226 * PID - PID|1 227 * [ PD1 ] - Not populated 228 * [ { ROL } ] - Not populated 229 * [ { NK1 } ] - Not populated 230 * PV1 - Not populated 231 * [ PV2 ] - Not populated 232 * [ { ROL2 } ] - Not populated 233 * [ { DB1 } ] - Not populated 234 * [ { OBX } ] - Not populated 235 * [ { AL1 } ] - Not populated 236 * [ { DG1 } ] - Not populated 237 * [ DRG ] - Not populated 238 * PROCEDURE (start) 239 * [{ 240 * PR1 - Not populated 241 * [ { ROL } ] - Not populated 242 * }] 243 * PROCEDURE (end) 244 * [ { GT1 } ] - Not populated 245 * INSURANCE (start) 246 * [{ 247 * IN1 - IN1|1 248 * [ IN2 ] - Not populated 249 * [ { IN3 } ] - Not populated 250 * [ { ROL } ] - Not populated 251 * }] 252 * [{ 253 * IN1 - IN1|2 254 * [ { PID } ] (non-standard) - PID|2 255 * [ IN2 ] - Not populated 256 * [ { IN3 } ] - Not populated 257 * [ { ROL } ] - Not populated 258 * }] 259 * INSURANCE (end) 260 * [ ACC ] - Not populated 261 * [ UB1 ] - Not populated 262 * [ UB2 ] - Not populated 263 * [ PDA ] - Not populated 264 * ADT_A01 (end) 265 * </pre></code> 266 * </p> 267 * 268 * @return A summary of the structure 269 * @throws HL7Exception If any problems occur encoding the structure 270 */ 271 public String printStructure() throws HL7Exception; 272 273}