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 ca.uhn.hl7v2.HL7Exception;
031import ca.uhn.hl7v2.parser.Parser;
032import ca.uhn.hl7v2.parser.PipeParser;
033import ca.uhn.hl7v2.validation.ValidationContext;
034import java.io.IOException;
035
036
037/**
038 * <p>
039 * Represents a complete HL7 message including all structures, segments, and fields.  
040 * </p><p>
041 * Note this it is not recommended to implement this interface directly, as it is
042 * subject to change. Instead, extend abstract implementations for your
043 * model classes, such as {@link AbstractMessage} and {@link AbstractGroup}
044 * </p>
045 * 
046 * @author Bryan Tripp (bryan_tripp@sourceforge.net)
047 */
048public interface Message extends Group {
049
050    /**
051     * Returns the version number of the HL7 version in which this 
052     * message structure is defined (e.g. "2.4")
053     */
054    public abstract String getVersion();
055    
056    /**
057     * @return the set of validation rules that applies to this message
058     */
059    public abstract ValidationContext getValidationContext();
060
061    /**
062     * @param theContext the set of validation rules that are to apply to this message
063     */
064    public void setValidationContext(ValidationContext theContext);
065
066
067    /**
068     * Convenience method which retrieves the field separator value from the first field of the first segment.
069     *
070     * Typically, the first segment is MSH, so this method will retrieve the
071     * value of MSH-1.
072     *
073     * @return The field separator
074     * @throws HL7Exception If an error occurs
075     * @since 1.0
076     */
077    public Character getFieldSeparatorValue() throws HL7Exception;
078
079
080    /**
081     * Convenience method which retrieves the encoding characters value from the second field of the first segment.
082     *
083     * Typically, the first segment is MSH, so this method will retrieve the
084     * value of MSH-2.
085     *
086     * @return The encoding characters
087     * @throws HL7Exception If an error occurs
088     * @since 1.0
089     */
090    public String getEncodingCharactersValue() throws HL7Exception;
091
092
093    /**
094     * Sets the parser to be used when parse/encode methods are called on this
095     * Message, as well as its children. It is recommended that if these methods
096     * are going to be called, a parser be supplied with the validation context
097     * wanted. Where possible, the parser should be reused for best performance,
098     * unless thread safety is an issue.
099     *
100     * Note that not all parsers can be used. As of version 1.0, only {@link PipeParser}
101     * supports this functionality
102     */
103    public void setParser(Parser parser);
104
105    
106    /**
107     * Returns the parser to be used when parse/encode methods are called on this
108     * Message, as well as its children. The default value is a new {@link PipeParser}
109     */
110    public Parser getParser();
111
112    
113    /**
114     * Parses the string into this message using the parser returned by {@link #getParser() }
115     */
116    public void parse(String string) throws HL7Exception;
117
118
119    /**
120     * Encodes this message using the parser returned by {@link #getParser() }
121     */
122    public String encode() throws HL7Exception;
123
124
125    /**
126     * <p>
127     * Generates and returns an ACK message which would be used to
128     * acknowledge this message successfully, with an MSA-1 code of "AA".
129     * The ACK generated will be of the same version as the value of MSH-12 in this message (as opposed
130     * to the version of the message class instance, if they are different)
131     * </p>
132     *
133     * <p>
134     * Note that this method will fail if it is not possible to
135     * generate an ACK for any reason, such as
136     * <ul>
137     * <li>Message version is invalid</li>
138     * <li>First segment is not an MSH</li>
139     * </p>
140     *
141     * @throws HL7Exception If the message can not be constructed
142     * @throws IOException If a failure occurs in generating a control ID for the message
143     */
144    public Message generateACK() throws HL7Exception, IOException;
145
146
147    /**
148     * <p>
149     * Generates and returns an ACK message which would be used to
150     * acknowledge this message successfully. The ACK generated will be
151     * of the same version as the value of MSH-12 in this message (as opposed
152     * to the version of the message class instance, if they are different)
153     * </p>
154     *
155     * <p>
156     * Note that this method will fail if it is not possible to
157     * generate an ACK for any reason, such as
158     * <ul>
159     * <li>Message version is invalid</li>
160     * <li>First segment is not an MSH</li>
161     * </p>
162     *
163     * @param theAcknowldegementCode The acknowledement code (MSA-1) to supply. If null, defaults to "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    public Message generateACK(String theAcknowldegementCode, HL7Exception theException) throws HL7Exception, IOException;
169
170    /**
171     * <p>
172     * Prints a summary of the contents and structure of this message. This is useful for
173     * debugging purposes, if you want to figure out where in the structure of a message
174     * a given segment has been placed.
175     * </p>
176     * <p>
177     * For instance, the following message (containing a few quirks for demonstration purposes):
178     * <code>
179     * <pre>MSH|^~\\&|^QueryServices||||20021011161756.297-0500||ADT^A01|1|D|2.4\r
180     * EVN|R01
181     * EVN|R02
182     * PID|1
183     * IN1|1
184     * IN1|2
185     * PID|2</pre></code>
186     * ...produces the following output:
187     * <code>
188     * <pre>ADT_A01 (start)
189     *    MSH - MSH|^~\&|^QueryServices||||20021011161756.297-0500||ADT^A01|1|D|2.4
190     *    EVN - EVN|R01
191     *    [ { EVN2 } ] (non-standard) - EVN|R02
192     *    PID - PID|1
193     *    [ PD1 ] - Not populated
194     *    [ { ROL } ] - Not populated
195     *    [ { NK1 } ] - Not populated
196     *    PV1 - Not populated
197     *    [ PV2 ] - Not populated
198     *    [ { ROL2 } ] - Not populated
199     *    [ { DB1 } ] - Not populated
200     *    [ { OBX } ] - Not populated
201     *    [ { AL1 } ] - Not populated
202     *    [ { DG1 } ] - Not populated
203     *    [ DRG ] - Not populated
204     *    PROCEDURE (start)
205     *    [{
206     *       PR1 - Not populated
207     *       [ { ROL } ] - Not populated
208     *    }]
209     *    PROCEDURE (end)
210     *    [ { GT1 } ] - Not populated
211     *    INSURANCE (start)
212     *    [{
213     *       IN1 - IN1|1
214     *       [ IN2 ] - Not populated
215     *       [ { IN3 } ] - Not populated
216     *       [ { ROL } ] - Not populated
217     *    }]
218     *    [{
219     *       IN1 - IN1|2
220     *       [ { PID } ] (non-standard) - PID|2
221     *       [ IN2 ] - Not populated
222     *       [ { IN3 } ] - Not populated
223     *       [ { ROL } ] - Not populated
224     *    }]
225     *    INSURANCE (end)
226     *    [ ACC ] - Not populated
227     *    [ UB1 ] - Not populated
228     *    [ UB2 ] - Not populated
229     *    [ PDA ] - Not populated
230     * ADT_A01 (end)
231     * </pre></code>
232     * </p>
233     * 
234     * @return A summary of the structure
235     * @throws HL7Exception If any problems occur encoding the structure
236     */
237    public String printStructure() throws HL7Exception;
238    
239}