View Javadoc

1   /**
2   The contents of this file are subject to the Mozilla Public License Version 1.1 
3   (the "License"); you may not use this file except in compliance with the License. 
4   You may obtain a copy of the License at http://www.mozilla.org/MPL/ 
5   Software distributed under the License is distributed on an "AS IS" basis, 
6   WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the 
7   specific language governing rights and limitations under the License. 
8   
9   The Original Code is "Message.java".  Description: 
10  "Represents a complete HL7 message including all structures, segments, and fields" 
11  
12  The Initial Developer of the Original Code is University Health Network. Copyright (C) 
13  2001.  All Rights Reserved. 
14  
15  Contributor(s): ______________________________________. 
16  
17  Alternatively, the contents of this file may be used under the terms of the 
18  GNU General Public License (the  �GPL�), in which case the provisions of the GPL are 
19  applicable instead of those above.  If you wish to allow use of your version of this 
20  file only under the terms of the GPL and not to allow others to use your version 
21  of this file under the MPL, indicate your decision by deleting  the provisions above 
22  and replace  them with the notice and other provisions required by the GPL License.  
23  If you do not delete the provisions above, a recipient may use your version of 
24  this file under either the MPL or the GPL. 
25  
26   */
27  
28  package ca.uhn.hl7v2.model;
29  
30  import ca.uhn.hl7v2.AcknowledgmentCode;
31  import ca.uhn.hl7v2.HL7Exception;
32  import ca.uhn.hl7v2.HapiContext;
33  import ca.uhn.hl7v2.parser.Parser;
34  import ca.uhn.hl7v2.parser.PipeParser;
35  import ca.uhn.hl7v2.validation.ValidationContext;
36  import java.io.IOException;
37  
38  /**
39   * <p>
40   * Represents a complete HL7 message including all structures, segments, and fields.
41   * </p>
42   * <p>
43   * Note this it is not recommended to implement this interface directly, as it is subject to change.
44   * Instead, extend abstract implementations for your model classes, such as {@link AbstractMessage}
45   * and {@link AbstractGroup}
46   * </p>
47   * 
48   * @author Bryan Tripp (bryan_tripp@sourceforge.net)
49   */
50  public interface Message extends Group {
51  
52  	/**
53  	 * Returns the version number of the HL7 version in which this message structure is defined
54  	 * (e.g. "2.4")
55  	 */
56  	public abstract String getVersion();
57  
58  	/**
59  	 * @return the set of validation rules that applies to this message
60  	 * 
61  	 * @deprecated ValidationContext instances private for Message instances will be removed in the
62  	 *             next release. Use getParser().getValidationContext().
63  	 */
64  	public abstract ValidationContext getValidationContext();
65  
66  	/**
67  	 * @param theContext the set of validation rules that are to apply to this message
68  	 * 
69  	 * @deprecated ValidationContext instances private for Message instances will be removed in the
70  	 *             next release. Use
71  	 *             {@link HapiContext#setValidationContext(ValidationContext)} then.
72  	 */
73  	public void setValidationContext(ValidationContext theContext);
74  
75  	/**
76  	 * Convenience method which retrieves the field separator value from the first field of the
77  	 * first segment.
78  	 * 
79  	 * Typically, the first segment is MSH, so this method will retrieve the value of MSH-1.
80  	 * 
81  	 * @return The field separator
82  	 * @throws HL7Exception If an error occurs
83  	 * @since 1.0
84  	 */
85  	public Character getFieldSeparatorValue() throws HL7Exception;
86  
87  	/**
88  	 * Convenience method which retrieves the encoding characters value from the second field of the
89  	 * first segment.
90  	 * 
91  	 * Typically, the first segment is MSH, so this method will retrieve the value of MSH-2.
92  	 * 
93  	 * @return The encoding characters
94  	 * @throws HL7Exception If an error occurs
95  	 * @since 1.0
96  	 */
97  	public String getEncodingCharactersValue() throws HL7Exception;
98  
99  	/**
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 {@link PipeParser} supports
106 	 * this functionality
107 	 */
108 	public void setParser(Parser parser);
109 
110 	/**
111 	 * Returns the parser to be used when parse/encode methods are called on this Message, as well
112 	 * as its children. The default value is a new {@link PipeParser}
113 	 */
114 	public Parser getParser();
115 
116 	/**
117 	 * Parses the string into this message using the parser returned by {@link #getParser() }
118 	 */
119 	public void parse(String string) throws HL7Exception;
120 
121 	/**
122 	 * Encodes this message using the parser returned by {@link #getParser() }
123 	 */
124 	public String encode() throws HL7Exception;
125 
126 	/**
127 	 * <p>
128 	 * Generates and returns an ACK message which would be used to acknowledge this message
129 	 * successfully, with an MSA-1 code of "AA". The ACK generated will be of the same version as
130 	 * the value of MSH-12 in this message (as opposed to the version of the message class instance,
131 	 * if they are different)
132 	 * </p>
133 	 * 
134 	 * <p>
135 	 * Note that this method will fail if it is not possible to generate an ACK for any reason, such
136 	 * as
137 	 * <ul>
138 	 * <li>Message version is invalid</li>
139 	 * <li>First segment is not an MSH</li>
140 	 * </p>
141 	 * 
142 	 * @throws HL7Exception If the message can not be constructed
143 	 * @throws IOException If a failure occurs in generating a control ID for the message
144 	 */
145 	public Message generateACK() throws HL7Exception, IOException;
146 
147 	/**
148 	 * <p>
149 	 * Generates and returns an ACK message which would be used to acknowledge this message
150 	 * successfully. The ACK generated will be of the same version as the value of MSH-12 in this
151 	 * message (as opposed to the version of the message class instance, if they are different)
152 	 * </p>
153 	 * 
154 	 * <p>
155 	 * Note that this method will fail if it is not possible to generate an ACK for any reason, such
156 	 * as
157 	 * <ul>
158 	 * <li>Message version is invalid</li>
159 	 * <li>First segment is not an MSH</li>
160 	 * </p>
161 	 * 
162 	 * @param theAcknowldegementCode The acknowledement code (MSA-1) to supply. If null, defaults to
163 	 *            "AA". To generate a typical NAK, use "AE"
164 	 * @param theException The exceptions used to populate the ERR segment (if any)
165 	 * @throws HL7Exception If the message can not be constructed
166 	 * @throws IOException If a failure occurs in generating a control ID for the message
167 	 * 
168 	 * @deprecated use {@link #generateACK(AcknowledgmentCode, HL7Exception)}
169 	 */
170 	public Message generateACK(String theAcknowldegementCode, HL7Exception theException)
171 			throws HL7Exception, IOException;
172 
173 	/**
174 	 * <p>
175 	 * Generates and returns an ACK message which would be used to acknowledge this message
176 	 * successfully. The ACK generated will be of the same version as the value of MSH-12 in this
177 	 * message (as opposed to the version of the message class instance, if they are different)
178 	 * </p>
179 	 * 
180 	 * <p>
181 	 * Note that this method will fail if it is not possible to generate an ACK for any reason, such
182 	 * as
183 	 * <ul>
184 	 * <li>Message version is invalid</li>
185 	 * <li>First segment is not an MSH</li>
186 	 * </p>
187 	 * 
188 	 * @param theAcknowlegementCode If null, defaults to
189 	 *            AcknowledgmentCode.AA. To generate a typical NAK, use AcknowledgmentCode.AE
190 	 * @param theException The exceptions used to populate the ERR segment (if any)
191 	 * @throws HL7Exception If the message can not be constructed
192 	 * @throws IOException If a failure occurs in generating a control ID for the message
193 	 */	
194 	public Message generateACK(AcknowledgmentCode theAcknowlegementCode, HL7Exception theException)
195 			throws HL7Exception, IOException;	
196 	/**
197 	 * <p>
198 	 * Prints a summary of the contents and structure of this message. This is useful for debugging
199 	 * purposes, if you want to figure out where in the structure of a message a given segment has
200 	 * been placed.
201 	 * </p>
202 	 * <p>
203 	 * For instance, the following message (containing a few quirks for demonstration purposes):
204 	 * <code>
205 	 * <pre>MSH|^~\\&|^QueryServices||||20021011161756.297-0500||ADT^A01|1|D|2.4\r
206 	 * EVN|R01
207 	 * EVN|R02
208 	 * PID|1
209 	 * IN1|1
210 	 * IN1|2
211 	 * PID|2</pre></code> ...produces the following output: <code>
212 	 * <pre>ADT_A01 (start)
213 	 *    MSH - MSH|^~\&|^QueryServices||||20021011161756.297-0500||ADT^A01|1|D|2.4
214 	 *    EVN - EVN|R01
215 	 *    [ { EVN2 } ] (non-standard) - EVN|R02
216 	 *    PID - PID|1
217 	 *    [ PD1 ] - Not populated
218 	 *    [ { ROL } ] - Not populated
219 	 *    [ { NK1 } ] - Not populated
220 	 *    PV1 - Not populated
221 	 *    [ PV2 ] - Not populated
222 	 *    [ { ROL2 } ] - Not populated
223 	 *    [ { DB1 } ] - Not populated
224 	 *    [ { OBX } ] - Not populated
225 	 *    [ { AL1 } ] - Not populated
226 	 *    [ { DG1 } ] - Not populated
227 	 *    [ DRG ] - Not populated
228 	 *    PROCEDURE (start)
229 	 *    [{
230 	 *       PR1 - Not populated
231 	 *       [ { ROL } ] - Not populated
232 	 *    }]
233 	 *    PROCEDURE (end)
234 	 *    [ { GT1 } ] - Not populated
235 	 *    INSURANCE (start)
236 	 *    [{
237 	 *       IN1 - IN1|1
238 	 *       [ IN2 ] - Not populated
239 	 *       [ { IN3 } ] - Not populated
240 	 *       [ { ROL } ] - Not populated
241 	 *    }]
242 	 *    [{
243 	 *       IN1 - IN1|2
244 	 *       [ { PID } ] (non-standard) - PID|2
245 	 *       [ IN2 ] - Not populated
246 	 *       [ { IN3 } ] - Not populated
247 	 *       [ { ROL } ] - Not populated
248 	 *    }]
249 	 *    INSURANCE (end)
250 	 *    [ ACC ] - Not populated
251 	 *    [ UB1 ] - Not populated
252 	 *    [ UB2 ] - Not populated
253 	 *    [ PDA ] - Not populated
254 	 * ADT_A01 (end)
255 	 * </pre></code>
256 	 * </p>
257 	 * 
258 	 * @return A summary of the structure
259 	 * @throws HL7Exception If any problems occur encoding the structure
260 	 */
261 	public String printStructure() throws HL7Exception;
262 
263 }