001 /** 002 The 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. 004 You may obtain a copy of the License at http://www.mozilla.org/MPL/ 005 Software distributed under the License is distributed on an "AS IS" basis, 006 WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the 007 specific language governing rights and limitations under the License. 008 009 The Original Code is "Message.java". Description: 010 "Represents a complete HL7 message including all structures, segments, and fields" 011 012 The Initial Developer of the Original Code is University Health Network. Copyright (C) 013 2001. All Rights Reserved. 014 015 Contributor(s): ______________________________________. 016 017 Alternatively, the contents of this file may be used under the terms of the 018 GNU General Public License (the ???GPL???), in which case the provisions of the GPL are 019 applicable instead of those above. If you wish to allow use of your version of this 020 file only under the terms of the GPL and not to allow others to use your version 021 of this file under the MPL, indicate your decision by deleting the provisions above 022 and replace them with the notice and other provisions required by the GPL License. 023 If you do not delete the provisions above, a recipient may use your version of 024 this file under either the MPL or the GPL. 025 026 */ 027 028 package ca.uhn.hl7v2.model; 029 030 import ca.uhn.hl7v2.HL7Exception; 031 import ca.uhn.hl7v2.parser.Parser; 032 import ca.uhn.hl7v2.parser.PipeParser; 033 import ca.uhn.hl7v2.validation.ValidationContext; 034 import java.io.IOException; 035 036 037 /** 038 * Represents a complete HL7 message including all structures, segments, and fields. 039 * @author Bryan Tripp (bryan_tripp@sourceforge.net) 040 */ 041 public interface Message extends Group { 042 043 /** 044 * Returns the version number of the HL7 version in which this 045 * message structure is defined (e.g. "2.4") 046 */ 047 public abstract String getVersion(); 048 049 /** 050 * @return the set of validation rules that applies to this message 051 */ 052 public abstract ValidationContext getValidationContext(); 053 054 /** 055 * @param theContext the set of validation rules that are to apply to this message 056 */ 057 public void setValidationContext(ValidationContext theContext); 058 059 060 /** 061 * Convenience method which retrieves the field separator value from the first field of the first segment. 062 * 063 * Typically, the first segment is MSH, so this method will retrieve the 064 * value of MSH-1. 065 * 066 * @return The field separator 067 * @throws HL7Exception If an error occurs 068 * @since 1.0 069 */ 070 public Character getFieldSeparatorValue() throws HL7Exception; 071 072 073 /** 074 * Convenience method which retrieves the encoding characters value from the second field of the first segment. 075 * 076 * Typically, the first segment is MSH, so this method will retrieve the 077 * value of MSH-2. 078 * 079 * @return The encoding characters 080 * @throws HL7Exception If an error occurs 081 * @since 1.0 082 */ 083 public String getEncodingCharactersValue() throws HL7Exception; 084 085 086 /** 087 * Sets the parser to be used when parse/encode methods are called on this 088 * Message, as well as its children. It is recommended that if these methods 089 * are going to be called, a parser be supplied with the validation context 090 * wanted. Where possible, the parser should be reused for best performance, 091 * unless thread safety is an issue. 092 * 093 * Note that not all parsers can be used. As of version 1.0, only {@link PipeParser} 094 * supports this functionality 095 */ 096 public void setParser(Parser parser); 097 098 099 /** 100 * Returns the parser to be used when parse/encode methods are called on this 101 * Message, as well as its children. The default value is a new {@link PipeParser} 102 */ 103 public Parser getParser(); 104 105 106 /** 107 * Parses the string into this message using the parser returned by {@link #getParser() } 108 */ 109 public void parse(String string) throws HL7Exception; 110 111 112 /** 113 * Encodes this message using the parser returned by {@link #getParser() } 114 */ 115 public String encode() throws HL7Exception; 116 117 118 /** 119 * <p> 120 * Generates and returns an ACK message which would be used to 121 * acknowledge this message successfully, with an MSA-1 code of "AA". 122 * The ACK generated will be of the same version as the value of MSH-12 in this message (as opposed 123 * to the version of the message class instance, if they are different) 124 * </p> 125 * 126 * <p> 127 * Note that this method will fail if it is not possible to 128 * generate an ACK for any reason, such as 129 * <ul> 130 * <li>Message version is invalid</li> 131 * <li>First segment is not an MSH</li> 132 * </p> 133 * 134 * @throws HL7Exception If the message can not be constructed 135 * @throws IOException If a failure occurs in generating a control ID for the message 136 */ 137 public Message generateACK() throws HL7Exception, IOException; 138 139 140 /** 141 * <p> 142 * Generates and returns an ACK message which would be used to 143 * acknowledge this message successfully. The ACK generated will be 144 * of the same version as the value of MSH-12 in this message (as opposed 145 * to the version of the message class instance, if they are different) 146 * </p> 147 * 148 * <p> 149 * Note that this method will fail if it is not possible to 150 * generate an ACK for any reason, such as 151 * <ul> 152 * <li>Message version is invalid</li> 153 * <li>First segment is not an MSH</li> 154 * </p> 155 * 156 * @param theAcknowldegementCode The acknowledement code (MSA-1) to supply. If null, defaults to "AA". To generate a typical NAK, use "AE" 157 * @param theException The exceptions used to populate the ERR segment (if any) 158 * @throws HL7Exception If the message can not be constructed 159 * @throws IOException If a failure occurs in generating a control ID for the message 160 */ 161 public Message generateACK(String theAcknowldegementCode, HL7Exception theException) throws HL7Exception, IOException; 162 163 }