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    }