Coverage Report

Coverage Report - ca.uhn.hl7v2.model.Message

Classes in this File

 /**
 The contents of this file are subject to the Mozilla Public License Version 1.1 
 (the "License"); you may not use this file except in compliance with the License. 
 You may obtain a copy of the License at http://www.mozilla.org/MPL/ 
 Software distributed under the License is distributed on an "AS IS" basis, 
 WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the 
 specific language governing rights and limitations under the License. 
 
 The Original Code is "Message.java".  Description: 
 "Represents a complete HL7 message including all structures, segments, and fields" 
 
 The Initial Developer of the Original Code is University Health Network. Copyright (C) 
 2001.  All Rights Reserved. 
 
 Contributor(s): ______________________________________. 
 
 Alternatively, the contents of this file may be used under the terms of the 
 GNU General Public License (the  �GPL�), in which case the provisions of the GPL are 
 applicable instead of those above.  If you wish to allow use of your version of this 
 file only under the terms of the GPL and not to allow others to use your version 
 of this file under the MPL, indicate your decision by deleting  the provisions above 
 and replace  them with the notice and other provisions required by the GPL License.  
 If you do not delete the provisions above, a recipient may use your version of 
 this file under either the MPL or the GPL. 
 
  */
 
 package ca.uhn.hl7v2.model;
 
 import java.io.IOException;
 
 import ca.uhn.hl7v2.AcknowledgmentCode;
 import ca.uhn.hl7v2.HL7Exception;
 import ca.uhn.hl7v2.parser.Parser;
 import ca.uhn.hl7v2.validation.ValidationContext;
 
 /**
  * <p>
  * Represents a complete HL7 message including all structures, segments, and fields.
  * </p>
  * <p>
  * Note this it is not recommended to implement this interface directly, as it is subject to change.
  * Instead, extend abstract implementations for your model classes, such as {@link AbstractMessage}
  * and {@link AbstractGroup}
  * </p>
  * 
  * @author Bryan Tripp (bryan_tripp@sourceforge.net)
  */
 public interface Message extends Group {
 
         /**
          * Returns the version number of the HL7 version in which this message structure is defined
          * (e.g. "2.4")
      * @return version number of the HL7 version
          */
         public abstract String getVersion();
 
         /**
          * Convenience method which retrieves the field separator value from the first field of the
          * first segment.
          * 
          * Typically, the first segment is MSH, so this method will retrieve the value of MSH-1.
          * 
          * @return The field separator
          * @throws HL7Exception If an error occurs
          * @since 1.0
          */
         public Character getFieldSeparatorValue() throws HL7Exception;
 
         /**
          * Convenience method which retrieves the encoding characters value from the second field of the
          * first segment.
          * 
          * Typically, the first segment is MSH, so this method will retrieve the value of MSH-2.
          * 
          * @return The encoding characters
          * @throws HL7Exception If an error occurs
          * @since 1.0
          */
         public String getEncodingCharactersValue() throws HL7Exception;
 
         /**
          * Sets the parser to be used when parse/encode methods are called on this Message, as well as
          * its children. It is recommended that if these methods are going to be called, a parser be
          * supplied with the validation context wanted. Where possible, the parser should be reused for
          * best performance, unless thread safety is an issue.
          * 
          * Note that not all parsers can be used. As of version 1.0, only PipeParser supports
          * this functionality
      *
      * @param parser the parser to be used when parse/encode methods are called on this Message
          */
         public void setParser(Parser parser);
 
         /**
          * Returns the parser to be used when parse/encode methods are called on this Message, as well
          * as its children. The default value is a new PipeParser.
      *
      * @return the parser to be used when parse/encode methods are called on this Message
          */
         public Parser getParser();
 
         /**
          * Parses the string into this message using the parser returned by {@link #getParser() }
      * @param string the message to be parsed
      * @throws HL7Exception if errors occurred during parsing
          */
         public void parse(String string) throws HL7Exception;
 
         /**
          * Encodes this message using the parser returned by {@link #getParser() }
      * @return the string-encoded message
      * @throws HL7Exception if error occurred during encoding
          */
         public String encode() throws HL7Exception;
 
         /**
          * <p>
          * Generates and returns an ACK message which would be used to acknowledge this message
          * successfully, with an MSA-1 code of "AA". The ACK generated will be of the same version as
          * the value of MSH-12 in this message (as opposed to the version of the message class instance,
          * if they are different)
          * </p>
          * 
          * <p>
          * Note that this method will fail if it is not possible to generate an ACK for any reason, such
          * as
          * <ul>
          * <li>Message version is invalid</li>
          * <li>First segment is not an MSH</li>
          * </p>
          *
      * @return the acknowledgment message
          * @throws HL7Exception If the message can not be constructed
          * @throws IOException If a failure occurs in generating a control ID for the message
          */
         public Message generateACK() throws HL7Exception, IOException;
 
         /**
          * <p>
          * Generates and returns an ACK message which would be used to acknowledge this message
          * successfully. The ACK generated will be of the same version as the value of MSH-12 in this
          * message (as opposed to the version of the message class instance, if they are different)
          * </p>
          * 
          * <p>
          * Note that this method will fail if it is not possible to generate an ACK for any reason, such
          * as
          * <ul>
          * <li>Message version is invalid</li>
          * <li>First segment is not an MSH</li>
          * </p>
          * 
          * @param theAcknowldegementCode The acknowledement code (MSA-1) to supply. If null, defaults to
          *            "AA". To generate a typical NAK, use "AE"
          * @param theException The exceptions used to populate the ERR segment (if any)
          * @throws HL7Exception If the message can not be constructed
          * @throws IOException If a failure occurs in generating a control ID for the message
          * 
          * @deprecated use {@link #generateACK(AcknowledgmentCode, HL7Exception)}
          */
         public Message generateACK(String theAcknowldegementCode, HL7Exception theException)
                         throws HL7Exception, IOException;
 
         /**
          * <p>
          * Generates and returns an ACK message which would be used to acknowledge this message
          * successfully. The ACK generated will be of the same version as the value of MSH-12 in this
          * message (as opposed to the version of the message class instance, if they are different)
          * </p>
          * 
          * <p>
          * Note that this method will fail if it is not possible to generate an ACK for any reason, such
          * as
          * <ul>
          * <li>Message version is invalid</li>
          * <li>First segment is not an MSH</li>
          * </p>
          * 
          * @param theAcknowlegementCode If null, defaults to
          *            AcknowledgmentCode.AA. To generate a typical NAK, use AcknowledgmentCode.AE
          * @param theException The exceptions used to populate the ERR segment (if any)
      * @return the acknoeldgement message
          * @throws HL7Exception If the message can not be constructed
          * @throws IOException If a failure occurs in generating a control ID for the message
          */        
         public Message generateACK(AcknowledgmentCode theAcknowlegementCode, HL7Exception theException)
                         throws HL7Exception, IOException;        
         /**
          * <p>
          * Prints a summary of the contents and structure of this message. This is useful for debugging
          * purposes, if you want to figure out where in the structure of a message a given segment has
          * been placed.
          * </p>
          * <p>
          * For instance, the following message (containing a few quirks for demonstration purposes):
          * <code>
          * <pre>MSH|^~\\&|^QueryServices||||20021011161756.297-0500||ADT^A01|1|D|2.4\r
          * EVN|R01
          * EVN|R02
          * PID|1
          * IN1|1
          * IN1|2
          * PID|2</pre></code> ...produces the following output: <code>
          * <pre>ADT_A01 (start)
          *    MSH - MSH|^~\&|^QueryServices||||20021011161756.297-0500||ADT^A01|1|D|2.4
          *    EVN - EVN|R01
          *    [ { EVN2 } ] (non-standard) - EVN|R02
          *    PID - PID|1
          *    [ PD1 ] - Not populated
          *    [ { ROL } ] - Not populated
          *    [ { NK1 } ] - Not populated
          *    PV1 - Not populated
          *    [ PV2 ] - Not populated
          *    [ { ROL2 } ] - Not populated
          *    [ { DB1 } ] - Not populated
          *    [ { OBX } ] - Not populated
          *    [ { AL1 } ] - Not populated
          *    [ { DG1 } ] - Not populated
          *    [ DRG ] - Not populated
          *    PROCEDURE (start)
          *    [{
          *       PR1 - Not populated
          *       [ { ROL } ] - Not populated
          *    }]
          *    PROCEDURE (end)
          *    [ { GT1 } ] - Not populated
          *    INSURANCE (start)
          *    [{
          *       IN1 - IN1|1
          *       [ IN2 ] - Not populated
          *       [ { IN3 } ] - Not populated
          *       [ { ROL } ] - Not populated
          *    }]
          *    [{
          *       IN1 - IN1|2
          *       [ { PID } ] (non-standard) - PID|2
          *       [ IN2 ] - Not populated
          *       [ { IN3 } ] - Not populated
          *       [ { ROL } ] - Not populated
          *    }]
          *    INSURANCE (end)
          *    [ ACC ] - Not populated
          *    [ UB1 ] - Not populated
          *    [ UB2 ] - Not populated
          *    [ PDA ] - Not populated
          * ADT_A01 (end)
          * </pre></code>
          * </p>
          * 
          * @return A summary of the structure
          * @throws HL7Exception If any problems occur encoding the structure
          */
         public String printStructure() throws HL7Exception;
 
 }

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 java.io.IOException;
31
32		import ca.uhn.hl7v2.AcknowledgmentCode;
33		import ca.uhn.hl7v2.HL7Exception;
34		import ca.uhn.hl7v2.parser.Parser;
35		import ca.uhn.hl7v2.validation.ValidationContext;
36
37		/**
38		* <p>
39		* Represents a complete HL7 message including all structures, segments, and fields.
40		* </p>
41		* <p>
42		* Note this it is not recommended to implement this interface directly, as it is subject to change.
43		* Instead, extend abstract implementations for your model classes, such as {@link AbstractMessage}
44		* and {@link AbstractGroup}
45		* </p>
46		*
47		* @author Bryan Tripp (bryan_tripp@sourceforge.net)
48		*/
49		public interface Message extends Group {
50
51		/**
52		* Returns the version number of the HL7 version in which this message structure is defined
53		* (e.g. "2.4")
54		* @return version number of the HL7 version
55		*/
56		public abstract String getVersion();
57
58		/**
59		* Convenience method which retrieves the field separator value from the first field of the
60		* first segment.
61		*
62		* Typically, the first segment is MSH, so this method will retrieve the value of MSH-1.
63		*
64		* @return The field separator
65		* @throws HL7Exception If an error occurs
66		* @since 1.0
67		*/
68		public Character getFieldSeparatorValue() throws HL7Exception;
69
70		/**
71		* Convenience method which retrieves the encoding characters value from the second field of the
72		* first segment.
73		*
74		* Typically, the first segment is MSH, so this method will retrieve the value of MSH-2.
75		*
76		* @return The encoding characters
77		* @throws HL7Exception If an error occurs
78		* @since 1.0
79		*/
80		public String getEncodingCharactersValue() throws HL7Exception;
81
82		/**
83		* Sets the parser to be used when parse/encode methods are called on this Message, as well as
84		* its children. It is recommended that if these methods are going to be called, a parser be
85		* supplied with the validation context wanted. Where possible, the parser should be reused for
86		* best performance, unless thread safety is an issue.
87		*
88		* Note that not all parsers can be used. As of version 1.0, only PipeParser supports
89		* this functionality
90		*
91		* @param parser the parser to be used when parse/encode methods are called on this Message
92		*/
93		public void setParser(Parser parser);
94
95		/**
96		* Returns the parser to be used when parse/encode methods are called on this Message, as well
97		* as its children. The default value is a new PipeParser.
98		*
99		* @return the parser to be used when parse/encode methods are called on this Message
100		*/
101		public Parser getParser();
102
103		/**
104		* Parses the string into this message using the parser returned by {@link #getParser() }
105		* @param string the message to be parsed
106		* @throws HL7Exception if errors occurred during parsing
107		*/
108		public void parse(String string) throws HL7Exception;
109
110		/**
111		* Encodes this message using the parser returned by {@link #getParser() }
112		* @return the string-encoded message
113		* @throws HL7Exception if error occurred during encoding
114		*/
115		public String encode() throws HL7Exception;
116
117		/**
118		* <p>
119		* Generates and returns an ACK message which would be used to acknowledge this message
120		* successfully, with an MSA-1 code of "AA". The ACK generated will be of the same version as
121		* the value of MSH-12 in this message (as opposed to the version of the message class instance,
122		* if they are different)
123		* </p>
124		*
125		* <p>
126		* Note that this method will fail if it is not possible to generate an ACK for any reason, such
127		* as
128		* <ul>
129		* <li>Message version is invalid</li>
130		* <li>First segment is not an MSH</li>
131		* </p>
132		*
133		* @return the acknowledgment message
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		* <p>
141		* Generates and returns an ACK message which would be used to acknowledge this message
142		* successfully. The ACK generated will be of the same version as the value of MSH-12 in this
143		* message (as opposed to the version of the message class instance, if they are different)
144		* </p>
145		*
146		* <p>
147		* Note that this method will fail if it is not possible to generate an ACK for any reason, such
148		* as
149		* <ul>
150		* <li>Message version is invalid</li>
151		* <li>First segment is not an MSH</li>
152		* </p>
153		*
154		* @param theAcknowldegementCode The acknowledement code (MSA-1) to supply. If null, defaults to
155		* "AA". To generate a typical NAK, use "AE"
156		* @param theException The exceptions used to populate the ERR segment (if any)
157		* @throws HL7Exception If the message can not be constructed
158		* @throws IOException If a failure occurs in generating a control ID for the message
159		*
160		* @deprecated use {@link #generateACK(AcknowledgmentCode, HL7Exception)}
161		*/
162		public Message generateACK(String theAcknowldegementCode, HL7Exception theException)
163		throws HL7Exception, IOException;
164
165		/**
166		* <p>
167		* Generates and returns an ACK message which would be used to acknowledge this message
168		* successfully. The ACK generated will be of the same version as the value of MSH-12 in this
169		* message (as opposed to the version of the message class instance, if they are different)
170		* </p>
171		*
172		* <p>
173		* Note that this method will fail if it is not possible to generate an ACK for any reason, such
174		* as
175		* <ul>
176		* <li>Message version is invalid</li>
177		* <li>First segment is not an MSH</li>
178		* </p>
179		*
180		* @param theAcknowlegementCode If null, defaults to
181		* AcknowledgmentCode.AA. To generate a typical NAK, use AcknowledgmentCode.AE
182		* @param theException The exceptions used to populate the ERR segment (if any)
183		* @return the acknoeldgement message
184		* @throws HL7Exception If the message can not be constructed
185		* @throws IOException If a failure occurs in generating a control ID for the message
186		*/
187		public Message generateACK(AcknowledgmentCode theAcknowlegementCode, HL7Exception theException)
188		throws HL7Exception, IOException;
189		/**
190		* <p>
191		* Prints a summary of the contents and structure of this message. This is useful for debugging
192		* purposes, if you want to figure out where in the structure of a message a given segment has
193		* been placed.
194		* </p>
195		* <p>
196		* For instance, the following message (containing a few quirks for demonstration purposes):
197		* <code>
198		* <pre>MSH\|^~\\&\|^QueryServices\|\|\|\|20021011161756.297-0500\|\|ADT^A01\|1\|D\|2.4\r
199		* EVN\|R01
200		* EVN\|R02
201		* PID\|1
202		* IN1\|1
203		* IN1\|2
204		* PID\|2</pre></code> ...produces the following output: <code>
205		* <pre>ADT_A01 (start)
206		* MSH - MSH\|^~\&\|^QueryServices\|\|\|\|20021011161756.297-0500\|\|ADT^A01\|1\|D\|2.4
207		* EVN - EVN\|R01
208		* [ { EVN2 } ] (non-standard) - EVN\|R02
209		* PID - PID\|1
210		* [ PD1 ] - Not populated
211		* [ { ROL } ] - Not populated
212		* [ { NK1 } ] - Not populated
213		* PV1 - Not populated
214		* [ PV2 ] - Not populated
215		* [ { ROL2 } ] - Not populated
216		* [ { DB1 } ] - Not populated
217		* [ { OBX } ] - Not populated
218		* [ { AL1 } ] - Not populated
219		* [ { DG1 } ] - Not populated
220		* [ DRG ] - Not populated
221		* PROCEDURE (start)
222		* [{
223		* PR1 - Not populated
224		* [ { ROL } ] - Not populated
225		* }]
226		* PROCEDURE (end)
227		* [ { GT1 } ] - Not populated
228		* INSURANCE (start)
229		* [{
230		* IN1 - IN1\|1
231		* [ IN2 ] - Not populated
232		* [ { IN3 } ] - Not populated
233		* [ { ROL } ] - Not populated
234		* }]
235		* [{
236		* IN1 - IN1\|2
237		* [ { PID } ] (non-standard) - PID\|2
238		* [ IN2 ] - Not populated
239		* [ { IN3 } ] - Not populated
240		* [ { ROL } ] - Not populated
241		* }]
242		* INSURANCE (end)
243		* [ ACC ] - Not populated
244		* [ UB1 ] - Not populated
245		* [ UB2 ] - Not populated
246		* [ PDA ] - Not populated
247		* ADT_A01 (end)
248		* </pre></code>
249		* </p>
250		*
251		* @return A summary of the structure
252		* @throws HL7Exception If any problems occur encoding the structure
253		*/
254		public String printStructure() throws HL7Exception;
255
256		}