Coverage Report - ca.uhn.hl7v2.model.Message
 
Classes in this File Line Coverage Branch Coverage Complexity
Message
N/A
N/A
1
 
 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  
 }