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 "ExampleUseTerser.java".  Description:
10   * "Example Code"
11   *
12   * The Initial Developer of the Original Code is University Health Network. Copyright (C)
13   * 2001.  All Rights Reserved.
14   *
15   * Contributor(s): James Agnew
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.examples;
29  
30  import ca.uhn.hl7v2.DefaultHapiContext;
31  import ca.uhn.hl7v2.HapiContext;
32  import ca.uhn.hl7v2.model.GenericMessage;
33  import ca.uhn.hl7v2.model.Message;
34  import ca.uhn.hl7v2.parser.CanonicalModelClassFactory;
35  import ca.uhn.hl7v2.parser.DefaultModelClassFactory;
36  import ca.uhn.hl7v2.parser.GenericModelClassFactory;
37  import ca.uhn.hl7v2.parser.PipeParser;
38  import ca.uhn.hl7v2.util.Terser;
39  
40  /**
41   * Example code illustrating how to handle multiple versions of HL7 from one codebase
42   * 
43   * @author <a href="mailto:jamesagnew@sourceforge.net">James Agnew</a>
44   * @version $Revision: 1.1 $ updated on $Date: 2011-05-22 16:52:21 $ by $Author: jamesagnew $
45   */
46  public class HandlingMultipleVersions {
47  
48  	public static void main(String[] args) throws Exception {
49  
50  		/*
51  		 * Often, you will need to handle multiple versions of HL7 from a sending system
52  		 * from within the same code base. Because HAPI uses different model classes for
53  		 * each version, this can seem difficult.
54  		 * 
55  		 * Before the first example, a bit of background information that is useful.
56  		 * HL7 v2 is a backwards compatible standard, for the most part. New versions
57  		 * of the standard will deprocate old fields and segments and groups, but they never
58  		 * remove them entirely. They will also rename fields and groups, but this has
59  		 * no effect on encoded messages if they are encoded using ER7 (pipe and hat)
60  		 * encoding, only on the message structure objects themselves.
61  		 * 
62  		 * Unfortunately, because of this renaming, it is not possible for the
63  		 * HAPI library to create a single version of a structure JAR which covers
64  		 * all versions of HL7 v2 (v2.1, v2.2, v2.3, etc). That said, it is always
65  		 * possible to use a HAPI message structure object to parse or encode a
66  		 * message of the same type from an earlier version of the standard. In
67  		 * other words, if you have a v2.2 ADT^A01 message, you can use the v2.3
68  		 * ADT_A01 structure class to parse it, and you can also use the v2.3 ADT_A01
69  		 * structure class to create a new v2.2 message if you are not planning on
70  		 * XML encoding it.  
71  		 * 
72  		 * The following example shows two ways of dealing with this situation. First,
73  		 * for this example, consider the following messages. Each is identical, aside
74  		 * from the version string: "2.5" and "2.3".
75  		 */
76  		
77          String v25message = "MSH|^~\\&|ULTRA|TML|OLIS|OLIS|200905011130||ORU^R01|20169838-v25|T|2.5\r"
78  			+ "PID|||7005728^^^TML^MR||TEST^RACHEL^DIAMOND||19310313|F|||200 ANYWHERE ST^^TORONTO^ON^M6G 2T9||(416)888-8888||||||1014071185^KR\r"
79  			+ "PV1|1||OLIS||||OLIST^BLAKE^DONALD^THOR^^^^^921379^^^^OLIST\r"
80  			+ "ORC|RE||T09-100442-RET-0^^OLIS_Site_ID^ISO|||||||||OLIST^BLAKE^DONALD^THOR^^^^L^921379\r"
81  			+ "OBR|0||T09-100442-RET-0^^OLIS_Site_ID^ISO|RET^RETICULOCYTE COUNT^HL79901 literal|||200905011106|||||||200905011106||OLIST^BLAKE^DONALD^THOR^^^^L^921379||7870279|7870279|T09-100442|MOHLTC|200905011130||B7|F||1^^^200905011106^^R\r"
82  			+ "OBX|1|ST|||Test Value";
83  		
84          String v23message = "MSH|^~\\&|ULTRA|TML|OLIS|OLIS|200905011130||ORU^R01|20169838-v23|T|2.3\r"
85  			+ "PID|||7005728^^^TML^MR||TEST^RACHEL^DIAMOND||19310313|F|||200 ANYWHERE ST^^TORONTO^ON^M6G 2T9||(416)888-8888||||||1014071185^KR\r"
86  			+ "PV1|1||OLIS||||OLIST^BLAKE^DONALD^THOR^^^^^921379^^^^OLIST\r"
87  			+ "ORC|RE||T09-100442-RET-0^^OLIS_Site_ID^ISO|||||||||OLIST^BLAKE^DONALD^THOR^^^^L^921379\r"
88  			+ "OBR|0||T09-100442-RET-0^^OLIS_Site_ID^ISO|RET^RETICULOCYTE COUNT^HL79901 literal|||200905011106|||||||200905011106||OLIST^BLAKE^DONALD^THOR^^^^L^921379||7870279|7870279|T09-100442|MOHLTC|200905011130||B7|F||1^^^200905011106^^R\r"
89  			+ "OBX|1|ST|||Test Value";
90  		
91          /*
92           * The first (and probably better in most ways) technique is as follows. Use a model class
93           * factory called the CanonicalModelClassFactory. This class forces a specific version of
94           * HL7 to be used. Because HL7 v2.x is a backwards compatible standard, you can choose the
95           * highest version you need to support, and the model classes will be compatible with
96           * messages from previous versions.
97           */
98  		
99          HapiContext context = new DefaultHapiContext();
100         
101         // Create the MCF. We want all parsed messages to be for HL7 version 2.5,
102         // despite what MSH-12 says.
103         CanonicalModelClassFactory mcf = new CanonicalModelClassFactory("2.5");
104         context.setModelClassFactory(mcf);
105 
106         // Pass the MCF to the parser in its constructor
107         PipeParser parser = context.getPipeParser();
108         
109         // The parser parses the v2.3 message to a "v25" structure
110         ca.uhn.hl7v2.model.v25.message.ORU_R01 msg = (ca.uhn.hl7v2.model.v25.message.ORU_R01) parser.parse(v23message);
111         
112         // 20169838-v23
113         System.out.println(msg.getMSH().getMessageControlID().getValue());
114 
115         // The parser also parses the v2.5 message to a "v25" structure
116         msg = (ca.uhn.hl7v2.model.v25.message.ORU_R01) parser.parse(v25message);
117         
118         // 20169838-v25
119         System.out.println(msg.getMSH().getMessageControlID().getValue());
120         
121         /*
122          * The second technique is to use the Terser. The Terser allows you
123          * to access field values using a path-like notation. For more information
124          * on the Terser, see the example here:
125          * http://hl7api.sourceforge.net/xref/ca/uhn/hl7v2/examples/ExampleUseTerser.html
126          */
127 
128         // This time we just use a normal ModelClassFactory, which means we will be
129         // using the standard version-specific model classes
130         context.setModelClassFactory(new DefaultModelClassFactory());
131 
132         // 20169838-v23
133         Message v23Message = parser.parse(v23message);
134         Terser t23 = new Terser(v23Message);
135         System.out.println(t23.get("/MSH-10"));
136 
137         // 20169838-v25
138         Message v25Message = parser.parse(v25message);
139         Terser t25 = new Terser(v25Message);
140         System.out.println(t25.get("/MSH-10"));
141         
142         /*
143          * Note that this second technique has one major drawback: Although 
144          * message definitions are backwards compatible, some group names
145          * change between versions. If you are accessing a group within
146          * a complex message structure, this can cause issues.
147          * 
148          * This is less of an issue for some message types where groups are
149          * not used much (e.g. ADT)
150          */
151 
152         // This works and prints "Test Value"
153         System.out.println(t23.get("/RESPONSE/ORDER_OBSERVATION/OBSERVATION(0)/OBX-5"));
154 
155         // This fails...
156         // System.out.println(t25.get("/RESPONSE/ORDER_OBSERVATION/OBSERVATION(0)/OBX-5"));
157         
158         // ...because this would be required to extract the OBX-5 value from a v2.5 message
159         System.out.println(t25.get("/PATIENT_RESULT/ORDER_OBSERVATION/OBSERVATION(0)/OBX-5"));
160         
161         /*
162          * A third technique which may occasionally be useful is to simply use
163          * a "Generic" message structure. Generic message structures can 
164          * represent anything within an HL7 message, but they don't actually
165          * model all of the intricacies of the structure within the message,
166          * but rather just model all of the data in an unstructured way.
167          */
168         
169         // Create a new context using a Generic Model Class Factory
170         context = new DefaultHapiContext();
171         context.setModelClassFactory(new GenericModelClassFactory());
172 
173         v25message = "MSH|^~\\&|ULTRA|TML|OLIS|OLIS|200905011130||ORU^R01|20169838-v25|T|2.5\r"
174 			+ "PID|||7005728^^^TML^MR||TEST^RACHEL^DIAMOND||19310313|F|||200 ANYWHERE ST^^TORONTO^ON^M6G 2T9||(416)888-8888||||||1014071185^KR\r"
175 			+ "PV1|1||OLIS||||OLIST^BLAKE^DONALD^THOR^^^^^921379^^^^OLIST\r"
176 			+ "ORC|RE||T09-100442-RET-0^^OLIS_Site_ID^ISO|||||||||OLIST^BLAKE^DONALD^THOR^^^^L^921379\r"
177 			+ "OBR|0||T09-100442-RET-0^^OLIS_Site_ID^ISO|RET^RETICULOCYTE COUNT^HL79901 literal|||200905011106|||||||200905011106||OLIST^BLAKE^DONALD^THOR^^^^L^921379||7870279|7870279|T09-100442|MOHLTC|200905011130||B7|F||1^^^200905011106^^R\r"
178 			+ "OBX|1|ST|||Test Value\r"
179 			+ "NTE||Note for OBX(1)\r"
180 			+ "OBX|2|ST|||Value number 2";
181 
182         // The parser will always parse this as a "GenericMessage"
183         GenericMessage message = (GenericMessage) context.getPipeParser().parse(v25message);
184         
185         /* 
186          * A generic message has a flat structure, so you can ask for any
187          * field by only its segment name, not a complex path 
188          */
189         Terser t = new Terser(message);
190         System.out.println(t.get("/OBX-5"));
191         // Prints: Test Value
192         
193         /*
194          * This technique isn't great for messages with complex structures. For
195          * example, the second OBX in the message above is a part of the base structure
196          * because GenericMessage has no groups.
197          * 
198          * It can be accessed using a new segment name (OBX2 instead of OBX)
199          * but this is error prone, so use with caution.
200          */
201         System.out.println(t.get("/OBX2-5"));
202         // Prints: Value number 2
203         
204 	}
205 
206 }